rwlock(3T)
NAME
rwlock, rwlock_init, rwlock_destroy, rw_rdlock, rw_wrlock, rw_tryrdlock, rw_trywrlock, rw_unlock − multiple readers, single writer locks
SYNOPSIS
#include <synch.h>
int rwlock_init(rwlock_t ∗rwlp, int type, void ∗ arg);
int rwlock_destroy(rwlock_t ∗rwlp);
int rw_rdlock(rwlock_t ∗rwlp);
int rw_wrlock(rwlock_t ∗rwlp);
int rw_unlock(rwlock_t ∗rwlp);
int rw_tryrdlock(rwlock_t ∗rwlp);
int rw_trywrlock(rwlock_t ∗rwlp);
MT-LEVEL
MT-Safe
DESCRIPTION
Multiple readers, single writer (readers/writer) locks allow many threads to have simultaneous read-only access to data while allowing only one thread to have write access at any given time. They are typically used to protect data that is searched more frequently than it is changed.
Readers/writer locks can be used to synchronize threads in this process and other processes if they are allocated in memory that is writable and shared among the cooperating processes (see mmap(2)) and have been initialized for this behavior.
Readers/writer locks must be initialized before use. rwlock_init() initializes the readers/writer lock pointed to by rwlp. A readers/writer lock can potentially have several different types of behavior, specified by type. Each type may specify additional behavior parameters via arg. type may be one of the following:
USYNC_PROCESS The readers/writer lock may be used to synchronize threads in this process and other processes. Only one process should initialize the readers/writer lock. arg is ignored.
USYNC_THREAD The readers/writer lock may be used to synchronize only threads in this process. arg is ignored.
Readers/writer locks may also be initialized by allocation in zeroed memory. In this case a type of USYNC_THREAD is assumed. Multiple threads must not initialize the same readers/writer lock simultaneously. A readers/writer lock must not be re-initialized while other threads may be using it.
rwlock_destroy() destroys any state associated with the readers/writer lock pointed to by rwlp. The space for storing the readers/writer lock is not freed.
rw_rdlock() acquires a read lock on the readers/writer lock pointed to by rwlp. If the readers/writer lock is already locked for writing, the calling thread blocks until the write lock is released. More than one thread may hold a read lock on a readers/writer lock at any one time.
rw_tryrdlock() attempts to acquire a read lock on the readers/writer lock pointed to by rwlp. If the readers/writer lock is already locked for writing, it returns an error. Otherwise the read lock is acquired.
rw_wrlock() acquires a write lock on the readers/writer lock pointed to by rwlp. If the readers/writer lock is already locked for reading or writing, the calling thread blocks until all the read locks and write locks are released. Only one thread may hold a write lock on a readers/writer lock at any one time.
rw_trywrlock() attempts to acquire a write lock on the readers/writer lock pointed to by rwlp. If the readers/writer lock is already locked for reading or writing, it returns an error.
rw_unlock() unlocks a readers/writer lock. The readers/writer lock must be locked and the calling thread must hold the lock either for reading or writing. If any other threads are waiting for the readers/writer lock to become available, one of them is unblocked.
RETURN VALUES
Zero is returned when successful. A non-zero value indicates an error.
ERRORS
If any of the following conditions are detected, these functions fail and return the corresponding value:
EINVAL Invalid argument.
EFAULT rwlp or arg point to an illegal address.
If any of the following conditions occur, rw_tryrdlock() and rw_trywrlock() return the corresponding value:
EBUSY The readers/writer lock pointed to by rwlp was already locked.
SEE ALSO
NOTES
These interfaces also available via:
#include <thread.h>
By default, there is no defined order of acquisition if multiple threads are waiting for a readers/writer lock. However, implementations usually bias acquisition order in some way so as to avoid writer starvation. The current implementation tends to favor writers over readers.
Sun Microsystems — Last change: 22 Jan 1993