Provided by: freebsd-manpages_8.2-1_all bug


     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


     #include <sys/param.h>
     #include <sys/proc.h>
     #include <sys/condvar.h>

     cv_init(struct cv *cvp, const char *desc);

     cv_destroy(struct cv *cvp);

     cv_wait(struct cv *cvp, lock);

     cv_wait_sig(struct cv *cvp, lock);

     cv_wait_unlock(struct cv *cvp, lock);

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

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

     cv_signal(struct cv *cvp);

     cv_broadcast(struct cv *cvp);

     cv_broadcastpri(struct cv *cvp, int pri);

     const char *
     cv_wmesg(struct cv *cvp);


     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.  In addition, the thread will
     fully drop the Giant mutex (even if recursed) while the it is suspended and will reacquire
     the Giant mutex before the function returns.  The cv_wait_unlock() function does not
     reacquire the lock before returning.  Note that the Giant mutex may be specified as lock.
     However, Giant may not be used as lock for the cv_wait_unlock() function.  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


     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().


     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.


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