SourcePro® 2024.1 |
SourcePro® API Reference Guide |
A condition variable used to delay and reawaken a thread based on program state. More...
#include <rw/sync/RWCondition.h>
Public Types | |
typedef RWTLockGuard< RWCondition > | LockGuard |
typedef RWTTryLockGuard< RWCondition > | TryLockGuard |
typedef RWTUnlockGuard< RWCondition > | UnlockGuard |
Public Member Functions | |
RWCondition (RWMutexLock &mutex, RWCancellationState state=0) | |
~RWCondition () | |
void | acquire () |
RWWaitStatus | acquire (unsigned long milliseconds) |
RWConditionRep * | getConditionRep () const |
void | release () |
void | signal () |
void | signalAll () |
bool | tryAcquire () |
void | wait () |
RWWaitStatus | wait (unsigned long milliseconds) |
Public Member Functions inherited from RWSynchObject | |
void | disableCancellation () |
void | enableCancellation (RWCancellationState) |
bool | isCancellationEnabled () const |
void | setCancellation (RWCancellationState) |
Protected Member Functions | |
RWMutexLock & | mutex () const |
Protected Member Functions inherited from RWSynchObject | |
RWSynchObject (const RWSynchObject &second) | |
RWSynchObject (RWCancellationState state=0) | |
RWSynchObject (RWStaticCtor) | |
RWSynchObject & | operator= (const RWSynchObject &second) |
void | testCancellation () |
Private Member Functions | |
RWCondition (const RWCondition &second) | |
RWCondition & | operator= (const RWCondition &second) |
Related Symbols | |
(Note that these are not member symbols.) | |
typedef pthread_cond_t | RWConditionRep |
typedef cond_t | RWConditionRep |
Related Symbols inherited from RWSynchObject | |
#define | RW_CANCELLATION_DISABLED |
#define | RW_CANCELLATION_ENABLED |
typedef void(* | RWCancellationState) () |
void | rwServiceCancellation (void) |
An RWCondition object is a condition variable that can be used to delay a thread until the program state satisfies some boolean condition, and to awaken that thread once the condition becomes true.
The name condition variable is perhaps a misnomer. The name seems to imply that a condition variable encapsulates a condition. This is not the case. A condition variable is associated with some arbitrary condition in a program. It simply provides a mechanism for threads to wait and signal. It is up to the application to wait at the appropriate point of execution when the condition is false, and to signal appropriately when the condition becomes true.
A condition variable must be initialized with a mutex. The mutex must be the same instance that is used to protect the program state involved in the condition test. To delay on a condition variable, a thread calls the wait() function which atomically releases the lock and logically adds the thread to a list of threads that are waiting on the same condition. Another thread can unblock one waiting thread, if there are any, by calling the signal() member function. All waiting threads can be awakened at once by calling the signalAll() member function. For each awakened thread, the wait() function reacquires the lock and returns control to the calling routine.
To use an RWCondition object, a thread evaluates a boolean expression under the protection of a mutex lock. When the expression is false
, the thread blocks on the condition variable, and the mutex is released. Later, when another thread changes the state of the conditional expression under protection of the mutex lock, it then signals that the condition state has changed. This causes one or all threads, depending on whether signal() or signalAll() is used, to block on the condition to awaken and to try to reacquire the lock.
A thread should always retest the condition when it is awakened, as the condition might have changed before the thread can reacquire the condition mutex. This is typically done in a loop:
When using RWCondition in a class inheriting from RWTMonitor, it is not uncommon to initialize the RWCondition with the monitor's mutex.
Predefined type for compatible guard.
Predefined type for compatible guard.
Predefined type for compatible guard.
RWCondition::RWCondition | ( | RWMutexLock & | mutex, |
RWCancellationState | state = 0 ) |
Creates a condition variable that is protected by the supplied mutex instance. The provided mutex must exist as long as the condition variable exists. Possible exceptions include RWTHRResourceLimit and RWTHRInternalError.
RWCondition::~RWCondition | ( | ) |
Default destructor.
|
private |
Assignment prohibited.
|
inline |
Blocks until the condition's mutex is released, acquires it, and continues. This function is provided as a convenience; you may also call the mutex acquire() function directly. Possible exceptions include RWCancellation, RWTHRResourceLimit, and RWTHRInternalError.
This function does not block in single-threaded builds. The underlying mutex acquire returns immediately to indicate success. If the mutex was unavailable for acquisition, a debug assertion will result or an RWTHRInternalError will be thrown.
|
inline |
Acquires the mutex associated with the condition variable. If the mutex is not available, blocks at least for the specified number of milliseconds, or until the mutex is released, whichever comes first. If the mutex is released within the specified time, the function acquires it and continues. If the mutex is not released, the function returns the time-out indication RW_THR_TIMEOUT. This function is provided as a convenience; you may also call the mutex timed acquire() function directly. Possible exceptions include RWCancellation, RWTHRResourceLimit, and RWTHRInternalError.
This function does not block in single-threaded builds. The underlying mutex acquire returns immediately.
RWConditionRep * RWCondition::getConditionRep | ( | ) | const |
Provides access to the underlying mechanism.
|
inlineprotected |
Returns a reference to the mutex associated with this condition variable.
|
private |
Copy construction prohibited.
|
inline |
Releases the mutex associated with the condition variable. This function is provided as a convenience; you may also call the mutex release() function directly. Possible exceptions include RWTHRInternalError.
void RWCondition::signal | ( | ) |
Signals one waiting thread that the condition associated with the condition variable has changed. Possible exceptions include RWTHRInternalError.
This function is a no-op in single-threaded builds.
void RWCondition::signalAll | ( | ) |
Signals all waiting threads that the condition associated with the condition variable has changed. Possible exceptions include RWTHRInternalError.
This function is a no-op in single-threaded builds.
|
inline |
Tries to acquire the condition's mutex (without blocking). Returns true
if acquired, or false
if the mutex is already owned by another thread. This function is provided as a convenience; you may also call the mutex tryAcquire() function directly. Possible exceptions include RWCancellation, RWTHRResourceLimit, and RWTHRInternalError.
void RWCondition::wait | ( | ) |
Releases the condition mutex, then waits for a thread to signal that the state condition associated with the condition variable has changed. When a thread has been awakened, the condition mutex is automatically reacquired. If another thread holds the mutex when the thread awakes, then the thread must wait until it can acquire the mutex before proceeding. Possible exceptions include RWCancellation and RWTHRInternalError.
Calling this function produces an assertion in single-threaded debug mode builds, and an RWTHRInternalError is thrown in release builds.
RWWaitStatus RWCondition::wait | ( | unsigned long | milliseconds | ) |
This function is similar to wait(), but returns RW_THR_TIMEOUT if the specified amount of time elapses before the thread signals. Otherwise, returns RW_THR_SIGNALED when the thread is signaled that the state condition has changed. Note that if the wait times out, the function won't return until the condition mutex can be reacquired. Possible exceptions include RWCancellation and RWTHRInternalError.
This function immediately returns RW_THR_TIMEOUT in single-threaded builds.
|
related |
Typedef for the internal condition variable.
|
related |
Typedef for the internal condition variable.
Copyright © 2024 Rogue Wave Software, Inc., a Perforce company. All Rights Reserved. |