Sun Microsystems, Inc. gratefully acknowledges The Open Group for
permission to reproduce portions of its copyrighted documentation.
Original documentation from The Open Group can be obtained online at
http://www.opengroup.org/bookstore/.

The Institute of Electrical and Electronics Engineers and The Open
Group, have given us permission to reprint portions of their
documentation.

In the following statement, the phrase ``this text'' refers to portions
of the system documentation.

Portions of this text are reprinted and reproduced in electronic form
in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition,
Standard for Information Technology -- Portable Operating System
Interface (POSIX), The Open Group Base Specifications Issue 6,
Copyright (C) 2001-2004 by the Institute of Electrical and Electronics
Engineers, Inc and The Open Group. In the event of any discrepancy
between these versions and the original IEEE and The Open Group
Standard, the original IEEE and The Open Group Standard is the referee
document. The original Standard can be obtained online at
http://www.opengroup.org/unix/online.html.

This notice shall appear on any product containing this material.

The contents of this file are subject to the terms of the
Common Development and Distribution License (the "License").
You may not use this file except in compliance with the License.

You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
or http://www.opensolaris.org/os/licensing.
See the License for the specific language governing permissions
and limitations under the License.

When distributing Covered Code, include this CDDL HEADER in each
file and include the License file at usr/src/OPENSOLARIS.LICENSE.
If applicable, add the following below this CDDL HEADER, with the
fields enclosed by brackets "[]" replaced with your own identifying
information: Portions Copyright [yyyy] [name of copyright owner]


Portions Copyright (c) 1995 IEEE. All Rights Reserved.
Copyright (c) 2001, The IEEE and The Open Group. All Rights Reserved.
Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved.

cond_init, cond_wait, cond_timedwait, cond_reltimedwait, cond_signal, cond_broadcast, cond_destroy - condition variables

cc -mt [ flag... ] file... [ library... ]
#include <thread.h>
#include <synch.h>

int cond_init(cond_t *cvp, int type, void *arg);

int cond_wait(cond_t *cvp, mutex_t *mp);

int cond_timedwait(cond_t *cvp, mutex_t *mp,
 timestruc_t *abstime);

int cond_reltimedwait(cond_t *cvp, mutex_t *mp,
 timestruc_t *reltime);

int cond_signal(cond_t *cvp);

int cond_broadcast(cond_t *cvp);

int cond_destroy(cond_t *cvp);

Condition variables and mutexes should be global. Condition variables that are allocated in writable memory can synchronize threads among processes if they are shared by the cooperating processes (see mmap(2)) and are initialized for this purpose.

The scope of a condition variable is either intra-process or inter-process. This is dependent upon whether the argument is passed implicitly or explicitly to the initialization of that condition variable. A condition variable does not need to be explicitly initialized. A condition variable is initialized with all zeros, by default, and its scope is set to within the calling process. For inter-process synchronization, a condition variable must be initialized once, and only once, before use.

A condition variable must not be simultaneously initialized by multiple threads or re-initialized while in use by other threads.

Attributes of condition variables can be set to the default or customized at initialization.

The cond_init() function initializes the condition variable pointed to by cvp. A condition variable can have several different types of behavior, specified by type. No current type uses arg although a future type may specify additional behavior parameters with arg. The type argument c take one of the following values: USYNC_THREAD

USYNC_PROCESS

Initializing condition variables can also be accomplished by allocating in zeroed memory, in which case, a type of USYNC_THREAD is assumed.

If default condition variable attributes are used, statically allocated condition variables can be initialized by the macro DEFAULTCV.

Default condition variable initialization (intra-process):

cond_t cvp;

cond_init(&cvp, NULL, NULL); /*initialize condition variable
 with default*/

or

cond_init(&cvp, USYNC_THREAD, NULL);

or

cond_t cond = DEFAULTCV;

Customized condition variable initialization (inter-process):

cond_init(&cvp, USYNC_PROCESS, NULL); /* initialize cv with
 inter-process scope */

The condition wait interface allows a thread to wait for a condition and atomically release the associated mutex that it needs to hold to check the condition. The thread waits for another thread to make the condition true and that thread's resulting call to signal and wakeup the waiting thread.

The cond_wait() function atomically releases the mutex pointed to by mp and causes the calling thread to block on the condition variable pointed to by cvp. The blocked thread may be awakened by cond_signal(), cond_broadcast(), or when interrupted by delivery of a UNIX signal or a fork().

