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

Qore Programming Language Reference Manual 0.8.11

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

- Class List
- Class Index
- Class Hierarchy
- Class Members

All Classes Namespaces Functions Variables Groups Pages
Public Member Functions | List of all members
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

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

Qore::Thread::Condition::constructor | ( |  | ) |

Creates the Condition object.

Example:
  my Condition $cond();

Qore::Thread::Condition::copy | ( |  | ) |

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

Example:
  my Condition $new_cond = $cond.copy();

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

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

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));