pthread_mutex_clocklock()

Lock a mutex with a time limit measured against a specific clock

Synopsis:

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

int pthread_mutex_clocklock(
                  pthread_mutex_t *mutex, 
                  clockid_t clk, 
                  const struct timespec *abstime );

Arguments:

mutex: The mutex that you want to lock.
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_mutex_clocklock() function locks the mutex object referenced by mutex. If the mutex is already locked, the calling thread blocks until the mutex becomes available as in the pthread_mutex_lock() function. If the mutex can't be locked without waiting for another thread to unlock the mutex, the wait is terminated when the specified time limit expires.

By default, if a thread with a higher priority than the mutex owner attempts to lock a mutex, then the effective priority of the current owner is increased to that of the higher-priority blocked thread waiting for the mutex. The owner returns to its real priority when it unlocks the mutex. For more information, see “Mutexes: mutual exclusion locks” in the QNX Neutrino Microkernel chapter of the System Architecture guide.

The timeout expires when the absolute time specified by abstime passes, as measured by the clock, clk, on which timeouts are based (i.e., when the value of that clock equals or exceeds abstime), or if the absolute time specified by abstime has already been passed at the time of the call.

The timeout is based on the clk clock. The timespec datatype is defined in the <time.h> header.

If the mutex can be locked immediately, the validity of the abstime parameter isn't checked, and the function won't fail with a timeout.

As a consequence of the priority inheritance rules (for mutexes initialized with the PTHREAD_PRIO_INHERIT protocol), if a timed mutex wait is terminated because its timeout expires, the priority of the owner of the mutex is adjusted as necessary to reflect the fact that this thread is no longer among the threads waiting for the mutex.

Returns:

EOK

Success.

EAGAIN

The mutex couldn't be acquired because the maximum number of recursive locks for the mutex has been exceeded.

EDEADLK

One of the following occurred:

The mutex type is PTHREAD_MUTEX_ERRORCHECK, and the current thread already owns the mutex.
A deadlock condition was detected.

EINVAL

One of the following occurred:

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 was created with a protocol attribute of PTHREAD_PRIO_PROTECT, and the calling thread's priority is higher than the mutex's current priority ceiling.
The process or thread would have blocked, and the abs_timeout parameter specified a nanoseconds field value less than zero or greater than or equal to 1000 million.
The value specified by mutex doesn't refer to an initialized mutex object.
The mutex has died; see SyncMutexEvent().

ENOTRECOVERABLE

The mutex is a robust mutex, and the state that it protects isn't recoverable. All you can do with the mutex is destroy it by calling pthread_mutex_destroy().

EOWNERDEAD

The mutex is a robust mutex and the process containing the previous owning thread terminated while holding the mutex lock. The calling thread acquires the mutex lock; it's up to the new owner to make the state consistent (see pthread_mutex_consistent()).

ETIMEDOUT

The mutex couldn't be locked before the specified timeout expired.

Classification:

POSIX 1003.1

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