HP-UX Reference (11i v3 07/02) - 3 Library Functions N-Z (vol 7)

p
pthread_cond_wait(3T) pthread_cond_wait(3T)
(Pthread Library)
NAME
pthread_cond_wait(), pthread_cond_timedwait() - wait or timed wait on a condition variable
SYNOPSIS
#include <pthread.h>
int pthread_cond_wait(
pthread_cond_t *__restrict
cond,
pthread_mutex_t *__restrict
mutex
);
int pthread_cond_timedwait(
pthread_cond_t *__restrict
cond,
pthread_mutex_t *__restrict
mutex,
const struct timespec *__restrict
abstime
);
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 condition has not been signaled or broadcast.
DESCRIPTION
The
pthread_cond_wait()
function is used to wait for the occurrence of a condition associated with
the condition variable cond.
The
pthread_cond_timedwait()
function is used to wait a limited amount of time for the
occurrence 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 initialized by a call to
pthread_cond_init()
or statically initialized with the macro PTHREAD_COND_INITIALIZER.
Both functions should be called with mutex locked by the calling thread. If mutex is not locked by the cal-
ling thread, undefined behavior 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
pthread_cond_signal()
or pthread_cond_broadcast() 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 perform a condition wait. Spurious wakeups may occur when waiting on a condi-
tion 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 con-
dition wait. Since the return values from
pthread_cond_wait() and
pthread_cond_timedwait() do not imply anything about the value of the predicate, the predicate
should be re-evaluated.
A condition wait is a cancellation point. When the calling thread has deferred cancellation enabled, can-
cellation requested will be acted upon. If a cancellation request is acted upon while a thread is blocked in
one of these functions, mutex is reacquired before calling the cancellation cleanup handlers. The cancella-
tion cleanup handlers should release mutex so that application deadlock does not occur. If the condition sig-
nal 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.
180 Hewlett-Packard Company − 1 − HP-UX 11i Version 3: February 2007