<?xml version="1.0" encoding="utf-8"?>

<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

<!-- This component and the accompanying materials are made available under the terms of the License 

"Eclipse Public License v1.0" which accompanies this distribution, 

and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->

<!-- Initial Contributors:

    Nokia Corporation - initial contribution.

Contributors: 

-->

<!DOCTYPE concept

  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

<concept id="GUID-EAA6A9FB-A470-550C-B7B4-FF68A733A2D5" xml:lang="en"><title>Thread

Synchronisation</title><shortdesc>Kernel-side techniques to protect critical regions in code or to

allow safe access to shared data.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

<p>Kernel-side code can use a number of techniques to perform thread synchronisation,

to protect critical regions within threads or to ensure that shared data can

be safely read or modified. </p>

<ul>

<li id="GUID-F76D1379-CEA0-5CEA-A050-88CCF23AFAC6"><p> <xref href="GUID-EAA6A9FB-A470-550C-B7B4-FF68A733A2D5.dita#GUID-EAA6A9FB-A470-550C-B7B4-FF68A733A2D5/GUID-86E98109-EC1A-58B7-8AB2-EFD100739261">Mutexes</xref>  </p> </li>

<li id="GUID-614F64B3-04C0-5ED0-9286-C64B8B1C4235"><p> <xref href="GUID-EAA6A9FB-A470-550C-B7B4-FF68A733A2D5.dita#GUID-EAA6A9FB-A470-550C-B7B4-FF68A733A2D5/GUID-00E1F006-3D2C-52A3-BFCB-4D6A59321B26">Semaphores</xref> </p> </li>

<li id="GUID-7970F858-7480-5EEB-A924-2157E40FB44E"><p> <xref href="GUID-EAA6A9FB-A470-550C-B7B4-FF68A733A2D5.dita#GUID-EAA6A9FB-A470-550C-B7B4-FF68A733A2D5/GUID-7E632FD5-03B6-5D39-8A97-8F1948F2BB5B">Thread critical section</xref>  </p> </li>

<li id="GUID-A3BFB534-95F0-5B32-A996-955AE40C19E6"><p> <xref href="GUID-EAA6A9FB-A470-550C-B7B4-FF68A733A2D5.dita#GUID-EAA6A9FB-A470-550C-B7B4-FF68A733A2D5/GUID-7AECE882-9D48-5109-AE38-38BF0F8F717F">Atomic operations</xref>  </p> </li>

<li id="GUID-C4B47444-2A35-5E0C-92EF-C33DDD68D0E1"><p> <xref href="GUID-EAA6A9FB-A470-550C-B7B4-FF68A733A2D5.dita#GUID-EAA6A9FB-A470-550C-B7B4-FF68A733A2D5/GUID-A0FB7718-F39C-5FB3-B67C-430B490F6430">The system lock</xref>  </p> </li>

<li id="GUID-ECFF18B2-9279-5B68-9939-78C897F32FB8"><p> <xref href="GUID-EAA6A9FB-A470-550C-B7B4-FF68A733A2D5.dita#GUID-EAA6A9FB-A470-550C-B7B4-FF68A733A2D5/GUID-1806CDC5-9941-5CFC-B1F1-82BBA8D4F65B">The kernel lock</xref>  </p> </li>

<li id="GUID-AF3CD2DE-B4FD-5D1B-B9CC-FB2E32380D38"><p> <xref href="GUID-EAA6A9FB-A470-550C-B7B4-FF68A733A2D5.dita#GUID-EAA6A9FB-A470-550C-B7B4-FF68A733A2D5/GUID-961912E5-2D89-518A-A6EA-3AAC15D17B81">Disabling interrupts</xref>  </p> </li>

</ul>

<section id="GUID-86E98109-EC1A-58B7-8AB2-EFD100739261"><title>Mutexes</title> <p>A

mutex (mutual exclusion) is a mechanism to prevent more than one thread from

executing a section of code concurrently. The most common use is to synchronise

access to data shared between two or more threads. </p> <p>There are two types

of mutex: the fast mutex, and a more general heavyweight mutex - the Symbian

platform mutex. Which one you use depends on the needs of your code and the

context in which it runs. </p> <ul>

<li id="GUID-737BE53A-9A91-5CEA-9073-E47D3B3DB9E8"><p> <xref href="GUID-EAA6A9FB-A470-550C-B7B4-FF68A733A2D5.dita#GUID-EAA6A9FB-A470-550C-B7B4-FF68A733A2D5/GUID-09377BC3-770A-5558-B3A9-A7E2CE11EBC3">The fast mutex</xref>  </p> </li>

<li id="GUID-5952D847-0802-5B05-9CE8-6316DCA96245"><p> <xref href="GUID-EAA6A9FB-A470-550C-B7B4-FF68A733A2D5.dita#GUID-EAA6A9FB-A470-550C-B7B4-FF68A733A2D5/GUID-F5B59A23-48E0-5596-B589-10DD2549F124">The Symbian platform mutex</xref>  </p> </li>

</ul> <p id="GUID-09377BC3-770A-5558-B3A9-A7E2CE11EBC3"><b>The fast mutex</b> </p> <p>A

fast mutex is the fundamental way of allowing mutual exclusion between <i>nanokernel</i> threads.

Remember that a Symbian platform thread, and a thread in a personality layer

are also nanokernel threads. </p> <p>A fast mutex is represented by a <xref href="GUID-D5B555DA-3D17-3ED2-A931-CB35BD93A953.dita"><apiname>NFastMutex</apiname></xref> object.

It is designed to be as fast as possible, especially in the case where there

is no contention, and is also designed to occupy as little RAM as possible.

A fast mutex is intended to protect <i>short</i> critical sections of code </p> <ul>

<li id="GUID-646DB0EC-1627-5BDF-8068-D6717106DB17"><p> <xref href="GUID-EAA6A9FB-A470-550C-B7B4-FF68A733A2D5.dita#GUID-EAA6A9FB-A470-550C-B7B4-FF68A733A2D5/GUID-4EE0B5C4-0473-54CD-A585-F2905FA76968">Rules</xref> </p> </li>

<li id="GUID-3C470241-DD9E-52CF-B58D-C86A9301BEEE"><p> <xref href="GUID-EAA6A9FB-A470-550C-B7B4-FF68A733A2D5.dita#GUID-EAA6A9FB-A470-550C-B7B4-FF68A733A2D5/GUID-083C9D63-A69D-5E66-9274-178F329F8445">How to use</xref>  </p> </li>

<li id="GUID-D7C801A7-B0C1-5AF1-8594-CB994BDECF7B"><p> <xref href="GUID-EAA6A9FB-A470-550C-B7B4-FF68A733A2D5.dita#GUID-EAA6A9FB-A470-550C-B7B4-FF68A733A2D5/GUID-111E74A3-8442-5598-8BB9-F78E2A77610A">Example using NFastmutex to protect a critical region</xref>  </p> </li>

</ul> <p id="GUID-4EE0B5C4-0473-54CD-A585-F2905FA76968"><b>Rules</b> </p> <p>A

