Index for Section 3

Alphabetical listing for P

Bottom of page

pthread_cond_wait(3)
NAME
  pthread_cond_wait - Causes a thread to wait for the specified condition
  variable to be signaled or broadcasted

SYNOPSIS
  #include <pthread.h>

  int pthread_cond_wait(
	  pthread_cond_t *cond,
	  pthread_mutex_t *mutex );

LIBRARY
  DECthreads POSIX 1003.1c Library (libpthread.so)

STANDARDS
  Interfaces documented on this reference page conform to industry standards
  as follows:

  IEEE Std 1003.1c-1995, POSIX System Application Program Interface

PARAMETERS
  cond
      Condition variable that the calling thread waits on.

  mutex
      Mutex associated with the condition variable specified in cond.

DESCRIPTION
  This routine causes a thread to wait for the specified condition variable
  to be signaled or broadcasted. Each condition corresponds to one or more
  Boolean relations, called a predicate, based on shared data. The calling
  thread waits for the data to reach a particular state for the predicate to
  become true. However, the return from this routine does not imply anything
  about the value of the predicate, and it should be reevaluated upon return.

  Call this routine after you have locked the mutex specified in mutex. The
  results of this routine are unpredictable if this routine is called without
  first locking the mutex.

  This routine atomically releases the mutex and causes the calling thread to
  wait on the condition. When the thread regains control after calling
  pthread_cond_wait(3), the mutex is locked and the thread is the owner. This
  is true regardless of why the wait ended. If general cancelability is
  enabled, the thread reacquires the mutex (blocking for it if necessary)
  before the cleanup handlers are run (or before the exception is raised).

  A thread that changes the state of storage protected by the mutex in such a
  way that a predicate associated with a condition variable might now be
  true, must call either pthread_cond_signal(3) or pthread_cond_broadcast(3)
  for that condition variable. If neither call is made, any thread waiting on
  the condition variable continues to wait.

  This routine might (with low probability) return when the condition
  variable has not been signaled or broadcasted. When this occurs, the mutex
  is reacquired before the routine returns. To handle this type of situation,
  enclose each call to this routine in a loop that checks the predicate. The
  loop provides documentation of your intent and protects against these
  spurious wakeups, while also allowing correct behavior even if another
  thread consumes the desired state before the awakened thread runs.

  It is illegal for threads to wait on the same condition variable by
  specifying different mutexes.

  The only routines which are supported for use with asynchronous
  cancelability enabled are those which disable asynchronous cancelability.

RETURN VALUES
  If an error condition occurs, this routine returns an integer value
  indicating the type of error. Possible return values are as follows:

  0   Successful completion.

  [EINVAL]
      The value specified by cond, or mutex is invalid, or: Different mutexes
      are supplied for concurrent pthread_cond_wait(3) operations or
      pthread_cond_timedwait operations on the same condition variable, or:
      The mutex was not owned by the calling thread at the time of the call.

  [ENOMEM]
      DECthreads cannot acquire memory needed to block using a statically
      initialized condition variable.

ERRORS
  None

SEE ALSO
  Functions: pthread_cond_broadcast(3), pthread_cond_destroy(3),
  pthread_cond_init(3), pthread_cond_signal(3), pthread_cond_timedwait(3),

  Manuals: Guide to DECthreads and Programmer's Guide

Index for Section 3

Alphabetical listing for P

Top of page