Standard C Library Functions cond_init(3C)
NAME
cond_init, cond_wait, cond_timedwait, cond_reltimedwait,
cond_signal, cond_broadcast, cond_destroy - condition vari-
ablesSYNOPSIS
cc -mt [ flag... ] file... [ library... ]
#include
#include
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);
DESCRIPTION
Initialize Condition variables and mutexes should be global. Conditionvariables that are allocated in writable memory can syn-
chronize 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 needto be explicitly initialized. A condition variable is ini-
tialized with all zeros, by default, and its scope is set towithin the calling process. For inter-process synchroniza-
tion, a condition variable must be initialized once, and only once, before use.SunOS 5.11 Last change: 5 Jun 2007 1
Standard C Library Functions cond_init(3C)
A condition variable must not be simultaneously initializedby 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 The condition variable can synchronize
threads only in this process. This is the default.USYNC_PROCESS The condition variable can synchronize
threads in this process and otherprocesses. Only one process should initial-
ize the condition variable. The object ini-
tialized with this attribute must be allo-
cated in memory shared between processes, either in System V shared memory (see shmop(2)) or in memory mapped to a file (see mmap(2)). It is illegal to initialize the object this way and to not allocate it in such shared memory. Initializing condition variables can also be accomplished by allocating in zeroed memory, in which case, a type ofUSYNC_THREAD is assumed.
If default condition variable attributes are used, stati-
cally 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*/SunOS 5.11 Last change: 5 Jun 2007 2
Standard C Library Functions cond_init(3C)
orcond_init(&cvp, USYNC_THREAD, NULL);
orcond_t cond = DEFAULTCV;
Customized condition variable initialization (inter-
process):cond_init(&cvp, USYNC_PROCESS, NULL); /* initialize cv with
inter-process scope */
Condition Wait 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 threadmay 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 whenthe 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 reac-
quire the mutex. Condition Signaling A condition signal allows a thread to unblock a singlethread waiting on the condition variable, whereas a condi-
tion broadcast allows a thread to unblock all threads wait-
ing on the condition variable.SunOS 5.11 Last change: 5 Jun 2007 3
Standard C Library Functions cond_init(3C)
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, thencond_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 themutex that threads calling cond_wait(), cond_timedwait(), or
cond_reltimedwait() have associated with the condition vari-
able during their waits. If, however, predictable scheduling behavior is required, then that mutex should be locked bythe thread prior to calling cond_signal() or
cond_broadcast().
Destroy 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.RETURN VALUES
Upon successful completion, these functions return 0. Other-
wise, a non-zero value is returned to indicate the error.
ERRORS
The cond_timedwait() and cond_reltimedwait() functions will
fail if: ETIME The time specified by abstime or reltime has passed.The cond_wait(), cond_timedwait(), and cond_reltimedwait()
functions will fail if: EINTR Interrupted. The calling thread was awakened by the delivery of a UNIX signal.SunOS 5.11 Last change: 5 Jun 2007 4
Standard C Library Functions cond_init(3C)
If the mutex pointed to by mp is a robust mutex (initializedwith 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 ofthe mutex_lock() function on the mutex_init(3C) manual page.
ENOTRECOVERABLE The mutex was protecting the state that has now been left irrecoverable. The mutex has not been acquired. EOWNERDEAD The last owner of the mutex died while holding the mutex, possibly leaving the state it was protecting inconsistent. The mutex is now owned by the caller. These functions may fail if:EFAULT The cond, attr, cvp, arg, abstime, or mutex argu-
ment points to an illegal address.EINVAL Invalid argument. For cond_init(), type is not a
recognized type. For cond_timedwait(), the number
of nanoseconds is greater than or equal to 1,000,000,000.EXAMPLES
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 condi-
tion.The cond_timedwait() function is normally used in a loop
testing some condition. It uses an absolute timeout valueSunOS 5.11 Last change: 5 Jun 2007 5
Standard C Library Functions cond_init(3C)
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);
ATTRIBUTES
See attributes(5) for descriptions of the following attri-
butes:SunOS 5.11 Last change: 5 Jun 2007 6
Standard C Library Functions cond_init(3C)
____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| MT-Level | MT-Safe |
|_____________________________|_____________________________|
SEE ALSO
fork(2), mmap(2), setitimer(2), shmop(2), mutex_init(3C),
signal(3C), attributes(5), condition(5), mutex(5), stan-
dards(5) NOTES 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 aresult 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 thescheduling 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 byreltime. 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. Ifeither cond_timedwait() or cond_reltimedwait() returns
because of a timeout, it returns the error value ETIME.SunOS 5.11 Last change: 5 Jun 2007 7