|
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-6408C26A-2736-59A9-B785-6B119143619B" xml:lang="en"><title>How |
|
13 to use a thread-death notifier</title><shortdesc>Describes the thread-death notifier and provides a code snippet |
|
14 to show you how to use it.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
15 <p>To use a thread-death notifier, a thread which needs to know about the |
|
16 death of other threads: </p> |
|
17 <ul> |
|
18 <li id="GUID-914D2BE7-BFD3-58E3-ABD4-53371512332F"><p>constructs an <codeph>RUndertaker</codeph> handle |
|
19 and then calls its <codeph>Create()</codeph> member function to create the |
|
20 associated Kernel side object. The <codeph>RUndertaker</codeph> handle is <keyword>process-relative</keyword> which |
|
21 means that the handle is <i>not</i> closed if the requesting thread dies. </p> </li> |
|
22 <li id="GUID-F46FEA42-38C3-526D-AC05-225BDD3A8714"><p>issues a notification |
|
23 request to the thread-death notifier, passing a reference to a <codeph>TRequestStatus</codeph> object |
|
24 and a reference to a <codeph>TInt</codeph>. </p> </li> |
|
25 </ul> |
|
26 <p>When any other thread dies, the requesting thread's <keyword>request semaphore</keyword> is |
|
27 signalled to indicate that the notification request is complete. The <codeph>TRequestStatus</codeph> object |
|
28 supplied by the requesting thread is set to <codeph>KErrDied</codeph>. </p> |
|
29 <p>In addition, the Kernel opens a local thread-relative handle on the dying |
|
30 thread. (thread-relative, here, means relative to the requesting thread) and |
|
31 sets the <codeph>TInt</codeph>, supplied by the requesting thread, to the |
|
32 resulting handle-number. The requesting thread can construct an <codeph>RThread</codeph> from |
|
33 this handle-number. The following diagram helps visualise the situation. </p> |
|
34 <fig id="GUID-5B53CA3B-5365-5C54-B2BC-EA8BA684F15E"> |
|
35 <title> Thread-death notifier </title> |
|
36 <image href="GUID-70483E81-311F-5247-9F39-3940F20C0EB1_d0e242598_href.png" placement="inline"/> |
|
37 </fig> |
|
38 <p>The following code fragments demonstrate this: </p> |
|
39 <codeblock id="GUID-B5A219AD-CC59-50CE-A65B-0D3F4FD32F7A" xml:space="preserve">{ |
|
40 ... |
|
41 RUndertaker the_undertaker; |
|
42 TRequestStatus the_status; |
|
43 TInt the_dyingthread_handle_number; |
|
44 ... |
|
45 the_undertaker.Create(); |
|
46 the_undertaker.Logon(the_status,the_dyingthread_handle_number); |
|
47 User::WaitForRequest(the_status); |
|
48 ... |
|
49 ...// prepare for a long wait |
|
50 ... |
|
51 RThread r; |
|
52 r.SetHandle(the_dyingthread_handle_number); |
|
53 ... |
|
54 ...// Now have an open thread-relative handle to the |
|
55 ...// dying thread so we can, for example, ... |
|
56 if (r.ExitReason()==0x666) |
|
57 { |
|
58 ... |
|
59 } |
|
60 ...// We have an open handle on the dying thread; the dying thread |
|
61 ...// remains in existence until we close it. |
|
62 r.Close(); |
|
63 ... |
|
64 }</codeblock> |
|
65 <p>In practical code, an <codeph>RUndertaker</codeph> is used by an active |
|
66 object. </p> |
|
67 <p>The <codeph>RUndertaker</codeph> handle also offers a <codeph>LogonCancel()</codeph> function. |
|
68 Calling this function, causes the requesting thread's <keyword>request semaphore</keyword> to |
|
69 be signalled and any wait to complete. The <codeph>TRequestStatus</codeph> is |
|
70 set to <codeph>KErrCancel</codeph>. </p> |
|
71 <p>This technique of using an <codeph>RUndertaker</codeph> is not guaranteed |
|
72 to report the death of all threads. In particular, if a second thread dies |
|
73 while a requesting thread is handling the request completion due to the death |
|
74 of a first thread (but before it can make another notification request), the |
|
75 death of this second thread will go unnoticed. </p> |
|
76 </conbody></concept> |