ISO C Condition Variables (The GNU C Library)

#### 36.1.5 Condition Variables ¶

Mutexes are not the only synchronization mechanisms available. For some more complex tasks, the GNU C Library also implements condition variables, which allow the programmer to think at a higher level when solving complex synchronization problems. They are used to synchronize threads waiting on a certain condition to happen.

The fundamental data type for condition variables is the `cnd_t`:

Data Type: cnd_t ¶

  The `cnd_t` uniquely identifies a condition variable object.

The following functions are used for working with condition variables:

Function: `int` cnd_init `(cnd_t *cond)` ¶

  Preliminary: | MT-Safe | AS-Safe | AC-Safe | See POSIX Safety Concepts.

  `cnd_init` initializes a new condition variable, identified by cond.

  This function may return `thrd_success`, `thrd_nomem`, or `thrd_error`.

Function: `int` cnd_signal `(cnd_t *cond)` ¶

  Preliminary: | MT-Safe | AS-Safe | AC-Safe | See POSIX Safety Concepts.

  `cnd_signal` unblocks one thread that is currently waiting on the condition variable pointed to by cond. If a thread is successfully unblocked, this function returns `thrd_success`. If no threads are blocked, this function does nothing and returns `thrd_success`. Otherwise, this function returns `thrd_error`.

Function: `int` cnd_broadcast `(cnd_t *cond)` ¶

  Preliminary: | MT-Safe | AS-Safe | AC-Safe | See POSIX Safety Concepts.

  `cnd_broadcast` unblocks all the threads that are currently waiting on the condition variable pointed to by cond. This function returns `thrd_success` on success. If no threads are blocked, this function does nothing and returns `thrd_success`. Otherwise, this function returns `thrd_error`.

Function: `int` cnd_wait `(cnd_t *cond, mtx_t *mutex)` ¶

  Preliminary: | MT-Safe | AS-Unsafe lock | AC-Unsafe lock | See POSIX Safety Concepts.

  `cnd_wait` atomically unlocks the mutex pointed to by mutex and blocks on the condition variable pointed to by cond until the thread is signaled by `cnd_signal` or `cnd_broadcast`. The mutex is locked again before the function returns.

  This function returns either `thrd_success` or `thrd_error`.

Function: `int` cnd_timedwait `(cnd_t *restrict cond, mtx_t *restrict mutex, const struct timespec *restrict time_point)` ¶

  Preliminary: | MT-Safe | AS-Unsafe lock | AC-Unsafe lock | See POSIX Safety Concepts.

  `cnd_timedwait` atomically unlocks the mutex pointed to by mutex and blocks on the condition variable pointed to by cond until the thread is signaled by `cnd_signal` or `cnd_broadcast`, or until the calendar time pointed to by time_point has been reached. The mutex is locked again before the function returns.

  As for `mtx_timedlock`, since this function takes an absolute time, if a duration is required, the calendar time must be calculated manually. See Time Basics, and Calendar Time.

  This function may return `thrd_success`, `thrd_nomem`, or `thrd_error`.

Function: `void` cnd_destroy `(cnd_t *cond)` ¶

  Preliminary: | MT-Safe | AS-Safe | AC-Safe | See POSIX Safety Concepts.

  `cnd_destroy` destroys the condition variable pointed to by cond. If there are threads waiting on cond, the behavior is undefined.