Tribblix: manual page: pthread_mutex

PTHRAD_MUTEX_TIMEDLOCK(3C) Standard C Library Functions

NAME

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

LIBRARY

Standard C Library (libc, -lc)

SYNOPSIS

#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);

DESCRIPTION

The pthread_mutex_clocklock(), pthread_mutex_timedlock(),
pthread_mutex_relclocklock_np(), and pthread_mutex_reltimedlock_np()
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 pthread_mutex_clocklock() and pthread_mutex_relclocklock_np()
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 pthread_mutex_reltimedlock_np() functions
will always utilize the realtime clock, CLOCK_REALTIME.

The pthread_mutex_clocklock() and pthread_mutex_timedlock() 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 pthread_mutex_reltimedlock_np()
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.

RETURN VALUES

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

ERRORS

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:

EINVAL 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.

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

INTERFACE STABILITY

Committed

MT-LEVEL
MT-Safe