RWCondition Class Reference

A condition variable used to delay and reawaken a thread based on program state. More...

#include <rw/sync/RWCondition.h>

Inheritance diagram for RWCondition:

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 (RWCancellationState state=0)
	RWSynchObject (RWStaticCtor)
	RWSynchObject (const RWSynchObject &second)
RWSynchObject &	operator= (const RWSynchObject &second)
void	testCancellation ()

Private Member Functions
	RWCondition (const RWCondition &second)
RWCondition &	operator= (const RWCondition &second)

Related Functions
(Note that these are not member functions.)
typedef pthread_cond_t	RWConditionRep
typedef cond_t	RWConditionRep
Related Functions inherited from RWSynchObject
#define	RW_CANCELLATION_DISABLED
#define	RW_CANCELLATION_ENABLED
typedef void(*	RWCancellationState) ()
void	rwServiceCancellation (void)

Detailed Description

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:

while (!my_boolean_expression)
    cv.wait();

When using RWCondition in a class inheriting from RWTMonitor, it is not uncommon to initialize the RWCondition with the monitor's mutex.

Example

#include <rw/sync/RWCondition.h>
#include <rw/sync/RWTMonitor.h>
#include <rw/sync/RWMutexLock.h>
#include <rw/tvslist.h>

// Producer Consumer queue example
template <class T>
class PCBuffer
    : RWTMonitor<RWMutexLock>
{
private:
    RWCondition roomInBuffer_;
    RWCondition elementAvailable_;
    RWTValSlist<T> buffer_;
    size_t maxEntries_;
public:
    PCBuffer(size_t maxEntries)
        : maxEntries_(maxEntries),
          roomInBuffer_(mutex()),    // init with monitor mutex
          elementAvailable_(mutex()) // init with monitor mutex
    {}

    void put(T t) {
        LockGuard lock(monitor()); // acquire monitor mutex
        while (!(buffer_.entries() < maxEntries_)) {
            roomInBuffer_.wait();   // mutex released automatically
            // thread must have been signaled AND
            // mutex reacquired to reach here
        }
        buffer_.append(t);
        elementAvailable_.signal();
        // mutex automatically released in LockGuard destructor
    }

    T get(void) {
        LockGuard lock(monitor());   // acquire monitor mutex
        while (!(buffer_.entries() > 0)) {
            elementAvailable_.wait(); // mutex released
            //automatically
            // thread must have been signalled AND
            // mutex reacquired to reach here
        }
        T val = buffer_.removeFirst();
        roomInBuffer_.signal();
        return val;
        // mutex automatically released in LockGuard destructor
    }
};

Member Typedef Documentation

typedef RWTLockGuard<RWCondition> RWCondition::LockGuard

Predefined type for compatible guard.

typedef RWTTryLockGuard<RWCondition> RWCondition::TryLockGuard

Predefined type for compatible guard.

typedef RWTUnlockGuard<RWCondition> RWCondition::UnlockGuard

Predefined type for compatible guard.

Constructor & Destructor Documentation

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.

RWCondition::RWCondition ( const RWCondition &  second )

private

Assignment prohibited.

Member Function Documentation

void RWCondition::acquire ( void  )

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.

RWWaitStatus RWCondition::acquire ( unsigned long  milliseconds )

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.

Condition:

This function is available only in build configurations based on POSIX or Solaris threads.

RWMutexLock & RWCondition::mutex ( void  ) const

inlineprotected

Returns a reference to the mutex associated with this condition variable.

RWCondition& RWCondition::operator= ( const RWCondition &  second )

private

Copy construction prohibited.

void RWCondition::release ( )

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.

bool RWCondition::tryAcquire ( )

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.

Friends And Related Function Documentation

typedef pthread_cond_t RWConditionRep

related

Typedef for the internal condition variable.

Condition:

This type is used for build configurations based on POSIX threads.

typedef cond_t RWConditionRep

related

Typedef for the internal condition variable.

Condition:

This type is used for build configurations based on Solaris threads.