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-056B9A65-EC59-4B2E-9F10-E487343B5F5F" xml:lang="en"><title>SemaphoreExample:

    13 thread synchronisation using semaphores</title><shortdesc>Explains how to use Semaphores to achieve thread synchronization.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

    14 <p>It is recommended to use semaphores instead of thread priorities for the

    15 following reasons:<ul>

    16 <li><p> In a uniprocessor environment, setting the thread priorities does

    17 not guarantee prioritized or serialized execution.</p></li>

    18 <li><p>In a multiprocessor or SMP environment, thread priorities are irrelevant

    19 as multiple threads can run simultaneously.</p></li>

    20 </ul></p>

    21 <section id="GUID-48668C9B-6B42-4FE8-899B-403D5EB5FB53"><title>Download</title> <p>Click on the following link to download

    22 the example: <xref href="guid-6013a680-57f9-415b-8851-c4fa63356636/zips/guid-34775913-c5c2-41ba-a591-827039bbe7af.zip" scope="external">SemaphoreExample.zip</xref></p><p>Click: <xref href="guid-6013a680-57f9-415b-8851-c4fa63356636/guid-34775913-c5c2-41ba-a591-827039bbe7af.html" scope="peer">browse</xref> to view the example code. </p></section>

    23 <section id="GUID-2E531F3D-EEC8-40FD-9F32-2071FDECAE61"><title>Description: </title><p> The example creates a database containing

    24 a table of three columns with integer entries.</p><p> The example creates

    25 two threads:</p><ul>

    26 <li><p><codeph>WriterThread</codeph>: This thread calls a periodic function

    27 at an interval of one second, and in each iteration it inserts one row of

    28 integers in the table. </p></li>

    29 <li><p><codeph>ReaderThread</codeph>: This thread also calls a periodic function

    30 at an interval of one second, and in each iteration it reads one row of integers

    31 following the last row read.</p></li>

    32 </ul><p> The example uses a macro <codeph>USE_SEMAPHORE</codeph> to show the

    33 difference between the code using semaphores and the code which doesn't use

    34 semaphores. When not using semaphores, it is not guaranteed that the <codeph>ReaderThread</codeph> will

    35 be able to read the database because in an SMP environment, data may not yet

    36 have been written by the <codeph>WriterThread</codeph>.</p><p>Using a semaphore

    37 serializes the thread execution. The read operation waits on the semaphore

    38 until it gets a signal from the write operation. This ensures that the <codeph>ReaderThread</codeph> only

    39 reads a row from the database after the <codeph>WriterThread</codeph> has

    40 written it. </p></section>

    41 <section id="GUID-07CAD3CA-86DB-4245-8565-C618E59718A5"><title>Class summary</title><ul>

    42 <li><p><xref href="GUID-B0E661BC-4058-3256-B9C3-5A4FD52F6DE5.dita"><apiname>RThread</apiname></xref> - A handle to a thread.</p></li>

    43 <li><p><xref href="GUID-F4A68645-2265-307F-B951-8295827E000B.dita"><apiname>RDbStoreDatabase</apiname></xref> - DBMS Store database implementation</p></li>

    44 <li><p><xref href="GUID-AED27A76-3645-3A04-B80D-10473D9C5A27.dita"><apiname>RSemaphore</apiname></xref> - Used for thread synchronization. </p></li>

    45 </ul></section>

    46 <section id="GUID-863B0EDF-F3F8-4345-9FEE-824350A2DBCE"><title>Building and configuring</title> <p>To build the example: </p> <ul>

    47 <li id="GUID-037442C7-2436-5152-9A3E-9DC0B4283A9C"><p>The example builds an

    48 executable called <filepath>semaphoreexample.exe</filepath> in the standard

    49 location. </p> </li>

    50 <li id="GUID-B7C849B9-0885-5253-A78B-71854F86D772"><p>You can build the example

    51 from your IDE or the command line. </p> <p>If you use an IDE, import the <filepath>bld.inf</filepath> file

    52 of the example into your IDE, and use the build command of the IDE. </p> <p>If

    53 you use the command line, open a command prompt, and set the current directory

    54 to the source code directory of the example. You can then build the example

    55 with the SBSv1 build tools with the following commands: </p> <p><userinput>bldmake

    56 bldfiles</userinput> </p> <p><userinput>abld build</userinput> </p> <p><xref href="GUID-793A5EF9-CC16-5EEB-9011-6431EA76EB15.dita">How to use bldmake</xref> and <xref href="GUID-B6B54E07-3B34-5D5C-8815-93383FA8FB4B.dita">How to use abld</xref> describe

    57 how to use the SBSv1 build tools. </p> </li>

    58 </ul> </section>

    59 <section id="GUID-278DD8CF-28AF-4826-B938-20EC19F3A5B0"><title>Running the example</title> <p>The example code contains a

    60 macro<codeph>USE_SEMAPHORE</codeph> in the <filepath>mmp</filepath> file.

    61 By default it is commented out and on execution the example runs without using

    62 semaphores; the macro should be uncommented to use semaphores. The console

    63 output will generally look the same whether using semaphores or not if there

    64 is a single processor, but differences will occur in an SMP environment. Run

    65 the example following the instructions provided in the console. </p> </section>

    66 </conbody></concept>