CND(3C) | Standard C Library Functions | CND(3C) |
cnd
,
cnd_broadcast
, cnd_destroy
,
cnd_init
, cnd_signal
,
cnd_timedwait
, cnd_wait
— C11 condition variable functions
#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);
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.
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.
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.
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.
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.
cond_broadcast(3C), cond_destroy(3C), cond_init(3C), cond_signal(3C), cond_timedwait(3C), cond_wait(3C), threads.h(3HEAD), attributes(7), threads(7)
January 11, 2015 | OmniOS |