pthread_cond_timedwait()

Timed wait on condition variable

Synopsis:

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

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

Library:

libc

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.

You shouldn't use a recursive mutex with condition variables.

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 cond, mutex or abstime was invalid.
Concurrent waits or timed waits on cond used different mutexes.
The current thread doesn't own mutex.

ETIMEDOUT

The time specified by abstime has passed.

Examples:

Here's an extremely simple example that waits 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 = PTHREAD_COND_INITIALIZER;

void* t(void* x)
{
    int retval;

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

        exit(EXIT_FAILURE);
    }

    /*
     Let pthread_cond_timedwait() break out and try 
     to acquire mutex
    */
    fprintf(stderr, "sleeping...\n");
    sleep(30);

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

        exit(EXIT_FAILURE);
    }

    return 0;
}
    
int main(int argc, char* argv[])
{
    struct timespec to;
    int retval;

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

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

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

        exit(EXIT_FAILURE);
    }
    
    if (retval = pthread_create(0, 0, t, 0)) {
        fprintf(stderr, "pthread_create %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);
    }
    
    return EXIT_SUCCESS;
}

Classification:

POSIX 1003.1 (Threads)

See also:

pthread_cond_broadcast(), pthread_cond_init(), pthread_cond_signal(), pthread_cond_wait(), SyncCondvarWait(), TimerTimeout()