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 *cond,
pthread_mutex_t *mutex
);
int pthread_cond_timedwait(
pthread_cond_t *cond,
pthread_mutex_t *mutex,
const struct timespec *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 indicated 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 calling 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()
Hewlett-Packard Company - 1 - HP-UX Release 11.00: October 1997
pthread_cond_wait(3T) pthread_cond_wait(3T)
Pthread Library
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 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
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, cancellation 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 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
Upon successful completion, pthread_cond_wait() and
pthread_cond_timedwait() return zero. Otherwise, an error number is
returned to indicate the error (the errno variable is not set).
ERRORS
If any of the following occur, the pthread_cond_timedwait() function
returns the corresponding error number.
[ETIMEDOUT] abstime has passed and a condition signal has not
been received.
For each of the following conditions, if the condition is detected,
the pthread_cond_wait() and pthread_cond_timedwait() functions return
the corresponding error number:
Hewlett-Packard Company - 2 - HP-UX Release 11.00: October 1997
pthread_cond_wait(3T) pthread_cond_wait(3T)
Pthread Library
[EINVAL] 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 PTHREAD_MUTEX_NORMAL
or PTHREAD_MUTEX_DEFAULT mutex on HP-UX.
[EFAULT] cond, mutex or abstime parameter points to an
illegal address.
[EINVAL] Different mutexes are being used for cond. This
error is not detected on HP-UX.
WARNINGS
It is important to note that when pthread_cond_wait() or
pthread_cond_timedwait() return without error, the associated
predicate may still be false. When pthread_cond_timedwait() 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
PTHREAD_MUTEX_RECURSIVE mutex.
EXAMPLES
pthread_cond_wait() 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.
pthread_mutex_t mutex = PTHREAD_MUTEX_INITIALIZER;
pthread_cond_t cond = PTHREAD_COND_INITIALIZER;
(void)pthread_mutex_lock(&mutex);
while (predicate == FALSE) {
(void)pthread_cond_wait(&cond, &mutex);
}
(void)pthread_mutex_unlock(&mutex);
pthread_cond_timedwait() 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.
pthread_mutex_t mutex = PTHREAD_MUTEX_INITIALIZER;
pthread_cond_t cond = PTHREAD_COND_INITIALIZER;
struct timespec abstime;
(void)pthread_mutex_lock(&mutex);
pthread_cond_wait(3T) pthread_cond_wait(3T)
Pthread Library
abstime = absolute time to timeout.
while (predicate == FALSE) {
ret = pthread_cond_timedwait(&cond, &mutex, &abstime);
if (ret == ETIMEDOUT) {
if (predicate == FALSE) {
/* Code for time-out condition */
} else {
/* success condition */
break;
}
}
}
(void)pthread_mutex_unlock(&mutex);
Code for success condition.
AUTHOR
pthread_cond_wait() and pthread_cond_timedwait() were derived from the
IEEE POSIX P1003.1c standard.
SEE ALSO
pthread_cond_init(3T), pthread_cond_signal(3T).
STANDARDS CONFORMANCE
pthread_cond_wait(): POSIX 1003.1c.
pthread_cond_timedwait(): POSIX 1003.1c.