Class RSemaphore

class RSemaphore : public RHandleBase;

Description

A handle to a semaphore.

The semaphore itself is a Kernel side object.

As with all handles, they should be closed after use. RHandleBase provides the necessary RHandleBase::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.

Members

Defined in 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()Signals the semaphore once.
• Signal(TInt)Signals the semaphore one or more times.
• Wait()Waits for a signal on the semaphore.
• Wait(TInt)Waits for a signal on the semaphore, or a timeout.

Inherited from RHandleBase:

• Attributes()const
• BTraceId()constReturns a unique object identifier for use with BTrace
• Close()Closes the handle.
• 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

See also:

• RHandleBase::Close()Closes the handle.

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

Description

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

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

By default, any thread in the process can use this instance of RSemaphore to access the semaphore. However, specifying EOwnerThread as the second parameter to this function, means that only the opening thread can use this instance of RSemaphore to access the semaphore; any other thread in this process that wants to access the semaphore must either duplicate the handle or use RSemaphore::OpenGlobal(const TDesC &,TOwnerType) again.

Parameters

const TFindSemaphore &aFind A reference to the TFindSemaphore object used to find the semaphore. 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.

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

Description

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

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

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

Parameters

TInt aCount The initial value of the semaphore count. 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.

Panic codes

USER 105 if aCount is negative.

See also:

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

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

Description

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

The kernel side object representing the semaphore is given the name contained in the specified descriptor, which makes it global. This means that any thread in any process can search for the semaphore, using TFindSemaphore, and open a handle to it. If the specified name is empty the kernel side object representing the semaphore is unnamed and so cannot be opened by name. It can however be passed to another process as a process parameter or via IPC.

By default, any thread in the process can use this instance of RSemaphore to access the semaphore. However, specifying EOwnerThread as the third parameter to this function, means that only the creating thread can use this instance of RSemaphore to access the semaphore; any other thread in this process that wants to access the semaphore must either duplicate this handle or use RSemaphore::OpenGlobal(const TDesC &,TOwnerType).

Parameters

const TDesC16 &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. 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.

Panic codes

USER 105 if aCount is negative.

See also:

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

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

Description

Opens a handle to a global semaphore.

Global semaphores are identified by name.

By default, any thread in the process can use this instance of RSemaphore to access the semaphore. However, specifying EOwnerThread as the second parameter to this function, means that only the opening thread can use this instance of RSemaphore to access the semaphore; any other thread in this process that wants to access the semaphore must either duplicate the handle or use RSemaphore::OpenGlobal(const TDesC &,TOwnerType) again.

Parameters

const TDesC16 &aName A reference to the descriptor containing the name of the global semaphore to be opened. 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.

See also:

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

IMPORT_C TInt Open(RMessagePtr2 aMessage, TInt aParam, TOwnerType aType=EOwnerProcess);

Description

Opens a handle to a semaphore using a handle number sent by a client to a server.

This function is called by the server.

Parameters

RMessagePtr2 aMessage The message pointer. TInt aParam An index specifying which of the four message arguments contains the handle number. 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; KErrArgument, if the value of aParam is outside the range 0-3; KErrBadHandle, if not a valid handle; otherwise one of the other system-wide error codes.

IMPORT_C TInt Open(TInt aArgumentIndex, TOwnerType aType=EOwnerProcess);

Description

Opens a handle to a semaphore using a handle number passed as an environment data item to the child process during the creation of that child process.

Note that this function can only be called successfully once.

Parameters

TInt aArgumentIndex An index that identifies the slot in the process environment data that contains the handle number. This is a value relative to zero, i.e. 0 is the first item/slot. This can range from 0 to 15. 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; KErrNotFound, if the slot indicated by aArgumentIndex is empty; KErrArgument, if the slot does not contain a Semaphore handle; otherwise one of the other system-wide error codes.

See also:

• RProcess::SetParameter(TInt,RHandleBase)Sets the specified handle into the specified environment data slot for this proc...

IMPORT_C void Wait();

Description

Waits for a signal 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 added to a 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 in priority order.

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

IMPORT_C TInt Wait(TInt aTimeout);

Description

Waits for a signal on the semaphore, or a timeout.

Parameters

TInt aTimeout The timeout value in micoseconds

Return value

TInt KErrNone if the wait has completed normally; KErrGeneral if the semaphore is being reset, i.e the semaphore is about to be deleted. KErrArgument if aTimeout is negative; otherwise one of the other system wide error codes indicating that the timeout has expired.

IMPORT_C void Signal();

Description

Signals the semaphore once.

The function increments the semaphore count by one. If the count was negative before being incremented, the highest priority 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.

IMPORT_C void Signal(TInt aCount);

Description

Signals the semaphore one or more times.

The function increments the semaphore count. If the count was negative before being incremented, the highest priority 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.

Parameters

TInt aCount The number of times the semaphore is to be signalled.