CONDVAR(9) BSD Kernel Developer's Manual CONDVAR(9)NAME
condvar, cv_init, cv_destroy, cv_wait, cv_wait_sig, cv_timedwait,
cv_timedwait_sig, cv_signal, cv_broadcast, cv_broadcastpri — kernel con‐
dition variable
SYNOPSIS
#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_signal(struct cv *cvp);
void
cv_broadcast(struct cv *cvp);
void
cv_broadcastpri(struct cv *cvp, int pri);
DESCRIPTION
Condition variables are used in conjunction with locks to wait for condi‐
tions 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 condition 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. cv_broadcastpri() is a synonym for cv_broadcast() in DragonFly.
A thread must hold l before calling cv_wait(), cv_wait_sig(),
cv_timedwait(), or cv_timedwait_sig(). When a thread waits on a condi‐
tion, l is atomically released before the thread is blocked, then atomi‐
cally reacquired before the function call returns. All waiters must pass
the same l 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 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().
IMPLEMENTATION NOTES
Condition variables exist primarily for code imported from other systems;
for DragonFly code, the tsleep(/) wakeup() family of functions should be
used instead.
Condition variables can currently only release lockmgr(9) locks.
RETURN VALUES
If successful, cv_wait_sig(), cv_timedwait(), and cv_timedwait_sig()
return 0. Otherwise, a non-zero error code is returned.
FILES
Condition variables are implemented in /sys/kern/kern_condvar.c. The
public interface and structure is found in /sys/sys/condvar.h.
SEE ALSOlockmgr(9), tsleep(9)HISTORY
Condition variables appeared in DragonFly 2.7.
AUTHORS
This manual page was written by Jason Evans for FreeBSD.
BSD April 16, 2010 BSD