PTHRAD_MUTEX_TIMEDLOCK(3C) Standard C Library Functions PTHRAD_MUTEX_TIMEDLOCK(3C)

pthread_mutex_clocklock, pthread_mutex_timedlock, pthread_mutex_relclocklock_np, pthread_mutex_reltimedlock_np — lock a mutex with a timeout

Standard C Library (libc, -lc)

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

int
pthread_mutex_clocklock(pthread_mutex_t *restrict mutex, clockid_t clock, const struct timespec *restrict abs_timeout);

int
pthread_mutex_timedlock(pthread_mutex_t *restrict mutex, const struct timespec *restrict abs_timeout);

int
pthread_mutex_relclocklock_np(pthread_mutex_t *restrict mutex, clockid_t clock, const struct timespec *restrict rel_timeout);

int
pthread_mutex_reltimedlock_np(pthread_mutex_t *restrict mutex, const struct timespec *restrict rel_timeout);

The (), (), pthread_mutex_relclocklock_np(), and () functions all lock the mutex object mutex. If the mutex is already locked, the calling thread will block until the mutex becomes available just as pthread_mutex_lock(3C); however, if the mutex does not become available within a specified timeout, then the function call will terminate without acquiring the lock and return the ETIMEDOUT error. These functions all differ in terms of how the timeout is specified and the clock that is used to determine when the timeout has elapsed.

In general, the system provides the ability to program timeouts against either the realtime clock, CLOCK_REALTIME, which measures the wall clock and is subject to changes due to time synchronization daemons such as NTP and PTP, or the high-resolution clock, CLOCK_HIGHRES, which is a non-adjustable high-resolution clock that is provided by system hardware. The specified timeout may either be specified as an absolute time in the future or as a relative amount of time that should elapse. Each clock has its own resolution, which can be determined by clock_getres(3C). Timeouts may be rounded up to a given clock's resolution. Due to scheduling effects, it is possible that more time may elapse than was specified in the timeout when the caller does not successfully acquire the lock.

The () and () functions allow the clock source to be used to be specified by the clock argument. While there are additional clocks in the system, only CLOCK_REALTIME or CLOCK_HIGHRES may be specified. The thread and process-specific CPU time clocks cannot be used. Conversely, the pthread_mutex_timedlock() and () functions will always utilize the realtime clock, CLOCK_REALTIME.

The () and () functions treat the timeout value, abs_timeout, as the absolute time in the future when the timeout should expire. Conversely, the pthread_mutex_relclocklock_np() and () functions operate in terms of a relative time. The timer will expire when a specified amount of time passes on the clock specified as indicated by rel_timeout.

If the mutex, mutex, can be immediately locked, then the timeout value is ignored entirely, even if the timeout had already expired or represented a value that didn't make sense. Both are only checked if the thread would block on the mutex itself.

Mutexes may have priority inheritance enabled via the PTHREAD_PRIO_INHERIT attribute. When a thread is blocked on a timed mutex, it may boost the priority of the mutex owner based on the priority inheritance rules. When the timer expires, the calling thread will no longer be blocking on the mutex and therefore will no longer provide any potential priority inheritance. If it had boosted the holder of the mutex, then the owner's scheduling priority will be re-evaluated.

Upon successful completion, the pthread_mutex_clocklock(), pthread_mutex_timedlock(), pthread_mutex_relclocklock_np(), and pthread_mutex_reltimedlock_np() functions will return and successfully have entered the mutex, mutex. Otherwise, an error number is returned to indicate the error.

The pthread_mutex_clocklock(), pthread_mutex_timedlock(), pthread_mutex_relclocklock_np(), and pthread_mutex_reltimedlock_np() functions will all fail for the same reasons as pthread_mutex_lock(3C). In addition, they will fail if:

The caller would have blocked and the timeout parameter specified a nanoseconds field value less than zero or greater than or equal to 1,000 million.

For pthread_mutex_clocklock() and pthread_mutex_relclocklock_np() the value of clock is either unsupported for locking or unknown to the system.

The mutex could not be locked before the specified timeout expired.

time(2), clock_getres(3C), pthread_mutex_destroy(3C), pthread_mutex_lock(3C), pthread_mutex_trylock(3C), attributes(7), standards(7)

June 22, 2024 OmniOS