NAME | SYNOPSIS | DESCRIPTION | RETURN VALUES | ERRORS | EXAMPLES | ATTRIBUTES | SEE ALSO | NOTES
cc -mt [ flag... ] file...[ library... ] #include <thread.h> #include <synch.h>int cond_init(cond_t *cvp, int type, void *arg);
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.
Condition variables' attributes may be set to the default or customized at initialization.
cond_init() 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 via arg . type may be one of the following:
The condition variable can synchronize threads only in this process. This is the default.
The condition variable can synchronize threads in this process and other processes. Only one process should initialize the condition variable. The object initialized with this attribute must be allocated 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 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.
cond_wait() 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() .
cond_wait() and cond_timedwait() always return with the mutex locked and owned by the calling thread even when returning an error.
A condition signal allows a thread to unblock the next thread waiting on the condition variable, whereas, a condition broadcast allows a thread to unblock all threads waiting on the condition variable.
cond_signal() unblocks one thread that is blocked on the condition variable pointed to by cvp .
cond_broadcast() 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.
Both functions should be called under the protection of the same mutex that is used with the condition variable being signaled. Otherwise, the condition variable may be signaled between the test of the associated condition and blocking in cond_wait() . This can cause an infinite wait.
The condition destroy functions destroy any state, but not the space, associated with the condition variable.
cond_destroy() 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.
These functions may fail if:
cond , attr , cvp , arg , abstime , or mutex point to an illegal address.
Invalid argument. For cond_init() , type is not a recognized type. For cond_timedwait() , the specified number of seconds, abstime , is greater than current_time + 100,000,000 , where current_time is the current time, or the number of nanoseconds is greater than or equal to 1,000,000,000 .
The cond_timedwait() function may fail if:
The time specified by abstime has passed.
(void) mutex_lock(mp); while (cond == FALSE) { (void) cond_wait(cvp, mp); } (void) mutex_unlock(mp);
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 == ETIMEDOUT) { /* 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) , condition(3THR) , mutex(3THR) , signal(3C) , attributes(5) , standards(5)
The only policy currently supported is SCHED_OTHER . In Solaris, under the SCHED_OTHER policy, there is no established order in which threads are unblocked.
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() or cond_timedwait() . The thread(s) that are unblocked compete for the mutex according to the scheduling policy, and as if each had called mutex_lock(3THR) .
When cond_wait() returns the value of the condition is indeterminate and must be reevaluated.
cond_timedwait() is 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 . Note that cond_timedwait() may continue to block as it trys to reacquire the mutex pointed to by mp , which may be locked by another thread. If abstime then cond_timedwait() returns because of a timeout, it returns the error code ETIME .
NAME | SYNOPSIS | DESCRIPTION | RETURN VALUES | ERRORS | EXAMPLES | ATTRIBUTES | SEE ALSO | NOTES