Unix/Linux Go Back    

RedHat 9 (Linux i386) - man page for pthread_cond_wait (redhat section 3)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


       pthread_cond_init,   pthread_cond_destroy,   pthread_cond_signal,  pthread_cond_broadcast,
       pthread_cond_wait, pthread_cond_timedwait - operations on conditions

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

       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_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 corre-
       sponds 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.

       pthread_cond_wait and pthread_cond_timedwait are cancellation points. If a thread is  can-
       celled  while  suspended  in one of these functions, the thread immediately resumes execu-
       tion, 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.

       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 sig-
       nal handler may deadlock the calling thread.

       All condition variable functions return 0 on success and a non-zero error code on error.

       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:

		     the  condition  variable  was  not  signaled  until the timeout specified by

	      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.

       Xavier Leroy <Xavier.Leroy@inria.fr>

       pthread_condattr_init(3), pthread_mutex_lock(3), pthread_mutex_unlock(3), gettimeofday(2),

       Consider  two  shared variables x and y, protected by the mutex mut, and a condition vari-
       able 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:

	      while (x <= y) {
		      pthread_cond_wait(&cond, &mut);
	      /* operate on x and y */

       Modifications on x and y that may cause x to become greater than y should signal the  con-
       dition if needed:

	      /* modify x and y */
	      if (x > y) pthread_cond_broadcast(&cond);

       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

       To wait for x to becomes greater than y with a timeout of 5 seconds, do:

	      struct timeval now;
	      struct timespec timeout;
	      int retcode;

	      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 */

					   LinuxThreads 			  PTHREAD_COND(3)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums

All times are GMT -4. The time now is 08:44 PM.