pthread_rwlock.h

Implementation of a fair, POSIX conforming reader/writer lock.

Note

Do not include this header file directly, but pthread.h.

int pthread_rwlock_init(pthread_rwlock_t * rwlock, const pthread_rwlockattr_t * attr)

Initialize a reader/writer lock.

A zeroed out datum is initialized.

Parameters

rwlock:Lock to initialize. attr:Unused.

Return values

• 0 on success. EINVAL if rwlock == NULL.

int pthread_rwlock_destroy(pthread_rwlock_t * rwlock)

Destroy a reader/writer lock.

This is a no-op. Destroying a reader/writer lock while a thread holds it, or there are threads waiting for it causes undefined behavior. Datum must be reinitialized before using it again.

Parameters

rwlock:Lock to destroy.

Return values

• 0 on success. EINVAL if rwlock == NULL. EBUSY if the lock was in use.

int pthread_rwlock_rdlock(pthread_rwlock_t * rwlock)

Lock a reader/writer lock for reading.

This function may block.

Parameters

rwlock:Lock to acquire for reading.

Return values

• 0 if the lock could be acquired. EINVAL if rwlock == NULL.

int pthread_rwlock_tryrdlock(pthread_rwlock_t * rwlock)

Try to lock a reader/writer lock for reader.

This function won’t block.

Parameters

rwlock:Lock to acquire for reading.

Return values

• 0 if the lock could be acquired. EBUSY if acquiring the lock cannot be done without blocking. EINVAL if rwlock == NULL.

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

Try to acquire a read lock in a given timeframe.

Parameters

rwlock:Lock to acquire for reading. abstime:Maximum timestamp when to wakeup, absolute.

Return values

• 0 if the lock could be acquired. EDEADLK if the lock could not be acquired in the given timeframe. EINVAL if rwlock == NULL.

int pthread_rwlock_wrlock(pthread_rwlock_t * rwlock)

Lock a reader/writer lock for writing.

This function may block.

Parameters

rwlock:Lock to acquire for writing.

Return values

• 0 if the lock could be acquired. EINVAL if rwlock == NULL.

int pthread_rwlock_trywrlock(pthread_rwlock_t * rwlock)

Try to lock a reader/writer lock for writing.

This function won’t block.

Parameters

rwlock:Lock to acquire for writing.

Return values

• 0 if the lock could be acquired. EBUSY if acquiring the lock cannot be done without blocking. EINVAL if rwlock == NULL.

int pthread_rwlock_timedwrlock(pthread_rwlock_t * rwlock, const struct timespec * abstime)

Try to acquire a write lock in a given timeframe.

Parameters

rwlock:Lock to acquire for writing. abstime:Maximum timestamp when to wakeup, absolute.

Return values

• 0 if the lock could be acquired. EDEADLK if the lock could not be acquired in the given timeframe. EINVAL if rwlock == NULL.

int pthread_rwlock_unlock(pthread_rwlock_t * rwlock)

Unlock the reader/writer lock.

Must only be used if the lock is currently held. You may release the lock out of another thread, but the lock, operate, unlock logic must not be broken.

Parameters

rwlock:Lock to release

Return values

• 0 on success. EPERM if the lock was not held for any operation. EINVAL if rwlock == NULL.

bool __pthread_rwlock_blocked_readingly(const pthread_rwlock_t * rwlock)

Internal function to determine of the lock can be acquired for reading.

Parameters

rwlock:Lock to query.

Return values

• false if locking for reading is possible without blocking.

bool __pthread_rwlock_blocked_writingly(const pthread_rwlock_t * rwlock)

Internal function to determine of the lock can be acquired for writing.

Parameters

rwlock:Lock to query.

Return values

• false if locking for writing is possible without blocking.

struct pthread_rwlock_t

A fair reader writer lock.

The implementation ensures that readers and writers of the same priority won’t starve each other. E.g. no new readers will get into the critical section if a writer of the same or a higher priority already waits for the lock.

int readers

The current amount of reader inside the critical section.

• == 0: no thread is in the critical section.
• > 0: the number of readers currently in the critical section.
• < 0: a writer is currently in the critical section.

priority_queue_t queue

Queue of waiting threads.

mutex_t mutex

Provides mutual exclusion on reading and writing on the structure.

struct __pthread_rwlock_waiter_node_t

Internal structure that stores one waiting thread.

bool is_writer

false: reader; true: writer

sched.h::thread_t * thread

waiting thread

priority_queue.h::priority_queue_node_t qnode

Node to store in pthread_rwlock_t::queue.

bool continue_

This is not a spurious wakeup.