NAME
pthread_cond —
condition variable
interface
LIBRARY
POSIX Threads Library (libpthread, -lpthread)
SYNOPSIS
#include <pthread.h>
int
pthread_cond_init(
pthread_cond_t
* restrict cond,
const
pthread_condattr_t * restrict attr);
pthread_cond_t cond =
PTHREAD_COND_INITIALIZER
;
int
pthread_cond_destroy(
pthread_cond_t
*cond);
int
pthread_cond_broadcast(
pthread_cond_t
*cond);
int
pthread_cond_signal(
pthread_cond_t
*cond);
int
pthread_cond_wait(
pthread_cond_t
* restrict cond,
pthread_mutex_t * restrict
mutex);
int
pthread_cond_timedwait(
pthread_cond_t
* restrict cond,
pthread_mutex_t * restrict
mutex,
const struct
timespec * restrict abstime);
DESCRIPTION
Condition variables are intended to be used to communicate changes in the state
of data shared between threads. Condition variables are always associated with
a mutex to provide synchronized access to the shared data. A single predicate
should always be associated with a condition variable. The predicate should
identify a state of the shared data that must be true before the thread
proceeds.
The
pthread_cond_init() function creates a new condition
variable, with attributes specified with
attr. If
attr is
NULL
the default
attributes are used. The
pthread_cond_destroy() function
frees the resources allocated by the condition variable
cond.
The macro
PTHREAD_COND_INITIALIZER
can be used to
initialize a condition variable when it can be statically allocated and the
default attributes are appropriate. The effect is similar to calling
pthread_cond_init() with
attr
specified as
NULL
, except that no error checking is
done.
The difference between
pthread_cond_broadcast() and
pthread_cond_signal() is that the former unblocks all
threads waiting for the condition variable, whereas the latter blocks only one
waiting thread. If no threads are waiting on
cond,
neither function has any effect. If more than one thread is blocked on a
condition variable, the used scheduling policy determines the order in which
threads are unblocked. The same mutex used for waiting must be held while
calling either function. Although neither function strictly enforces this
requirement, undefined behavior may follow if the mutex is not held.
The
pthread_cond_wait() function atomically blocks the current
thread waiting on the condition variable specified by
cond, and unlocks the mutex specified by
mutex. The
pthread_cond_timedwait()
function behaves similarly, but unblocks also if the system time reaches the
time specified in
abstime, represented as
struct timespec (see
timespec(3)). With both
functions the waiting thread unblocks after another thread calls
pthread_cond_signal() or
pthread_cond_broadcast() with the same condition variable
and by holding the same
mutex that was associated with
cond by either one of the blocking functions. The
current thread holds the lock on
mutex upon return from
either function.
Note that a call to
pthread_cond_wait() or
pthread_cond_timedwait() may wake up spontaneously, without
a call to
pthread_cond_signal() or
pthread_cond_broadcast(). The caller should prepare for this
by invoking either function within a predicate loop that tests whether the
thread should proceed.
As noted, when calling either function that waits on a condition variable, a
temporary binding is established between the condition variable
cond and the mutex
mutex. During
this time, the effect of an attempt by any thread to wait on that condition
variable using a different mutex is undefined. The same mutex must be held
while broadcasting or signaling on
cond. Additionally,
the same mutex must be used for concurrent calls to
pthread_cond_wait() and
pthread_cond_timedwait(). Only when a condition variable is
known to be quiescent may an application change the mutex associated with it.
In this implementation, none of the functions enforce this requirement, but if
the mutex is not held or independent mutexes are used the resulting behaviour
is undefined.
RETURN VALUES
If successful, all functions return zero. Otherwise, an error number will be
returned to indicate the error.
ERRORS
The
pthread_cond_init() function may fail if:
-
-
- [
EINVAL
]
- The value specified by attr is
invalid.
The
pthread_cond_destroy() function may fail if:
-
-
- [
EBUSY
]
- The variable cond is locked by
another thread.
-
-
- [
EINVAL
]
- The value specified by cond is
invalid.
Both
pthread_cond_broadcast() and
pthread_cond_signal() may fail if:
-
-
- [
EINVAL
]
- The value specified by cond is
invalid.
Both
pthread_cond_wait() and
pthread_cond_timedwait() may fail if:
-
-
- [
EINVAL
]
- The value specified by cond or the
value specified by mutex is invalid.
-
-
- [
EPERM
]
- The value specified by mutex was not
locked in the condition wait.
The
pthread_cond_timedwait() function may additionally fail
if:
-
-
- [
ETIMEDOUT
]
- The system time has reached or exceeded the time specified
in abstime.
SEE ALSO
pthread(3),
pthread_barrier(3),
pthread_condattr(3),
pthread_mutex(3),
pthread_rwlock(3),
pthread_spin(3)
STANDARDS
These functions conform to
IEEE Std 1003.1-2001
(“POSIX.1”).