rwlock(SYNCH)
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(SYNCH).
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(SYNCH),
rwlock_destroy(SYNCH),
rwlock_init(SYNCH),
rw_rdlock(SYNCH),
rw_tryrdlock(SYNCH),
rw_trywrlock(SYNCH),
rw_unlock(SYNCH),
rw_wrlock(SYNCH)
© 2005 The SCO Group, Inc. All rights reserved.
SCO OpenServer Release 6.0.0 - 01 June 2005