Note: This class is not available with the PO_NO_THREAD_CLASSES
parse option.
Condition objects, when used along with a Mutex object, allow Qore threads to sleep until a certain condition becomes true.
Table 4.869. Condition Method Overview
Method | Except? | Description |
---|---|---|
N | Creates the Condition object. | |
N | Destroys the Condition object. | |
N | Creates a new Condition object, not based on the original. | |
Y | Signals a single blocked thread to wake up. | |
Y | Signals all threads blocked on this Condition object to wake up. | |
Y | Blocks a thread until signaled. | |
N | Returns the number of threads currently blocked on this object. |
Creates the Condition object.
new Condition()
$cond = new Condition();
Table 4.870. Arguments for Condition::constructor()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method takes no arguments. |
Table 4.871. Return Values for Condition::constructor()
Return Type | Description |
---|---|
Condition Object | The new Condition object. |
Creates a new Condition object, not based on the original.
Condition::copy()
$new_cond = $cond.copy();
Table 4.872. Arguments for Condition::copy()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method takes no arguments. |
Table 4.873. Return Values for Condition::copy()
Return Type | Description |
---|---|
Condition Object | A new Condition object, not based on the original. |
Signals a single blocked thread to wake up. Normally this method call will be made while the same Mutex object used for Condition::wait() calls is locked. Then, when the thread calling this method unlocks the Mutex object, the thread(s) woken up by this call can continue executing.
Condition::signal()
$cond.signal();
Table 4.874. Arguments for Condition::signal()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method takes no arguments. |
Table 4.875. Return Values for Condition::signal()
Return Type | Description |
---|---|
n/a | This method returns no values. |
Table 4.876. Exceptions Thrown by Condition::signal()
err | desc |
---|---|
| This exception should never be thrown - it indicates a low-level error in executing the method. |
Wakes up all threads waiting on the Condition object. Normally this method call will be made while the same Mutex object used for Condition::wait() calls is locked. Then, when the thread calling this method unlocks the Mutex object, the thread(s) woken up by this call can continue executing.
Condition::broadcast()
$cond.broadcast();
Table 4.877. Arguments for Condition::broadcast()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method takes no arguments. |
Table 4.878. Return Values for Condition::broadcast()
Return Type | Description |
---|---|
n/a | This method returns no value. |
Table 4.879. Exceptions Thrown by Condition::broadcast()
err | desc |
---|---|
| This exception should never be thrown - it indicates a low-level error in executing the method. |
Blocks a thread on the Condition object. Must be called with a Mutex argument, and the Mutex must be locked before the call. This method will atomically unlock the Mutex 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 Mutex will be reacquired before control returns to the blocked thread. The wait condition should always be tested again when the thread is unblocked.
Also accepts an optional timeout value in milliseconds. Like all Qore functions and methods taking timeout values, a relative time value may be passed instead of an integer to make the timeout units clear (ex: 2500ms
for 2.5 seconds). Also if the call times out, the Mutex will also be acquired when the Condition::wait() call returns and a non-zero return value will be returned.
Condition::wait(mutex, [timeout_ms]
)
$mutex.lock(); while ($num > 0) $cond.wait($mutex); # ... do something $mutex.unlock();
Table 4.880. Arguments for Condition::wait()
Argument | Type | Description |
---|---|---|
| Mutex Object | The Mutex object to use for synchronization on this Condition object. The Mutex must be locked before calling this method. |
| Integer or Relative Date/Time | An optional timeout value; integers are interpreted as milliseconds; relative date/time values are interpreted literally. |
Table 4.881. Return Values for Condition::wait()
Return Type | Description |
---|---|
Integer | 0 for success, -1 for errors (timeout). |
Table 4.882. Exceptions Thrown by Condition::wait()
err | desc |
---|---|
| This exception should never be thrown - it indicates a low-level error in executing the method. |
Returns the number of threads currently blocked on this object.
Condition::wait_count()
$num_threads = $cond.wait_count();
Table 4.883. Arguments for Condition::wait_count()
Argument | Type | Description |
---|---|---|
n/a | n/a | This method takes no arguments. |
Table 4.884. Return Values for Condition::wait_count()
Return Type | Description |
---|---|
Integer | The number of threads currently blocked on this object. |