ABCDEFGHIJKLMNOPQRSTUVWXYZ

pthread_cond_destroy

PTHREAD_COND(3)                                                PTHREAD_COND(3)



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 pro-
       cessors  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 execu-
       tion 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 vari-
       able 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  sig-
       naling the condition, this guarantees that the condition cannot be sig-
       naled (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  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  argu-
       ment  to pthread_cond_wait and pthread_cond_timedwait, and finally exe-
       cutes 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_sig-
       nal  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)