fast mutex is, be definition, fast and the price to be paid is that there

are a few rules that must be obeyed: </p> <ul>

<li id="GUID-25FC4814-1BBB-5C6D-90FB-12E75274C388"><p>a thread can only hold

one fast mutex at a time, i.e. a thread cannot wait on a fast mutex if it

already holds another fast mutex </p> </li>

<li id="GUID-693AB846-4629-5E3C-A14C-53A0879F1DB8"><p>a thread cannot wait

on the same fast mutex more than once </p> </li>

<li id="GUID-11EEC812-0BC7-5FFA-8D7B-DBD400CA5958"><p>a thread must not block

or exit while holding a fast mutex because the thread is in an implied <xref href="GUID-EAA6A9FB-A470-550C-B7B4-FF68A733A2D5.dita#GUID-EAA6A9FB-A470-550C-B7B4-FF68A733A2D5/GUID-7E632FD5-03B6-5D39-8A97-8F1948F2BB5B">critical

section</xref>. </p> </li>

</ul> <p>In the moving memory model, the user address space is not guaranteed

to be consistent while a kernel thread holds a fast mutex. </p> <p id="GUID-083C9D63-A69D-5E66-9274-178F329F8445"><b>How

to use</b> </p> <p>Typically you declare a fast mutex in a class declaration,

for example: </p> <codeblock id="GUID-D1839B94-A1AF-5693-841F-F58C583F5D7E" xml:space="preserve">class DImpSysTest : public DLogicalChannelBase

    {

    ...

public:

    ...

    NFastMutex iMutex;

    ...

    };

</codeblock> <p>When you want to get hold of the fast mutex, i.e. when you

are about to enter a section of code that no other thread is executing concurrently,

you wait on that fast mutex. If no other thread has the mutex, then your thread

gets the mutex, and control flows into your critical code. On exiting the

section of code, you signal the fast mutex, which relinquishes it. </p> <p>If,

on the other hand, another thread already has the fast mutex, then your thread

blocks, and only resumes when the other thread exits the code section by signalling

the fast mutex. </p> <p>Getting and relinquishing the mutex is done using

the <codeph>Wait()</codeph> and <codeph>Signal()</codeph> functions of the <xref href="GUID-D5B555DA-3D17-3ED2-A931-CB35BD93A953.dita"><apiname>NFastMutex</apiname></xref> class.

However, you will normally use the nanokernel functions: </p> <ul>

<li id="GUID-E2D93FB0-7E2B-5497-AAC1-DF1F2DA388E0"><p> <xref href="GUID-3A3C08F3-3D33-3D9E-80E7-7855C7B21E02.dita#GUID-3A3C08F3-3D33-3D9E-80E7-7855C7B21E02/GUID-133C9428-F0BE-399E-A986-5AE72460C720"><apiname>NKern::FMWait()</apiname></xref>  </p> </li>

<li id="GUID-4E620FA6-4146-5C90-8B67-20050A1A88D1"><p> <xref href="GUID-3A3C08F3-3D33-3D9E-80E7-7855C7B21E02.dita#GUID-3A3C08F3-3D33-3D9E-80E7-7855C7B21E02/GUID-FBD38D01-21A1-3E92-BA1D-719EBCC7AF1D"><apiname>NKern::FMSignal()</apiname></xref>  </p> </li>

</ul> <p>respectively, passing a pointer to your <xref href="GUID-D5B555DA-3D17-3ED2-A931-CB35BD93A953.dita"><apiname>NFastMutex</apiname></xref> object. </p> <p>The

kernel lock must be held when <xref href="GUID-D5B555DA-3D17-3ED2-A931-CB35BD93A953.dita#GUID-D5B555DA-3D17-3ED2-A931-CB35BD93A953/GUID-76E5AE32-9A70-344A-9E6B-5B439622715A"><apiname>NFastMutex::Wait()</apiname></xref> and <xref href="GUID-D5B555DA-3D17-3ED2-A931-CB35BD93A953.dita#GUID-D5B555DA-3D17-3ED2-A931-CB35BD93A953/GUID-CA8C65D8-E59A-385A-92B8-2B22A4A2F1CB"><apiname>NFastMutex::Signal()</apiname></xref> are

called. <xref href="GUID-3A3C08F3-3D33-3D9E-80E7-7855C7B21E02.dita#GUID-3A3C08F3-3D33-3D9E-80E7-7855C7B21E02/GUID-133C9428-F0BE-399E-A986-5AE72460C720"><apiname>NKern::FMWait()</apiname></xref> and <xref href="GUID-3A3C08F3-3D33-3D9E-80E7-7855C7B21E02.dita#GUID-3A3C08F3-3D33-3D9E-80E7-7855C7B21E02/GUID-FBD38D01-21A1-3E92-BA1D-719EBCC7AF1D"><apiname>NKern::FMSignal()</apiname></xref> do

this for you. They make sure that the kernel lock is on while <xref href="GUID-D5B555DA-3D17-3ED2-A931-CB35BD93A953.dita#GUID-D5B555DA-3D17-3ED2-A931-CB35BD93A953/GUID-76E5AE32-9A70-344A-9E6B-5B439622715A"><apiname>NFastMutex::Wait()</apiname></xref> and <xref href="GUID-D5B555DA-3D17-3ED2-A931-CB35BD93A953.dita#GUID-D5B555DA-3D17-3ED2-A931-CB35BD93A953/GUID-CA8C65D8-E59A-385A-92B8-2B22A4A2F1CB"><apiname>NFastMutex::Signal()</apiname></xref> are

called by wrapping them in a pair of <xref href="GUID-3A3C08F3-3D33-3D9E-80E7-7855C7B21E02.dita#GUID-3A3C08F3-3D33-3D9E-80E7-7855C7B21E02/GUID-7CBBF72B-4519-38DD-92CA-38AF636AFD8A"><apiname>NKern::Lock()</apiname></xref> and <xref href="GUID-3A3C08F3-3D33-3D9E-80E7-7855C7B21E02.dita#GUID-3A3C08F3-3D33-3D9E-80E7-7855C7B21E02/GUID-A1A42137-906C-30F1-AF61-4F786FC372DE"><apiname>NKern::Unlock()</apiname></xref> calls. </p> <p>Although

this sounds like you will be blocking while holding the kernel lock, in reality

you do not because the thread is not blocked until after the kernel lock is

released. </p> <p>Be aware however that there may be situations where you

already have the kernel lock, or in the case of IDFCs, you do not need to

acquire it as no preemption can occur. In these cases, you just call <xref href="GUID-D5B555DA-3D17-3ED2-A931-CB35BD93A953.dita#GUID-D5B555DA-3D17-3ED2-A931-CB35BD93A953/GUID-76E5AE32-9A70-344A-9E6B-5B439622715A"><apiname>NFastMutex::Wait()</apiname></xref> and <xref href="GUID-D5B555DA-3D17-3ED2-A931-CB35BD93A953.dita#GUID-D5B555DA-3D17-3ED2-A931-CB35BD93A953/GUID-CA8C65D8-E59A-385A-92B8-2B22A4A2F1CB"><apiname>NFastMutex::Signal()</apiname></xref>. </p> <p>The following diagram illustrates the general principle: </p> <fig id="GUID-30A0EA62-83CF-5AB9-A07E-525D0972E55B">

