Qore Programming Language Reference Manual  0.8.12.9
Qore::Thread::Condition Class Reference

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

Public Member Functions

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-ERRORThis 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-ERRORThis 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
lockthe AbstractSmartLock object to use for synchronization on this Condition object. The AbstractSmartLock must be locked before calling this method
timeout_msa 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-ERRORThis 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
lockthe 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));