pthread_cond_timedwait()

Wait on a condition variable, with a time limit

Synopsis:

#include <pthread.h>
#include <time.h>

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

Arguments:

cond
The condition variable on which to block the thread.
mutex
The mutex associated with the condition variable.
abstime
A pointer to a timespec structure that specifies the maximum time to block the thread, expressed as an absolute time.

Library:

libc

Use the -l c option to qcc to link against this library. This library is usually included automatically.

Description:

The pthread_cond_timedwait() function blocks the calling thread on the condition variable cond, and unlocks the associated mutex mutex. The calling thread must have locked mutex before waiting on the condition variable. Upon return from the function, the mutex is again locked and owned by the calling thread.

The calling thread is blocked until either another thread performs a signal or broadcast on the condition variable, the absolute time specified by abstime has passed, a signal is delivered to the thread, or the thread is canceled (waiting on a condition variable is a cancellation point). In all cases, the thread reacquires the mutex before being unblocked.

To specify the clock source for the condvar, call pthread_condattr_setclock(). As discussed in "Advanced topics" in the Clocks, Timers, and Getting a Kick Every So Often chapter of Getting Started with QNX Neutrino, CLOCK_MONOTONIC isn't affected by changes to the system time; the default, CLOCK_REALTIME, is.

Note: Don't use a recursive mutex with condition variables.

If a thread that's blocked on a condition variable is canceled, the thread reacquires the mutex that's guarding the condition variable, so that the thread's cleanup handlers run in the same state as the critical code before and after the call to this function. If some other thread owns the lock, the canceled thread blocks until the mutex is available.

Note:
  • Make sure that the thread's cleanup handlers unlock the mutex.
  • To specify a timeout of less than a second, obtain the current time using clock_gettime(), and then add the number of nanoseconds to the abstime.tv_nsec field.
  • You can use nsec2timespec() to convert times in nanoseconds to a timespec structure (and timespec2nsec() to convert them back again).

Returns:

EOK
Success, or the call was interrupted by a signal.
EAGAIN
Insufficient system resources are available to wait on the condition.
EFAULT
A fault occurred trying to access the buffers provided.
EINVAL
One or more of the following is true:
  • One or more of cond, mutex and abstime is invalid.
  • Concurrent waits or timed waits on cond used different mutexes.
EPERM
The current thread doesn't own the mutex.
ETIMEDOUT
The time specified by abstime has passed.

Examples:

Wait five seconds while trying to acquire control over a condition variable:

#include <errno.h>
#include <pthread.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <time.h>
#include <unistd.h>

pthread_mutex_t m = PTHREAD_MUTEX_INITIALIZER;
pthread_cond_t c;

int main(int argc, char* argv[])
{
    struct timespec to;
    int retval;
    pthread_condattr_t attr;

    fprintf(stderr, "starting...\n");

    /* Set up the condvar attributes to use CLOCK_MONOTONIC. */

    pthread_condattr_init( &attr);
    pthread_condattr_setclock( &attr, CLOCK_MONOTONIC);
    pthread_cond_init( &c, &attr);

    /*
     Here's the interesting bit; we'll wait for
     five seconds FROM NOW when we call 
     pthread_cond_timedwait().
    */
    clock_gettime(CLOCK_MONOTONIC, &to);
    to.tv_sec += 5;

    if ((retval = pthread_mutex_lock(&m))) {
        fprintf(stderr, "pthread_mutex_lock %s\n", 
                strerror(retval));

        exit(EXIT_FAILURE);
    }

    if ((retval = pthread_cond_timedwait(&c, &m, &to)))
    {
        fprintf(stderr, "pthread_cond_timedwait %s\n",
                strerror(retval));

        exit(EXIT_FAILURE);
    }

    if ((retval = pthread_mutex_unlock(&m))) {
        fprintf(stderr, "pthread_mutex_unlock %s\n", 
                strerror(retval));

        exit(EXIT_FAILURE);
    }
 
    return EXIT_SUCCESS;
}

Classification:

POSIX 1003.1 THR

Safety:  
Cancellation point Yes
Interrupt handler No
Signal handler Yes
Thread Yes