<title>Fast mutex</title>

<image href="GUID-3AFE0D8B-FB9B-5355-A63B-FB71DD13E7D0_d0e73917_href.png" placement="inline"/>

</fig> <p>There are a number of assumptions here, one of which is that the

priorities are such that thread T1 does not run until a reschedule occurs,

after T2 has been interrupted. </p> <p id="GUID-111E74A3-8442-5598-8BB9-F78E2A77610A"><b>Example

using NFastmutex to protect a critical region</b> </p> <p>The file <filepath>...\f32test\nkern\d_implicit.cpp</filepath> is

a device driver that contains 3 threads and 3 separate sub-tests. The third

test, identified as <codeph>ETestDummy</codeph>, shows how to protect a critical

region using a nanokernel fast mutex. </p> <p>The mutex itself is declared

in the channel class: </p> <codeblock id="GUID-7EFD970B-9500-5F68-8BAD-21718F3953BC" xml:space="preserve">class DImpSysTest : public DLogicalChannelBase

    {

    ...

public:

    ...

    NFastMutex iMutex;

    ...

    };

</codeblock> <p>The function <codeph>Start()</codeph> takes an argument that

sets the test number. This function initialises some test variables, creates

three threads, and also initialises the mutex: </p> <codeblock id="GUID-A131C888-FAE0-53D3-BF12-E06D54E6A093" xml:space="preserve">TInt DImpSysTest::Start(TInt aTest)

    {

    ...

    new (&iMutex) NFastMutex;

    ...    

    }

</codeblock> <p>The overloaded <codeph>new</codeph> operator is called with

the existing mutex as its argument, with the side effect of calling the constructor

to initialise the mutex. There is also a corresponding <codeph>Stop()</codeph> function

to kill the threads and return the results to the caller. </p> <p>Look at

the test case for <codeph>iTestNum == ETestDummy</codeph>, where thread 1

and thread 3 use the mutex as if sharing a critical resource. </p> <codeblock id="GUID-A97F5CF0-F7D8-5A08-9033-908AEF2AE576" xml:space="preserve">void DImpSysTest::Thread1(TAny* aPtr)

    {

    DImpSysTest& d=*(DImpSysTest*)aPtr;

    ...    

    FOREVER

        {

        NKern::FMWait(&d.iMutex);

        // this is a critical region protected by d.iMutex

        NKern::FMSignal(&d.iMutex);

        ...

        }

    }</codeblock> <codeblock id="GUID-8D0EA108-B735-5189-99EE-0FE895B3A933" xml:space="preserve">void DImpSysTest::Thread3(TAny* aPtr)

    {

    DImpSysTest& d=*(DImpSysTest*)aPtr;

    ...

    if (d.iTestNum==RImpSysTest::ETestPriority)

        {

        ...

        }

    else if (d.iTestNum==RImpSysTest::ETestDummy)

        {

        FOREVER

            {

            ...

            if (x<85)

                {

                ...

                }

            else

                {

                NKern::FMWait(&d.iMutex);

                // this is a critical region protected by d.iMutex

                NKern::FMSignal(&d.iMutex);

                }

            }

        }

    }

</codeblock> <p>Each thread takes a pointer to the channel object as an argument,

this is the <codeph>aPtr</codeph> value passed to both <codeph>Thread1()</codeph> and <codeph>Thread3()</codeph> and

each thread dereferences it to find the mutex. The important point is that

there is only one mutex object, which is accessed by all interested threads. </p> <p>Before

entering the critical region, the threads call <xref href="GUID-3A3C08F3-3D33-3D9E-80E7-7855C7B21E02.dita#GUID-3A3C08F3-3D33-3D9E-80E7-7855C7B21E02/GUID-133C9428-F0BE-399E-A986-5AE72460C720"><apiname>NKern::FMWait()</apiname></xref> to

gain ownership of the mutex. Before leaving the critical region, they call <xref href="GUID-3A3C08F3-3D33-3D9E-80E7-7855C7B21E02.dita#GUID-3A3C08F3-3D33-3D9E-80E7-7855C7B21E02/GUID-FBD38D01-21A1-3E92-BA1D-719EBCC7AF1D"><apiname>NKern::FMSignal()</apiname></xref> to

relinquish ownership. </p> <p id="GUID-F5B59A23-48E0-5596-B589-10DD2549F124"><b>The

Symbian platform mutex</b> </p> <p>The Symbian platform mutex provides mutual

exclusion between Symbian platform threads without the restrictions imposed

by the fast mutex. </p> <p>The Symbian platform mutex is represented by a <codeph>DMutex</codeph> object. </p> <ul>

<li id="GUID-AAE481BE-1ABB-5E0E-AB89-1D53393B0C5B"><p> <xref href="GUID-EAA6A9FB-A470-550C-B7B4-FF68A733A2D5.dita#GUID-EAA6A9FB-A470-550C-B7B4-FF68A733A2D5/GUID-94F9C4EF-24D5-514A-BD21-B10B1A83CE28">Characteristics</xref> </p> </li>

<li id="GUID-BDA5D5F8-B508-5D9D-97DC-65AE2166817F"><p> <xref href="GUID-EAA6A9FB-A470-550C-B7B4-FF68A733A2D5.dita#GUID-EAA6A9FB-A470-550C-B7B4-FF68A733A2D5/GUID-61387415-4A5B-5C98-A028-F62DA7114790">How to use</xref>  </p> </li>

<li id="GUID-7DF42A70-D80B-5883-B96D-3452A11CD137"><p> <xref href="GUID-EAA6A9FB-A470-550C-B7B4-FF68A733A2D5.dita#GUID-EAA6A9FB-A470-550C-B7B4-FF68A733A2D5/GUID-EF2F2EBB-CDC2-5367-957A-2A004453F6C7">Example using DMutex to protect critical regions</xref>  </p> </li>

</ul> <p id="GUID-94F9C4EF-24D5-514A-BD21-B10B1A83CE28"><b>Characteristics</b> </p> <p>Operations

on a <codeph>DMutex</codeph> are more complicated, and therefore slower, than

those on a <xref href="GUID-D5B555DA-3D17-3ED2-A931-CB35BD93A953.dita"><apiname>NFastMutex</apiname></xref>. However, a <codeph>DMutex</codeph> gives

you the following: </p> <ul>

<li id="GUID-62A9B213-D77A-5151-B50A-8DA2EBA88433"><p>it is possible to wait

on a Symbian platform mutex multiple times, provided it is signalled the exact

same number of times </p> </li>

<li id="GUID-EEB436F1-3F54-50BC-9009-E1EAB055199A"><p>It is possible to hold

several Symbian platform mutexes simultaneously, although care is needed to

