rwlock(3synch) rwlock(3synch)
NAME
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);
Parameters
lock pointer to reader-writer lock to be initialized
type USYNC_THREAD or USYNC_PROCESS
arg NULL (reserved for future use)
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 re-initialized.
rw_rdlock
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.
Copyright 1994 Novell, Inc. Page 1
rwlock(3synch) rwlock(3synch)
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
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
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, rw_trywrlock 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
rw_trywrlock makes a single attempt to acquire the reader-
writer lock pointed to by lock in write mode; it does not
Copyright 1994 Novell, Inc. Page 2
rwlock(3synch) rwlock(3synch)
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 by a writer, or there are
writers waiting, rw_trywrlock immediately returns EBUSY to the
caller, without acquiring the lock.
rw_unlock
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
Copyright 1994 Novell, Inc. Page 3
rwlock(3synch) rwlock(3synch)
processes.
USAGE
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
rwlock_destroy(3synch), rwlock_init(3synch),
rw_rdlock(3synch), rw_tryrdlock(3synch), rw_trywrlock(3synch),
rw_unlock(3synch), rw_wrlock(3synch), synch(3synch)
Copyright 1994 Novell, Inc. Page 4