condvar(9)

NAME

condvar, cv_init, cv_destroy, cv_wait, cv_wait_sig,

cv_timedwait,
cv_timedwait_sig, cv_signal, cv_broadcast, cv_broadcastpri,

cv_wmesg kernel condition variable

SYNOPSIS

#include <sys/param.h>
#include <sys/proc.h>
#include <sys/condvar.h>
void
cv_init(struct cv *cvp, const char *desc);
void
cv_destroy(struct cv *cvp);
void
cv_wait(struct cv *cvp, struct mtx *mp);
int
cv_wait_sig(struct cv *cvp, struct mtx *mp);
int
cv_timedwait(struct cv *cvp, struct mtx *mp, int timo);
int
cv_timedwait_sig(struct cv *cvp, struct mtx *mp, int timo);
void
cv_signal(struct cv *cvp);
void
cv_broadcast(struct cv *cvp);
void
cv_broadcastpri(struct cv *cvp, int pri);
const char *
cv_wmesg(struct cv *cvp);

DESCRIPTION

Condition variables are used in conjunction with mutexes to

wait for conditions to occur. Condition variables are created with

cv_init(), where
cvp is a pointer to space for a struct cv, and desc is a

pointer to a
null-terminated character string that describes the condi

tion variable.
Condition variables are destroyed with cv_destroy().

Threads wait on
condition variables by calling cv_wait(), cv_wait_sig(),

cv_timedwait(),
or cv_timedwait_sig(). Threads unblock waiters by calling

cv_signal() to
unblock one waiter, or cv_broadcast() or cv_broadcastpri()

to unblock all
waiters. In addition to waking waiters, cv_broadcastpri()

ensures that
all of the waiters have a priority of at least pri by rais

ing the priority of any threads that do not. cv_wmesg() returns the de

scription
string of cvp, as set by the initial call to cv_init().

A thread must hold mp before calling cv_wait(),

cv_wait_sig(),
cv_timedwait(), or cv_timedwait_sig(). When a thread waits

on a condition, mp is atomically released before the thread is

blocked, then atomically reacquired before the function call returns. All

waiters must pass
the same mp in conjunction with cvp.

When cv_wait(), cv_wait_sig(), cv_timedwait(), and

cv_timedwait_sig()
unblock, their calling threads are made runnable.

cv_timedwait() and
cv_timedwait_sig() wait for at most timo / HZ seconds before

being
unblocked and returning EWOULDBLOCK; otherwise, they return

0.
cv_wait_sig() and cv_timedwait_sig() return prematurely with

a value of
EINTR or ERESTART if a signal is caught, or 0 if signaled

via cv_signal()
or cv_broadcast().

RETURN VALUES

If successful, cv_wait_sig(), cv_timedwait(), and

cv_timedwait_sig()
return 0. Otherwise, a non-zero error code is returned.

cv_wmesg() returns the description string that was passed to

cv_init().

ERRORS

cv_wait_sig() and cv_timedwait_sig() will fail if:

[EINTR] An unmasked signal was caught.

[ERESTART] A masked signal was caught.

cv_timedwait() and cv_timedwait_sig() will fail if:

[EWOULDBLOCK] Timeout expired.

SEE ALSO

msleep(9), mtx_pool(9), mutex(9), sema(9), sx(9)

BSD December 11, 2000

BSD