4.22. Thread::Condition Class

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.868. Condition Method Overview

Method

Except?

Description

Condition::constructor()

N

Creates the Condition object.

Condition::destructor()

N

Destroys the Condition object.

Condition::copy()

N

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

Condition::signal()

Y

Signals a single blocked thread to wake up.

Condition::broadcast()

Y

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

Condition::wait()

Y

Blocks a thread until signaled.

Condition::wait_count()

N

Returns the number of threads currently blocked on this object.


4.22.1. Condition::constructor()

Synopsis

Creates the Condition object.

Usage
new Condition()
Example
$cond = new Condition();

Table 4.869. Arguments for Condition::constructor()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 4.870. Return Values for Condition::constructor()

Return Type

Description

Condition Object

The new Condition object.


4.22.2. Condition::destructor()

Synopsis

Destroys the object.

Usage
delete lvalue
Example
delete $cond;

4.22.3. Condition::copy()

Synopsis

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

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

Table 4.871. Arguments for Condition::copy()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 4.872. Return Values for Condition::copy()

Return Type

Description

Condition Object

A new Condition object, not based on the original.


4.22.4. Condition::signal()

Synopsis

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.

Usage
Condition::signal()
Example
$cond.signal();

Table 4.873. Arguments for Condition::signal()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 4.874. Return Values for Condition::signal()

Return Type

Description

n/a

This method returns no values.


Table 4.875. Exceptions Thrown by Condition::signal()

err

desc

CONDITION-SIGNAL-ERROR

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


4.22.5. Condition::broadcast()

Synopsis

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.

Usage
Condition::broadcast()
Example
$cond.broadcast();

Table 4.876. Arguments for Condition::broadcast()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 4.877. Return Values for Condition::broadcast()

Return Type

Description

n/a

This method returns no value.


Table 4.878. Exceptions Thrown by Condition::broadcast()

err

desc

CONDITION-BROADCAST-ERROR

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


4.22.6. Condition::wait()

Synopsis

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.

Usage
Condition::wait(mutex, [timeout_ms])
Example
$mutex.lock();
while ($num > 0)
    $cond.wait($mutex);
# ... do something
$mutex.unlock();

Table 4.879. Arguments for Condition::wait()

Argument

Type

Description

mutex

Mutex Object

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

[timeout_ms]

Integer or Relative Date/Time

An optional timeout value; integers are interpreted as milliseconds; relative date/time values are interpreted literally.


Table 4.880. Return Values for Condition::wait()

Return Type

Description

Integer

0 for success, -1 for errors (timeout).


Table 4.881. Exceptions Thrown by Condition::wait()

err

desc

CONDITION-WAIT-ERROR

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


4.22.7. Condition::wait_count()

Synopsis

Returns the number of threads currently blocked on this object.

Usage
Condition::wait_count()
Example
$num_threads = $cond.wait_count();

Table 4.882. Arguments for Condition::wait_count()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 4.883. Return Values for Condition::wait_count()

Return Type

Description

Integer

The number of threads currently blocked on this object.