Qore::Thread::Condition Class Reference

The Condition class can be used For blocking a thread until a condition becomes True. More...

#include <QC_Condition.dox.h>

Public Member Methods
nothing	broadcast ()
	Signals all threads blocked on this Condition object to wake up. More...
	constructor ()
	Creates the Condition object. More...
	copy ()
	Creates a new Condition object, not based on the original. More...
nothing	signal ()
	Signals a single blocked thread to wake up. More...
int	wait (AbstractSmartLock lock, timeout timeout_ms=0)
	Blocks a thread until signaled; accepts an optional timeout value. More...
int	wait_count (AbstractSmartLock lock)
	Returns the number of threads currently blocked on this object using the AbstractSmartLock passed. More...

Detailed Description

The Condition class can be used For blocking a thread until a condition becomes True.

Restrictions:

Qore::PO_NO_THREAD_CLASSES

Condition objects, when used along with an AbstractSmartLock object (such as RWLock and Mutex objects), allow Qore threads to sleep until a certain condition becomes True.

Note

This class is not available with the PO_NO_THREAD_CLASSES parse option.

Member Function Documentation

broadcast()

nothing Qore::Thread::Condition::broadcast

(

)

Signals all threads blocked on this Condition object to wake up.

Normally this method call will be made while the same AbstractSmartLock object used for Condition::wait() calls is locked. Then, when the thread calling this method unlocks the AbstractSmartLock object, the thread(s) woken up by this call can continue executing.

Example:

m.lock();
cond.broadcast();
m.unlock();

Exceptions

CONDITION-BROADCAST-ERROR

This exception should never be thrown - it indicates a low-level error in executing the method

constructor()

Qore::Thread::Condition::constructor

(

)

Creates the Condition object.

Example:

Condition cond();

copy()

Qore::Thread::Condition::copy

(

)

Creates a new Condition object, not based on the original.

Example:

Condition new_cond = cond.copy();

signal()

nothing Qore::Thread::Condition::signal

(

)

Signals a single blocked thread to wake up.

Normally this method call will be made while the same AbstractSmartLock object used for Condition::wait() calls is locked. Then, when the thread calling this method unlocks the AbstractSmartLock object, the thread woken up by this call can continue executing.

Example:

m.lock();
cond.signal();
m.unlock();

Exceptions

CONDITION-SIGNAL-ERROR

This exception should never be thrown - it indicates a low-level error in executing the method

wait()

int Qore::Thread::Condition::wait	(	AbstractSmartLock	lock,
		timeout	timeout_ms = 0
	)

Blocks a thread until signaled; accepts an optional timeout value.

Must be called with an AbstractSmartLock argument, and the AbstractSmartLock must be locked before the call. This method will atomically unlock the AbstractSmartLock object and wait on this Condition object to be woken up with a Condition::signal() or Condition::broadcast() method call in another thread. At this point, the AbstractSmartLock will be reacquired with the same state as it was acquired previously before control returns to the blocked thread. The wait condition should always be tested again when the thread is unblocked.

Parameters

lock

the AbstractSmartLock object to use for synchronization on this Condition object. The AbstractSmartLock must be locked before calling this method

timeout_ms

a timeout value to wait for the condition to be triggered; integers are interpreted as milliseconds; relative date/time values are interpreted literally (with a resolution of milliseconds). Timeout values <= 0 mean do not time out. If a timeout value > 0 is given and the call times out, the AbstractSmartLock will also be acquired when the Condition::wait() call returns and ETIMEDOUT will be returned.

Returns

0 for success, ETIMEDOUT if a timeout has occurred

Example:

m.lock();
on_exit m.unlock();
while (some_value > 0) {
    cond.wait(m);
}
printf("finally some_value is 0\n");

Exceptions

CONDITION-WAIT-ERROR

This exception should never be thrown - it indicates a low-level error in executing the method

wait_count()

int Qore::Thread::Condition::wait_count

(

AbstractSmartLock

lock

)

Returns the number of threads currently blocked on this object using the AbstractSmartLock passed.

Parameters

lock	the AbstractSmartLock object to check for blocked threads on this Condition object; the AbstractSmartLock can be in any state (locked or unlocked) for this call (does not necessarily have to be locked).

Returns

The number of threads currently blocked on this object using the AbstractSmartLock object passed

Example:

printf("%d thread(s) waiting on the Condition\n", cond.wait_count(m));