Class RSemaphore

RSemaphore

Support

Supported from 5.0

Description

Provides a handle to a semaphore. The semaphore itself is a Kernel object.

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

Derivation

RHandleBase Handle to an object RSemaphore Provides a handle to a semaphore

Defined in RSemaphore:
Count(), CreateGlobal(), CreateLocal(), Open(), OpenGlobal(), Signal(), Wait()

Inherited from RHandleBase:
Close(), Duplicate(), Handle(), SetHandle()

TInt CreateLocal(TInt aCount,TOwnerType aType=EOwnerProcess);

Description

Creates a semaphore, setting its initial count, and opens this handle to that semaphore.

The Kernel side object representing the semaphore is unnamed. It is, therefore, local to the calling process. The handle can be used directly by any thread within the calling process, but no other RSemaphore object can open a duplicate handle.

By default, ownership of this semaphore handle is vested in the current process, but can be vested in the current thread by passing EOwnerThread as the second parameter to this function.

Parameters

TInt aCount The initial value of the semaphore count. This value must not be negative otherwise the function raises a USER 105 panic. TOwnerType aType An enumeration whose enumerators define the ownership of this semaphore handle. If not explicitly specified, EOwnerProcess is taken as default.

Return value

TInt KErrNone if successful, otherwise another of the system_wide error codes.

TInt CreateGlobal(const TDesC& aName,TInt aCount,TOwnerType aType=EOwnerProcess);

Description

Creates a semaphore, setting its initial count, and opens this handle to that semaphore.

The semaphore is visible globally and is assigned the name contained in the descriptor aName; other threads may open a handle to this semaphore.

By default, ownership of this semaphore handle is vested in the current process, but can be vested in the current thread by passing EOwnerThread as the second parameter to this function.

Parameters

const TDesC& aName A reference to the descriptor containing the name to be assigned to this global semaphore. TInt aCount The initial value of the semaphore count. This value must not be negative otherwise the function raises a USER 105 panic. TOwnerType aType An enumeration whose enumerators define the ownership of this semaphore handle. If not explicitly specified, EOwnerProcess is taken as default.

Return value

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

TInt OpenGlobal(const TDesC& aName,TOwnerType aType=EOwnerProcess);

Description

Opens a handle onto a specified existing global semaphore.

By default, ownership of this semaphore handle is vested in the current process, but can be vested in the current thread by passing EOwnerThread as the second parameter to this function.

Parameters

const TDesC& aName A reference to the descriptor containing the name of the global semaphore which is to be opened. TOwnerType aType=EOwnerProcess An enumeration whose enumerators define the ownership of this semaphore handle. If not explicitly specified, EOwnerProcess is taken as default.

Return value

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

TInt Open(const TFindSemaphore& aFind,TOwnerType aType=EOwnerProcess);

Description

Opens a handle onto the global semaphore found using a TFindSemaphore object.

A TFindSemaphore object is used to find all global semaphores whose full names match a specified pattern.

By default, ownership of this semaphore handle is vested in the current process, but can be vested in the current thread by passing EOwnerThread as the second parameter to this function.

Parameters

const TFindSemaphore& aFind A reference to the TFindSemaphore object used to find the semaphore. TOwnerType aType=EOwnerProcess An enumeration whose enumerators define the ownership of this semaphore handle. If not explicitly specified, EOwnerProcess is taken as default.

Return value

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

void Wait();

Description

Waits on the semaphore.

The function decrements the semaphore count by one and returns immediately if it is zero or positive.

If the semaphore count is negative after being decremented, the calling thread is marked as waiting (on a semaphore); the thread is added to the end of a FIFO queue of threads maintained by this semaphore.

The thread waits until the semaphore is signalled. More than one thread can be waiting on a particular semaphore at a time. When there are multiple threads waiting on a semaphore, they are released on a first-in first-out basis.

If the semaphore is deleted, all threads waiting on that semaphore are released.

void Signal();
void Signal(TInt aCount);

Description

Signals the semaphore.

The function increments the semaphore count by one. If the count was negative before being incremented, the first thread waiting on the semaphore’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.

The function Signal(aCount) is equivalent to calling Signal() aCount times.

Parameters

TInt aCount The number of times the semaphore is to be signalled. If this parameter is not specified, the semaphore is signalled once.

TInt Count();

Description

Gets the current value of the semaphore count.

Return value

TInt The current value of the semaphore count.