205 lines
5.2 KiB
Plaintext
205 lines
5.2 KiB
Plaintext
'\"macro stdmacro
|
|
.TH pthread_cond_wait 3P
|
|
.\"
|
|
.\" ----------------
|
|
.SH NAME
|
|
pthread_cond_init,
|
|
pthread_cond_signal, pthread_cond_broadcast,
|
|
pthread_cond_wait, pthread_cond_timedwait,
|
|
pthread_cond_destroy
|
|
\- condition variables
|
|
.\"
|
|
.\" ----------------
|
|
.Op c p a
|
|
.SH C SYNOPSIS
|
|
.nf
|
|
.ft 3
|
|
#include <pthread.h>
|
|
.HP
|
|
.ft 3
|
|
int pthread_cond_init(pthread_cond_t \(**cond,
|
|
.br
|
|
const pthread_condattr_t \(**attr);
|
|
.HP
|
|
.ft 3
|
|
int pthread_cond_signal(pthread_cond_t \(**cond);
|
|
.HP
|
|
.ft 3
|
|
int pthread_cond_broadcast(pthread_cond_t \(**cond);
|
|
.HP
|
|
.ft 3
|
|
int pthread_cond_wait(pthread_cond_t \(**cond,
|
|
.br
|
|
pthread_mutex_t \(**mutex);
|
|
.HP
|
|
.ft 3
|
|
int pthread_cond_timedwait(pthread_cond_t \(**cond,
|
|
.br
|
|
pthread_mutex_t \(**mutex, const struct timespec \(**abstime);
|
|
.HP
|
|
.ft 3
|
|
int pthread_cond_destroy(pthread_cond_t \(**cond);
|
|
.ft 1
|
|
.Op
|
|
.\"
|
|
.\" ----------------
|
|
.SH DESCRIPTION
|
|
Condition variables provide high performance synchronization
|
|
primitives to wait for or wake up threads waiting for certain
|
|
conditions to be satisfied.
|
|
Functions are provided to wait on a condition variable and to wake
|
|
up (signal) threads that are waiting on the condition variable.
|
|
.\"
|
|
.\" ----------------
|
|
.SS Initialize
|
|
Condition variables may be initialized either dynamically, by calling
|
|
.IR pthread_cond_init (),
|
|
or statically, via the macro
|
|
.BR PTHREAD_COND_INITIALIZER .
|
|
.\"
|
|
.PP
|
|
The personality of the condition variable is determined by the
|
|
attribute structure
|
|
.I attr
|
|
passed with the call to
|
|
.IR pthread_cond_init ().
|
|
These attributes are set by calls to
|
|
.I pthread_condattr_init()
|
|
and the various condition variable attribute functions.
|
|
If
|
|
.I attr
|
|
is null (or the condition variable is statically initialized)
|
|
the default attributes are used.
|
|
.\"
|
|
.SS Wait
|
|
The functions
|
|
.IR pthread_cond_wait ()
|
|
and
|
|
.IR pthread_cond_timedwait ()
|
|
are used to block on a condition variable.
|
|
They must be called with
|
|
.I mutex
|
|
locked by the calling thread.
|
|
The functions atomically release
|
|
.I mutex
|
|
and block the calling thread on the condition variable
|
|
.IR cond .
|
|
Before return, the mutex is reacquired for the calling thread.
|
|
.\"
|
|
.LP
|
|
A condition wait is a cancellation point [see
|
|
.IR pthread_cancel ()].
|
|
When the cancelability enable state of a thread is set to
|
|
.BR PTHREAD_CANCEL_DEFERRED ,
|
|
a side-effect of acting on a cancellation request while in a
|
|
condition wait is that the mutex is re-acquired before calling the
|
|
first cancellation handler.
|
|
A thread that has been unblocked because it has been cancelled while
|
|
waiting on a condition variable does not consume any condition
|
|
signal that may be directed at the condition variable.
|
|
.\"
|
|
.LP
|
|
The function
|
|
.IR pthread_cond_timedwait ()
|
|
is the same as
|
|
.IR pthread_cond_wait ()
|
|
except that an error is returned if the absolute time
|
|
(that is, system or wall-clock time) specified by
|
|
.I abstime
|
|
passes before the waiting thread is signalled.
|
|
If a time-out occurs,
|
|
.IR pthread_cond_timedwait ()
|
|
still reacquires
|
|
.I mutex
|
|
before returning to the caller.
|
|
.\"
|
|
.SS Signal
|
|
The functions
|
|
.IR pthread_cond_signal ()
|
|
and
|
|
.IR pthread_cond_broadcast ()
|
|
are used to unblock threads waiting on a condition variable.
|
|
.\"
|
|
.LP
|
|
The
|
|
.IR pthread_cond_signal ()
|
|
function unblocks one of the threads that are blocked on
|
|
.IR cond ;
|
|
at the time of the call.
|
|
The function
|
|
.IR pthread_cond_broadcast ()
|
|
unblocks all threads blocked on
|
|
the specified condition variable at the time of the call.
|
|
.\"
|
|
.LP
|
|
If more than one thread is blocked on a condition variable, the scheduling
|
|
policy determines the order in which threads are unblocked.
|
|
Calls to
|
|
.IR pthread_cond_signal ()
|
|
and
|
|
.IR pthread_cond_broadcast ()
|
|
have no effect if there are no threads blocked on
|
|
the condition variable at the time of the calls.
|
|
.\"
|
|
.LP
|
|
A thread may call
|
|
.IR pthread_cond_signal ()
|
|
or
|
|
.IR pthread_cond_broadcast ()
|
|
without holding the mutex with which threads calling
|
|
.IR pthread_cond_wait ()
|
|
or
|
|
.IR pthread_cond_timedwait ()
|
|
have associated with the condition variable during their waits.
|
|
However,
|
|
predictable scheduling behavior is only guaranteed if the associated
|
|
mutex is locked by a thread calling
|
|
.IR pthread_cond_signal ()
|
|
or
|
|
.IR pthread_cond_broadcast ().
|
|
.\"
|
|
.SS Destroy
|
|
The routine
|
|
.IR pthread_cond_destroy ()
|
|
de-initializes the condition variable object referenced by
|
|
.IR cond ;
|
|
the condition variable object becomes uninitialized.
|
|
.\"
|
|
.SH "DIAGNOSTICS"
|
|
All of the condition variable functions return zero
|
|
if successful;
|
|
otherwise, an error number is returned.
|
|
.PP
|
|
.IR pthread_cond_destroy ()
|
|
can return the following error:
|
|
.TP 15
|
|
.B [EBUSY]
|
|
The condition variable is currently being used by one or more threads.
|
|
.PP
|
|
.IR pthread_cond_timedwait ()
|
|
can return the following errors:
|
|
.TP 15
|
|
.B [ETIMEDOUT]
|
|
The timeout occurred before the thread was awakened by
|
|
.IR pthread_cond_signal ()
|
|
or
|
|
.IR pthread_cond_broadcast ().
|
|
.TP 15
|
|
.B [EINVAL]
|
|
No timespec structure was passed or the contents of the timespec
|
|
structure were invalid.
|
|
.SH "SEE ALSO"
|
|
pthread_cancel(3P),
|
|
pthread_condattr_init(3P),
|
|
pthread_mutex_lock(3P),
|
|
pthread_mutex_unlock(3P).
|
|
.SH NOTES
|
|
A return from
|
|
.IR pthread_cond_wait ()
|
|
or
|
|
.IR pthread_cond_timedwait ()
|
|
does not guarantee that the condition or event for which the caller was
|
|
waiting actually occurred.
|
|
It is the responsibility of the call to recheck the condition wait
|
|
predicate before proceeding.
|