No specific order of acquisition is guaranteed when more than one thread blocks on the condition variable.

Note - pthread_cond_wait() is a cancellation point. If a cancel is pending and the calling thread has cancellation enabled, the thread terminates and begins executing its cleanup handlers while continuing to hold the lock.

Return Values

pthread_cond_wait() returns zero after completing successfully. Any other return value indicates that an error occurred. When the following condition occurs, the function fails and returns the corresponding value.

EINVAL

The value specified by cv or mp is invalid.

Unblock One Thread

pthread_cond_signal(3THR)

Use pthread_cond_signal(3THR) to unblock one thread that is blocked on the condition variable pointed to by cv. (For Solaris threads, see "cond_signal(3THR)".)

Prototype:
int	pthread_cond_signal(pthread_cond_t *cv);

#include <pthread.h>

pthread_cond_t cv;
int ret;

/* one condition variable is signaled */
ret = pthread_cond_signal(&cv); 

Call pthread_cond_signal() under the protection of the same mutex used with the condition variable being signaled. Otherwise, the condition variable could be signaled between the test of the associated condition and blocking in pthread_cond_wait(), which can cause an infinite wait.

The scheduling policy determines the order in which blocked threads are awakened. For SCHED_OTHER, threads are awakened in priority order.

When no threads are blocked on the condition variable, calling pthread_cond_signal() has no effect.

Return Values

pthread_cond_signal() returns zero after completing successfully. Any other return value indicates that an error occurred. When the following condition occurs, the function fails and returns the corresponding value.

EINVAL

cv points to an illegal address.

Example 4-8 shows how to use pthread_cond_wait() and pthread_cond_signal().

Example 4-8 Using pthread_cond_wait() and pthread_cond_signal()

pthread_mutex_t count_lock;
pthread_cond_t count_nonzero;
unsigned count;

decrement_count()
{
    pthread_mutex_lock(&count_lock);
    while (count == 0)
        pthread_cond_wait(&count_nonzero, &count_lock);
    count = count - 1;
    pthread_mutex_unlock(&count_lock);
}

increment_count()
{
    pthread_mutex_lock(&count_lock);
    if (count == 0)
        pthread_cond_signal(&count_nonzero);
    count = count + 1;
    pthread_mutex_unlock(&count_lock);
}

Block Until a Specified Time

pthread_cond_timedwait(3THR)

Prototype:
int	pthread_cond_timedwait(pthread_cond_t *cv,
    pthread_mutex_t *mp, const struct timespec *abstime);

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

pthread_cond_t cv;
pthread_mutex_t mp;
timestruct_t abstime;
int ret;

/* wait on condition variable */
ret = pthread_cond_timedwait(&cv, &mp, &abstime); 

Use pthread_cond_timedwait(3THR) as you would use pthread_cond_wait(), except that pthread_cond_timedwait() does not block past the time of day specified by abstime. pthread_cond_timedwait() always returns with the mutex locked and owned by the calling thread, even when it is returning an error. (For Solaris threads, see "cond_timedwait(3THR)".)

The pthread_cond_timedwait() function blocks until the condition is signaled or until the time of day, specified by the last argument, has passed.

Note - pthread_cond_timedwait() is also a cancellation point.

Return Values

pthread_cond_timedwait() returns zero after completing successfully. Any other return value indicates that an error occurred. When either of the following conditions occurs, the function fails and returns the corresponding value.

EINVAL

cv or abstime points to an illegal address.

ETIMEDOUT

The time specified by abstime has passed.

The timeout is specified as a time of day so that the condition can be retested efficiently without recomputing the value, as shown in Example 4-9.

Example 4-9 Timed Condition Wait

pthread_timestruc_t to;
pthread_mutex_t m;
pthread_cond_t c;
...
pthread_mutex_lock(&m);
to.tv_sec = time(NULL) + TIMEOUT;
to.tv_nsec = 0;
while (cond == FALSE) {
    err = pthread_cond_timedwait(&c, &m, &to);
    if (err == ETIMEDOUT) {
        /* timeout, do something */
        break;
    }
}
pthread_mutex_unlock(&m);

Block For a Specified Interval

pthread_cond_reltimedwait_np(3THR)

Prototype:
int  pthread_cond_reltimedwait_np(pthread_cond_t *cv, 
    pthread_mutex_t *mp, 
   const struct timespec *reltime);

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

pthread_cond_t cv;
pthread_mutex_t mp;
timestruct_t reltime;
int ret;

/* wait on condition variable */
ret = pthread_cond_reltimedwait_np(&cv, &mp, &reltime); 

Use pthread_cond_reltimedwait_np(3THR) as you would use pthread_cond_timedwait(), except that pthread_cond_reltimedwait_np() takes a relative time interval rather than an absolute future time of day as the value of its last argument. pthread_cond_reltimedwait_np() always returns with the mutex locked and owned by the calling thread, even when it is returning an error. (For Solaris threads, see cond_reltimedwait(3THR).) The pthread_cond_reltimedwait_np() function blocks until the condition is signaled or until the time interval, specified by the last argument, has elapsed.

Note - pthread_cond_reltimedwait_np() is also a cancellation point.