PTHREAD_RWLOCK_TIMEDRDLOCK(3C) Standard C Library Functions PTHREAD_RWLOCK_TIMEDRDLOCK(3C)

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

Standard C Library (libc, -lc)

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

The (), (), pthread_rwlock_relclockrdlock_np(), and () 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 () 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_rwlock_timedrdlock() and () functions will always utilize the realtime clock, CLOCK_REALTIME.

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

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

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

The read lock could not be acquired because the maximum number of read locks for lock would be exceeded.
The calling thread already holds a write lock on rwlock
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.

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

clock_getres(3C), pthread_rwlock_destroy(3C), pthread_rwlock_rdlock(3C), pthread_rwlock_timedwrlock(3C), pthread_rwlock_tryrdlock(3C), pthread_rwlock_trywrlock(3C), pthread_rwlock_unlock(3C), pthread_rwlock_wrlock(3C), attributes(7), standards(7)

October 29, 2024 OmniOS