avoid deadlock situations </p> </li>

<li id="GUID-324BD7DC-7CDB-57DD-879B-E88CEA7CD194"><p>A thread can block while

holding a Symbian platform mutex </p> </li>

<li id="GUID-EA7C07F8-58D3-59C9-9C2A-6D82D4F6FC3B"><p>A Symbian platform mutex

provides priority inheritance, although there is a limit on the number of

threads that can wait on any <codeph>DMutex</codeph> (currently this is 10). </p> </li>

</ul> <p>When a Symbian platform mutex is created it is given an 'order' value.

This is a deadlock prevention mechanism, although it is used only in debug

builds. When waiting on a mutex the system checks that the order value is

less than the order value of any mutex that the thread is already waiting

on. </p> <p>In general, most code written for device drivers should use values

which are greater than any used by the kernel itself. There are 8 constants

defined in <filepath>kernel.h</filepath> that are available for this purpose: <xref href="GUID-815054D8-4894-3DAB-9272-C8AAF3A11FD1.dita"><apiname>KMutexOrdGeneral0</apiname></xref> through <xref href="GUID-52E535B0-67FC-3353-89F7-BC2AF3947635.dita"><apiname>KMutexOrdGeneral7</apiname></xref>. </p> <p>The kernel faults with “Mutex Ordering Violation” if you try to

wait on a mutex that violates the ordering rules. </p> <p>Note: the only time

when these values would not be suitable is when the kernel calls back into

non-kernel code while a mutex is already held by the kernel. This occurs in

only two cases: </p> <ul>

<li id="GUID-BE5D7153-03EC-5E07-9E50-6A164ED7976F"><p>The debug event handler

callback </p> </li>

<li id="GUID-C13DA224-565F-582C-8255-872D87D31CC2"><p>The various timer classes

like <xref href="GUID-342B7499-4702-3C0F-B42A-66A5CA515F85.dita"><apiname>TTimer</apiname></xref>. This should not be an issue because device

drivers should use the <xref href="GUID-D8CF05A3-5C9B-3662-92DA-3290C6EE7FD2.dita"><apiname>NTimer</apiname></xref> class which does not callback

while <codeph>DMutexes</codeph> are held. </p> </li>

</ul> <p id="GUID-61387415-4A5B-5C98-A028-F62DA7114790"><b>How to use</b> </p> <p>Typically

you declare the mutex in a class declaration, for example: </p> <codeblock id="GUID-1704CB00-7A0E-54AB-8197-23264A487621" xml:space="preserve">class DCrashHandler : public DKernelEventHandler

    {

    ...

private:

    DMutex* iHandlerMutex;

    ...

    };

</codeblock> <p>You do not create a <codeph>DMutex</codeph> object directly;

instead you use the kernel function <xref href="GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D.dita#GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D/GUID-FEBBDA4F-412E-3AE5-9098-8E2F6BF3E969"><apiname>Kern::MutexCreate()</apiname></xref>.

You pass a <codeph>DMutex*</codeph> type to the kernel function, which creates

the <codeph>DMutex</codeph> object and returns a reference to it through the <codeph>DMutex</codeph> pointer. </p> <p>Getting

and relinquishing the mutex is done using the kernel functions: </p> <ul>

<li id="GUID-703EEF8E-D70F-57F6-8ED8-56CCC7EA00DB"><p> <xref href="GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D.dita#GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D/GUID-1F0C28A8-9E9A-3AA3-A441-BA8406B3A06A"><apiname>Kern::MutexWait()</apiname></xref>  </p> </li>

<li id="GUID-A80C8CA6-8E2C-5174-BC2A-EB3B1F18C49A"><p> <xref href="GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D.dita#GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D/GUID-B8080F86-1342-31EA-9A28-205354CA0CB9"><apiname>Kern::MutexSignal()</apiname></xref>  </p> </li>

</ul> <p>respectively, passing a reference to the <codeph>DMutex</codeph> object

created earlier. Note that although you pass a <codeph>DMutex</codeph> object

around, the member functions and member data of the class are considered as

internal to Symbian platform. However, you can call <codeph>Open()</codeph> and <codeph>Close()</codeph> on <codeph>DMutex</codeph> as

they are members of the base class <xref href="GUID-E48F1435-14B6-37F1-BE47-2EA803AFE497.dita"><apiname>DObject</apiname></xref>. </p> <p id="GUID-EF2F2EBB-CDC2-5367-957A-2A004453F6C7"><b>Example

using DMutex to protect critical regions</b> </p> <p>This example code fragment

uses two <codeph>DMutex</codeph> objects to protect a critical region of code

in a device driver. It implements a minimal debug agent in a device driver.

When a channel is opened to the device driver, the <codeph>DoCreate()</codeph> function

creates a crash handler (in 2 phases). The <codeph>DCrashHandler</codeph> class

contains two <codeph>DMutex</codeph> objects: </p> <codeblock id="GUID-C8EE7472-E897-53EC-BAC5-C8C6299ED512" xml:space="preserve">class DCrashHandler : public DKernelEventHandler

    {

    ...

private:

    DMutex* iHandlerMutex;    // serialise access to crash handler

    ...

    DMutex* iDataMutex;    // serialise access to following members

    ...

    };</codeblock> <p>The two <codeph>DMutex</codeph> objects are created

in the second phase of the crash handler creation, i.e. when the member function <codeph>DCrashHandler::Create()</codeph> is

called. Here's the code: </p> <codeblock id="GUID-A23289A3-3E5D-595A-A039-E4BE73A133D8" xml:space="preserve">TInt DCrashHandler::Create(DLogicalDevice* aDevice)

    {

    TInt r;

    ...

    r = Kern::MutexCreate(iHandlerMutex, KHandlerMutexName, KMutexOrdDebug);

    ...

    r = Kern::MutexCreate(iDataMutex, KDataMutexName, KMutexOrdDebug-1);

    ...

    }</codeblock> <p>The names of the mutexes are passed as the literal descriptors: <codeph>KHandlerMutexName</codeph> and <codeph>KDataMutexName</codeph>, and have the values <i>CtHandlerMutex</i> and <i>CtDataMutex</i> respectively. </p> <p>Notice

that the data mutex has an order value less than the handler mutex. This guards

against deadlock - we are asking the kernel to check that any thread waits

on the handler mutex before it waits on the data mutex. </p> <p>When a thread

panics, or an exception occurs, program control eventually reaches <codeph>DCrashHandler::HandleCrash()</codeph>.

The device driver is derived from <xref href="GUID-E7550422-5121-3393-A85E-BB797969CD2A.dita"><apiname>DLogicalChannelBase</apiname></xref>,

and the current thread is the one that crashed and this is a Symbian platform

thread, which means that it can wait on a <codeph>DMutex</codeph>. In fact,

it waits on two mutexes, and does so in the order mentioned above. The mutexes

