Tribblix: manual page: pthread_rwlock

PTHREAD_RWLOCK_TIMEDRDLOCK(3C) Standard C Library Functions

NAME

pthread_rwlock_clockrdlock, pthread_rwlock_timedrdlock,
pthread_rwlock_relclockrdlock_np, pthread_rwlock_reltimedrdlock_np -
lock a read-write lock for reading

LIBRARY

Standard C Library (libc, -lc)

SYNOPSIS

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

int
pthread_rwlock_clockrdlock(pthread_rwlock_t *restrict rwlock,
clockid_t clock, const struct timespec *restrict abstime);

int
pthread_rwlock_timedrdlock(pthread_rwlock_t *restrict rwlock,
const struct timespec *restrict abstime);

int
pthread_rwlock_relclockrdlock_np(pthread_rwlock_t *restrict rwlock,
clockid_t clock, const struct timespec *restrict reltime);

int
pthread_rwlock_reltimedrdlock_np(pthread_rwlock_t *restrict rwlock,
const struct timespec *restrict reltime);

DESCRIPTION

The pthread_rwlock_clockrdlock(), pthread_rwlock_timedrdlock(),
pthread_rwlock_relclockrdlock_np(), and
pthread_rwlock_reltimedrdlock_np() functions apply a read lock to the
read-write lock referenced by rwlock. The calling thread will acquire
a read lock if there are no writers currently holding the lock and no
writers that are blocking to acquire a lock (writers starve readers).
However, if the read-write lock rwlock is not available, the calling
thread will be suspended and wait for the lock to become avaialble. If
the lock 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_rwlock_clockrdlock() and
pthread_rwlock_relclockrdlock_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_rwlock_timedrdlock() and
pthread_rwlock_reltimedrdlock_np() functions will always utilize the
realtime clock, CLOCK_REALTIME.

The pthread_rwlock_clockrdlock() and pthread_rwlock_timedrdlock()
functions treat the timeout value, abstime, as the absolute time in the
future when the timeout should expire. Conversely, the
pthread_rwlock_relclockrdlock_np() and
pthread_rwlock_reltimedrdlock_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 reltime. If the read-
write lock, rwlock, can be immediately read-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 read-write lock itself.

Similarly, if a signal that causes a signal handler to be executed is
delivered to a thread blocked on a read-write lock, then upon return
from the signal handler, the thread resumes waiting for the lock as
though it was not interrupted.

It is illegal for a thread to acquire a read lock on the same read-
write lock that it already holds a write lock on.

RETURN VALUES

Upon successful completion, the pthread_rwlock_clockrdlock(),
pthread_rwlock_timedrdlock(), pthread_rwlock_relclockrdlock_np(), and
pthread_rwlock_reltimedrdlock_np() return 0 and have successfully
acquired a read lock on rwlock. Otherwise, an error number is returned
to indicate the error.

ERRORS

The pthread_rwlock_clockrdlock(), pthread_rwlock_timedrdlock(),
pthread_rwlock_relclockrdlock_np(), and
pthread_rwlock_reltimedrdlock_np() will fail if:

EAGAIN The read lock could not be acquired because the
maximum number of read locks for lock would be
exceeded.

EDEADLK The calling thread already holds a write lock on
rwlock

EINVAL The value specified by rwlock does not refer to an
initialized read-write lock object. The timeout
nanosecond value is less than zero or greater than
or equal to 1,000 million.

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

ETIMEDOUT The lock could not be acquired before the specified
timeout expired.

INTERFACE STABILITY

Committed

MT-LEVEL
MT-Safe