👤
Home Man
Search
Today's Posts
Register

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:
Select Section of Man Page:
Select Man Page Repository:

NetBSD 6.1.5 - man page for cv_wait_sig (netbsd section 9)

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

NAME
     cv, condvar, cv_init, cv_destroy, cv_wait, cv_wait_sig, cv_timedwait, cv_timedwait_sig,
     cv_signal, cv_broadcast, cv_has_waiters -- condition variables

SYNOPSIS
     #include <sys/condvar.h>

     void
     cv_init(kcondvar_t *cv, const char *wmesg);

     void
     cv_destroy(kcondvar_t *cv);

     void
     cv_wait(kcondvar_t *cv, kmutex_t *mtx);

     int
     cv_wait_sig(kcondvar_t *cv, kmutex_t *mtx);

     int
     cv_timedwait(kcondvar_t *cv, kmutex_t *mtx, int ticks);

     int
     cv_timedwait_sig(kcondvar_t *cv, kmutex_t *mtx, int ticks);

     void
     cv_signal(kcondvar_t *cv);

     void
     cv_broadcast(kcondvar_t *cv);

     bool
     cv_has_waiters(kcondvar_t *cv);

     options DIAGNOSTIC
     options LOCKDEBUG

DESCRIPTION
     Condition variables (CVs) are used in the kernel to synchronize access to resources that are
     limited (for example, memory) and to wait for pending I/O operations to complete.

     The kcondvar_t type provides storage for the CV object.  This should be treated as an opaque
     object and not examined directly by consumers.

OPTIONS
     options DIAGNOSTIC

	   Kernels compiled with the DIAGNOSTIC option perform basic sanity checks on CV opera-
	   tions.

     options LOCKDEBUG

	   Kernels compiled with the LOCKDEBUG option perform potentially CPU intensive sanity
	   checks on CV operations.

FUNCTIONS
     cv_init(cv, wmesg)

	   Initialize a CV for use.  No other operations can be performed on the CV until it has
	   been initialized.

	   The wmesg argument specifies a string of no more than 8 characters that describes the
	   resource or condition associated with the CV.  The kernel does not use this argument
	   directly but makes it available for utilities such as ps(1) to display.

     cv_destroy(cv)

	   Release resources used by a CV.  The CV must not be in use when it is destroyed, and
	   must not be used afterwards.

     cv_wait(cv, mtx)

	   Cause the current LWP to wait non-interruptably for access to a resource, or for an
	   I/O operation to complete.  The LWP will resume execution when awoken by another
	   thread using cv_signal() or cv_broadcast().

	   mtx specifies a kernel mutex to be used as an interlock, and must be held by the call-
	   ing LWP on entry to cv_wait().  It will be released once the LWP has prepared to
	   sleep, and will be reacquired before cv_wait() returns.

	   A small window exists between testing for availability of a resource and waiting for
	   the resource with cv_wait(), in which the resource may become available again.  The
	   interlock is used to guarantee that the resource will not be signalled as available
	   until the calling LWP has begun to wait for it.

	   Non-interruptable waits have the potential to deadlock the system, and so must be kept
	   short (typically, under one second).

     cv_wait_sig(cv, mtx)

	   As per cv_wait(), but causes the current LWP to wait interruptably.	If the LWP
	   receives a signal, or is interrupted by another condition such as its containing
	   process exiting, the wait is ended early and an error code returned.

	   If cv_wait_sig() returns as a result of a signal, the return value is ERESTART if the
	   signal has the SA_RESTART property.	If awoken normally, the value is zero, and EINTR
	   under all other conditions.

     cv_timedwait(cv, mtx, ticks)

	   As per cv_wait(), but will return early if a timeout specified by the ticks argument
	   expires.

	   ticks is an architecture and system dependent value related to the number of clock
	   interrupts per second.  See hz(9) for details.  The mstohz(9) macro can be used to
	   convert a timeout expressed in milliseconds to one suitable for cv_timedwait().  If
	   the ticks argument is zero, cv_timedwait() behaves exactly like cv_wait().

	   If the timeout expires before the LWP is awoken, the return value is EWOULDBLOCK.  If
	   awoken normally, the return value is zero.

     cv_timedwait_sig(cv, mtx, ticks)

	   As per cv_wait_sig(), but also accepts a timeout value and will return EWOULDBLOCK if
	   the timeout expires.

     cv_signal(cv)

	   Awaken one LWP (potentially among many) that is waiting on the specified condition
	   variable.  The mutex passed to the wait function (mtx) must also be held when calling
	   cv_signal().

	   (Note that cv_signal() is erroneously named in that it does not send a signal in the
	   traditional sense to LWPs waiting on a CV.)

     cv_broadcast(cv)

	   Awaken all LWPs waiting on the specified condition variable.  The mutex passed to the
	   wait function (mtx) must also be held when calling cv_broadcast().

     cv_has_waiters(cv)

	   Return true if one or more LWPs are waiting on the specified condition variable.

	   cv_has_waiters() cannot test reliably for interruptable waits.  It should only be used
	   to test for non-interruptable waits made using cv_wait().

	   cv_has_waiters() should only be used when making diagnostic assertions, and must be
	   called while holding the interlocking mutex passed to cv_wait().

EXAMPLES
     Consuming a resource:

	     /*
	      * Lock the resource.  Its mutex will also serve as the
	      * interlock.
	      */
	     mutex_enter(&res->mutex);

	     /*
	      * Wait for the resource to become available.
	      */
	     while (res->state == BUSY)
		     cv_wait(&res->condvar, &res->mutex);

	     /*
	      * It's now available to us.  Take ownership of the
	      * resource, and consume it.
	      */
	     res->state = BUSY;
	     mutex_exit(&res->mutex);
	     consume(res);

     Releasing a resource for the next consumer to use:

	     mutex_enter(&res->mutex);
	     res->state = IDLE;
	     cv_signal(&res->condvar);
	     mutex_exit(&res->mutex);

CODE REFERENCES
     The core of the CV implementation is in sys/kern/kern_condvar.c.

     The header file sys/sys/condvar.h describes the public interface.

SEE ALSO
     sigaction(2), errno(9), mb(9), mstohz(9), mutex(9), rwlock(9)

     Jim Mauro and Richard McDougall, Solaris Internals: Core Kernel Architecture, Prentice Hall,
     2001, ISBN 0-13-022496-0.

HISTORY
     The CV primitives first appeared in NetBSD 5.0.

BSD					   June 4, 2008 				      BSD


All times are GMT -4. The time now is 09:52 AM.

Unix & Linux Forums Content Copyrightę1993-2018. All Rights Reserved.
×
UNIX.COM Login
Username:
Password:  
Show Password