# pthread_cond_timedwait

## PROLOG



           This manual page is part of the POSIX Programmer's Manual.  The
           Linux implementation of this interface may differ (consult the
           corresponding Linux manual page for details of Linux behavior), or
           the interface may not be implemented on Linux.
    


## NAME



           pthread_cond_timedwait, pthread_cond_wait — wait on a condition
    


## SYNOPSIS



           #include <pthread.h>
    
           int pthread_cond_timedwait(pthread_cond_t *restrict _cond_ ,
               pthread_mutex_t *restrict _mutex_ ,
               const struct timespec *restrict _abstime_);
           int pthread_cond_wait(pthread_cond_t *restrict _cond_ ,
               pthread_mutex_t *restrict _mutex_);
    


## DESCRIPTION



           The _pthread_cond_timedwait_() and _pthread_cond_wait_() functions
           shall block on a condition variable. The application shall ensure
           that these functions are called with _mutex_ locked by the calling
           thread; otherwise, an error (for PTHREAD_MUTEX_ERRORCHECK and
           robust mutexes) or undefined behavior (for other mutexes) results.
    
           These functions atomically release _mutex_ and cause the calling
           thread to block on the condition variable _cond_ ; atomically here
           means ``atomically with respect to access by another thread to the
           mutex and then the condition variable''. That is, if another
           thread is able to acquire the mutex after the about-to-block
           thread has released it, then a subsequent call to
           _pthread_cond_broadcast_() or _pthread_cond_signal_() in that thread
           shall behave as if it were issued after the about-to-block thread
           has blocked.
    
           Upon successful return, the mutex shall have been locked and shall
           be owned by the calling thread. If _mutex_ is a robust mutex where
           an owner terminated while holding the lock and the state is
           recoverable, the mutex shall be acquired even though the function
           returns an error code.
    
           When using condition variables there is always a Boolean predicate
           involving shared variables associated with each condition wait
           that is true if the thread should proceed. Spurious wakeups from
           the _pthread_cond_timedwait_() or _pthread_cond_wait_() functions may
           occur. Since the return from _pthread_cond_timedwait_() or
           _pthread_cond_wait_() does not imply anything about the value of
           this predicate, the predicate should be re-evaluated upon such
           return.
    
           When a thread waits on a condition variable, having specified a
           particular mutex to either the _pthread_cond_timedwait_() or the
           _pthread_cond_wait_() operation, a dynamic binding is formed between
           that mutex and condition variable that remains in effect as long
           as at least one thread is blocked on the condition variable.
           During this time, the effect of an attempt by any thread to wait
           on that condition variable using a different mutex is undefined.
           Once all waiting threads have been unblocked (as by the
           _pthread_cond_broadcast_() operation), the next wait operation on
           that condition variable shall form a new dynamic binding with the
           mutex specified by that wait operation. Even though the dynamic
           binding between condition variable and mutex may be removed or
           replaced between the time a thread is unblocked from a wait on the
           condition variable and the time that it returns to the caller or
           begins cancellation cleanup, the unblocked thread shall always re-
           acquire the mutex specified in the condition wait operation call
           from which it is returning.
    
           A condition wait (whether timed or not) is a cancellation point.
           When the cancelability type of a thread is set to
           PTHREAD_CANCEL_DEFERRED, a side-effect of acting upon a
           cancellation request while in a condition wait is that the mutex
           is (in effect) re-acquired before calling the first cancellation
           cleanup handler. The effect is as if the thread were unblocked,
           allowed to execute up to the point of returning from the call to
           _pthread_cond_timedwait_() or _pthread_cond_wait_(), but at that point
           notices the cancellation request and instead of returning to the
           caller of _pthread_cond_timedwait_() or _pthread_cond_wait_(), starts
           the thread cancellation activities, which includes calling
           cancellation cleanup handlers.
    
           A thread that has been unblocked because it has been canceled
           while blocked in a call to _pthread_cond_timedwait_() or
           _pthread_cond_wait_() shall not consume any condition signal that
           may be directed concurrently at the condition variable if there
           are other threads blocked on the condition variable.
    
           The _pthread_cond_timedwait_() function shall be equivalent to
           _pthread_cond_wait_(), except that an error is returned if the
           absolute time specified by _abstime_ passes (that is, system time
           equals or exceeds _abstime_) before the condition _cond_ is signaled
           or broadcasted, or if the absolute time specified by _abstime_ has
           already been passed at the time of the call. When such timeouts
           occur, _pthread_cond_timedwait_() shall nonetheless release and re-
           acquire the mutex referenced by _mutex_ , and may consume a condition
           signal directed concurrently at the condition variable.
    
           The condition variable shall have a clock attribute which
           specifies the clock that shall be used to measure the time
           specified by the _abstime_ argument. The _pthread_cond_timedwait_()
           function is also a cancellation point.
    
           If a signal is delivered to a thread waiting for a condition
           variable, upon return from the signal handler the thread resumes
           waiting for the condition variable as if it was not interrupted,
           or it shall return zero due to spurious wakeup.
    
           The behavior is undefined if the value specified by the _cond_ or
           _mutex_ argument to these functions does not refer to an initialized
           condition variable or an initialized mutex object, respectively.
    


