Provided by: freebsd-manpages_7.0-2_all bug

NAME

     condvar, cv_init, cv_destroy, cv_wait, cv_wait_sig, cv_wait_unlock,
     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, lock);

     int
     cv_wait_sig(struct cv *cvp, lock);

     void
     cv_wait_unlock(struct cv *cvp, lock);

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

     int
     cv_timedwait_sig(struct cv *cvp, lock, 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_wait_unlock(), 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().

     The lock argument is a pointer to either a mutex(9), rwlock(9), or sx(9)
     lock.  A mutex(9) argument must be initialized with MTX_DEF and not
     MTX_SPIN.  A thread must hold lock before calling cv_wait(),
     cv_wait_sig(), cv_wait_unlock(), cv_timedwait(), or cv_timedwait_sig().
     When a thread waits on a condition, lock is atomically released before
     the thread is blocked, then reacquired before the function call returns.
     The cv_wait_unlock() function does not reacquire the lock before
     returning.  All waiters must pass the same lock in conjunction with cvp.

     When cv_wait(), cv_wait_sig(), cv_wait_unlock(), 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]            A signal was caught and the system call should be
                        interrupted.

     [ERESTART]         A signal was caught and the system call should be
                        restarted.

     cv_timedwait() and cv_timedwait_sig() will fail if:

     [EWOULDBLOCK]      Timeout expired.

SEE ALSO

     locking(9), mtx_pool(9), mutex(9), rwlock(9), sema(9), sleep(9), sx(9)