The cond_wait(), cond_timedwait(), and cond_reltimedwait() functions always return with the mutex locked and owned by the calling thread even when returning an error, except when the mutex has the LOCK_ROBUST attribute and has been left irrecoverable by the mutex's last owner. The cond_wait(), cond_timedwait(), and cond_reltimedwait() functions return the appropriate error value if they fail to internally reacquire the mutex.

A condition signal allows a thread to unblock a single thread waiting on the condition variable, whereas a condition broadcast allows a thread to unblock all threads waiting on the condition variable.

The cond_signal() function unblocks one thread that is blocked on the condition variable pointed to by cvp.

The cond_broadcast() function unblocks all threads that are blocked on the condition variable pointed to by cvp.

If no threads are blocked on the condition variable, then cond_signal() and cond_broadcast() have no effect.

The cond_signal() or cond_broadcast() functions can be called by a thread whether or not it currently owns the mutex that threads calling cond_wait(), cond_timedwait(), or cond_reltimedwait() have associated with the condition variable during their waits. If, however, predictable scheduling behavior is required, then that mutex should be locked by the thread prior to calling cond_signal() or cond_broadcast().

The condition destroy functions destroy any state, but not the space, associated with the condition variable.

The cond_destroy() function destroys any state associated with the condition variable pointed to by cvp. The space for storing the condition variable is not freed.

Upon successful completion, these functions return 0. Otherwise, a non-zero value is returned to indicate the error.

The cond_timedwait() and cond_reltimedwait() functions will fail if: ETIME

The cond_wait(), cond_timedwait(), and cond_reltimedwait() functions will fail if: EINTR

If the mutex pointed to by mp is a robust mutex (initialized with the LOCK_ROBUST attribute), the cond_wait(), cond_timedwait() and cond_reltimedwait() functions will, under the specified conditions, return the following error values. For complete information, see the description of the mutex_lock() function on the mutex_init(3C) manual page. ENOTRECOVERABLE

EOWNERDEAD

These functions may fail if: EFAULT

EINVAL

Example 1 Use cond_wait() in a loop to test some condition.

The cond_wait() functin is normally used in a loop testing some condition, as follows:

(void) mutex_lock(mp);
while (cond == FALSE) {
 (void) cond_wait(cvp, mp);
}
(void) mutex_unlock(mp);

Example 2 Use cond_timedwait() in a loop to test some condition.

The cond_timedwait() function is normally used in a loop testing some condition. It uses an absolute timeout value as follows:

timestruc_t to;
...
(void) mutex_lock(mp);
to.tv_sec = time(NULL) + TIMEOUT;
to.tv_nsec = 0;
while (cond == FALSE) {
 err = cond_timedwait(cvp, mp, &to);
 if (err == ETIME) {
 /* timeout, do something */
 break;
 }
}
(void) mutex_unlock(mp);

Example 3 Use cond_reltimedwait() in a loop to test some condition.

The cond_reltimedwait() function is normally used in a loop testing in some condition. It uses a relative timeout value as follows:

timestruc_t to;
...
(void) mutex_lock(mp);
while (cond == FALSE) {
 to.tv_sec = TIMEOUT;
 to.tv_nsec = 0;
 err = cond_reltimedwait(cvp, mp, &to);
 if (err == ETIME) {
 /* timeout, do something */
 break;
 }
}
(void) mutex_unlock(mp);

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE ATTRIBUTE VALUE

MT-Level MT-Safe

fork(2), mmap(2), setitimer(2), shmop(2), mutex_init(3C), signal(3C), attributes(5), condition(5), mutex(5), standards(5)

If more than one thread is blocked on a condition variable, the order in which threads are unblocked is determined by the scheduling policy. When each thread, unblocked as a result of a cond_signal() or cond_broadcast(), returns from its call to cond_wait() or cond_timedwait() , the thread owns the mutex with which it called cond_wait(), cond_timedwait(), or cond_reltimedwait(). The thread(s) that are unblocked compete for the mutex according to the scheduling policy and as if each had called mutex_lock(3C).

When cond_wait() returns the value of the condition is indeterminate and must be reevaluated.

The cond_timedwait() and cond_reltimedwait() functions are similar to cond_wait(), except that the calling thread will not wait for the condition to become true past the absolute time specified by abstime or the relative time specified by reltime. Note that cond_timedwait() or cond_reltimedwait() might continue to block as it trys to reacquire the mutex pointed to by mp, which may be locked by another thread. If either cond_timedwait() or cond_reltimedwait() returns because of a timeout, it returns the error value ETIME.