are signalled further on in the same function. </p> <codeblock id="GUID-2F3C91C3-3323-5025-B7C3-2490595463FB" xml:space="preserve">void DCrashHandler::HandleCrash(TAny* aContext)

    {

    ...

    // Ensure that, at any time, at most one thread executes the

    // following code.  This simplifies user-side API.

    Kern::MutexWait(*iHandlerMutex);

    ...

    Kern::MutexWait(*iDataMutex);

    ...

    // access crash handler data <-------------------------------------

    ...

    Kern::MutexSignal(*iDataMutex);

    ...

    Kern::MutexSignal(*iHandlerMutex);

    }</codeblock> <p> <codeph> iHandlerMutex</codeph> ensures that only one

thread at a time uses the above code. <codeph>iDataMutex</codeph> protects

a smaller critical region where the crash handler’s data is accessed. This

data is also protected by <codeph>iDataMutex</codeph> in the <codeph>DCrashHandler::Trap()</codeph> function. </p> <codeblock id="GUID-D202D9A0-FB4B-5BD2-BE7A-5B843AC83A97" xml:space="preserve">void DCrashHandler::Trap(TRequestStatus* aRs, TAny* aCrashInfo)

    {

    ...

    Kern::MutexWait(*iDataMutex);

    ...

    // access crash handler data <-------------------------------------

    ...

    Kern::MutexSignal(*iDataMutex);

    ...

    } 

</codeblock> <p>A <codeph>DMutex</codeph> is a reference counting object,

and is derived from <xref href="GUID-E48F1435-14B6-37F1-BE47-2EA803AFE497.dita"><apiname>DObject</apiname></xref>. This means that once you have

finished with it, you must call <codeph>Close()</codeph> on it to reduce the

number of open references. </p> <p>In this example, both <codeph>DMutex</codeph> objects

are closed in the <codeph>DCrashHandler</codeph> destructor: </p> <codeblock id="GUID-9FAC3B34-D484-53FA-87D9-9AF5EC5C21D2" xml:space="preserve">DCrashHandler::~DCrashHandler()

    {

    ...

    if (iDataMutex)

        {

        iDataMutex->Close(NULL);

        }

    if (iHandlerMutex)

        {

        iHandlerMutex->Close(NULL);

        }

    ...

    }</codeblock> </section>

<section id="GUID-00E1F006-3D2C-52A3-BFCB-4D6A59321B26"><title>Semaphores</title> <p>A

semaphore is synchronisation primitive that you can use: </p> <ul>

<li id="GUID-FDB08035-E850-54D3-8D4B-3F589AAC66EC"><p>to signal one thread

from another thread </p> </li>

<li id="GUID-A9E08C05-C149-5E6A-8062-D26A00BAFBA4"><p>to signal a thread from

an Interrupt Service Routine using an IDFC. </p> </li>

</ul> <p>In EKA2, there are two types of semaphore: the fast semaphore, and

a more general semaphore - the Symbian platform semaphore. Which one you use

depends on the needs of your code and the context in which it is runs. </p> <ul>

<li id="GUID-381F815A-4B74-519E-AC95-2DF5983DAED2"><p> <xref href="GUID-EAA6A9FB-A470-550C-B7B4-FF68A733A2D5.dita#GUID-EAA6A9FB-A470-550C-B7B4-FF68A733A2D5/GUID-371EE12E-56D6-5520-8FB9-B9B2CE8AB0E1">The fast semaphore</xref>  </p> </li>

<li id="GUID-EF9B5D15-914F-5E6B-B47E-BE93612DC322"><p> <xref href="GUID-EAA6A9FB-A470-550C-B7B4-FF68A733A2D5.dita#GUID-EAA6A9FB-A470-550C-B7B4-FF68A733A2D5/GUID-6132B7FF-C664-5E21-8BF5-1BC9BAF00061">The Symbian platform semaphore</xref>  </p> </li>

</ul> <p id="GUID-371EE12E-56D6-5520-8FB9-B9B2CE8AB0E1"><b>The fast semaphore</b> </p> <p>A

fast semaphore is a fast lightweight mechanism that a thread can use to wait

for events. It provides a way of posting events to a single thread because

the semaphore can keep count of the number of events posted. </p> <p>A fast

semaphore is represented by a <xref href="GUID-22982E51-E746-37CB-9672-97B58C2672BF.dita"><apiname>NFastSemaphore</apiname></xref> object, and

this is implemented by the <i>nanokernel</i>. Remember that a Symbian platform

thread, and a thread in a personality layer are also nanokernel threads. </p> <ul>

<li id="GUID-F5F04369-2F0B-5FEA-B49A-E90C7C1CAF2D"><p> <xref href="GUID-EAA6A9FB-A470-550C-B7B4-FF68A733A2D5.dita#GUID-EAA6A9FB-A470-550C-B7B4-FF68A733A2D5/GUID-DF231F3F-A702-50DC-9E98-199808D228FD">Rules</xref> </p> </li>

<li id="GUID-4AF23A2C-FD0C-557F-93A9-BCDF9D8EC162"><p> <xref href="GUID-EAA6A9FB-A470-550C-B7B4-FF68A733A2D5.dita#GUID-EAA6A9FB-A470-550C-B7B4-FF68A733A2D5/GUID-E75C6B54-64D2-5936-BF38-9AF40F9F7400">How to use</xref>  </p> </li>

<li id="GUID-73BE532A-3A55-5995-8615-BE50C615C3BF"><p> <xref href="GUID-EAA6A9FB-A470-550C-B7B4-FF68A733A2D5.dita#GUID-EAA6A9FB-A470-550C-B7B4-FF68A733A2D5/GUID-1F74B3EC-A2E3-5B1E-9C8E-FFF15084C6DF">Example using NFastSemaphore and the NKern functions</xref>  </p> </li>

<li id="GUID-45269DDA-FE9C-5075-BEAB-8030A5DC2DC0"><p> <xref href="GUID-EAA6A9FB-A470-550C-B7B4-FF68A733A2D5.dita#GUID-EAA6A9FB-A470-550C-B7B4-FF68A733A2D5/GUID-2C0E4009-3E15-5197-B327-06699BFE2221">Example using the NFastSemaphore::Signal() function</xref>  </p> </li>

</ul> <p id="GUID-DF231F3F-A702-50DC-9E98-199808D228FD"><b>Rules</b> </p> <p>Because

of its lightweight structure, only the <i>owning thread</i> is allowed to

wait on it. </p> <p id="GUID-E75C6B54-64D2-5936-BF38-9AF40F9F7400"><b>How

to use</b> </p> <p>Typically you declare a fast semaphore in a class declaration,

for example: </p> <codeblock id="GUID-7C06D593-07EC-5A00-950A-FA71A0611753" xml:space="preserve">class DCrashHandler : public DKernelEventHandler

    {

    ...

private:

    NFastSemaphore iSem;

    ...

    };

</codeblock> <p>You need to initialise the <xref href="GUID-22982E51-E746-37CB-9672-97B58C2672BF.dita"><apiname>NFastSemaphore</apiname></xref> by: </p> <ul>