## RETURN VALUE



           Except for **[ETIMEDOUT]** , **[ENOTRECOVERABLE]** , and **[EOWNERDEAD]** , all
           these error checks shall act as if they were performed immediately
           at the beginning of processing for the function and shall cause an
           error return, in effect, prior to modifying the state of the mutex
           specified by _mutex_ or the condition variable specified by _cond_.
    
           Upon successful completion, a value of zero shall be returned;
           otherwise, an error number shall be returned to indicate the
           error.
    


## ERRORS



           These functions shall fail if:
    
           **ENOTRECOVERABLE**
                  The state protected by the mutex is not recoverable.
    
           **EOWNERDEAD**
                  The mutex is a robust mutex and the process containing the
                  previous owning thread terminated while holding the mutex
                  lock. The mutex lock shall be acquired by the calling
                  thread and it is up to the new owner to make the state
                  consistent.
    
           **EPERM** The mutex type is PTHREAD_MUTEX_ERRORCHECK or the mutex is
                  a robust mutex, and the current thread does not own the
                  mutex.
    
           The _pthread_cond_timedwait_() function shall fail if:
    
           **ETIMEDOUT**
                  The time specified by _abstime_ to _pthread_cond_timedwait_()
                  has passed.
    
           **EINVAL** The _abstime_ argument specified a nanosecond value less than
                  zero or greater than or equal to 1000 million.
    
           These functions may fail if:
    
           **EOWNERDEAD**
                  The mutex is a robust mutex and the previous owning thread
                  terminated while holding the mutex lock. The mutex lock
                  shall be acquired by the calling thread and it is up to the
                  new owner to make the state consistent.
    
           These functions shall not return an error code of **[EINTR]**.
    
           _The following sections are informative._
    


## EXAMPLES



           None.
    


## APPLICATION USAGE



           Applications that have assumed that non-zero return values are
           errors will need updating for use with robust mutexes, since a
           valid return for a thread acquiring a mutex which is protecting a
           currently inconsistent state is **[EOWNERDEAD]**.  Applications that
           do not check the error returns, due to ruling out the possibility
           of such errors arising, should not use robust mutexes. If an
           application is supposed to work with normal and robust mutexes, it
           should check all return values for error conditions and if
           necessary take appropriate action.
    


