Provided by: glibc-doc_2.31-0ubuntu9.16_all bug

NAME

       pthread_cond_init,   pthread_cond_destroy,   pthread_cond_signal,  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_condattr_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 synchronization device that allows
       threads to suspend execution and relinquish the processors until some predicate on  shared
       data  is satisfied. The basic operations on conditions are: signal the condition (when the
       predicate becomes true), and wait for the condition, suspending the thread execution until
       another thread signals the condition.

       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 variable 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
       absolute  time,  with  the  same  origin  as  time(2) and gettimeofday(2): an abstime of 0
       corresponds to 00:00:00 GMT, January 1, 1970.

       pthread_cond_destroy destroys a condition variable, freeing the resources it  might  hold.
       No  threads must be waiting 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  cancellation  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_cond_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_signal 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                           PTHREAD_COND(3)