# pthread_cond_init

## NAME



           pthread_cond_init, pthread_cond_signal, pthread_cond_broadcast,
           pthread_cond_wait, pthread_cond_timedwait, pthread_cond_destroy -
           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_mutex_lock**()).
    
           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 cancelation
           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 cancelation.
           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 ._
    
           The **pthread_cond_destroy**() function returns the following error
           code on error:
    
                  **EBUSY** Some threads are currently waiting on _cond ._
    


## 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 become 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);**
    


* * *