|
1 <?xml version="1.0" encoding="utf-8"?> |
|
2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. --> |
|
3 <!-- This component and the accompanying materials are made available under the terms of the License |
|
4 "Eclipse Public License v1.0" which accompanies this distribution, |
|
5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". --> |
|
6 <!-- Initial Contributors: |
|
7 Nokia Corporation - initial contribution. |
|
8 Contributors: |
|
9 --> |
|
10 <!DOCTYPE concept |
|
11 PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> |
|
12 <concept id="GUID-975F53E5-1C13-5063-B817-795F2623737B" xml:lang="en"><title>Sharable |
|
13 sessions</title><shortdesc>Describes how a session can be shared by threads.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
14 <p>A session can be shared by threads provided the server is marked as supporting |
|
15 shared sessions. </p> |
|
16 <section id="GUID-33D699D4-50DD-4B46-BFEA-8E9AD46C66C1"><title>Sharing</title> <p>Once a server has started, and a client |
|
17 has connected to that server (by creating a session), then the client thread |
|
18 can make the session sharable. There are two types of sharing: </p> <ul> |
|
19 <li id="GUID-4AF39204-BA70-50CB-9D13-185655322A1D"><p>where the session is |
|
20 sharable among all threads belonging to the same process as the originating |
|
21 thread. </p> </li> |
|
22 <li id="GUID-69DFB418-D434-58B0-A27E-57C053C822A5"><p>where the session is |
|
23 sharable among all threads in the system, i.e. across all processes. </p> </li> |
|
24 </ul> <p>A server must support the creation of sharable sessions, otherwise |
|
25 an attempt to make a session sharable panics the calling thread. Servers can |
|
26 be created to be either unsharable, sharable among threads in the same process, |
|
27 or sharable among all threads in the system. </p> <p><b>Sharing |
|
28 a session among threads in a single process</b> </p> <p>There are two ways |
|
29 of doing this: </p> <ul> |
|
30 <li id="GUID-285E2AE9-DEB7-502E-B8B2-47D3B45F50EB"><p>if the session has already |
|
31 been created, then call <xref href="GUID-6D8A458C-9A39-3000-A3BC-060A2A3663E6.dita#GUID-6D8A458C-9A39-3000-A3BC-060A2A3663E6/GUID-0A453CA9-9DF7-35B8-963E-D75763626136"><apiname>RSessionBase::ShareAuto()</apiname></xref>, which |
|
32 has the effect of mutating the handle from a thread relative handle to a process |
|
33 relative handle. The handle can then be shared by the threads. Until this |
|
34 function is called, the session is specific to the originating thread, and |
|
35 cannot be used by any other thread. </p> </li> |
|
36 <li id="GUID-BD414669-EE7A-5821-A591-12D77CD0FBA9"><p>if the session has not |
|
37 yet been created, then create the session as sharable from the beginning using |
|
38 one of the overloads of <codeph>RSessionBase::CreateSession()</codeph> that |
|
39 takes a <codeph>TIpcSessionType</codeph> argument - <i>this is the preferred |
|
40 method</i> </p> </li> |
|
41 </ul> <b>Sharing |
|
42 a session among threads across all processes</b><p> There are two ways of |
|
43 doing this:<ul> |
|
44 <li><p>if the session has already been created, then call <xref href="GUID-6D8A458C-9A39-3000-A3BC-060A2A3663E6.dita#GUID-6D8A458C-9A39-3000-A3BC-060A2A3663E6/GUID-943BCB86-1497-3940-BDA5-6DB1767DA395"><apiname>RSessionBase::ShareProtected()</apiname></xref>, |
|
45 which has the effect of mutating the handle from a thread relative handle |
|
46 to a process relative handle; this is also protected and can be passed to |
|
47 another process. The handle can then be shared by the threads. Until this |
|
48 function is called, the session is specific to the originating thread, and |
|
49 cannot be used by any other thread.</p></li> |
|
50 <li><p>if the session has not yet been created, then create the session as |
|
51 sharable from the beginning using one of the overloads of <codeph>RSessionBase::CreateSession()</codeph> that |
|
52 takes a <codeph>TIpcSessionType</codeph> argument - <i>this is the preferred |
|
53 method</i></p></li> |
|
54 </ul></p> </section> |
|
55 <section id="GUID-49F7BFC0-2DD3-4AA5-A105-18ACFE702789"><title>Server exit</title> <p>If the server terminates, all outstanding |
|
56 messages which have been sent to it are completed with a <codeph>KErrServerTerminated</codeph> code. |
|
57 Any attempt to send further messages, or to share session, fail immediately |
|
58 with <codeph>KErrServerTerminated</codeph>. The only valid operation on such |
|
59 a session is to close it. </p> </section> |
|
60 <section id="GUID-20F18655-D04E-40CE-8199-058DA9AD1585"><title>Session closure</title> <p>If <codeph>Close()</codeph> is |
|
61 called on a session, any outstanding messages on the session may not be completed |
|
62 for the client. Following this, the only message that the server receives |
|
63 from the session is the disconnect message. </p> </section> |
|
64 <section id="GUID-C4508E0A-50FC-4780-AEAA-08018CF2AB7F"><title>Client thread exit</title> <p>If a session has not been shared, |
|
65 then the session is closed as part of normal thread cleanup. </p> <p>If a |
|
66 session has been shared, the session handle is owned by the process and is |
|
67 not automatically cleaned up with the thread. In addition, the server is not |
|
68 informed that the thread has terminated. </p> <p>The only way to free resources |
|
69 owned by the session is to explicitly close the session, or to terminate the |
|
70 client process. Note that this makes it possible for a session to have no |
|
71 client threads ! </p> </section> |
|
72 <section id="GUID-9F7C4330-C524-4D8E-A78D-B519CF737D7D"><title>Message slots</title> <p>The maximum number of message slots |
|
73 that can be allocated to a session, or the maximum number that can be dynamically |
|
74 acquired from the system-wide pool, is 255. </p> </section> |
|
75 </conbody></concept> |