Tribblix: manual page: cnd.3c

CND(3C) Standard C Library Functions CND(3C)

NAME

cnd, cnd_broadcast, cnd_destroy, cnd_init, cnd_signal, cnd_timedwait,
cnd_wait - C11 condition variable functions

SYNOPSIS

#include <threads.h>

int
cnd_init(cnd_t *cnd);

void
cnd_destroy(cnd_t *cnd);

int
cnd_broadcast(cnd_t *cnd);

int
cnd_signal(cnd_t *cnd);

int
cnd_timedwait(cnd_t *restrict cnd, mtx_t *restrict mtx,
const struct timespec *abstime);

int
cnd_wait(cnd_t *restrict cnd, mtx_t *restrict mtx);

DESCRIPTION

The cnd family of functions implement condition variables which allow
threads within a process to wait until a condition occurs and be
signaled when it does. These functions behave similar to both the
POSIX threads and illumos threads; however, they have slightly
different call signatures and return values. For more information, see
threads(7). Importantly, they do not allow for inter-process
synchronization.

Creating and Destroy Condition Variables

The function cnd_init() initializes the condition variable referred to
by cnd. The condition variable is suitable for intra-process use.
Initializing an already initialized condition variable results in
undefined behavior.

The function cnd_destroy() destroys an initialized condition variable
at which point it is illegal to use it, though it may be initialized
again.

Condition Waiting

The function cond_wait() can be used to wait on a condition variable.
A thread that waits on a condition variable blocks until another thread
signals that the condition has changed, generally after making the
condition that was false, true.

The function cond_wait() atomically release the mutex pointed to by mtx
and blocks on the condition variable cond. When the thread returns, it
will once again be holding mtx and must check the current state of the
condition. There is no guarantee that another thread has not gotten in
and changed the value before being woken. In addition, a thread
blocking on a condition variable, may be woken spuriously, such as when
a signal is received or fork() is called .

The function cond_timedwait() allows a thread to block in a similar
fashion to cond_wait(), except that when the absolute time specified in
seconds since the epoch (based on CLOCK_REALTIME) in UTC, expires, then
the thread will be woken up. The timeout is specified in abstime.

Conditional Signaling

The cnd_signal() and cnd_broadcast() functions can be used to signal
threads waiting on the condition variable cnd that they should be woken
up and check the variable again. The cnd_signal() function will only
wake a single thread that is blocked on the condition variable cnd;
while cnd_broadcast() will wake up every thread waiting on the
condition variable cnd.

A thread calling either cnd_signal() or cnd_broadcast() is not required
to hold any of the mutexes that are associated with the condition
variable.

If there are no threads currently blocked in the condition variable cnd
then neither function has an effect.

RETURN VALUES

Upon successful completion, the cond_init() function returns
thrd_success. If insufficient memory was available, then thrd_nomem is
returned; otherwise, if any other error occurred, thrd_error is
returned.

Upon successful completion, the cond_broadcast(), cond_signal(), and
cond_wait() functions return thrd_success. Otherwise, they return
thrd_error to indicate that an error occurred and they were unable to
complete.

Upon successful completion, the cond_timedwait() function returns
thrd_success. If abstime expires without being signaled, it instead
returns thrd_timedout. Otherwise, thrd_error is returned to indicate
an error.

INTERFACE STABILITY

Standard

MT-LEVEL
MT-Safe