pthread_cond_timedwait

Causes a thread to wait for a condition variable to be signaled or broadcasted such that it will awake after a specified period of time.

Syntax

pthread_cond_timedwait(
                       cond,
                       mutex,
                       abstime );
 



Argument         Data Type               Access

cond             opaque pthread_cond_t   modify

mutex            opaque pthread_mutex_t  modify

abstime          structure timespec      read

C Binding

#include 


int
pthread_cond_timedwait (
         pthread_cond_t   *cond,
         pthread_mutex_t   *mutex,
         const struct timespec   *abstime);

Arguments

cond

Condition variable that a thread waits on.

mutex

Mutex associated with the condition variable specified in cond.

abstime

Absolute time at which the wait expires, if the condition has not been signaled or broadcasted. See the pthread_get_expiration_np routine, which is used to obtain a value for this argument.

The abstime argument is specified in Universal Coordinated Time (UTC). In the UTC-based model, time is represented as seconds since the Epoch. The Epoch is defined as the time 0 hours, 0 minutes, 0 seconds, January 1st, 1970 UTC. Seconds since the Epoch is a value interpreted as the number of seconds between a specified time and the Epoch.

Description

• The specified condition variable is signaled or broadcasted.

• The current system clock time is greater than or equal to the time specified by the abstime argument.

This routine is identical to pthread_cond_wait, except that this routine can return before a condition variable is signaled or broadcasted; specifically, when a specified time expires. For more information, see the pthread_cond_wait description.

This routine atomically releases the mutex and causes the calling thread to wait on the condition. The atomicity is important, because it means the thread cannot miss a wakeup while the mutex is unlocked. When the timer expires or when the wait is satisfied as a result of some thread calling pthread_cond_signal or pthread_cond_ broadcast, the mutex is reacquired before returning to the caller.

If the current time equals or exceeds the expiration time, this routine returns immediately, without releasing the mutex or causing the current thread to wait. Your code should check the return status whenever this routine returns and take the appropriate action. Otherwise, waiting on the condition variable can become a nonblocking loop.

Call this routine after you lock the mutex specified in mutex. The results of this routine are unpredictable if this routine is called without first locking the mutex.

Return Values

Return        Description

0             Successful completion.

[EINVAL]      The value specified by cond,
              mutex, or abstime is invalid,
              or:

              Different mutexes are supplied for concurrent pthread_
              cond_timedwait operations or pthread_cond_wait
              operations on the same condition variable, or:

              The mutex was not owned by the current thread at the
              time of the call.

[ETIMEDOUT]   The time specified by abstime expired.

[ENOMEM]      DECthreads cannot acquire memory needed to block using
              a statically initialized condition variable.

Associated Routines

   pthread_cond_broadcast
   pthread_cond_destroy
   pthread_cond_init
   pthread_cond_signal
   pthread_cond_wait
   pthread_get_expiration_np