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-24477051-265A-5FE5-B479-ACB3EE27B825" xml:lang="en"><title>Synchronisation

    13 Techniques</title><shortdesc>Describes the use of <apiname>RThread::Rendezvous()</apiname> to

    14 synchronize threads.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

    15 <p>There are a number of techniques to synchronize or coordinate the activities

    16 of your threads with one another: </p>

    17 <ul>

    18 <li id="GUID-E5EC8F8C-2129-5750-AFDC-F4B15E3874C9"><p> <xref href="GUID-24477051-265A-5FE5-B479-ACB3EE27B825.dita#GUID-24477051-265A-5FE5-B479-ACB3EE27B825/GUID-68FCE30C-5487-501E-842C-6895717FD636">Thread Rendezvous</xref> </p> </li>

    19 </ul>

    20 <section id="GUID-68FCE30C-5487-501E-842C-6895717FD636"><title>Thread Rendezvous</title> <p>The <xref href="GUID-B0E661BC-4058-3256-B9C3-5A4FD52F6DE5.dita#GUID-B0E661BC-4058-3256-B9C3-5A4FD52F6DE5/GUID-83AADCC6-1AD8-32D8-A6E6-B86B47C97DC2"><apiname>RThread::Rendezvous()</apiname></xref> function

    21 allows a thread to signal that it has reached a point in its execution. This

    22 works in a similar way to the <xref href="GUID-77B673ED-F7EE-3D50-88A7-F8FBFCB2D64E.dita"><apiname>Logon()</apiname></xref> function, except

    23 that <xref href="GUID-77B673ED-F7EE-3D50-88A7-F8FBFCB2D64E.dita"><apiname>Logon()</apiname></xref> signals the termination of a thread, and <xref href="GUID-45C22917-DC6E-3C95-BFE5-B8E9B316D4E3.dita"><apiname>Rendezvous()</apiname></xref> signals

    24 that a particular point within the thread has been reached. </p> <p>The classic

    25 use for this function is in a server, where the main thread must wait until

    26 the initialisation of the server thread has completed before continuing. </p> </section>

    27 <section id="GUID-7A87E7D5-255B-4626-ADB0-7A8F3F839C3C"><title>Using Rendezvous</title> <p>The following example shows code

    28 a function creating a thread and then waiting for it to reach a certain point

    29 before continuing. The code shown here is taken from <filepath>…\examples\base\threadsandprocesses\Rendezvous\</filepath>,

    30 which you can build and run. </p> <codeblock id="GUID-292F2672-390D-5D14-9615-8894315A1645" xml:space="preserve">      // create threads to wait for

    31     RThread thread;

    32 

    33         // indicate completion status

    34     TRequestStatus myThreadRendezvousStatus;

    35 

    36         // pass 500 as the parameter to MyThread        

    37     TInt r=thread.Create(KMsgMyThreadName, MyThread, KDefaultStackSize, KHeapSize,KHeapSize,(TAny*) 2000000, EOwnerThread); 

    38     if (r!=KErrNone)

    39         {   

    40         console->Printf(KMsgCreateThreadFailed);

    41             return;

    42         }

    43         // create rendezvous

    44     thread.Rendezvous(myThreadRendezvousStatus);

    45 

    46         //EXCECUTE THREAD!

    47     console->Printf(KMsgStartThread);                    

    48     thread.Resume();

    49 

    50     User::WaitForRequest(myThreadRendezvousStatus);

    51     if(myThreadRendezvousStatus==KErrNone)

    52         {

    53         console->Printf(KMsgThreadRendezvousReached);

    54         }

    55         else

    56         {

    57         console->Printf(KMsgSomethingIsWrong);   

    58         }   

    59         

    60     thread.Close();

    61     console-&gt;Printf(KMsgEndOfTest);</codeblock> <p>The following function

    62 is the <codeph>MyThread()</codeph> function created in the previous example.

    63 The <codeph>MyThread()</codeph> function calls the rendezvous function to

    64 signal that the rendezvous point has been reached, <codeph>MyThread()</codeph> can

    65 then continue. </p> <codeblock id="GUID-94F0244E-B3E8-54F0-9BD8-6BB8942BA30F" xml:space="preserve">TInt MyThread(TAny* aParameter)

    66     {

    67         // simulate some processing

    68     User::After((TInt)aParameter);      

    69             

    70             // signal Rendezvous

    71     RThread::Rendezvous(KErrNone);

    72     

    73         // simulate some processing

    74     User::After((TInt)aParameter);      

    75     

    76     return(KErrNone);

    77     }</codeblock> <note><p> <codeph>MyThread()</codeph> can fail before signalling

    78 the <xref href="GUID-251A11AD-1D92-3F9C-AAEF-3D0FC9728C7E.dita"><apiname>Rendezvous</apiname></xref>, for example, if <codeph>MyThread()</codeph> panics

    79 with a <codeph>KERN-EXEC 3</codeph>, then the <xref href="GUID-251A11AD-1D92-3F9C-AAEF-3D0FC9728C7E.dita"><apiname>Rendezvous</apiname></xref> completes

    80 with the reason code <codeph>KErrDied</codeph> or another system wide error

    81 code other than <codeph>KErrNone</codeph>. </p></note><p>If <xref href="GUID-B3606A64-D3FB-3B92-8675-FBFD57675564.dita"><apiname>MyThread()</apiname></xref> enters

    82 a never ending loop before the rendezvous is reached, then this situation

    83 cannot be detected and results in the calling thread waiting indefinitely

    84 for the rendezvous. This can be avoided by careful programming. </p> </section>

    85 </conbody></concept>