Class RCondVar

class RCondVar : public RHandleBase;

Description

A handle to a condition variable.

The condition variable itself is a kernel side object.

Handles 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.

• RCondVar - A handle to a condition variable.

Members

Defined in RCondVar:

• Broadcast()Broadcast to a condition variable
• CreateGlobal(const TDesC &,TOwnerType)Creates a global condition variable and opens this handle to it.
• CreateLocal(TOwnerType)Creates a condition variable and opens this handle to it.
• Open(RMessagePtr2,TInt,TOwnerType)Opens a handle to a condition variable using a handle number sent by a client to...
• Open(TInt,TOwnerType)Opens a handle to a condition variable using a handle number passed as an enviro...
• OpenGlobal(const TDesC &,TOwnerType)Opens a handle to a global condition variable.
• Signal()Signal a condition variable
• TimedWait(RMutex &,TInt)Wait on a condition variable with timeout
• Wait(RMutex &)Wait on a condition variable

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.

IMPORT_C TInt CreateLocal(TOwnerType aType=EOwnerProcess);

Description

Creates a condition variable and opens this handle to it.

The kernel side object representing the condition variable is unnamed and so the condition variable cannot be found by name and hence it is local to the current process.

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

Parameters

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

Return value

TInt KErrNone if successful, otherwise one 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 CreateGlobal(const TDesC &aName, TOwnerType aType=EOwnerProcess);

Description

Creates a global condition variable and opens this handle to it.

If the specified name is a non-empty string the kernel side object representing the condition variable is given the specified name and is therefore global. It may subsequently be opened by name using the RCondVar::OpenGlobal(const TDesC &,TOwnerType) function. If the specified name is empty the kernel side object representing the condition variable is unnamed and so cannot be opened by name. It can however be passed to another process as a process parameter or via IPC.

If the specified name is non-empty it must consist entirely of printable ASCII characters (codes 0x20 to 0x7e inclusive) and may not contain : * or ?.

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

Parameters

const TDesC16 &aName The name to be assigned to this condition variable. TOwnerType aType An enumeration whose enumerators define the ownership of this condition variable handle. If not explicitly specified, EOwnerProcess is taken as default.

Return value

TInt KErrNone if successful, otherwise one of the other system wide error codes.

See also:

• RCondVar::OpenGlobal(const TDesC &,TOwnerType)Opens a handle to a global condition variable.
• RHandleBase::Duplicate(const RThread &,TOwnerType)Creates a valid handle to the kernel object for which the specified thread alrea...
• RProcess::SetParameter(TInt,RHandleBase)Sets the specified handle into the specified environment data slot for this proc...
• TIpcArgs::Set(TInt,RHandleBase)Sets an argument value of RHandleBase type.

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

Description

Opens a handle to a global condition variable.

Global condition variables are identified by name.

By default, any thread in the process can use this instance of RCondVar to access the condition variable. However, specifying EOwnerThread as the parameter to this function means that only the creating thread can use this instance of RCondVar to access the condition variable; any other thread in this process that wants to access the condition variable must either duplicate this handle or use OpenGlobal again.

Parameters

const TDesC16 &aName The name of the global condition variable which is to be opened. TOwnerType aType An enumeration whose enumerators define the ownership of this condition variable 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 condition variable 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 condition variable 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 condition variable 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 condition variable 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 condition variable 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 TInt Wait(RMutex &aMutex);

Pre-Condition

The specified mutex is held by the current thread.

Description

Wait on a condition variable

This call releases the specified mutex then atomically blocks the current thread on this condition variable. The atomicity here is with respect to the condition variable and mutex concerned. Specifically if the condition variable is signalled at any time after the mutex is released then this thread will be awakened. Once the thread has awakened it will reacquire the specified mutex before this call returns (except in the case where the condition variable has been deleted).

The usage pattern for this is as follows:

    mutex.Wait();
    while(!CONDITION)
        condvar.Wait(mutex);
    STATEMENTS;
    mutex.Signal();

where CONDITION is an arbitrary condition involving any number of user-side variables whose integrity is protected by the mutex.

It is necessary to loop while testing the condition because there is **no** guarantee that the condition has been satisfied when the condition variable is signalled. Different threads may be waiting on different conditions or the condition may have already been absorbed by another thread. All that can be said is that the thread will awaken whenever something happens which **might** affect the condition.

It needs to be stressed that if:

condvar.Wait(mutex);

completes, it does not necessarily mean that the condition is yet satisfied, hence the necessity for the loop.

Post-Condition

The specified mutex is held by the current thread unless the return value is KErrGeneral in which case the condition variable no longer exists.

Parameters

RMutex &aMutex The mutex to be released and reacquired.

Return value

TInt KErrNone if the condition variable has been signalled. KErrInUse if another thread is already waiting on this condition variable in conjunction with a different mutex. KErrGeneral if the condition variable is deleted.

Panic codes

KERN-EXEC 0 if either the condition variable or mutex handles are not valid. KERN-EXEC 54 if the current thread does not hold the specified mutex.

See also:

• RCondVar::Signal()Signal a condition variable
• RCondVar::Broadcast()Broadcast to a condition variable

IMPORT_C TInt TimedWait(RMutex &aMutex, TInt aTimeout);

Pre-Condition

The specified mutex is held by the current thread.

Description

Wait on a condition variable with timeout

This is the same as RCondVar::Wait(RMutex) except that there is a time limit on how long the current thread will block while waiting for the condition variable.

Post-Condition

The specified mutex is held by the current thread unless the return value is KErrGeneral in which case the condition variable no longer exists.

Parameters

RMutex &aMutex The mutex to be released and reacquired. TInt aTimeout The maximum time to wait in microseconds. 0 means no maximum.

Return value

TInt KErrNone if the condition variable has been signalled. KErrInUse if another thread is already waiting on this condition variable in conjunction with a different mutex. KErrGeneral if the condition variable is deleted. KErrTimedOut if the timeout expired before the condition variable was signalled.

Panic codes

KERN-EXEC 0 if either the condition variable or mutex handles are not valid. KERN-EXEC 54 if the current thread does not hold the specified mutex.

IMPORT_C void Signal();

Description

Signal a condition variable

This unblocks a single thread which is currently blocked on the condition variable. The highest priority waiting thread which is not explicitly suspended will be the one unblocked. If there are no threads currently waiting this call does nothing.

It is not required that any mutex is held when calling this function but it is recommended that the mutex associated with the condition variable is held since otherwise a race condition can result from the condition variable being signalled just after the waiting thread testing the condition and before it calls RCondVar::Wait(RMutex &).

IMPORT_C void Broadcast();

Description

Broadcast to a condition variable

This unblocks all threads which are currently blocked on the condition variable. If there are no threads currently waiting this call does nothing.

It is not required that any mutex is held when calling this function but it is recommended that the mutex associated with the condition variable is held since otherwise a race condition can result from the condition variable being signalled just after the waiting thread testing the condition and before it calls RCondVar::Wait(RMutex &).