NAME

pthread_cond_init, pthread_cond_destroy, pthread_cond_wait, pthread_cond_timedwait, pthread_cond_broadcast, pthread_cond_signal — block and unblock threads with condition variables

SYNOPSIS

POSIX Threads Library (libpthread, -lpthread)
#include <pthread.h>

int
pthread_cond_init(pthread_cond_t *cond, const pthread_condattr_t *attr);

int
pthread_cond_destroy(pthread_cond_t *cond);

int
pthread_cond_wait(pthread_cond_t *cond, pthread_mutex_t *mutex);

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

int
pthread_cond_broadcast(pthread_cond_t *cond);

int
pthread_cond_signal(pthread_cond_t *cond);

DESCRIPTION

The pthread_cond_init() function creates a new condition variable with attributes specified by attr. If attr is NULL, the default attributes are used.

The pthread_cond_destroy() function frees the resources associated with the condition variable cond.

The pthread_cond_wait() function atomically blocks the current thread by waiting on the condition variable cond, and unlocks the mutex specified by mutex. The waiting thread unblocks only after another thread calls pthread_cond_broadcast() or pthread_cond_signal() with the same condition variable. The pthread_cond_timedwait() function does the same, but returns after the system time reaches abstime. In all cases, both functions then reacquire the lock on mutex before returning.

The pthread_cond_broadcast() function unblocks all threads waiting for the condition variable cond. The pthread_cond_signal() function unblocks at least one thread waiting for the condition variable cond.

RETURN VALUES

These functions return zero for success and positive error numbers for failure.

ERRORS

pthread_cond_init() fails if:

[EINVAL]: The value specified by attr is invalid.
[ENOMEM]: The process cannot allocate enough memory to create another condition variable.
[EAGAIN]: The system temporarily lacks the resources to create another condition variable.

The other functions fail if:

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

pthread_cond_destroy() additionally fails if:

[EBUSY]: The variable cond is locked by another thread.

pthread_cond_timedwait() additionally fails if:

[ETIMEDOUT]: The system time has reached or exceeded the time specified in abstime.

STANDARDS