## RATIONALE



           If an implementation detects that the value specified by the _cond_
           argument to _pthread_cond_timedwait_() or _pthread_cond_wait_() does
           not refer to an initialized condition variable, or detects that
           the value specified by the _mutex_ argument to
           _pthread_cond_timedwait_() or _pthread_cond_wait_() does not refer to
           an initialized mutex object, it is recommended that the function
           should fail and report an **[EINVAL]** error.
    
       **Condition Wait Semantics**
           It is important to note that when _pthread_cond_wait_() and
           _pthread_cond_timedwait_() return without error, the associated
           predicate may still be false.  Similarly, when
           _pthread_cond_timedwait_() returns with the timeout error, the
           associated predicate may be true due to an unavoidable race
           between the expiration of the timeout and the predicate state
           change.
    
           The application needs to recheck the predicate on any return
           because it cannot be sure there is another thread waiting on the
           thread to handle the signal, and if there is not then the signal
           is lost. The burden is on the application to check the predicate.
    
           Some implementations, particularly on a multi-processor, may
           sometimes cause multiple threads to wake up when the condition
           variable is signaled simultaneously on different processors.
    
           In general, whenever a condition wait returns, the thread has to
           re-evaluate the predicate associated with the condition wait to
           determine whether it can safely proceed, should wait again, or
           should declare a timeout. A return from the wait does not imply
           that the associated predicate is either true or false.
    
           It is thus recommended that a condition wait be enclosed in the
           equivalent of a ``while loop'' that checks the predicate.
    
       **Timed Wait Semantics**
           An absolute time measure was chosen for specifying the timeout
           parameter for two reasons. First, a relative time measure can be
           easily implemented on top of a function that specifies absolute
           time, but there is a race condition associated with specifying an
           absolute timeout on top of a function that specifies relative
           timeouts. For example, assume that _clock_gettime_() returns the
           current time and _cond_relative_timed_wait_() uses relative
           timeouts:
    
               clock_gettime(CLOCK_REALTIME, &now)
               reltime = sleep_til_this_absolute_time -now;
               cond_relative_timed_wait(c, m, &reltime);
    
           If the thread is preempted between the first statement and the
           last statement, the thread blocks for too long. Blocking, however,
           is irrelevant if an absolute timeout is used. An absolute timeout
           also need not be recomputed if it is used multiple times in a
           loop, such as that enclosing a condition wait.
    
           For cases when the system clock is advanced discontinuously by an
           operator, it is expected that implementations process any timed
           wait expiring at an intervening time as if that time had actually
           occurred.
    
       **Cancellation and Condition Wait**
           A condition wait, whether timed or not, is a cancellation point.
           That is, the functions _pthread_cond_wait_() or
           _pthread_cond_timedwait_() are points where a pending (or
           concurrent) cancellation request is noticed. The reason for this
           is that an indefinite wait is possible at these points—whatever
           event is being waited for, even if the program is totally correct,
           might never occur; for example, some input data being awaited
           might never be sent. By making condition wait a cancellation
           point, the thread can be canceled and perform its cancellation
           cleanup handler even though it may be stuck in some indefinite
           wait.
    
           A side-effect of acting on a cancellation request while a thread
           is blocked on a condition variable is to re-acquire the mutex
           before calling any of the cancellation cleanup handlers. This is
           done in order to ensure that the cancellation cleanup handler is
           executed in the same state as the critical code that lies both
           before and after the call to the condition wait function. This
           rule is also required when interfacing to POSIX threads from
           languages, such as Ada or C++, which may choose to map
           cancellation onto a language exception; this rule ensures that
           each exception handler guarding a critical section can always
           safely depend upon the fact that the associated mutex has already
           been locked regardless of exactly where within the critical
           section the exception was raised. Without this rule, there would
           not be a uniform rule that exception handlers could follow
           regarding the lock, and so coding would become very cumbersome.
    
           Therefore, since _some_ statement has to be made regarding the state
           of the lock when a cancellation is delivered during a wait, a
           definition has been chosen that makes application coding most
           convenient and error free.
    
           When acting on a cancellation request while a thread is blocked on
           a condition variable, the implementation is required to ensure
           that the thread does not consume any condition signals directed at
           that condition variable if there are any other threads waiting on
           that condition variable. This rule is specified in order to avoid
           deadlock conditions that could occur if these two independent
           requests (one acting on a thread and the other acting on the
           condition variable) were not processed independently.
    
       **Performance of Mutexes and Condition Variables**
           Mutexes are expected to be locked only for a few instructions.
           This practice is almost automatically enforced by the desire of
           programmers to avoid long serial regions of execution (which would
           reduce total effective parallelism).
    
           When using mutexes and condition variables, one tries to ensure
           that the usual case is to lock the mutex, access shared data, and
           unlock the mutex. Waiting on a condition variable should be a
           relatively rare situation. For example, when implementing a read-
           write lock, code that acquires a read-lock typically needs only to
           increment the count of readers (under mutual-exclusion) and
           return. The calling thread would actually wait on the condition
           variable only when there is already an active writer. So the
           efficiency of a synchronization operation is bounded by the cost
           of mutex lock/unlock and not by condition wait. Note that in the
           usual case there is no context switch.
    
           This is not to say that the efficiency of condition waiting is
           unimportant. Since there needs to be at least one context switch
           per Ada rendezvous, the efficiency of waiting on a condition
           variable is important. The cost of waiting on a condition variable
           should be little more than the minimal cost for a context switch
           plus the time to unlock and lock the mutex.
    
       **Features of Mutexes and Condition Variables**
           It had been suggested that the mutex acquisition and release be
           decoupled from condition wait. This was rejected because it is the
           combined nature of the operation that, in fact, facilitates
           realtime implementations. Those implementations can atomically
           move a high-priority thread between the condition variable and the
           mutex in a manner that is transparent to the caller. This can
           prevent extra context switches and provide more deterministic
           acquisition of a mutex when the waiting thread is signaled. Thus,
           fairness and priority issues can be dealt with directly by the
           scheduling discipline.  Furthermore, the current condition wait
           operation matches existing practice.
    
       **Scheduling Behavior of Mutexes and Condition Variables**
           Synchronization primitives that attempt to interfere with
           scheduling policy by specifying an ordering rule are considered
           undesirable.  Threads waiting on mutexes and condition variables
           are selected to proceed in an order dependent upon the scheduling
           policy rather than in some fixed order (for example, FIFO or
           priority). Thus, the scheduling policy determines which thread(s)
           are awakened and allowed to proceed.
    
       **Timed Condition Wait**
           The _pthread_cond_timedwait_() function allows an application to
           give up waiting for a particular condition after a given amount of
           time. An example of its use follows:
    
               (void) pthread_mutex_lock(&t.mn);
                   t.waiters++;
                   clock_gettime(CLOCK_REALTIME, &ts);
                   ts.tv_sec += 5;
                   rc = 0;
                   while (! mypredicate(&t) && rc == 0)
                       rc = pthread_cond_timedwait(&t.cond, &t.mn, &ts);
                   t.waiters--;
                   if (rc == 0 || mypredicate(&t))
                       setmystate(&t);
               (void) pthread_mutex_unlock(&t.mn);
    
           By making the timeout parameter absolute, it does not need to be
           recomputed each time the program checks its blocking predicate. If
           the timeout was relative, it would have to be recomputed before
           each call.  This would be especially difficult since such code
           would need to take into account the possibility of extra wakeups
           that result from extra broadcasts or signals on the condition
           variable that occur before either the predicate is true or the
           timeout is due.
    


## FUTURE DIRECTIONS



           None.
    


* * *