man.bsd.lv manual page server

Manual Page Search Parameters
CONDVAR(9) Kernel Developer's Manual CONDVAR(9)

condvar, cv_init, cv_destroy, cv_wait, cv_wait_sig, cv_timedwait, cv_timedwait_sig, cv_mtx_wait, cv_mtx_wait_sig, cv_mtx_timedwait, cv_mtx_timedwait_sig, cv_signal, cv_broadcast, cv_broadcastprikernel condition variable

#include <sys/param.h>
#include <sys/systm.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 lock *l);

int
cv_wait_sig(struct cv *cvp, struct lock *l);

int
cv_timedwait(struct cv *cvp, struct lock *l, int timo);

int
cv_timedwait_sig(struct cv *cvp, struct lock *l, int timo);

void
cv_mtx_wait(struct cv *cvp, struct mtx *m);

int
cv_mtx_wait_sig(struct cv *cvp, struct mtx *m);

int
cv_mtx_timedwait(struct cv *cvp, struct mtx *m, int timo);

int
cv_mtx_timedwait_sig(struct cv *cvp, struct mtx *m, int timo);

void
cv_signal(struct cv *cvp);

void
cv_broadcast(struct cv *cvp);

void
cv_broadcastpri(struct cv *cvp, int pri);

Condition variables are used in conjunction with locks to wait for conditions to occur. Condition variables are created with (), 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 condition variable. Condition variables are destroyed with (). Threads wait on condition variables by calling cv_wait(), cv_wait_sig(), cv_timedwait(), or cv_timedwait_sig(). Threads unblock waiters by calling () to unblock one waiter, or () or () to unblock all waiters. cv_broadcastpri() is a synonym for cv_broadcast() in DragonFly and discards the pri parameter.

A thread must hold l before calling (), (), (), or (). When a thread waits on a condition, l is atomically released before the thread is blocked, then atomically reacquired before the function call returns. All waiters must pass the same l in conjunction with cvp.

When (), (), (), and () 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().

(), (), (), and () work the same as cv_wait(), cv_wait_sig(), cv_timedwait(), and cv_timedwait_sig() except that they take struct mtx argument m.

Condition variables exist primarily for code imported from other systems; for DragonFly code, the tsleep() / wakeup() family of functions should be used instead.

If successful, cv_wait_sig(), cv_timedwait(), cv_timedwait_sig() cv_mtx_wait_sig(), cv_mtx_timedwait(), and cv_mtx_timedwait_sig() return 0. Otherwise, a non-zero error code is returned.

Condition variables are implemented in /sys/kern/kern_condvar.c. The public interface and structure is found in /sys/sys/condvar.h.

locking(9), lockmgr(9), mutex(9), tsleep(9)

Condition variables appeared in DragonFly 2.7.

This manual page was written by Jason Evans for FreeBSD.

June 29, 2018 DragonFly-5.6.1