Sharable sessions

A session can be shared by all threads in a client process.

Note that in ER5, there is no concept of sharable sessions.

Once a server has started, a client thread can connect to that server. Following a successful connection, the client thread can make the session sharable among all the client threads in that process through a call to RSessionBase::Share(). Until this function is called, the session is specific to the connecting client thread.

A server must support the creation of sharable sessions, otherwise a call to RSessionBase::Share() raises a panic.

Before client threads can send messages on a shared session, they must attach to the session. This ensures that the necessary Kernel resources have been acquired.

Depending on the type of share, client threads can:

• attach themselves explicitly.

• be auto attached when they first send a message

Explicit attachment

If the share specifies explicit attachment, then a client thread must call RSessionBase::Attach() before attempting to send messages on the shared session. Failure to attach before sending a message causes the calling thread to panic.

If the session is not shared, then an attempt to attach raises a panic.

If the attach fails, the client thread is notified by a simple return code; i.e. no leave occurs and no panic is raised.

Auto attachment

If the share specifies auto attachment, then the thread is automatically attached when it attempts to send its first message.

If auto attachment fails, then the client thread is panicked (USER 135).

If the server terminates, all outstanding messages which have been sent to it are completed with a KErrServerTerminated code. Any attempt to send further messages, or to attach to a shared session, fail immediately with KErrServerTerminated. The only valid operation on such a session is to close it.

If Close() is called on a session, any outstanding messages on the session may not be completed for the client. Following this, the only message that the server receives from the session is the disconnect message.

If a session has not been shared, then the session is closed as part of normal thread cleanup.

If a session has been shared, the session handle is owned by the process and is not automatically cleaned up with the thread. In addition, the server is not informed that the thread has terminated.

The only way to free resources owned by the session is to explicitly close the session, or to terminate the client process. Note that this makes it possible for a session to have no client threads !

The maximum number of message slots that can be allocated to a session, or the maximum number that can be dynamically acquired from the system-wide pool, is 255.