<li id="GUID-76AA23BF-787E-5F02-9293-651D6A2ABCD4"><p>constructing the semaphore </p> </li>

<li id="GUID-9DCCF8D9-8196-540F-A843-3E8771CFBBDC"><p>setting the thread that

owns the semaphore, i.e. the thread that will be allowed to wait in it. </p> </li>

</ul> <p>The semaphore is initialised when its constructor is called. However,

setting the owning thread requires explicit code. For example, the following

code fragment is typical and sets the owning thread to be the current thread: </p> <codeblock id="GUID-CF5E165F-3512-57C1-9CC3-8EE3077904CA" xml:space="preserve">iSem.iOwningThread = (NThreadBase*)NKern::CurrentThread();</codeblock> <p>Waiting

and signalling the fast semaphore is done by using the <codeph>Wait()</codeph> and <codeph>Signal()</codeph> functions

of the <xref href="GUID-22982E51-E746-37CB-9672-97B58C2672BF.dita"><apiname>NFastSemaphore</apiname></xref> class. However, you will normally

use the nanokernel functions: </p> <ul>

<li id="GUID-238D3B34-3E98-5388-8B33-F0FB47679CDD"><p> <xref href="GUID-3A3C08F3-3D33-3D9E-80E7-7855C7B21E02.dita#GUID-3A3C08F3-3D33-3D9E-80E7-7855C7B21E02/GUID-D2691899-C802-3A4F-9E72-487B07E6E1D0"><apiname>NKern::FSWait()</apiname></xref>  </p> </li>

<li id="GUID-94485609-3EAC-5986-ACE6-8485942D2273"><p> <xref href="GUID-3A3C08F3-3D33-3D9E-80E7-7855C7B21E02.dita#GUID-3A3C08F3-3D33-3D9E-80E7-7855C7B21E02/GUID-B4B058FF-F077-3F0A-A344-F6FB36D987C6"><apiname>NKern::FSSignal()</apiname></xref>  </p> </li>

</ul> <p>respectively, passing a pointer to your <xref href="GUID-22982E51-E746-37CB-9672-97B58C2672BF.dita"><apiname>NFastSemaphore</apiname></xref> object. </p> <p>The

kernel lock must be held when <xref href="GUID-22982E51-E746-37CB-9672-97B58C2672BF.dita#GUID-22982E51-E746-37CB-9672-97B58C2672BF/GUID-F6262C01-5999-36D1-AF7D-F7E3741ED411"><apiname>NFastSemaphore::Wait()</apiname></xref> and <xref href="GUID-22982E51-E746-37CB-9672-97B58C2672BF.dita#GUID-22982E51-E746-37CB-9672-97B58C2672BF/GUID-B1104DF4-7490-33D9-BB64-83E16D9BA723"><apiname>NFastSemaphore::Signal()</apiname></xref> are

called. <xref href="GUID-3A3C08F3-3D33-3D9E-80E7-7855C7B21E02.dita#GUID-3A3C08F3-3D33-3D9E-80E7-7855C7B21E02/GUID-D2691899-C802-3A4F-9E72-487B07E6E1D0"><apiname>NKern::FSWait()</apiname></xref> and <xref href="GUID-3A3C08F3-3D33-3D9E-80E7-7855C7B21E02.dita#GUID-3A3C08F3-3D33-3D9E-80E7-7855C7B21E02/GUID-B4B058FF-F077-3F0A-A344-F6FB36D987C6"><apiname>NKern::FSSignal()</apiname></xref> do

this for you. They make sure that the kernel lock is on while <xref href="GUID-22982E51-E746-37CB-9672-97B58C2672BF.dita#GUID-22982E51-E746-37CB-9672-97B58C2672BF/GUID-F6262C01-5999-36D1-AF7D-F7E3741ED411"><apiname>NFastSemaphore::Wait()</apiname></xref> and <xref href="GUID-22982E51-E746-37CB-9672-97B58C2672BF.dita#GUID-22982E51-E746-37CB-9672-97B58C2672BF/GUID-B1104DF4-7490-33D9-BB64-83E16D9BA723"><apiname>NFastSemaphore::Signal()</apiname></xref> are called by wrapping them in a pair of <xref href="GUID-3A3C08F3-3D33-3D9E-80E7-7855C7B21E02.dita#GUID-3A3C08F3-3D33-3D9E-80E7-7855C7B21E02/GUID-7CBBF72B-4519-38DD-92CA-38AF636AFD8A"><apiname>NKern::Lock()</apiname></xref> and <xref href="GUID-3A3C08F3-3D33-3D9E-80E7-7855C7B21E02.dita#GUID-3A3C08F3-3D33-3D9E-80E7-7855C7B21E02/GUID-A1A42137-906C-30F1-AF61-4F786FC372DE"><apiname>NKern::Unlock()</apiname></xref> calls. </p> <p>Although

this sounds like you will be blocking while holding the kernel lock, in reality

you do not because the thread is not blocked until after the kernel lock is

released. </p> <p>Be aware however that there may be situations where you

already have the kernel lock, or in the case of IDFCs, you do not need to

acquire it as no preemption can occur. In these cases, you just call <xref href="GUID-22982E51-E746-37CB-9672-97B58C2672BF.dita#GUID-22982E51-E746-37CB-9672-97B58C2672BF/GUID-F6262C01-5999-36D1-AF7D-F7E3741ED411"><apiname>NFastSemaphore::Wait()</apiname></xref> and <xref href="GUID-22982E51-E746-37CB-9672-97B58C2672BF.dita#GUID-22982E51-E746-37CB-9672-97B58C2672BF/GUID-B1104DF4-7490-33D9-BB64-83E16D9BA723"><apiname>NFastSemaphore::Signal()</apiname></xref>. </p> <p>You can use use a fast semaphore to block a thread until an interrupt

occurs, but you cannot signal the semaphore directly from the interrupt service

routine (ISR) that services that interrupt; instead, you must queue an IDFC,

and signal from there. </p> <p id="GUID-1F74B3EC-A2E3-5B1E-9C8E-FFF15084C6DF"><b>Example

using NFastSemaphore and the NKern functions</b> </p> <p>This is an example

that synchronises threads using the <xref href="GUID-22982E51-E746-37CB-9672-97B58C2672BF.dita"><apiname>NFastSemaphore</apiname></xref> class,

and is part of code that implements a minimal debug agent in a device driver.

The full code for this can be found in <filepath>...\e32utils\d_exc\minkda.cpp</filepath>. </p> <p>When

a channel is opened, the <codeph>DoCreate()</codeph> function creates a crash

handler (in 2 phases).This is a <codeph>DCrashHandler</codeph> object, and

importantly, contains a <xref href="GUID-22982E51-E746-37CB-9672-97B58C2672BF.dita"><apiname>NFastSemaphore</apiname></xref>. </p> <codeblock id="GUID-C092DA58-C4AF-528C-B648-481A3B6EC5A6" xml:space="preserve">class DCrashHandler : public DKernelEventHandler

    {

    ...

private:

    NFastSemaphore iSuspendSem; // for suspending crashed thread

    ...

    };</codeblock> <p>When a thread panics, or an exception occurs, program

