mtx_timedlock()

Updated: April 19, 2023

Lock a mutex, with a time limit

Synopsis:

#include <threads.h>
#include <time.h>

int mtx_timedlock( mtx_t *mutex,
                   const struct timespec * ts );

Arguments:

mutex
The mutex that you want to lock.
ts
A pointer to a timespec structure that specifies the absolute time at which the time-out 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 mtx_timedlock() 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 mtx_lock(). If the mutex can't be locked without waiting for another thread to unlock the mutex, the wait is terminated when the specified timeout 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 ts passes, as measured by the clock on which timeouts are based (i.e., when the value of that clock equals or exceeds ts), or if the absolute time specified by ts has already been passed at the time of the call.

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

Returns:

thrd_success
Success.
thrd_error
An error occurred.
thrd_timedout
The mutex couldn't be locked before the specified timeout expired.

Classification:

C11

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