pthread_cond_wait(3P)

NAME
     pthread_cond_init, pthread_cond_signal, pthread_cond_broadcast,
     pthread_cond_wait, pthread_cond_timedwait, pthread_cond_destroy -
     condition variables

C SYNOPSIS
     #include <pthread.h>

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

     int pthread_cond_signal(pthread_cond_t *cond);

     int pthread_cond_broadcast(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_destroy(pthread_cond_t *cond);

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.

   Initialize
     Condition variables may be initialized either dynamically, by calling
     pthread_cond_init(), or statically, via the macro
     PTHREAD_COND_INITIALIZER.

     The personality of the condition variable is determined by the attribute
     structure attr passed with the call to pthread_cond_init().  These
     attributes are set by calls to pthread_condattr_init() and the various
     condition variable attribute functions.  If attr is null (or the
     condition variable is statically initialized) the default attributes are
     used.

   Wait
     The functions pthread_cond_wait() and pthread_cond_timedwait() are used
     to block on a condition variable.  They must be called with mutex locked
     by the calling thread.  The functions atomically release mutex and block
     the calling thread on the condition variable cond.  Before return, the
     mutex is reacquired for the calling thread.

     A condition wait is a cancellation point [see pthread_cancel()].  When
     the cancelability enable state of a thread is set to
     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.

     The function pthread_cond_timedwait() is the same as pthread_cond_wait()
     except that an error is returned if the absolute time (that is, system or
     wall-clock time) specified by abstime passes before the waiting thread is
     signalled.  If a time-out occurs, pthread_cond_timedwait() still
     reacquires mutex before returning to the caller.

   Signal
     The functions pthread_cond_signal() and pthread_cond_broadcast() are used
     to unblock threads waiting on a condition variable.

     The pthread_cond_signal() function unblocks one of the threads that are
     blocked on cond; at the time of the call.  The function
     pthread_cond_broadcast() unblocks all threads blocked on the specified
     condition variable at the time of the call.

     If more than one thread is blocked on a condition variable, the
     scheduling policy determines the order in which threads are unblocked.
     Calls to pthread_cond_signal() and pthread_cond_broadcast() have no
     effect if there are no threads blocked on the condition variable at the
     time of the calls.

     A thread may call pthread_cond_signal() or pthread_cond_broadcast()
     without holding the mutex with which threads calling pthread_cond_wait()
     or 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
     pthread_cond_signal() or pthread_cond_broadcast().

   Destroy
     The routine pthread_cond_destroy() de-initializes the condition variable
     object referenced by cond; the condition variable object becomes
     uninitialized.

DIAGNOSTICS
     All of the condition variable functions return zero if successful;
     otherwise, an error number is returned.

     pthread_cond_destroy() can return the following error:

     [EBUSY]        The condition variable is currently being used by one or
                    more threads.

     pthread_cond_timedwait() can return the following errors:

     [ETIMEDOUT]    The timeout occurred before the thread was awakened by
                    pthread_cond_signal() or pthread_cond_broadcast().

     [EINVAL]       No timespec structure was passed or the contents of the
                    timespec structure were invalid.

SEE ALSO
     pthread_cancel(3P), pthread_condattr_init(3P), pthread_mutex_lock(3P),
     pthread_mutex_unlock(3P).

NOTES
     A return from pthread_cond_wait() or 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.