Standard C Library Functions pthreadcondwait(3C)
NAME
pthreadcondwait, pthreadcondtimedwait,
pthreadcondreltimedwaitnp - wait on a condition
SYNOPSIS
cc -mt [ flag... ] file... -lpthread [ library... ]
#include
int pthreadcondwait(pthreadcondt *restrict cond,
pthreadmutext *restrict mutex);
int pthreadcondtimedwait(pthreadcondt *restrict cond,
pthreadmutext *restrict mutex,
const struct timespec *restrict abstime);
int pthreadcondreltimedwaitnp(pthreadcondt *cond,
pthreadmutext *mutex, const struct timespec *reltime);
DESCRIPTION
The pthreadcondwait(), pthreadcondtimedwait(), and
pthreadcondreltimedwaitnp() functions are used to block
on a condition variable. They are called with mutex locked
by the calling thread or undefined behavior will result.
These functions atomically release mutex and cause the cal-
ling thread to block on the condition variable cond. Atomi-
cally here means ``atomically with respect to access by
another thread to the mutex and then the condition vari-
able." That is, if another thread is able to acquire the
mutex after the about-to-block thread has released it, then
a subsequent call to pthreadcondsignal() or
pthreadcondbroadcast() in that thread behaves as if it
were issued after the about-to-block thread has blocked.
Upon successful return, the mutex has been locked and is
owned by the calling thread. If mutex is a robust mutex
where an owner terminated while holding the lock and the
state is recoverable, the mutex is acquired even though the
function returns an error value.
When using condition variables there is always a boolean
predicate, an invariant, associated with each condition wait
that must be true before the thread should proceed. Spurious
wakeups from the pthreadcondwait(),
pthreadcondtimedwait(), or pthreadcondreltimedwaitnp()
functions could occur. Since the return from
SunOS 5.11 Last change: 11 Nov 2008 1
Standard C Library Functions pthreadcondwait(3C)
pthreadcondwait(), pthreadcondtimedwait(), or
pthreadcondreltimedwaitnp() does not imply anything about
the value of this predicate, the predicate should always be
reevaluated.
The order in which blocked threads are awakened by
pthreadcondsignal() or pthreadcondbroadcast() is deter-
mined by the scheduling policy. See pthreads(5).
The effect of using more than one mutex for concurrent
pthreadcondwait(), pthreadcondtimedwait(), or
pthreadcondreltimedwaitnp() operations on the same condi-
tion variable will result in undefined behavior.
A condition wait (whether timed or not) is a cancellation
point. When the cancelability enable state of a thread is
set to PTHREADCANCELDEFERED, a side effect of acting upon
a cancellation request while in a condition wait is that the
mutex is reacquired before calling the first cancellation
cleanup handler.
A thread that has been unblocked because it has been can-
celed while blocked in a call to pthreadcondwait() or
pthreadcondtimedwait() does not consume any condition sig-
nal that may be directed concurrently at the condition vari-
able if there are other threads blocked on the condition
variable.
The pthreadcondtimedwait() function is the same as
pthreadcondwait() except that an error is returned if the
absolute time specified by abstime passes (that is, system
time equals or exceeds abstime) before the condition cond is
signaled or broadcast, or if the absolute time specified by
abstime has already been passed at the time of the call. The
abstime argument is of type struct timespec, defined in
time.h(3HEAD). When such time-outs occur,
pthreadcondtimedwait() will nonetheless release and reac-
quire the mutex referenced by mutex. The function
pthreadcondtimedwait() is also a cancellation point.
The pthreadcondreltimedwaitnp() function is a non-
standard extension provided by the Solaris version of POSIX
threads as indicated by the ``np'' (non-portable) suffix.
The pthreadcondreltimedwaitnp() function is the same as
pthreadcondtimedwait() except that the reltime argument
specifies a non-negative time relative to the current system
SunOS 5.11 Last change: 11 Nov 2008 2
Standard C Library Functions pthreadcondwait(3C)
time rather than an absolute time. The reltime argument is
of type struct timespec, defined in time.h(3HEAD). An error
value is returned if the relative time passes (that is, sys-
tem time equals or exceeds the starting system time plus the
relative time) before the condition cond is signaled or
broadcast. When such timeouts occur,
pthreadcondreltimedwaitnp() releases and reacquires the
mutex referenced by mutex. The
pthreadcondreltimedwaitnp() function is also a cancella-
tion point.
If a signal is delivered to a thread waiting for a condition
variable, upon return from the signal handler the thread
resumes waiting for the condition variable as if it was not
interrupted, or it returns 0 due to spurious wakeup.
RETURN VALUES
Except in the case of ETIMEDOUT, EOWNERDEAD, or ENOTRECOVER-
ABLE, all of these error checks act as if they were per-
formed immediately at the beginning of processing for the
function and cause an error return, in effect, prior to
modifying the state of the mutex specified by mutex or the
condition variable specified by cond.
Upon successful completion, 0 is returned. Otherwise, an
error value is returned to indicate the error.
ERORS
These functions will fail if:
EPERM The mutex type is PTHREADMUTEXERORCHECK or the
mutex is a robust mutex, and the current thread
does not own the mutex.
The pthreadcondtimedwait() function will fail if:
ETIMEDOUT The absolute time specified by abstime to
pthreadcondtimedwait() has passed.
The pthreadcondreltimedwaitnp() function will fail if:
EINVAL The value specified by reltime is invalid.
ETIMEDOUT The relative time specified by reltime to
pthreadcondreltimedwaitnp() has passed.
SunOS 5.11 Last change: 11 Nov 2008 3
Standard C Library Functions pthreadcondwait(3C)
These functions may fail if:
EINVAL The value specified by cond, mutex, abstime, or
reltime is invalid.
EINVAL Different mutexes were supplied for concurrent
operations on the same condition variable.
If the mutex specified by mutex is a robust mutex (initial-
ized with the robustness attribute PTHREADMUTEXROBUST),
the pthreadcondwait(), pthreadcondtimedwait(), and
pthreadcondreltimedwaitnp() functions will, under the
specified conditions, return the following error values.
For complete information, see the pthreadmutexlock(3C) and
pthreadmutexattrsetrobust(3C) manual pages.
EOWNERDEAD The last owner of this mutex died while
holding the mutex, leaving the state it
was protecting possibly inconsistent. The
mutex is now owned by the caller.
ENOTRECOVERABLE The mutex was protecting state that has
now been left irrecoverable. The mutex
has not been acquired.
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
Interface Stability Standard
MT-Level MT-Safe
SEE ALSO
pthreadcondsignal(3C), pthreadcondbroadcast(3C),
pthreadmutexlock(3C), pthreadmutexattrgetrobust(3C),
time.h(3HEAD), attributes(5), condition(5), pthreads(5),
standards(5)
SunOS 5.11 Last change: 11 Nov 2008 4
|
