pthread_cond_timedwait()

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, whichatomically releases the specified mutex and causes the callingthread to block on the condition variable The blocked thread maybe awakened by a call to pthread_cond_signal() or pthread_cond_broadcast() ,or if the time specified by abstime is reached.

This function atomicallyreleases the mutex, causing the calling thread to block on thecondition variable Upon successful completion, the mutex islocked and owned by the calling thread.

pthread_cond_timedwait() is the same as pthread_cond_wait() , except an error isreturned if the system time equals or exceeds the time specifiedby abstime before the condition variable is signaled orbroadcast, or if the absolute time specified by abstimehas 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 sharedvariables related to each condition wait. This predicate shouldbecome true only when the thread should proceed. Because thereturn from pthread_cond_timedwait() does not indicateanything about the value of this predicate, the predicate shouldbe 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 threadobtaining the mutex); the reevaluation of the predicate ensuresconsistency.

The pthread_cond_timedwait() function is a cancellation point. If a cancellation request isacted on while in a condition wait when the cancellation type ofa thread is set to deferred, the mutex is reacquired beforecalling the first cancellation cleanup handler. In other words,the thread is unblocked, allowed to execute up to the point ofreturning from the call pthread_cond_timedwait() , butinstead of returning to the caller, it performs the threadcancellation.

---

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 thewait 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 aninitialized condition variable, or mutex does notrefer to an initialized mutex. Different mutexes werespecified in multiple waits on cond. mutexis not owned by the caller.

EFAULT 

cond, mutex,or abstime is an invalid pointer.

ETIMEDOUT 

The specified absolute time has passed.

---