PTHREAD_COND(3)                                   PTHREAD_COND(3)

NAME
       pthread_cond_init, pthread_cond_destroy, pthread_cond_sig-
       nal,      pthread_cond_broadcast,       pthread_cond_wait,
       pthread_cond_timedwait - operations on conditions

SYNOPSIS
       #include <pthread.h>

       pthread_cond_t cond = PTHREAD_COND_INITIALIZER;

       int  pthread_cond_init(pthread_cond_t  *cond, pthread_con-
       dattr_t *cond_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
       A condition (short for ``condition variable'') is  a  syn-
       chronization  device that allows threads to suspend execu-
       tion and relinquish the processors until some predicate on
       shared  data  is satisfied. The basic operations on condi-
       tions  are:  signal  the  condition  (when  the  predicate
       becomes  true), and wait for the condition, suspending the
       thread execution until another thread signals  the  condi-
       tion.

       A  condition  variable  must  always  be associated with a
       mutex, to avoid the race condition where a thread prepares
       to wait on a condition variable and another thread signals
       the condition just before the first thread actually  waits
       on it.

       pthread_cond_init initializes the condition variable cond,
       using the condition attributes specified in cond_attr,  or
       default attributes if cond_attr is NULL.  The LinuxThreads
       implementation  supports  no  attributes  for  conditions,
       hence the cond_attr parameter is actually ignored.

       Variables  of  type pthread_cond_t can also be initialized
       statically, using the constant PTHREAD_COND_INITIALIZER.

       pthread_cond_signal restarts one of the threads  that  are
       waiting on the condition variable cond.  If no threads are
       waiting on cond, nothing happens. If several  threads  are
       waiting  on  cond, exactly one is restarted, but it is not
       specified which.

       pthread_cond_broadcast restarts all the threads  that  are
       waiting  on  the condition variable cond.  Nothing happens
       if no threads are waiting on cond.

       pthread_cond_wait atomically unlocks  the  mutex  (as  per
       pthread_unlock_mutex) and waits for the condition variable
       cond to be signaled. The thread execution is suspended and
       does not consume any CPU time until the condition variable
       is signaled. The mutex  must  be  locked  by  the  calling
       thread on entrance to pthread_cond_wait.  Before returning
       to the calling thread, pthread_cond_wait re-acquires mutex
       (as per pthread_lock_mutex).

       Unlocking  the mutex and suspending on the condition vari-
       able is done  atomically.  Thus,  if  all  threads  always
       acquire  the  mutex  before  signaling the condition, this
       guarantees that the condition cannot be signaled (and thus
       ignored) between the time a thread locks the mutex and the
       time it waits on the condition variable.

       pthread_cond_timedwait atomically unlocks mutex and  waits
       on cond, as pthread_cond_wait does, but it also bounds the
       duration of the wait. If cond has not been signaled within
       the  amount  of time specified by abstime, the mutex mutex
       is  re-acquired  and  pthread_cond_timedwait  returns  the
       error ETIMEDOUT.  The abstime parameter specifies an abso-
       lute time, with the same origin as time(2) and  gettimeof-
       day(2):  an abstime of 0 corresponds to 00:00:00 GMT, Jan-
       uary 1, 1970.

       pthread_cond_destroy destroys a condition variable,  free-
       ing  the resources it might hold. No threads must be wait-
       ing   on   the   condition   variable   on   entrance   to
       pthread_cond_destroy.  In the LinuxThreads implementation,
       no resources are associated with condition variables, thus
       pthread_cond_destroy actually does nothing except checking
       that the condition has no waiting threads.

CANCELLATION
       pthread_cond_wait and pthread_cond_timedwait are cancella-
       tion  points.  If a thread is cancelled while suspended in
       one of these functions,  the  thread  immediately  resumes
       execution,   then   locks  again  the  mutex  argument  to
       pthread_cond_wait and pthread_cond_timedwait, and  finally
       executes the cancellation.  Consequently, cleanup handlers
       are assured that mutex is locked when they are called.

ASYNC-SIGNAL SAFETY
       The condition functions are  not  async-signal  safe,  and
       should not be called from a signal handler. In particular,
       calling pthread_cond_signal or pthread_cond_broadcast from
       a signal handler may deadlock the calling thread.

RETURN VALUE
       All condition variable functions return 0 on success and a
       non-zero error code on error.

ERRORS
       pthread_cond_init,                    pthread_cond_signal,
       pthread_cond_broadcast, and pthread_cond_wait never return
       an error code.

       The pthread_cond_timedwait function returns the  following
       error codes on error:

              ETIMEDOUT
                     the  condition  variable  was  not  signaled
                     until the timeout specified by abstime

              EINTR  pthread_cond_timedwait was interrupted by  a
                     signal

       The  pthread_cond_destroy  function  returns the following
       error code on error:

              EBUSY  some threads are currently waiting on  cond.

AUTHOR
       Xavier Leroy <Xavier.Leroy@inria.fr>

SEE ALSO
       pthread_condattr_init(3),           pthread_mutex_lock(3),
       pthread_mutex_unlock(3), gettimeofday(2), nanosleep(2).

EXAMPLE
       Consider two shared variables x and y,  protected  by  the
       mutex  mut,  and  a  condition variable cond that is to be
       signaled whenever x becomes greater than y.

              int x,y;
              pthread_mutex_t mut = PTHREAD_MUTEX_INITIALIZER;
              pthread_cond_t cond = PTHREAD_COND_INITIALIZER;

       Waiting until x is greater than y is performed as follows:

              pthread_mutex_lock(&mut);
              while (x <= y) {
                      pthread_cond_wait(&cond, &mut);
              }
              /* operate on x and y */
              pthread_mutex_unlock(&mut);

       Modifications  on  x  and  y  that  may  cause x to become
       greater than y should signal the condition if needed:

              pthread_mutex_lock(&mut);
              /* modify x and y */
              if (x > y) pthread_mutex_broadcast(&cond);
              pthread_mutex_unlock(&mut);

       If it can be proved that at most one waiting thread  needs
       to  be  waken  up  (for  instance,  if  there are only two
       threads communicating through x and y),  pthread_cond_sig-
       nal  can  be used as a slightly more efficient alternative
       to     pthread_cond_broadcast.      In     doubt,      use
       pthread_cond_broadcast.

       To  wait for x to becomes greater than y with a timeout of
       5 seconds, do:

              struct timeval now;
              struct timespec timeout;
              int retcode;

              pthread_mutex_lock(&mut);
              gettimeofday(&now);
              timeout.tv_sec = now.tv_sec + 5;
              timeout.tv_nsec = now.tv_usec * 1000;
              retcode = 0;
              while (x <= y && retcode != ETIMEDOUT) {
                      retcode = pthread_cond_timedwait(&cond, &mut, &timeout);
              }
              if (retcode == ETIMEDOUT) {
                      /* timeout occurred */
              } else {
                      /* operate on x and y */
              }
              pthread_mutex_unlock(&mut);

                           LinuxThreads                         1