pthread_cond_wait(3T)pthread_cond_wait(3T)NAMEpthread_cond_wait(), pthread_cond_timedwait() - wait or timed wait on a
condition variable
SYNOPSIS
Parameters
cond Pointer to the condition variable to be waited on.
mutex Pointer to the mutex associated with the condition variable
cond.
abstime Absolute time at which the wait expires, even if the condi‐
tion has not been signaled or broadcast.
DESCRIPTION
The function is used to wait for the occurrence of a condition associ‐
ated with the condition variable cond.
The function is used to wait a limited amount of time for the occur‐
rence of a condition associated with the condition variable cond. The
abstime parameter specifies the time at which this function should time
out. If the absolute time specified by abstime passes and the indi‐
cated condition has not been signaled, the function returns an error to
the caller.
Note: abstime is the time at which the wait expires, not the length of
time the thread will wait.
The condition variabled denoted by cond must have been dynamically ini‐
tialized by a call to or statically initialized with the macro
Both functions should be called with mutex locked by the calling
thread. If mutex is not locked by the calling thread, undefined behav‐
ior will result. These functions atomically release mutex and cause
the calling thread to block on the condition variable cond. If another
thread is able to acquire the mutex after the about-to-block thread has
released it but before it has actually blocked, a subsequent call to or
by the other thread will behave as if it were issued after the about-
to-block thread has blocked.
When the condition is signaled or the timed wait expires, the caller is
unblocked and will reacquire mutex before returning. Whether these
functions succeed or fail, mutex will always be reacquired before
returning to the caller.
Using different mutexes for concurrent calls to these functions on the
same condition variable results in undefined behavior.
When using condition variables, there is a predicate associated with
the condition wait. If this predicate is false, the thread should per‐
form a condition wait. Spurious wakeups may occur when waiting on a
condition variable. A spurious wakeup occurs when a thread returns
from a condition wait when it should really continue waiting. A normal
signal being delivered to a thread may cause a spurious wakeup during a
condition wait. Since the return values from and do not imply anything
about the value of the predicate, the predicate should be re-evaluated.
A condition wait is a When the calling thread has deferred cancellation
enabled, cancellation requested will be acted upon. If a cancellation
request is acted upon while a thread is blocked in one of these func‐
tions, mutex is reacquired before calling the cancellation cleanup han‐
dlers. The cancellation cleanup handlers should release mutex so that
application deadlock does not occur. If the condition signal and the
cancellation request both occur, the canceled thread will not consume
the condition signal (i.e., a different thread will be unblocked due to
the condition signal).
If a signal is delivered to a thread waiting for a condition variable,
upon return from the signal handler, the thread may return zero due to
a spurious wakeup or continue waiting for the condition.
RETURN VALUE
and return the following values:
Successful completion.
Failure.
An error number is returned to indicate the error. (The
variable is not set.)
ERRORS
The following error value is returned by if the corresponding condition
is detected.
abstime has passed and a condition signal has not been
received.
One of the following error values is returned by and if the correspond‐
ing condition is detected.
A cond, mutex, or abstime parameter points to an
illegal address.
The value specified by
cond, mutex, or abstime is invalid.
mutex is not owned by the calling thread. This
error is not returned for a or mutex on HP-UX.
Different mutexes are being used for
cond. This error is not detected on HP-UX.
WARNINGS
It is important to note that when or return without error, the associ‐
ated predicate may still be false. When returns with the timeout
error, the associated predicate may be true. It is recommended that a
condition wait be enclosed in the equivalent of a "while loop," which
checks the predicate.
Undefined behavior results if these functions are called with a mutex.
EXAMPLES
is recommended to be used in a loop testing the predicate associated
with it. This will take care of any spurious wakeups that may occur.
is also recommended to be used in a loop. This function can return
success even if the predicate is not true. It should be called in a
loop while checking the predicate. If the function times out, the
predicate may still have become true. The predicate should be checked
before processing the timeout case. The example given below does not
do any other error checking.
AUTHOR
and were derived from the IEEE POSIX P1003.1c standard.
SEE ALSOpthread_cond_init(3T), pthread_cond_signal(3T).
STANDARDS CONFORMANCE
Pthread Library pthread_cond_wait(3T)
