pthread_rwlock_fcfs_alloc, pthread_rwlock_fcfs_gain_read, pthread_rwlock_gain_write, pthread_rwlock_fcfs_timed_gain_read, pthread_rwlock_fcfs_timed_gain_write, pthread_rwlock_fcfs_try_gain_read, pthread_rwlock_fcfs_try_gain_write, pthread_rwlock_fcfs_release, pthread_rwlock_fcfs_destroy - operations on a first-come first-served readers/writers lock.

#include <pthread/rwlock_fcfs.h>

pthread_rwlock_fcfs_t * rwlock = pthread_rwlock_fcfs_alloc();

int pthread_rwlock_fcfs_gain_read(pthread_rwlock_fcfs_t * rwlock);

int pthread_rwlock_fcfs_gain_write(pthread_rwlock_fcfs_t * rwlock);

int pthread_rwlock_fcfs_try_gain_read(pthread_rwlock_fcfs_t * rwlock);

int pthread_rwlock_fcfs_try_gain_write(pthread_rwlock_fcfs_t * rwlock);

int pthread_rwlock_fcfs_timed_gain_read(pthread_rwlock_fcfs_t * rwlock, const struct timespec * abstime, int (*continue_callback)(void * context), void * context);

int pthread_rwlock_fcfs_timed_gain_write(pthread_rwlock_fcfs_t * rwlock, const struct timespec * abstime, int (*continue_callback)(void * context), void * context);

void pthread_rwlock_fcfs_release(pthread_rwlock_fcfs_t * rwlock);

void pthread_rwlock_fcfs_destroy(pthread_rwlock_fcfs_t * rwlock);

A Readers/Writers Lock (or "rwlock" for short) is a mechanism that allows an arbitrary number of readers, or alternatively one and only one writer to access a resource at a given time. A First-Come First-Served RWLock makes sure every pending thread will get its turn eventually.

To create a new rwlock call pthread_rwlock_fcfs_alloc(). From then on, more than one thread can use the lock simultaneously.

pthread_rwlock_fcfs_gain_read and pthread_rwlock_fcfs_gain_write can be used to gain read or write access for rwlock. They block indefinitely until the access is granted. They return 0 on success or -1 if the lock is going to be destroyed and should no longer be accessed.

pthread_rwlock_fcfs_try_gain_read and pthread_rwlock_fcfs_try_gain_write attempt to gain a read or write permission and if they do not succeed they exit immediately. They return 0 upon success, -1 if the lock is going to be destroyed, and non-zero otherwise.

pthread_rwlock_fcfs_timed_gain_read and pthread_rwlock_fcfs_timed_gain_write attempt to gain a permission while initially waiting until abstime. If by that time access is not granted, then continue_callback will be called to find out if the functions should continue waiting.

continue_callback is responsible for setting a new value for abstime and should return 1 if it wishes to continue wait for a permission or 0 otherwise. callback_context is the argument which it receives as an argument.

If continue_callback is set to NULL, then it will be ignored, and the function will terminate once the initial wait is over.

pthread_rwlock_fcfs_timed_gain_read and pthread_rwlock_fcfs_timed_gain_write return 0 upon success, 1 if they failed to gain a read or write permission and -1 if the lock is going to be destroyed.

pthread_rwlock_fcfs_release releases a previously granted read or write permission.

pthread_rwlock_fcfs_destroy can be used to destroy a previously allocated rwlock.

These RWLock functions are not async-signal safe, and should not be called from a signal handler.

All the rwlock functions return 0 on success, -1 if the rwlock is going to be destroyed, and a non-zero error code on error.

Shlomi Fish <shlomif@vipe.technion.ac.il>.

See the test_rwlock.c file inside the pthreads' FCFS RWLock distribution.