rwlock(3synch)

rwlock: rwlock_init, rw_rdlock, rw_wrlock, rw_tryrdlock, rw_trywrlock, rw_unlock, rwlock_destroy, -- overview of reader-writer lock routines

Synopsis

   cc [options] -Kthread file
   
   #include <synch.h>
   

   int rwlock_init(rwlock_t *lock, int type, void *arg);
   

   int rw_rdlock(rwlock_t *lock);
   

   int rw_wrlock(rwlock_t *lock);
   

   int rw_tryrdlock(rwlock_t *lock);
   

   int rw_trywrlock(rwlock_t *lock);
   

   int rw_unlock(rwlock_t *lock);
   

   int rwlock_destroy(rwlock_t *lock);

Description

Reader-writer locks allow many threads to have simultaneous read-only access to data, while allowing only one thread to have write access at any time. They are typically used to protect data that is searched more often than it is changed.

rwlock_init

rwlock_init initializes the reader-writer lock pointed to by rwlock to be of type type and in the unlocked state. Once initialized, the lock can be used any number of times without being reinitialized.

Parameters

lock: pointer to reader-writer lock to be initialized
type: USYNC_THREAD or USYNC_PROCESS
arg: NULL (reserved for future use)

rw_rdlock(3synch)

rw_rdlock acquires the reader-writer lock pointed to by lock in read mode.

A reader-writer lock can be held by any number of readers at one time, but only one writer at a time can hold the lock. Once a writer has requested the lock with rw_wrlock, all subsequent requests for the lock in either read or write mode are queued.

If the lock is free, or is currently held by another reader and there are no writers waiting, rw_rdlock increments the reader count and the caller proceeds. If a writer holds the lock or if any writer is waiting for the lock, the caller blocks to wait for the lock.

rw_wrlock(3synch)

rw_wrlock acquires the reader-writer lock pointed to by lock in write mode.

Only one writer at a time can hold a reader-writer lock, although any number of readers can hold the lock at any time. Once a writer has requested the lock with rw_wrlock, all subsequent requests for the lock in either read or write mode are blocked.

When no other readers or writers hold the lock, rw_wrlock will acquire the lock, and the caller will proceed. Any other write and read requests for the lock will block until the caller unlocks the lock with rw_unlock(3synch).

If the lock is held by any readers when rw_wrlock is called, and no writer is waiting for the lock, the caller blocks until all the current readers have released the lock. If the lock is held by another writer, or if there are any other writers already waiting for the lock, the caller blocks to wait for the lock.

rw_tryrdlock(3synch)

rw_tryrdlock attempts once to acquire the reader-writer lock pointed to by lock in read mode; it does not block the caller if the lock is unavailable.

A reader-writer lock can be held by any number of readers at one time, but only one writer at a time can hold the lock.

If the lock is free or is currently held by another reader and there are no writers waiting, rw_tryrdlock increments the reader count and the caller proceeds.

If the lock is currently held by a writer, or there are writers waiting, rw_tryrdlock immediately returns EBUSY to the caller, without acquiring the lock.

rw_trywrlock(3synch)

rw_trywrlock makes a single attempt to acquire the reader-writer lock pointed to by lock in write mode; it does not block the caller if the lock is unavailable.

A reader-writer lock can be held by any number of readers at one time, but only one writer at a time can hold the lock.

If the lock is free, rw_trywrlock acquires the lock in write mode and the caller proceeds.

If the lock is currently held, rw_trywrlock immediately returns EBUSY to the caller, without acquiring the lock.

rw_unlock(3synch)

rw_unlock releases a reader-writer lock previously acquired by rw_rdlock, rw_wrlock, rw_tryrdlock, or rw_trywrlock. The behavior differs according to whether the caller is a reader or a writer:

When a writer calls rw_unlock, the lock is unlocked.
When a reader calls rw_unlock, the reader count is decremented. If the reader count is zero, rw_unlock unlocks the lock, otherwise, the lock is not unlocked.

When rw_unlock unlocks the lock, the first waiter (reader or writer) is activated.

If the thread activated is a reader, all subsequent readers are activated (up to the next writer or end of queue) and the count of readers holding the lock is changed to reflect this.
If the thread activated is a writer, no other threads are activated and the lock is marked as being held by a writer.

rwlock_destroy

rwlock_destroy destroys the reader-writer lock pointed to by lock. This includes invalidating the lock and freeing any associated dynamically allocated resources.

USYNC_THREAD and USYNC_PROCESS reader-Writer locks

Reader-writer locks are initialized to be one of two types: USYNC_THREAD or USYNC_PROCESS. USYNC_THREAD locks are available only to threads within the current process. USYNC_PROCESS locks can be used by threads in different processes.

Warnings

Operations on locks initialized with rwlock_init are not recursive--a thread can deadlock if it attempts to reacquire a reader-writer lock that it already has acquired.

References

Intro(3synch), rwlock_destroy(3synch), rwlock_init(3synch), rw_rdlock(3synch), rw_tryrdlock(3synch), rw_trywrlock(3synch), rw_unlock(3synch), rw_wrlock(3synch)