Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help 
CONDVAR(9)		    Kernel Developer's Manual		      CONDVAR(9)

NAME
     condvar,	cv_init,   cv_destroy,	 cv_wait,  cv_wait_sig,  cv_wait_unlock,
     cv_timedwait,  cv_timedwait_sbt,  cv_timedwait_sig,   cv_timedwait_sig_sbt,
     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_sbt(struct cv *cvp, lock, sbintime_t sbt, sbintime_t pr,
	 int flags);

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

     int
     cv_timedwait_sig_sbt(struct cv *cvp, lock, sbintime_t sbt, sbintime_t pr,
	 int flags);

     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 condi-
     tions 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-ter-
     minated  character string that describes the condition variable.  Condition
     variables are destroyed with cv_destroy().  Threads wait on condition vari-
     ables by  calling	cv_wait(),  cv_wait_sig(),  cv_wait_unlock(),  cv_timed-
     wait(),  or cv_timedwait_sig().  Threads unblock waiters by calling cv_sig-
     nal() to unblock one waiter, or cv_broadcast() or cv_broadcastpri() to  un-
     block  all  waiters.   In addition to waking waiters, cv_broadcastpri() en-
     sures 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 descrip-
     tion 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  re-
     turns.   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 wait-
     ers 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().

     cv_timedwait_sbt() and cv_timedwait_sig_sbt() functions take  sbt	argument
     instead  of  timo.   It allows to specify relative or absolute unblock time
     with higher resolution in form of sbintime_t.  The parameter pr  allows  to
     specify  wanted  absolute	event  precision.  The parameter flags allows to
     pass additional callout_reset_sbt() flags.

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 inter-
			rupted.

     [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
     callout(9),   locking(9),	 mtx_pool(9),	mutex(9),   rwlock(9),	sema(9),
     sleep(9), sx(9)

FreeBSD ports 15.quarterly	February 19, 2013		      CONDVAR(9)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=condvar&sektion=9&manpath=FreeBSD+15.1-RELEASE+and+Ports.quarterly>

home | help