PTHREAD_COND(3) | Library Functions Manual | PTHREAD_COND(3) |
pthread_cond
, pthread_cond_init
,
pthread_cond_destroy
,
pthread_cond_broadcast
,
pthread_cond_signal
,
pthread_cond_wait
,
pthread_cond_timedwait
—
#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);
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 unblocks
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.
pthread_cond_init
() function may fail if:
EINVAL
]The pthread_cond_destroy
() function may
fail if:
EBUSY
]EINVAL
]Both pthread_cond_broadcast
() and
pthread_cond_signal
() may fail if:
EINVAL
]Both pthread_cond_wait
() and
pthread_cond_timedwait
() may fail if:
EINVAL
]EPERM
]The pthread_cond_timedwait
() function may
additionally fail if:
ETIMEDOUT
]July 8, 2010 | NetBSD 9.0 |