cond_timedwait(SYNCH)

cond_timedwait -- wait on a condition variable for a limited time

Synopsis

   cc [options] -Kthread file
   
   #include <synch.h>
   

   int cond_timedwait(cond_t *cond, mutex_t *mutex, timestruc_t *abstime);

Description

cond_timedwait, similar to cond_wait(SYNCH), 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, cond_timedwait returns ETIME to the caller. The calling thread must lock the mutual exclusion lock (mutex) pointed to by mutex before calling cond_timedwait, otherwise the behavior is unpredictable.

cond_timedwait automatically releases the mutex, and waits on the condition variable cond. When the condition is signaled or the time expires, cond_timedwait reacquires the mutex and returns to the caller. The wait can also be interrupted by a UNIX system signal, in which case mutex is reacquired, the signal handler is called, and cond_timedwait returns EINTR.

User-visible timers are not affected by a call to 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 be checked on return, as a return might not have been caused by a change in the condition.

Parameters

cond: pointer to the condition variable to wait for
mutex: pointer to a locked mutex
abstime: absolute time at which to time out

cond parameter

The condition variable denoted by cond must previously have been initialized (see cond_init(SYNCH)).

mutex parameter

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 cond_wait, otherwise the behavior is unpredictable.

abstime parameter

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

Usage

See the description of how to use condition variables under USAGE on condition(SYNCH).

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 cond_timedwait.

Return values

cond_timedwait returns zero for success and an error number for failure.

Errors

If any of the following conditions is detected, cond_timedwait returns the corresponding value:

EINTR: the wait was interrupted by a UNIX system signal
EINVAL: invalid argument specified
EINVAL: abstime is NULL
ETIME: time specified by abstime has passed

References

condition(SYNCH), cond_broadcast(SYNCH), cond_destroy(SYNCH), cond_init(SYNCH), cond_signal(SYNCH), cond_wait(SYNCH), gettimeofday(S), Intro(SYNCH), mutex(SYNCH)