[ Engines and Threads | Reference Manual | Alphabetic Index ]

# condition_wait(+Handle, +Timeout)

Wait for a condition to be signaled on a handle

Handle
  A handle for an object supporting condition signaling
Timeout
  Timeout in seconds (integer or float), or the atom 'block'

## Description

This is a low-level primitive that, together with condition_signal/2 and with_mutex/2, can be used to implement synchronization between concurrent threads.

The predicate blocks the current thread's execution until condition_signal/2 on Handle is invoked by another thread.

See condition_signal/2 for usage pattern, examples, and a list of handle types that support this operation.

This predicate must always be executed in a context where the Handle has been locked, i.e. inside with_mutex/2.

NOTE: the predicate will also be unblocked (and succeed) when the engine receives a throw/exit request via engine_post/2.

### Modes and Determinism

- condition_wait(+, +) is det

### Exceptions

(4) instantiation fault
  Handle or Timeout is not instantiated.
(5) type error
  Handle is not a handle.
(5) type error
  Timeout is neither integer, float, nor the atom 'block'
(6) out of range
  Timeout is a negative number
(141) unimplemented functionality
  Handle refers to an object that does not support this operation.
(170) system interface error
  Operating system error, e.g. Handle was not locked.

## Examples

    See condition_signal/2

## See Also

is_handle / 2, condition_signal / 2, with_mutex / 2, name_to_handle / 3