pthread_cond_clockwait()

Wait on a condition variable, with a time limit measured against a specific clock

Synopsis:

#include <pthread.h>
#include <time.h>

int pthread_cond_clockwait( 
            pthread_cond_t *cond, 
            pthread_mutex_t *mutex,
            clockid_t clk, 
            const struct timespec *abstime );

Arguments:

cond: The condition variable on which to block the thread.
mutex: The mutex associated with the condition variable.
clk: The clock against which the time limit is measured. The clock source is specified using the clk variable. The clk variable must be set to either CLOCK_REALTIME, CLOCK_ SOFTTIME or CLOCK_MONOTONIC.
abstime: A pointer to a timespec structure that specifies the absolute time at which the timeout is to expire.

Library:

libc

Use the -l c option to qcc to link against this library. This library is usually included automatically.

Description:

The pthread_cond_clockwait() function blocks the calling thread on the condition variable cond, and unlocks the associated mutex mutex. The calling thread must have locked mutex before waiting on the condition variable. Upon return from the function, the mutex is again locked and owned by the calling thread.

The calling thread is blocked until either another thread performs a signal or broadcast on the condition variable, the absolute time specified by abstime has passed, a signal is delivered to the thread, or the thread is canceled (waiting on a condition variable is a cancellation point). In all cases, the thread reacquires the mutex before being unblocked.

Note: Don't use a recursive mutex with condition variables.

If a thread that's blocked on a condition variable is canceled, the thread reacquires the mutex that's guarding the condition variable, so that the thread's cleanup handlers run in the same state as the critical code before and after the call to this function. If some other thread owns the lock, the canceled thread blocks until the mutex is available.

Note:

Make sure that the thread's cleanup handlers unlock the mutex.
To specify a timeout of less than a second, obtain the current time using clock_gettime(), and then add the number of nanoseconds to the abstime.tv_nsec field.
You can use nsec2timespec() to convert times in nanoseconds to a timespec structure (and timespec2nsec() to convert them back again).

Returns:

EOK

Success, or the call was interrupted by a signal.

EFAULT

A fault occurred trying to access the buffers provided.

EINVAL

One or more of the following are true:

One or more of cond, mutex, clk, and abstime are invalid.
The clock is used in a context which does not make sense for a timeout; for example, when using CLOCK_THREAD_CPUTIME_ID.
The use of the clock as a timeout is not supported; for example, when using another thread's CPUTIME clock.
The clock does not exist.
The mutex has died; see SyncMutexEvent().

EPERM

The current thread doesn't own the mutex.

ETIMEDOUT

The time specified by abstime has passed.

Classification:

POSIX 1003.1

Safety:
Cancellation point	Yes
Interrupt handler	No
Signal handler	Yes
Thread	Yes