DragonFly On-Line Manual Pages

CONDVAR(9)            DragonFly Kernel Developer's Manual           CONDVAR(9)

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 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
     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
     locking(9), lockmgr(9), mutex(9), tsleep(9)

HISTORY
     Condition variables appeared in DragonFly 2.7.

AUTHORS
     This manual page was written by Jason Evans for FreeBSD.

DragonFly 5.3                    June 29, 2018                   DragonFly 5.3