Content-type: text/html Man page of pthread_cond_wait

pthread_cond_wait

Section: C Library Functions (3)
Index Return to Main Contents
 

NAME

pthread_cond_wait - Causes a thread to wait for the specified condition variable to be signaled or broadcasted.  

LIBRARY

DECthreads POSIX 1003.1c Library (libpthread.so)  

SYNOPSIS

#include <pthread.h>

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

STANDARDS

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

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

PARAMETERS

Condition variable that the calling thread waits on. 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. The atomicity is important, because it means the thread cannot miss a wakeup while the mutex is unlocked. When the wait is satisfied as a result of some thread calling pthread_cond_signal(3) or pthread_cond_broadcast(3), the mutex is reacquired before returning to the caller.

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.

 

RETURN VALUES

If an error condition occurs, this routine returns an integer value indicating the type of error. Possible return values are as follows: Successful completion. 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. DECthreads cannot acquire memory needed to block using a statically initialized condition variable.  

ERRORS

None  

RELATED INFORMATION

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

delim off


 

Index

NAME
LIBRARY
SYNOPSIS
STANDARDS
PARAMETERS
DESCRIPTION
RETURN VALUES
ERRORS
RELATED INFORMATION

This document was created by man2html, using the manual pages.
Time: 02:42:10 GMT, October 02, 2010