pthread_cond_timedwait()

wait on a condition for specified time 

Function

SYNOPSIS

#include <pthread.h>

int pthread_cond_timedwait(pthread_cond_t *cond, pthread_mutex_t *mutex, const struct timespec *abstime);

DESCRIPTION

The pthread_cond_timedwait() 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(), or if the time specified by abstime is reached.

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.

pthread_cond_timedwait() is the same as pthread_cond_wait(), except an error is returned if the system time equals or exceeds the time specified by abstime before the condition variable is signaled or broadcast, or if the absolute time specified by abstime has already passed at the time of the call. When timeouts occur, pthread_cond_timedwait() releases and reacquires the mutex.

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_timedwait() does not indicate anything about the value of this predicate, the predicate should be reevaluated on return. Unwanted wakeups from pthread_cond_timedwait() 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_timedwait() 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_timedwait(), 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.

abstime 

Is the absolute time at which the wait is cancelled if not signaled or broadcast.

RETURN VALUES

On success, pthread_cond_timedwait() 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, mutex, or abstime is an invalid pointer.

ETIMEDOUT 

The specified absolute time has passed.

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_wait(), pthread_mutex_init()

PTC MKS Toolkit 10.4 Documentation Build 39.