Standard C Library Functions condinit(3C)
NAME
condinit, condwait, condtimedwait, condreltimedwait,
condsignal, condbroadcast, conddestroy - condition vari-
ables
SYNOPSIS
cc -mt [ flag... ] file... [ library... ]
#include
#include
int condinit(condt *cvp, int type, void *arg);
int condwait(condt *cvp, mutext *mp);
int condtimedwait(condt *cvp, mutext *mp,
timestruct *abstime);
int condreltimedwait(condt *cvp, mutext *mp,
timestruct *reltime);
int condsignal(condt *cvp);
int condbroadcast(condt *cvp);
int conddestroy(condt *cvp);
DESCRIPTION
Initialize
Condition variables and mutexes should be global. Condition
variables 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 need
to be explicitly initialized. A condition variable is ini-
tialized with all zeros, by default, and its scope is set to
within 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 condinit(3C)
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 condinit() 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:
USYNCTHREAD The condition variable can synchronize
threads only in this process. This is the
default.
USYNCPROCES The condition variable can synchronize
threads in this process and other
processes. 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 of
USYNCTHREAD 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):
condt cvp;
condinit(&cvp, NUL, NUL); /*initialize condition variable
with default*/
SunOS 5.11 Last change: 5 Jun 2007 2
Standard C Library Functions condinit(3C)
or
condinit(&cvp, USYNCTHREAD, NUL);
or
condt cond = DEFAULTCV;
Customized condition variable initialization (inter-
process):
condinit(&cvp, USYNCPROCES, NUL); /* 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 condwait() 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 condsignal(), condbroadcast(), or when
interrupted by delivery of a UNIX signal or a fork().
The condwait(), condtimedwait(), and condreltimedwait()
functions always return with the mutex locked and owned by
the calling thread even when returning an error, except when
the mutex has the LOCKROBUST attribute and has been left
irrecoverable by the mutex's last owner. The condwait(),
condtimedwait(), and condreltimedwait() 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 single
thread 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 condinit(3C)
The condsignal() function unblocks one thread that is
blocked on the condition variable pointed to by cvp.
The condbroadcast() 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
condsignal() and condbroadcast() have no effect.
The condsignal() or condbroadcast() functions can be
called by a thread whether or not it currently owns the
mutex that threads calling condwait(), condtimedwait(), or
condreltimedwait() have associated with the condition vari-
able during their waits. If, however, predictable scheduling
behavior is required, then that mutex should be locked by
the thread prior to calling condsignal() or
condbroadcast().
Destroy
The condition destroy functions destroy any state, but not
the space, associated with the condition variable.
The conddestroy() 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.
ERORS
The condtimedwait() and condreltimedwait() functions will
fail if:
ETIME The time specified by abstime or reltime has
passed.
The condwait(), condtimedwait(), and condreltimedwait()
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 condinit(3C)
If the mutex pointed to by mp is a robust mutex (initialized
with the LOCKROBUST attribute), the condwait(),
condtimedwait() and condreltimedwait() functions will,
under the specified conditions, return the following error
values. For complete information, see the description of
the mutexlock() function on the mutexinit(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 condinit(), type is not a
recognized type. For condtimedwait(), the number
of nanoseconds is greater than or equal to
1,000,000,000.
EXAMPLES
Example 1 Use condwait() in a loop to test some condition.
The condwait() functin is normally used in a loop testing
some condition, as follows:
(void) mutexlock(mp);
while (cond == FALSE) {
(void) condwait(cvp, mp);
}
(void) mutexunlock(mp);
Example 2 Use condtimedwait() in a loop to test some condi-
tion.
The condtimedwait() function is normally used in a loop
testing some condition. It uses an absolute timeout value
SunOS 5.11 Last change: 5 Jun 2007 5
Standard C Library Functions condinit(3C)
as follows:
timestruct to;
...
(void) mutexlock(mp);
to.tvsec = time(NUL) ] TIMEOUT;
to.tvnsec = 0;
while (cond == FALSE) {
err = condtimedwait(cvp, mp, &to);
if (err == ETIME) {
/* timeout, do something */
break;
}
}
(void) mutexunlock(mp);
Example 3 Use condreltimedwait() in a loop to test some
condition.
The condreltimedwait() function is normally used in a loop
testing in some condition. It uses a relative timeout value
as follows:
timestruct to;
...
(void) mutexlock(mp);
while (cond == FALSE) {
to.tvsec = TIMEOUT;
to.tvnsec = 0;
err = condreltimedwait(cvp, mp, &to);
if (err == ETIME) {
/* timeout, do something */
break;
}
}
(void) mutexunlock(mp);
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
SunOS 5.11 Last change: 5 Jun 2007 6
Standard C Library Functions condinit(3C)
ATRIBUTE TYPE ATRIBUTE VALUE
MT-Level MT-Safe
SEE ALSO
fork(2), mmap(2), setitimer(2), shmop(2), mutexinit(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 a
result of a condsignal() or condbroadcast(), returns from
its call to condwait() or condtimedwait() , the thread
owns the mutex with which it called condwait(),
condtimedwait(), or condreltimedwait(). The thread(s) that
are unblocked compete for the mutex according to the
scheduling policy and as if each had called mutexlock(3C).
When condwait() returns the value of the condition is
indeterminate and must be reevaluated.
The condtimedwait() and condreltimedwait() functions are
similar to condwait(), 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 condtimedwait() or condreltimedwait()
might continue to block as it trys to reacquire the mutex
pointed to by mp, which may be locked by another thread. If
either condtimedwait() or condreltimedwait() returns
because of a timeout, it returns the error value ETIME.
SunOS 5.11 Last change: 5 Jun 2007 7
|
