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 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. In addition to waking waiters, cv_broadcastpri() ensures that all of the waiters have a priority of at least pri by raising the priority of any threads that do not. cv_wmesg() returns the description 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.