Class RCriticalSection

class RCriticalSection : private RSemaphore;

Description

A handle to a critical section.

A critical section itself is a kernel object, and is implemented using a semaphore. The class RCriticalSection inherits privately from RSemaphore as a matter of implementation and this is, in effect, equivalent to using a semaphore.

The public functions of RSemaphore are not part of the public API of this class.

As with all handles, they should be closed after use. This class provides the necessary RCriticalSection::Close() function, which should be called when the handle is no longer required.

Derivation

• RHandleBase - A handle to an object.

• RSemaphore - A handle to a semaphore.

• RCriticalSection - A handle to a critical section.

Members

Defined in RCriticalSection:

• Close()Closes the handle to the critical section.
• CreateLocal(TOwnerType)Creates a critical section and opens this handle to the critical section.
• IsBlocked()constTests whether the critical section is occupied by another thread.
• RCriticalSection()Default constructor.
• Signal()Signals an exit from the critical section.
• Wait()Waits for the critical section to become free.

Inherited from RHandleBase:

• Attributes()const
• BTraceId()constReturns a unique object identifier for use with BTrace
• Duplicate(const RThread &,TOwnerType)Creates a valid handle to the kernel object for which the specified thread alrea...
• FullName()constGets the full name of the handle.
• FullName(TDes &)constGets the full name of the handle.
• Handle()constRetrieves the handle-number of the object associated with this handle.
• HandleInfo(THandleInfo *)Gets information about the handle.
• Name()constGets the name of the handle.
• Open(const TFindHandleBase &,TOwnerType)Opens a handle to a kernel side object found using a find-handle object.
• RHandleBase(TInt)Copy constructor.
• SetHandle(TInt)Sets the handle-number of this handle to the specified value.
• SetHandleNC(TInt)Sets the handle-number of this handle to the specified value, and marks it as no...
• SetReturnedHandle(TInt)Sets the handle-number of this handle to the specified value.
• iHandle

Inherited from RSemaphore:

• CreateGlobal(const TDesC &,TInt,TOwnerType)Creates a global semaphore, setting its initial count, and opens this handle to ...
• CreateLocal(TInt,TOwnerType)Creates a semaphore, setting its initial count, and opens this handle to the sem...
• Open(RMessagePtr2,TInt,TOwnerType)Opens a handle to a semaphore using a handle number sent by a client to a server...
• Open(TInt,TOwnerType)Opens a handle to a semaphore using a handle number passed as an environment dat...
• Open(const TFindSemaphore &,TOwnerType)Opens a handle to the global semaphore found using a TFindSemaphore object.
• OpenGlobal(const TDesC &,TOwnerType)Opens a handle to a global semaphore.
• Signal(TInt)Signals the semaphore one or more times.
• Wait(TInt)Waits for a signal on the semaphore, or a timeout.

See also:

• RHandleBase::Close()Closes the handle.

IMPORT_C RCriticalSection();

Description

Default constructor.

IMPORT_C TInt CreateLocal(TOwnerType aType=EOwnerProcess);

Description

Creates a critical section and opens this handle to the critical section.

The kernel side object representing the critical section is unnamed. This means that it is not possible to search for the critical section, which makes it local to the current process.

By default, any thread in the process can use this instance of RCriticalSection to access the critical section. However, specifying EOwnerThread as the parameter to this function, means that only the creating thread can use this instance of RCriticalSection to access the critical section; any other thread in this process that wants to access the critical section must duplicate this handle.

Parameters

TOwnerType aType An enumeration whose enumerators define the ownership of this critical section handle. If not explicitly specified, EOwnerProcess is taken as default.

Return value

TInt KErrNone if successful otherwise another of the system wide error codes.

See also:

• RHandleBase::Duplicate(const RThread &,TOwnerType)Creates a valid handle to the kernel object for which the specified thread alrea...

IMPORT_C void Close();

Description

Closes the handle to the critical section.

As a critical section object is implemented using a semaphore, this has the effect of closing the handle to the semaphore.

IMPORT_C void Wait();

Description

Waits for the critical section to become free.

If no other thread is in the critical section, control returns immediately and the current thread can continue into the section.

If another thread is already in the critical section, the current thread is marked as waiting (on a semaphore); the current thread is added to a queue of threads maintained by this critical section.

IMPORT_C void Signal();

Description

Signals an exit from the critical section.

A thread calls this function when it exits from the critical section. The first eligible thread waiting on the critical section's queue of threads is removed from that queue and, provided that it is not suspended for any other reason, is marked as ready to run. That thread will, therefore, be the next to proceed into the critical section.

inline TBool IsBlocked() const;

Description

Tests whether the critical section is occupied by another thread.

Return value

TBool True, if the critical section is occupied by another thread. False, otherwise.