NAME
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_broadcastpri —
kernel condition 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_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);
DESCRIPTION
Condition variables are used in conjunction with locks to wait for conditions to occur. Condition variables are created withcv_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 and discards the pri
parameter.
A thread must hold l before
calling
cv_wait(),
cv_wait_sig(),
cv_timedwait(),
or
cv_timedwait_sig().
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
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().
cv_mtx_wait(),
cv_mtx_wait_sig(),
cv_mtx_timedwait(),
and
cv_mtx_timedwait_sig()
work the same as cv_wait(),
cv_wait_sig(),
cv_timedwait(), and
cv_timedwait_sig() except that they take
struct mtx argument m.
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.
RETURN VALUES
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.
FILES
Condition variables are implemented in /sys/kern/kern_condvar.c. The public interface and structure is found in /sys/sys/condvar.h.
SEE ALSO
HISTORY
Condition variables appeared in DragonFly 2.7.
AUTHORS
This manual page was written by Jason Evans for FreeBSD.