DOC HOME SITE MAP MAN PAGES GNU INFO SEARCH PRINT BOOK
 

pthread_cond_wait(3pthread)


pthread_cond_wait, pthread_cond_timedwait -- wait on a condition variable

Synopsis

cc [options] -Kthread file

#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);

Description

pthread_cond_wait blocks the calling thread at the condition variable pointed to by cond to wait for the occurrence of a condition.

pthread_cond_timedwait, similar to pthread_cond_wait, blocks the calling thread at the condition variable pointed to by cond, to wait for the occurrence of a condition. However, if the absolute time denoted by abstime has passed and the indicated condition is not signaled, pthread_cond_timedwait returns ETIMEDOUT to the caller.

The calling thread must lock the mutual exclusion lock (mutex) pointed to by mutex before calling pthread_cond_wait or pthread_cond_timedwait, otherwise the behavior is unpredictable.

pthread_cond_wait or pthread_cond_timedwait atomically releases the mutex and waits on the condition variable cond. When the condition is signaled (via pthread_cond_signal) or a signal is delivered to a thread waiting for a condition variable, pthread_cond_wait or pthread_cond_timedwait reacquires the mutex and returns zero. If the time expires, pthread_cond_timedwait returns ETIMEDOUT.

User-visible timers are not affected by a call to pthread_cond_timedwait.

The calling thread can resume execution when the condition is signaled or broadcast, a timeout occurs, or when interrupted. The logical condition should always be checked on return, as a return might not have been caused by a change in the condition.

cond and mutex must previously have been initialized (see pthread_cond_init(3pthread)).

mutex is a mutual exclusion variable protecting a shared resource associated with the condition represented by the condition variable, cond. The calling thread must lock mutex before calling pthread_cond_wait or pthread_cond_timedwait, otherwise the behavior is unpredictable.

abstime represents the time at which pthread_cond_timedwait should time out. The time is expressed in elapsed seconds and nanoseconds since Universal Coordinated Time, January 1, 1970. gettimeofday(2) returns the current time, but in seconds and microseconds. To construct abstime, convert the current time to a struct timespec, and add to that the waiting time.

A wait for a condition, either timed or untimed, is a cancelletion point. When the cancelability enable state of a thread is set to PTHREAD_CANCEL_DEFERRED, acting on a cancellation request while in a condition wait causes the mutex to be reacquired before calling the first cancellation cleanup handler. The behavior is as if the thread were unblocked, allowed to execute up to the return from the call to pthread_cond_wait or pthread_cond_timedwait, but at that point sees the cancellation request and starts the thread cancellation activities, instead of returning to the caller. (See pthread_cancel(3pthread).)

Because the condition can change between the time the condition is signaled and the mutex is relocked, the calling thread must always recheck the condition upon return from pthread_cond_wait or pthread_cond_timedwait.

Return values

pthread_cond_wait and pthread_cond_timedwait return zero for success and an error number for failure.

Diagnostics

If any of the following conditions is detected, pthread_cond_wait and pthread_cond_timedwait return the corresponding value:

EINVAL
invalid argument specified
If the following condition is detected pthread_cond_timedwait returns the corresponding value:

ETIMEDOUT
time specified by abstime has passed

References

pthread_cond_broadcast(3pthread), pthread_cond_destroy(3pthread), pthread_cond_init(3pthread), pthread_cond_signal(3pthread), gettimeofday(2), Intro(3pthread),

Standards compliance

The Single UNIX Specification, Version 2; The Open Group.
© 2004 The SCO Group, Inc. All rights reserved.
UnixWare 7 Release 7.1.4 - 25 April 2004