GNU Info

Info Node: (libc.info)Condition Variables

(libc.info)Condition Variables


Next: POSIX Semaphores Prev: Mutexes Up: POSIX Threads
Enter node , (file) or (file)node

Condition Variables
===================

   A condition (short for "condition variable") is a synchronization
device that allows threads to suspend execution 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.

 - Function: int pthread_cond_init (pthread_cond_t *COND,
          pthread_condattr_t *cond_ATTR)
     `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'.

     This function always returns 0.

 - Function: int pthread_cond_signal (pthread_cond_t *COND)
     `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.

     This function always returns 0.

 - Function: int pthread_cond_broadcast (pthread_cond_t *COND)
     `pthread_cond_broadcast' restarts all the threads that are waiting
     on the condition variable COND. Nothing happens if no threads are
     waiting on COND.

     This function always returns 0.

 - Function: int pthread_cond_wait (pthread_cond_t *COND,
          pthread_mutex_t *MUTEX)
     `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.

     This function always returns 0.

 - Function: int pthread_cond_timedwait (pthread_cond_t *COND,
          pthread_mutex_t *MUTEX, const struct timespec *ABSTIME)
     `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 before time ABSTIME,
     the mutex MUTEX is re-acquired and `pthread_cond_timedwait'
     returns the error code `ETIMEDOUT'.  The wait can also be
     interrupted by a signal; in that case `pthread_cond_timedwait'
     returns `EINTR'.

     The ABSTIME parameter specifies an absolute time, with the same
     origin as `time' and `gettimeofday': an ABSTIME of 0 corresponds
     to 00:00:00 GMT, January 1, 1970.

 - Function: int pthread_cond_destroy (pthread_cond_t *COND)
     `pthread_cond_destroy' destroys the condition variable COND,
     freeing the resources it might hold.  If any threads are waiting
     on the condition variable, `pthread_cond_destroy' leaves COND
     untouched and returns `EBUSY'.  Otherwise it returns 0, and COND
     must not be used again until it is reinitialized.

     In the LinuxThreads implementation, no resources are associated
     with condition variables, so `pthread_cond_destroy' actually does
     nothing.

   `pthread_cond_wait' and `pthread_cond_timedwait' are cancellation
points. If a thread is canceled while suspended in one of these
functions, the thread immediately resumes execution, relocks the mutex
specified by  MUTEX, and finally executes the cancellation.
Consequently, cleanup handlers are assured that MUTEX is locked when
they are called.

   It is not safe to call the condition variable functions from a signal
handler. In particular, calling `pthread_cond_signal' or
`pthread_cond_broadcast' from a signal handler may deadlock the calling
thread.

   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);

   Condition attributes can be specified at condition creation time, by
passing a condition attribute object as second argument to
`pthread_cond_init'.  Passing `NULL' is equivalent to passing a
condition attribute object with all attributes set to their default
values.

   The LinuxThreads implementation supports no attributes for
conditions. The functions on condition attributes are included only for
compliance with the POSIX standard.

 - Function: int pthread_condattr_init (pthread_condattr_t *ATTR)
 - Function: int pthread_condattr_destroy (pthread_condattr_t *ATTR)
     `pthread_condattr_init' initializes the condition attribute object
     ATTR and fills it with default values for the attributes.
     `pthread_condattr_destroy' destroys the condition attribute object
     ATTR.

     Both functions do nothing in the LinuxThreads implementation.

     `pthread_condattr_init' and `pthread_condattr_destroy' always
     return 0.


automatically generated by info2www version 1.2.2.9