condvar man page on NetBSD

Printed from http://www.polarhome.com/service/man/?qf=condvar&af=0&tf=2&of=NetBSD

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 operations.

     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 avail‐
	   able 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 calling 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 condi‐
	   tion 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 mil‐
	   liseconds to one suitable for cv_timedwait().  If the ticks argu‐
	   ment 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 func‐
	   tion (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 condi‐
	   tion 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 asser‐
	   tions, 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
[top]
                             _         _         _ 
                            | |       | |       | |     
                            | |       | |       | |     
                         __ | | __ __ | | __ __ | | __  
                         \ \| |/ / \ \| |/ / \ \| |/ /  
                          \ \ / /   \ \ / /   \ \ / /   
                           \   /     \   /     \   /    
                            \_/       \_/       \_/ 
More information is available in HTML format for server NetBSD

List of man pages available for NetBSD

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net