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.
     The cv_wait_unlock() function does	not reacquire the lock before return-
     ing.  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)

FreeBSD	9.2			 June 5, 2007			   FreeBSD 9.2

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.0-RELEASE>

home | help