control eventually reaches <codeph>DCrashHandler::HandleCrash()</codeph>.

It is in this function that the owning thread is set – to the current nanokernel

thread (i.e. the one that crashed). This is the only thread allowed to wait

on the semaphore. The wait is just a few lines further down in the same function: </p> <codeblock id="GUID-B3543353-C441-542E-B0AA-737F5DFA1ADA" xml:space="preserve">void DCrashHandler::HandleCrash(TAny* aContext)

    {

    DThread* pC = &Kern::CurrentThread();

    ...

    if (iTrapRq != NULL)

        {

        iCrashedThread = pC;

        iSuspendSem.iOwningThread = &(iCrashedThread->iNThread);

        ...

        }

    ...

    if (iCrashedThread)

        {

        ...

        NKern::FSWait(&(iSuspendSem)); // Waits on the semaphore

        ...

        }

    ...

    }</codeblock> <p>At a later time, the debugger calls the driver’s <codeph>Request()</codeph> function

with either the <codeph>ECancelTrap</codeph> or <codeph>EKillCrashedThread</codeph> parameters.

One or other of the corresponding functions is called; each function is implemented

to signal the semaphore. </p> <codeblock id="GUID-E1D04D58-4614-58B1-B5A4-CA898B58B0E6" xml:space="preserve">void DCrashHandler::CancelTrap()

    {

    ...

    if (iCrashedThread != NULL)

        {

        NKern::FSSignal(&(iSuspendSem));

        }

    ...

    }</codeblock> <codeblock id="GUID-FB4B9BE1-272B-5F62-8C88-13FAF89BAE88" xml:space="preserve">void DCrashHandler::KillCrashedThread()

    {

    ...

    NKern::FSSignal(&iSuspendSem);

    }</codeblock> <p id="GUID-2C0E4009-3E15-5197-B327-06699BFE2221"><b>Example

using the NFastSemaphore::Signal() function</b> </p> <p>This is an example

code fragment taken from <filepath>...\e32test\misc\d_rndtim.cpp</filepath>. </p> <p>This

a device driver that uses a timer. The driver's logical channel can start

the timer, and it can wait for the timer to expire. The expiry of the timer

results in an interrupt; this results in a call to an ISR that schedules an

IDFC, which, in turn, signals the driver's logical channel. </p> <p>Because

the kernel is implicitly locked when the IDFC runs, there is no need to explicitly

lock the kernel, and <xref href="GUID-22982E51-E746-37CB-9672-97B58C2672BF.dita#GUID-22982E51-E746-37CB-9672-97B58C2672BF/GUID-B1104DF4-7490-33D9-BB64-83E16D9BA723"><apiname>NFastSemaphore::Signal()</apiname></xref> can be called

instead of <xref href="GUID-3A3C08F3-3D33-3D9E-80E7-7855C7B21E02.dita#GUID-3A3C08F3-3D33-3D9E-80E7-7855C7B21E02/GUID-B4B058FF-F077-3F0A-A344-F6FB36D987C6"><apiname>NKern::FSSignal()</apiname></xref>. </p> <p>The relevant part

of the driver's logical channel class is: </p> <codeblock id="GUID-30E361DA-817C-5792-8E61-6CEB37F28FB3" xml:space="preserve">class DRndTim : public DLogicalChannelBase

    {

    ...

public:

    NFastSemaphore iSem;

    ...

    };</codeblock> <p>The semaphore's owning thread is set in the logical

channel's constructor. Note that the constructor is called in the context

of the client thread, and it is this thread that is the owner of the semaphore.

This must also be the thread that waits for the semaphore, which it does when

at some later time it sends an <codeph>EControlWait</codeph> request to the

device driver to wait for the timer to expire. </p> <codeblock id="GUID-D32ABAEB-32C2-5D68-B76E-7C45D5828EED" xml:space="preserve">DRndTim::DRndTim()

    {

    iThread=&Kern::CurrentThread();

    iThread->Open();

    iSem.iOwningThread = &iThread->iNThread;

    ...

    }</codeblock> <p>The following code shows the implementation of this wait.

Note that it assumes that the timer has already been started, which we have

not shown here. </p> <p>The wait is initiated using the <xref href="GUID-3A3C08F3-3D33-3D9E-80E7-7855C7B21E02.dita#GUID-3A3C08F3-3D33-3D9E-80E7-7855C7B21E02/GUID-D2691899-C802-3A4F-9E72-487B07E6E1D0"><apiname>NKern::FSWait()</apiname></xref> function

as the kernel must be locked when the wait operation is done on the <xref href="GUID-22982E51-E746-37CB-9672-97B58C2672BF.dita"><apiname>NFastSemaphore</apiname></xref>. </p> <codeblock id="GUID-52D3817F-3214-5166-A998-35C468CC9BBE" xml:space="preserve">TInt DRndTim::Request(TInt aFunction, TAny* a1, TAny* a2)

    {

    TInt r = KErrNotSupported;

    switch (aFunction)

        {

    case RRndTim::EControlWait:

        NKern::FSWait(&iSem);

        r = KErrNone;

        break;

        ...

        }

    ...

    }</codeblock> <p>When the timer expires, the ISR runs, and this schedules

the IDFC, which in turn signals the client thread. The following code is the

IDFC implementation. </p> <codeblock id="GUID-907D7F1C-BEE5-5651-9F2A-F7E3421E4BA0" xml:space="preserve">void DRndTim::IDfcFn(TAny* aPtr)

    {

    DRndTim* d = (DRndTim*)aPtr;

    d->iSem.Signal();

    }</codeblock> <p>Note that this calls <xref href="GUID-22982E51-E746-37CB-9672-97B58C2672BF.dita#GUID-22982E51-E746-37CB-9672-97B58C2672BF/GUID-B1104DF4-7490-33D9-BB64-83E16D9BA723"><apiname>NFastSemaphore::Signal()</apiname></xref> rather

that <xref href="GUID-3A3C08F3-3D33-3D9E-80E7-7855C7B21E02.dita#GUID-3A3C08F3-3D33-3D9E-80E7-7855C7B21E02/GUID-B4B058FF-F077-3F0A-A344-F6FB36D987C6"><apiname>NKern::FSSignal()</apiname></xref> because IDFCs are called with the

kernel locked. </p> <p id="GUID-6132B7FF-C664-5E21-8BF5-1BC9BAF00061"><b>The

Symbian platform semaphore</b> </p> <p>Symbian platform semaphores are standard

counting semaphores that can be used by one or more Symbian platform threads.

The most common use of semaphores is to synchronise processing between threads,

i.e. to force a thread to wait until some processing is complete in one or

more other threads or until one or more events have occurred. </p> <p>The

Symbian platform semaphore is represented by a <xref href="GUID-48D9A672-11AA-3F21-8AB6-AB01032C52A5.dita"><apiname>DSemaphore</apiname></xref> object. </p> <ul>

