Rules for Allocating Session ---------------------------- Sessions are the key data structure in RMC. They're essentially light, app level context that manages the message flow between two applications. As addressed in the RMC design doc, session are very similar to TCP connections but with slightly different semantics. In RMC, there's only one session structure defined, but there are three session types defined by the way they're created. These session types are OPEN sessions, LISTEN sessions and ACCEPT sessions. OPEN sessions are created by client-side code: that is, code that initated a dialog with another application. LISTEN sessions are created by server-side code: that is, code that is waiting for some app to initiate a dialog via the rmc_open call. ACCEPT sessions are created implicilty by the RMC layer under a LISTEN session in response to a client-side rmc_open call. These sessions are mostly hidden from applications and unlike OPEN and LISTEN sessions, are managed by RMC. Client applications manage OPEN and LISTEN sessions. This means they allocate memory for these sessions, create them via the rmc_open or rmc_listen calls, and are responsible for closing these sessions (rmc_close or rmc_shutdown) and freeing the associated memory. On the SSC, applications may or may not control the memory used to allocate ACCCEPT sessions. Applications wishing to do so specify the new_session callback to the rmc_listen call. When a open request comes in from a client application, RMC will invoke this callback allowing the application control of the allocation and placement of the session structure. Related, when the open-side application closes it's session, the server is informed and calls another callback - the rmc_listen close_session callback. This callback provided the application with control over how the memory is released (or freed). In the R1.0.x releases, there are some cases where the close_session callback is called by RMC, but RMC wants the session structure to be preverved for immediate reuse - the RMC_FREE_SESSION macro is provided so that the callback code can interpret the RMC reuse policy. The mechanism works simply: at close time, RMC sets a field in the sessions structure before issuing the callback to signal the release policy for the session memory. The RMC_FREE_SESSION macro in the callback accesses this field to determine whether a release is needed. Application *MUST* not free the memory if the macro returns FALSE. A relavitely unknown feature of the SSC RMC implementation is that the new_session and close_session callbacks can be set to NULL. Doing so informs RMC that it's free to manage the ACCEPT sessions as it see's fit - applications are not required to allocate and free the sessions. It's also legal to set the new_session to NULL, but retain the close_session callback. When this is done, RMC will always mark the the session as not needing a release. Applications can assume this case implicitly knowing RMC_FREE_SESSION will return FALSE - the key is that RMC_FREE_SESSION is correct in either case. The model for EEE code is similar, but has one historical difference. Becasue RMC is an application, it ALWAYS manages the ACCEPT session memory. Review of the EEE rmc_listen reveals the missing new_session argument. Functionly, it's acts the same as the SSC variant with the new_session set to NULL - this holds true for the close callback as well - it can be set to NULL, or a valid handler. When set to a valid handler, it informs the application the session has been closed, but no release activity is required for the ACCEPT session. Related, the RMC_FREE_SESSION macro will always return FALSE. Error events and session close events ------------------------------------- Following the above rules, applications that encounter errors are responsible for closing the sessions they manage (i.e: OPEN/LISTEN sessions). Applications don't need to close ACCEPT sessions - they are simply informed of client-side close events via the close_session callback. Changes in R1.1 ----------------- The entire LISTEN and ACCEPT session handling in R1.0.x is maintained in R1.1. The OPEN session handling is also maintained with one additional feature. The open call has been expanded to take a abort_session callback. This callback allows client-side applications to be informed immediately when the server-side of the connection fails, regardless of whether they've got outstanding IO's or note. This differs from R1.0.x a bit - failures are discovered discovered one of two ways: via failure of a pending IO, or latently when a new IO is issued, times out and fails. Applications can set the abort_session callback to NULL in R1.1 to get R1.0.x compatible semantics....the only difference is that failures discovered via new IOs don't timeout - they're immediate. The real value of the callback comes from immediate discovery regardless of pending IOs.