A handle to a condition variable. More...

#include <e32std.h>

Inheritance diagram for RCondVar:

Public Member Functions
IMPORT_C TInt	CreateLocal (TOwnerType aType=EOwnerProcess)
	Creates a condition variable and opens this handle to it.

IMPORT_C TInt	CreateGlobal (const TDesC &aName, TOwnerType aType=EOwnerProcess)
	Creates a global condition variable and opens this handle to it.

IMPORT_C TInt	OpenGlobal (const TDesC &aName, TOwnerType aType=EOwnerProcess)
	Opens a handle to a global condition variable.

IMPORT_C TInt	Open (RMessagePtr2 aMessage, TInt aParam, TOwnerType aType=EOwnerProcess)
	Opens a handle to a condition variable using a handle number sent by a client to a server.

IMPORT_C TInt	Open (TInt aArgumentIndex, TOwnerType aType=EOwnerProcess)
	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.

IMPORT_C TInt	Wait (RMutex &aMutex)
	Wait on a condition variable.

IMPORT_C TInt	TimedWait (RMutex &aMutex, TInt aTimeout)
	Wait on a condition variable with timeout.

IMPORT_C void	Signal ()
	Signal a condition variable.

IMPORT_C void	Broadcast ()
	Broadcast to a condition variable.

Public Member Functions inherited from RHandleBase
	RHandleBase ()
	Default constructor.

TInt	Handle () const
	Retrieves the handle-number of the object associated with this handle.

void	SetHandle (TInt aHandle)
	Sets the handle-number of this handle to the specified value.

TInt	SetReturnedHandle (TInt aHandleOrError)
	Sets the handle-number of this handle to the specified value.

IMPORT_C void	Close ()
	Closes the handle.

IMPORT_C TName	Name () const
	Gets the name of the handle.

IMPORT_C TFullName	FullName () const
	Gets the full name of the handle.

IMPORT_C void	FullName (TDes &aName) const
	Gets the full name of the handle.

IMPORT_C void	SetHandleNC (TInt aHandle)
	Sets the handle-number of this handle to the specified value, and marks it as not closable.

IMPORT_C TInt	Duplicate (const RThread &aSrc, TOwnerType aType=EOwnerProcess)
	Creates a valid handle to the kernel object for which the specified thread already has a handle.

IMPORT_C void	HandleInfo (THandleInfo *anInfo)
	Gets information about the handle.

IMPORT_C TUint	Attributes () const

IMPORT_C TInt	BTraceId () const
	Returns a unique object identifier for use with BTrace.

IMPORT_C void	NotifyDestruction (TRequestStatus &aStatus)
	Internal technology API.

Additional Inherited Members
Public Types inherited from RHandleBase
enum	TAttributes { EReadAccess =0x1 , EWriteAccess =0x2 , EDirectReadAccess =0x4 , EDirectWriteAccess =0x8 }
	Read/Write attributes for the handle. More...

Static Public Member Functions inherited from RHandleBase
static void	DoExtendedClose ()

Protected Member Functions inherited from RHandleBase
	RHandleBase (TInt aHandle)
	Copy constructor.

IMPORT_C TInt	Open (const TFindHandleBase &aHandle, TOwnerType aType)
	Opens a handle to a kernel side object found using a find-handle object.

TInt	OpenByName (const TDesC &aName, TOwnerType aOwnerType, TInt aObjectType)
	Implementation for RXxxxx::Open/OpenGlocbal(const TDesC &aName,,TOwnerType aType) functions.

Static Protected Member Functions inherited from RHandleBase
static TInt	SetReturnedHandle (TInt aHandleOrError, RHandleBase &aHandle)

Protected Attributes inherited from RHandleBase
TInt	iHandle

Detailed 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 Close() function which should be called when the handle is no longer required.

See also: RHandleBase::Close

API status: Published to all clients. Released API.

Definition at line 3534 of file e32std.h.

Member Function Documentation

◆ Broadcast()

IMPORT_C void RCondVar::Broadcast ( )

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 Wait().

(generated from Symbian Developer Library)

◆ CreateGlobal()

IMPORT_C TInt RCondVar::CreateGlobal	(	const TDesC &	aName,
		TOwnerType	aType = `EOwnerProcess`
	)

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

RCondVar::OpenGlobal() RHandleBase::Duplicate() RProcess::SetParameter(TInt, RHandleBase) TIpcArgs::Set(TInt, RHandleBase) RMessagePtr2::Complete(RHandleBase)

Parameters

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

(generated from Symbian Developer Library)

◆ CreateLocal()

IMPORT_C TInt RCondVar::CreateLocal ( TOwnerType aType = EOwnerProcess )

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.

RHandleBase::Duplicate()

Parameters

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

(generated from Symbian Developer Library)

◆ Open() [1/2]

IMPORT_C TInt RCondVar::Open	(	RMessagePtr2	aMessage,
		TInt	aParam,
		TOwnerType	aType = `EOwnerProcess`
	)

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

aMessage	The message pointer.
aParam	An index specifying which of the four message arguments contains the handle number.
aType	An enumeration whose enumerators define the ownership of this condition variable handle. If not explicitly specified, EOwnerProcess is taken as default.

(generated from Symbian Developer Library)

◆ Open() [2/2]

IMPORT_C TInt RCondVar::Open	(	TInt	aArgumentIndex,
		TOwnerType	aType = `EOwnerProcess`
	)

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.

RProcess::SetParameter()

Parameters

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.
aType	An enumeration whose enumerators define the ownership of this condition variable handle. If not explicitly specified, EOwnerProcess is taken as default.

(generated from Symbian Developer Library)

◆ OpenGlobal()

IMPORT_C TInt RCondVar::OpenGlobal	(	const TDesC &	aName,
		TOwnerType	aType = `EOwnerProcess`
	)

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.

RHandleBase::Duplicate()

Parameters

aName	The name of the global condition variable which is to be opened.
aType	An enumeration whose enumerators define the ownership of this condition variable handle. If not explicitly specified, EOwnerProcess is taken as default.

(generated from Symbian Developer Library)

◆ Signal()

IMPORT_C void RCondVar::Signal ( )

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 Wait().

(generated from Symbian Developer Library)

◆ TimedWait()

IMPORT_C TInt RCondVar::TimedWait	(	RMutex &	aMutex,
		TInt	aTimeout
	)

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.

Parameters

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

Pre-condition: The specified mutex is held by the current thread.

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.

Panic condition: KERN-EXEC 0 if either the condition variable or mutex handles are not valid.

Panic condition: KERN-EXEC 54 if the current thread does not hold the specified mutex.

(generated from Symbian Developer Library)

◆ Wait()

IMPORT_C TInt RCondVar::Wait ( RMutex & aMutex )

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.

Parameters

aMutex The mutex to be released and reacquired.

Pre-condition: The specified mutex is held by the current thread.

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.

Panic condition: KERN-EXEC 0 if either the condition variable or mutex handles are not valid.

Panic condition: KERN-EXEC 54 if the current thread does not hold the specified mutex.

(generated from Symbian Developer Library)

The documentation for this class was generated from the following files:

Public Member Functions

Additional Inherited Members

Detailed Description

Member Function Documentation

◆ Broadcast()

◆ CreateGlobal()

◆ CreateLocal()

◆ Open() [1/2]

◆ Open() [2/2]

◆ OpenGlobal()

◆ Signal()

◆ TimedWait()

◆ Wait()