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

FreeBSD Man Pages

Man Page or Keyword Search:
Man Architecture
Apropos Keyword Search (all sections) Output format
home | help
CONDVAR(9)	       FreeBSD Kernel Developer's Manual	    CONDVAR(9)

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 con-
     ditions 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 wait-
     ers, 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	con-
     junction 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)

FreeBSD	10.1			 June 5, 2007			  FreeBSD 10.1

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUES | ERRORS | SEE ALSO

Want to link to this manual page? Use this URL:
<http://www.freebsd.org/cgi/man.cgi?query=condvar&sektion=9&manpath=FreeBSD+7.4-RELEASE>

home | help