Provided by: glibc-doc_2.3.6-0ubuntu20_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)