Crystal Space: csCondition Class Reference (Crystal Space Public API Reference)

| ## Public API Reference

- Main Page
- Modules
- Namespaces
- Classes
- Files
- Related Pages

- Alphabetical List
- Class List
- Class Hierarchy
- Class Members

# csCondition Class Reference

A condition object. More...

`#include <csutil/thread.h>`

Inheritance diagram for csCondition:

[legend]
List of all members.

## Public Member Functions
virtual char const * | GetLastError () const =0
| Return the last error description, else null if there was none.
virtual void | Signal (bool WakeAll=false)=0
| Wake up one or all threads waiting upon a change of condition.
virtual bool | Wait (csMutex *mutex, csTicks timeout=0)=0
| Wait for some change of condition.
## Static Public Member Functions
static csRef< csCondition > | Create (uint32 conditionAttributes=0)
| Create a condition with specific attributes.

## Detailed Description

A condition object.

Definition at line 271 of file thread.h.

## Member Function Documentation

static csRef<csCondition> csCondition::Create | ( | uint32 | conditionAttributes = `0` | ) | `[static]`

Create a condition with specific attributes.

Referenced by CS::SndSys::Queue< CS::SndSys::SndSysBasicStream::StreamNotificationEvent >::Queue().

virtual char const* csCondition::GetLastError | ( |  | ) | const`[pure virtual]`

Return the last error description, else null if there was none.

virtual void csCondition::Signal | ( | bool | WakeAll = `false` | ) | `[pure virtual]`

Wake up one or all threads waiting upon a change of condition.

If WakeAll is false, only one waiting thread will be awakened and given access to the associated mutex. If WakeAll is true, all threads waiting on the condition will be awakened and will vie for the associated mutex. Only one thread will win the mutex (thus gaining access to the condition); all other waiting threads will be re-suspended.

virtual bool csCondition::Wait | ( | csMutex * | mutex,
|  | csTicks | timeout = `0` |
| ) |  |  | `[pure virtual]`

Wait for some change of condition.

Suspends the calling thread until some other thread invokes Signal() to notify a change of condition.

Parameters:

  | mutex | The mutex to associate with this condition. The caller must already hold a lock on the mutex before calling Wait(), and all threads waiting on the condition must be using the same mutex. The mutex must not be locked recursively within the same thread. When called, Wait() releases the caller's lock on the mutex and suspends the caller's thread. Upon return from Wait(), the caller's lock on the mutex is restored.
  | timeout | The amount of time in milliseconds to wait for the the condition's state to change. If zero, the default, then it waits for a state change without timing-out. If non-zero, and the indicated time elapses without a state change being signaled, then false is returned.

Returns:
  Returns true if the caller was wakened normally. Returns false if the wait timed out, or if invoked with a recursive mutex, which is an invalid invocation style.

Remarks:
  The reason that the mutex must not be locked recursively is because the implicit unlock performed by Wait() must actually release the mutex in order for other threads to be able to satisfy the condition. With recursively locked mutexes, there is no guarantee that the one implicit unlock operation performed by Wait() will actually release the mutex since it might have been locked multiple times within the same thread.

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

- csutil/thread.h