pthread_cond_wait()

wait on a condition 

Function

SYNOPSIS

#include <pthread.h>

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

DESCRIPTION

The pthread_cond_wait() function blocks on the specified condition variable, which atomically releases the specified mutex and causes the calling thread to block on the condition variable The blocked thread may be awakened by a call to pthread_cond_signal() or pthread_cond_broadcast().

This function atomically releases the mutex, causing the calling thread to block on the condition variable Upon successful completion, the mutex is locked and owned by the calling thread.

When using condition variables, there should always be a boolean predicate involving shared variables related to each condition wait. This predicate should become true only when the thread should proceed. Because the return from pthread_cond_wait() does not indicate anything about the value of this predicate, the predicate should be reevaluated on return. Unwanted wakeups from pthread_cond_wait() may occur (since another thread could have obtained the mutex, changed the state and released the mutex, prior to this thread obtaining the mutex); the reevaluation of the predicate ensures consistency.

The pthread_cond_wait() function is a cancellation point. If a cancellation request is acted on while in a condition wait when the cancellation type of a thread is set to deferred, the mutex is reacquired before calling the first cancellation cleanup handler. In other words, the thread is unblocked, allowed to execute up to the point of returning from the call pthread_cond_wait(), but instead of returning to the caller, it performs the thread cancellation.

PARAMETERS

cond 

Is the condition variable to wait on.

mutex 

Is the mutex associated with the condition variable.

RETURN VALUES

On success, pthread_cond_wait() returns 0. On error, one of the following values is returned:

EINVAL 

cond does not refer to an initialized condition variable, or mutex does not refer to an initialized mutex. Different mutexes were specified in multiple waits on cond. mutex is not owned by the caller.

EFAULT 

cond or mutex is an invalid pointer.

CONFORMANCE

POSIX P1003.1 (1996)

MULTITHREAD SAFETY LEVEL

MT-safe.

PORTING ISSUES

None.

AVAILABILITY

PTC MKS Toolkit for Professional Developers
PTC MKS Toolkit for Professional Developers 64-Bit Edition
PTC MKS Toolkit for Enterprise Developers
PTC MKS Toolkit for Enterprise Developers 64-Bit Edition

SEE ALSO

Functions:
pthread_cond_broadcast(), pthread_cond_init(), pthread_cond_signal(), pthread_cond_timedwait(), pthread_mutex_init()

PTC MKS Toolkit 10.4 Documentation Build 39.