<li id="GUID-FE9B937B-9B60-5C92-A1CA-6FDE7E1623EE"><p> <xref href="GUID-EAA6A9FB-A470-550C-B7B4-FF68A733A2D5.dita#GUID-EAA6A9FB-A470-550C-B7B4-FF68A733A2D5/GUID-A396E34A-2B84-5EFC-8FE8-6DBE68A21A80">Characteristics</xref> </p> </li>

<li id="GUID-3880A591-1512-518E-8607-E5737C7B84A5"><p> <xref href="GUID-EAA6A9FB-A470-550C-B7B4-FF68A733A2D5.dita#GUID-EAA6A9FB-A470-550C-B7B4-FF68A733A2D5/GUID-6131CDB0-6249-5B9A-A969-9B25F8BCECF5">Rules</xref> </p> </li>

<li id="GUID-B97B8B09-CD5B-57E2-9E7F-AD1DD90847AA"><p> <xref href="GUID-EAA6A9FB-A470-550C-B7B4-FF68A733A2D5.dita#GUID-EAA6A9FB-A470-550C-B7B4-FF68A733A2D5/GUID-915A061E-C85E-5165-A12F-B3B214756AE0">How to use</xref>  </p> </li>

</ul> <p id="GUID-A396E34A-2B84-5EFC-8FE8-6DBE68A21A80"><b>Characteristics</b> </p> <p>A

Symbian platform semaphore is based on the value of a count, which the <codeph>DSemaphore</codeph> object

maintains. The value of the count indicates whether there are any threads

waiting on it. The general behaviour is: </p> <ul>

<li id="GUID-D71A8532-4D3B-5748-81C5-8E40C91FB4D3"><p>if the count is positive

or zero, then there are no threads waiting </p> </li>

<li id="GUID-8C86A1DF-14D4-55DD-8511-FA51C4706FBF"><p>if the count is negative,

the magnitude of the value is the number of threads that are waiting on it. </p> </li>

</ul> <p>There are two basic operations on semaphores: </p> <ul>

<li id="GUID-4193B915-82FB-5648-AD41-C1D5E345A8F1"><p>WAIT - this decrements

the count atomically. If the count remains non-negative the calling thread

continues to run; if the count becomes negative the calling thread is blocked. </p> </li>

<li id="GUID-F39A0E98-8662-5B7B-B266-027885DB3F6A"><p>SIGNAL - this increments

the count atomically. If the count was originally negative the next highest

priority waiting thread is released. </p> </li>

</ul> <p>Waiting threads are released in descending order of priority. Note

however that threads that are explicitly suspended as well as waiting on a

semaphore, are not kept on the semaphore wait queue; instead they are kept

on a separate suspended queue. Such threads are not regarded as waiting for

the semaphore; this means that if the semaphore is signalled, they will not

be released, and the semaphore count will just increase and may become positive. </p> <p>Symbian

platform semaphore operations are protected by the <xref href="GUID-EAA6A9FB-A470-550C-B7B4-FF68A733A2D5.dita#GUID-EAA6A9FB-A470-550C-B7B4-FF68A733A2D5/GUID-A0FB7718-F39C-5FB3-B67C-430B490F6430">system lock</xref> fast mutex rather than by locking the kernel. To guarantee

this, semaphore operations are done through kernel functions. </p> <p>Although

somewhat artificial, and not based on real code, the following diagram nevertheless

shows the basic idea behind Symbian platform semaphores. </p> <fig id="GUID-505BC4A5-BBCB-5A63-9795-C751719661BB">

<title>Symbian platform semaphore</title>

<image href="GUID-0FE0B646-A62F-55A8-A6E6-587D0909CE19_d0e74784_href.png" placement="inline"/>

</fig> <p id="GUID-6131CDB0-6249-5B9A-A969-9B25F8BCECF5"><b>Rules</b> </p> <p>There

are a few rules about the use of Symbian platform semaphores: </p> <ul>

<li id="GUID-B850F00A-D7E6-5542-9D9D-F07F2625E29B"><p>Only Symbian platform

threads are allowed to use Symbian platform semaphores </p> </li>

<li id="GUID-C848306E-7407-5397-8638-DB6AB7250A4E"><p>An IDFC is not allowed

to signal a Symbian platform semaphore. </p> </li>

</ul> <p id="GUID-915A061E-C85E-5165-A12F-B3B214756AE0"><b>How to use</b> </p> <p>Typically

you declare the Symbian platform semaphore in a class declaration, for example: </p> <codeblock id="GUID-19168C17-C570-5FEE-9339-FEA37E6D0043" xml:space="preserve">class X

    {

    ...

private:

    DSemaphore* iSemaphore;

    ...

    };

</codeblock> <p>You cannot create a <codeph>DSemaphore</codeph> object directly;

instead you must use the kernel function <xref href="GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D.dita#GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D/GUID-8D0C749E-BB1E-3DC1-85CD-945313F07146"><apiname>Kern::SemaphoreCreate()</apiname></xref>.

You pass a <codeph>DSemaphore*</codeph> type to the kernel function, which

creates the <codeph>DSemaphore</codeph> object and returns a reference to

it through the <codeph>DSemaphore</codeph> pointer. </p> <p>Waiting on the

semaphore and signalling the semaphore are done using the kernel functions: </p> <ul>

<li id="GUID-258E8300-3E13-502F-95C4-42DBA956BA0E"><p> <xref href="GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D.dita#GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D/GUID-B7442064-FD21-3DCE-A412-4233D36A8D10"><apiname>Kern::SemaphoreWait()</apiname></xref>  </p> </li>

<li id="GUID-4FF62788-06FB-5F71-A8AE-3539E498E05A"><p> <xref href="GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D.dita#GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D/GUID-F25FACED-5030-304D-95FA-8A1AE48565F3"><apiname>Kern::SemaphoreSignal()</apiname></xref>  </p> </li>

</ul> <p>respectively, passing a reference to the <codeph>DSemaphore</codeph> object

created earlier. Note that although you pass a <codeph>DSemaphore</codeph> object

around, the member functions and member data of the class are considered as

internal to Symbian platform, and indeed the member functions are not exported

and are not accessible except to the kernel itself. However, you can call <codeph>Open()</codeph> and <codeph>Close()</codeph> on <codeph>DSemaphore</codeph> as they are members of the base class <xref href="GUID-E48F1435-14B6-37F1-BE47-2EA803AFE497.dita"><apiname>DObject</apiname></xref>. </p> </section>

<section id="GUID-7E632FD5-03B6-5D39-8A97-8F1948F2BB5B"><title>Thread critical

section</title> <p>Putting a thread into a thread critical section prevents

it being killed or panicked. Any kill or panic request is deferred until the

thread leaves the critical section. </p> <p>A thread critical section is used

to protect a section of code that is changing a global data structure or some

other global resource. Killing a thread that is in the middle of manipulating

such a global data structure might leave it in a corrupt state, or marked

is being "in use". </p> <p>A thread critical section only applies to code

that is running on the kernel side but in the context of a user thread. Only