12 <concept id="GUID-5C1E776D-5AEF-5326-BEA6-F2108F42CB71" xml:lang="en"><title>condvar:

    12 <concept id="GUID-5C1E776D-5AEF-5326-BEA6-F2108F42CB71" xml:lang="en"><title>condvar: Using Condition Variables</title><shortdesc>Examples that explains how to use condition variables. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

    13 Using Condition Variables</title><shortdesc>Examples that explains how to use condition variables. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

    19 <section id="GUID-8209AA7E-0DFB-512D-9BEB-9063BA617BC5"><title>condvarglobal</title> <p>This

    18 <section id="GUID-8209AA7E-0DFB-512D-9BEB-9063BA617BC5"><title>condvarglobal</title> <p>This example shows the use of the global condition variable IPC

    20 example shows the use of the global condition variable IPC mechanism. The

    19 mechanism. The scope of a global condition variable is inter-process.

    21 scope of a global condition variable is inter-process. It can be shared by

    20 It can be shared by threads of any process in the system. </p> <p><b>Download</b> </p> <p>Click on the following link to download the

    22 threads of any process in the system. </p> <p><b>Download</b> </p> <p>Click

    21 example: <xref href="guid-6013a680-57f9-415b-8851-c4fa63356636/zips/guid-ddcb07c8-2646-4414-b33f-086f5758cbfe.zip" scope="external">condvarglobal .zip</xref></p><p>Click <xref href="guid-6013a680-57f9-415b-8851-c4fa63356636/guid-ddcb07c8-2646-4414-b33f-086f5758cbfe.html" scope="peer"> browse </xref> to view the example code</p><p><b>Class

    23 on the following link to download the example: <xref href="guid-6013a680-57f9-415b-8851-c4fa63356636/zips/guid-ddcb07c8-2646-4414-b33f-086f5758cbfe.zip" scope="external">condvarglobal .zip</xref></p><p>Click <xref href="guid-6013a680-57f9-415b-8851-c4fa63356636/guid-ddcb07c8-2646-4414-b33f-086f5758cbfe.html" scope="peer"> browse </xref> to view the example code</p><p><b>Class summary</b></p><p> <xref href="GUID-D16EF740-78E6-3D08-AE2F-AFA5E812FF2B.dita"><apiname>RCondVar </apiname></xref> <xref href="GUID-C0FEA3A0-7DD3-3B87-A919-CB973BC05766.dita"><apiname>RMutex </apiname></xref> <xref href="GUID-326A2F4D-0E99-31C0-A35D-E8BF45913F07.dita"><apiname>RChunk </apiname></xref> <xref href="GUID-3CECC9FC-58C1-3117-AAF2-FDF88341F56F.dita"><apiname>CPeriodic</apiname></xref> </p> <p><b>Description</b> </p> <p>This

    22 summary</b></p><p> <xref href="GUID-D16EF740-78E6-3D08-AE2F-AFA5E812FF2B.dita"><apiname>RCondVar </apiname></xref> <xref href="GUID-C0FEA3A0-7DD3-3B87-A919-CB973BC05766.dita"><apiname>RMutex </apiname></xref> <xref href="GUID-326A2F4D-0E99-31C0-A35D-E8BF45913F07.dita"><apiname>RChunk </apiname></xref> <xref href="GUID-3CECC9FC-58C1-3117-AAF2-FDF88341F56F.dita"><apiname>CPeriodic</apiname></xref> </p> <p><b>Description</b> </p> <p>This example uses an adder and subtractor

    24 example uses an adder and subtractor pattern to show the use of a global condition

    23 pattern to show the use of a global condition variable. Two processes,

    25 variable. Two processes, the adder and the subtractor, modify a shared variable

    24 the adder and the subtractor, modify a shared variable by adding and

    26 by adding and subtracting random amounts. The condition variable ensures that

    25 subtracting random amounts. The condition variable ensures that the

    27 the value remains within given limits, <codeph>KMaxValue</codeph> and <codeph>KMinValue</codeph>,

    26 value remains within given limits, <codeph>KMaxValue</codeph> and <codeph>KMinValue</codeph>, by blocking one of the processes if the value

    28 by blocking one of the processes if the value crosses a warning threshold. </p> <p>The

    27 crosses a warning threshold. </p> <p>The adder program creates a global

    29 adder program creates a global shared memory chunk. It also creates a global

    28 shared memory chunk. It also creates a global mutex to control access

    30 mutex to control access to the chunk and a global condition variable to signal

    29 to the chunk and a global condition variable to signal that the value

    31 that the value in the chunk is '<codeph>ready for use</codeph>'. It then initialises

    30 in the chunk is '<codeph>ready for use</codeph>'. It then initialises

    32 the value in the chunk to zero and periodically tries to add a random value

    31 the value in the chunk to zero and periodically tries to add a random

    33 between 1 and 10 . If, having added a value, it finds that the value of the

    32 value between 1 and 10 . If, having added a value, it finds that the

    34 chunk is greater than <codeph>KUpperThreshold</codeph>, it waits for a signal

    33 value of the chunk is greater than <codeph>KUpperThreshold</codeph>, it waits for a signal from the condition variable before adding

    35 from the condition variable before adding another value. </p> <p>The subtractor

    34 another value. </p> <p>The subtractor program periodically tries to

    36 program periodically tries to subtract a random value between 1 and 10 from

    35 subtract a random value between 1 and 10 from the global shared memory

    37 the global shared memory chunk. If, having subtracted a value, it finds that

    36 chunk. If, having subtracted a value, it finds that the value of the

    38 the value of the chunk is less than <codeph>KLowerThreshold</codeph>, it waits

    37 chunk is less than <codeph>KLowerThreshold</codeph>, it waits for

    39 for a signal from the condition variable before subtracting another value. </p> <p><b>Design

    38 a signal from the condition variable before subtracting another value. </p> <p><b>Design and implementation</b> </p> <fig id="GUID-1FAFB189-D2E4-5A05-8D8B-B3F7D28467FC">

    40 and implementation</b> </p> <fig id="GUID-1FAFB189-D2E4-5A05-8D8B-B3F7D28467FC">

    39 <image href="GUID-857A523E-E660-5AFA-98B1-3A5440A8372F_d0e255233_href.jpg" placement="inline"/>

    41 <image href="GUID-857A523E-E660-5AFA-98B1-3A5440A8372F_d0e250294_href.jpg" placement="inline"/>

    40 </fig> <p><b>Build</b> </p> <p>The ConditionVariable example builds

    42 </fig> <p><b>Build</b> </p> <p><xref href="GUID-3100800B-B2F7-50EF-BD4C-3C345ECCB2A5.dita">The

    41 the following binary files in the standard location (<filepath>\epoc32\release\winscw\

    43 Symbian build process</xref> describes how to build this example. The ConditionVariable

    44 example builds the following binary files in the standard location (<filepath>\epoc32\release\winscw\

    46 <li id="GUID-A699F4AF-3A5F-5C24-83CB-1762348AA1D2"><p> <b>adder.exe:</b> Demonstrates

    43 <li id="GUID-A699F4AF-3A5F-5C24-83CB-1762348AA1D2"><p> <b>adder.exe:</b> Demonstrates the use of the global condition variable. It creates

    47 the use of the global condition variable. It creates a global shared memory

    44 a global shared memory chunk and periodically adds random values to

    48 chunk and periodically adds random values to the chunk. </p> </li>

    45 the chunk. </p> </li>

    49 <li id="GUID-30A5BE77-8F99-5206-AD42-51E843D0D3C2"><p> <b>subtractor.exe:</b> Demonstrates

    46 <li id="GUID-30A5BE77-8F99-5206-AD42-51E843D0D3C2"><p> <b>subtractor.exe:</b> Demonstrates the use of the global condition variable. It periodically

    50 the use of the global condition variable. It periodically subtracts random

    47 subtracts random values from the chunk created by <filepath>adder.exe</filepath>. </p> </li>

    51 values from the chunk created by <filepath>adder.exe</filepath>. </p> </li>

    48 </ul> <p><b>How to run the Example</b> </p> <p>To run the example,

    52 </ul> <p><b>How to run the Example</b> </p> <p>To run the example, perform

    49 perform the following steps: </p> <ol id="GUID-312A1E16-C92B-5C33-9D80-83080412E657">

    53 the following steps: </p> <ol id="GUID-312A1E16-C92B-5C33-9D80-83080412E657">

    56 <li id="GUID-457E6D8F-A383-5CF6-BA6E-D98C8FAC20F4"><p>Run <filepath>subtract.exe</filepath> in

    52 <li id="GUID-457E6D8F-A383-5CF6-BA6E-D98C8FAC20F4"><p>Run <filepath>subtract.exe</filepath> in your new eshell. </p> </li>

    57 your new eshell. </p> </li>

    53 <li id="GUID-122618AE-028B-5BF9-BB4B-4F95099EE839"><p>Switch between

    58 <li id="GUID-122618AE-028B-5BF9-BB4B-4F95099EE839"><p>Switch between eshells

    54 eshells by pressing <b>CTRL+ALT+SHIFT+T</b>. </p> </li>

    59 by pressing <b>CTRL+ALT+SHIFT+T</b>. </p> </li>

    55 <li id="GUID-24CCA548-D350-53A7-9919-270EA0C71EC1"><p>To finish, stop

    60 <li id="GUID-24CCA548-D350-53A7-9919-270EA0C71EC1"><p>To finish, stop each

    56 each application by pressing any key. </p> </li>

    61 application by pressing any key. </p> </li>

    63 <section id="GUID-8CF8C4E2-4D74-54C8-9601-97CC44B9C943"><title>condvarlocal</title> <p>This

    58 <section id="GUID-8CF8C4E2-4D74-54C8-9601-97CC44B9C943"><title>condvarlocal</title> <p>This example shows the use of the local condition variable IPC

    64 example shows the use of the local condition variable IPC mechanism. The scope

    59 mechanism. The scope of a local condition variable is intra-process.

    65 of a local condition variable is intra-process. It can be shared by threads

    60 It can be shared by threads of the process that creates the condition

    66 of the process that creates the condition variable. </p> <p><b>Download</b> </p> <p>Click

    61 variable. </p> <p><b>Download</b> </p> <p>Click on the following link

    67 on the following link to download the example: <xref href="guid-6013a680-57f9-415b-8851-c4fa63356636/zips/guid-527239ad-3eff-4d62-a7fe-b7e43658dd2f.zip" scope="external">condvarlocal .zip </xref></p><p>Click <xref href="guid-6013a680-57f9-415b-8851-c4fa63356636/guid-527239ad-3eff-4d62-a7fe-b7e43658dd2f.html" scope="peer"> browse </xref> to view the example.</p> <p><b>Class summary</b></p><p> <xref href="GUID-C0FEA3A0-7DD3-3B87-A919-CB973BC05766.dita"><apiname>RMutex </apiname></xref><xref href="GUID-B0E661BC-4058-3256-B9C3-5A4FD52F6DE5.dita"><apiname>RThread </apiname></xref>  <xref href="GUID-3CECC9FC-58C1-3117-AAF2-FDF88341F56F.dita"><apiname>CPeriodic </apiname></xref> <xref href="GUID-D16EF740-78E6-3D08-AE2F-AFA5E812FF2B.dita"><apiname>RCondVar</apiname></xref></p> <p><b>Description</b> </p> <p>This

    62 to download the example: <xref href="guid-6013a680-57f9-415b-8851-c4fa63356636/zips/guid-527239ad-3eff-4d62-a7fe-b7e43658dd2f.zip" scope="external">condvarlocal .zip </xref></p><p>Click <xref href="guid-6013a680-57f9-415b-8851-c4fa63356636/guid-527239ad-3eff-4d62-a7fe-b7e43658dd2f.html" scope="peer"> browse </xref> to view the example.</p> <p><b>Class

    68 example uses the producer and the consumer model to show the use of the local

    63 summary</b></p><p> <xref href="GUID-C0FEA3A0-7DD3-3B87-A919-CB973BC05766.dita"><apiname>RMutex </apiname></xref><xref href="GUID-B0E661BC-4058-3256-B9C3-5A4FD52F6DE5.dita"><apiname>RThread </apiname></xref>  <xref href="GUID-3CECC9FC-58C1-3117-AAF2-FDF88341F56F.dita"><apiname>CPeriodic </apiname></xref> <xref href="GUID-D16EF740-78E6-3D08-AE2F-AFA5E812FF2B.dita"><apiname>RCondVar</apiname></xref></p> <p><b>Description</b> </p> <p>This example uses the producer and the

    69 condition variable. </p> <p>The example creates two local threads: a producer

    64 consumer model to show the use of the local condition variable. </p> <p>The example creates two local threads: a producer and a consumer.

    70 and a consumer. The two threads share a buffer, which is an object of the <codeph>CQueue</codeph> class.

    65 The two threads share a buffer, which is an object of the <codeph>CQueue</codeph> class. The CQueue object creates a local condition

    71 The CQueue object creates a local condition variable using the <codeph>RCondVar::CreateLocal()</codeph> function.

    66 variable using the <codeph>RCondVar::CreateLocal()</codeph> function.

    72 It also defines the methods to insert and remove a token from the queue. The <codeph>CQueue::Insert()</codeph> function

    67 It also defines the methods to insert and remove a token from the

    73 inserts a token into the queue and signals the condition variable. The <codeph>CQueue::Remove()</codeph> function

    68 queue. The <codeph>CQueue::Insert()</codeph> function inserts a token

    74 tries to remove a token from the queue. If the queue is empty, it must wait

    69 into the queue and signals the condition variable. The <codeph>CQueue::Remove()</codeph> function tries to remove a token from the queue. If the queue is

    75 for a signal from the condition variable. </p> <p>An object of the <codeph>CProducer</codeph> class

    70 empty, it must wait for a signal from the condition variable. </p> <p>An object of the <codeph>CProducer</codeph> class creates and

    76 creates and calls the producer thread. The producer thread is called once

    71 calls the producer thread. The producer thread is called once every

    77 every two seconds using an object of the <xref href="GUID-3CECC9FC-58C1-3117-AAF2-FDF88341F56F.dita"><apiname>CPeriodic</apiname></xref> class.

    72 two seconds using an object of the <xref href="GUID-3CECC9FC-58C1-3117-AAF2-FDF88341F56F.dita"><apiname>CPeriodic</apiname></xref> class.

    78 This thread inserts a token into the queue when it is called. It calls the <codeph>CQueue::Insert()</codeph> function

    73 This thread inserts a token into the queue when it is called. It calls

    79 on the shared <codeph>CQueue</codeph> object. </p> <p>An object of the <codeph>CConsumer</codeph> class

    74 the <codeph>CQueue::Insert()</codeph> function on the shared <codeph>CQueue</codeph> object. </p> <p>An object of the <codeph>CConsumer</codeph> class creates and calls the consumer thread. The consumer thread

    80 creates and calls the consumer thread. The consumer thread is called once

    75 is called once a second using an object of the <xref href="GUID-3CECC9FC-58C1-3117-AAF2-FDF88341F56F.dita"><apiname>CPeriodic</apiname></xref> class. This thread removes a token from the queue when it is called.

    81 a second using an object of the <xref href="GUID-3CECC9FC-58C1-3117-AAF2-FDF88341F56F.dita"><apiname>CPeriodic</apiname></xref> class. This thread

    76 It calls the <codeph>CQueue::Remove()</codeph> function on the shared <codeph>CQueue</codeph> object. </p> <p>For more information, refer to <xref href="http://support.entegrity.com/private/doclib/docs/osfhtm/develop/appdev/Appde179.htm" scope="external">Condition Variables</xref>. </p> <p> <note> Symbian

    82 removes a token from the queue when it is called. It calls the <codeph>CQueue::Remove()</codeph> function

    77 is not responsible for the content of external websites.</note>  </p> <p><b>Design and implementation</b> </p> <fig id="GUID-CA344322-0982-59C3-B93A-7A1F175728F3">

    83 on the shared <codeph>CQueue</codeph> object. </p> <p>For more information,

    78 <image href="GUID-CAB30473-7829-5F2E-9F45-A2344DEDFC35_d0e255432_href.jpg" placement="inline"/>

    84 refer to <xref href="http://support.entegrity.com/private/doclib/docs/osfhtm/develop/appdev/Appde179.htm" scope="external">Condition Variables</xref>. </p> <p> <note> Symbian

    79 </fig> <p><b>Build</b> </p> <p>The Symbian build process describes

    85 is not responsible for the content of external websites.</note>  </p> <p><b>Design

    80 how to build this example. The ConditionVariable example builds the

    86 and implementation</b> </p> <fig id="GUID-CA344322-0982-59C3-B93A-7A1F175728F3">

    81 following binary files in the standard location (<filepath>\epoc32\release\winscw\

    87 <image href="GUID-CAB30473-7829-5F2E-9F45-A2344DEDFC35_d0e250496_href.jpg" placement="inline"/>

    82              &lt;build_variant&gt;</filepath>) for Carbide.c++. </p> <p> <filepath>condvarlocal.exe</filepath>: Demonstrates the use of the

    88 </fig> <p><b>Build</b> </p> <p><xref href="GUID-3100800B-B2F7-50EF-BD4C-3C345ECCB2A5.dita">The

    83 local condition variable. </p> <p><b>How to run the Example</b> </p> <p>To run the example, perform the following steps: </p> <ol id="GUID-D07D5782-6A32-5552-B42B-7D2672F1C94F">

    89 Symbian build process</xref> describes how to build this example. The ConditionVariable

    84 <li id="GUID-CD0F5EAF-780F-5BC7-A216-2FE9CA3B284D"><p>Run <filepath>condvarlocal.exe</filepath>. The program calls the producer and the

    90 example builds the following binary files in the standard location (<filepath>\epoc32\release\winscw\

    85 consumer threads periodically as shown in the description section.

    91              &lt;build_variant&gt;</filepath>) for Carbide.c++. </p> <p> <filepath>condvarlocal.exe</filepath>:

    86 It also displays a menu. </p> </li>

    92 Demonstrates the use of the local condition variable. </p> <p><b>How to run

    87 <li id="GUID-106E7D1D-4ECB-5FA2-A42C-CB1549F4811F"><p>Press <b>‘d’</b> to display the contents of the queue. </p> </li>

    93 the Example</b> </p> <p>To run the example, perform the following steps: </p> <ol id="GUID-D07D5782-6A32-5552-B42B-7D2672F1C94F">

    88 <li id="GUID-AA9ABD22-E280-5F21-A1A1-F47FFAAC58F2"><p>Press <b>‘p’</b> to insert a token into the queue. </p> </li>

    94 <li id="GUID-CD0F5EAF-780F-5BC7-A216-2FE9CA3B284D"><p>Run <filepath>condvarlocal.exe</filepath>.

    89 <li id="GUID-96C5D556-0700-5632-80A1-E728C97A62C1"><p>Press any key

    95 The program calls the producer and the consumer threads periodically as shown

    90 to stop the program. </p> </li>

    96 in the description section. It also displays a menu. </p> </li>

    97 <li id="GUID-106E7D1D-4ECB-5FA2-A42C-CB1549F4811F"><p>Press <b>‘d’</b> to

    98 display the contents of the queue. </p> </li>

    99 <li id="GUID-AA9ABD22-E280-5F21-A1A1-F47FFAAC58F2"><p>Press <b>‘p’</b> to

   100 insert a token into the queue. </p> </li>

   101 <li id="GUID-96C5D556-0700-5632-80A1-E728C97A62C1"><p>Press any key to stop

   102 the program. </p> </li>