Standard C Library Functions rwlock(3C)
NAME
rwlock, rwlockinit, rwlockdestroy, rwrdlock, rwwrlock,
rwtryrdlock, rwtrywrlock, rwunlock - multiple readers,
single writer locks
SYNOPSIS
cc -mt [ flag... ] file...[ library... ]
#include
int rwlockinit(rwlockt *rwlp, int type, void * arg);
int rwlockdestroy(rwlockt *rwlp);
int rwrdlock(rwlockt *rwlp);
int rwwrlock(rwlockt *rwlp);
int rwunlock(rwlockt *rwlp);
int rwtryrdlock(rwlockt *rwlp);
int rwtrywrlock(rwlockt *rwlp);
DESCRIPTION
Many threads can have simultaneous read-only access to data,
while only one thread can have write access at any given
time. Multiple read access with single write access is con-
trolled by locks, which are generally used to protect data
that is frequently searched.
Readers/writer locks can synchronize threads in this process
and other processes if they are allocated in writable memory
and shared among cooperating processes (see mmap(2)), and
are initialized for this purpose.
Additionally, readers/writer locks must be initialized prior
to use. rwlockinit() The readers/writer lock pointed to by
rwlp is initialized by rwlockinit(). A readers/writer lock
is capable of having several types of behavior, which is
specified by type. arg is currently not used, although a
future type may define new behavior parameters by way of
arg.
SunOS 5.11 Last change: 14 May 1998 1
Standard C Library Functions rwlock(3C)
The type argument can be one of the following:
USYNCPROCES The readers/writer lock can synchronize
threads in this process and other
processes. The readers/writer lock should
be initialized by only one process. arg is
ignored. A readers/writer lock initialized
with this type, must be allocated in
memory shared between processses, i.e.
either in Sys V shared memory (see
shmop(2)) or in memory mapped to a file
(see mmap(2)). It is illegal to initialize
the object this way and to not allocate it
in such shared memory.
USYNCTHREAD The readers/writer lock can synchronize
threads in this process, only. arg is
ignored.
Additionally, readers/writer locks can be initialized by
allocation in zeroed memory. A type of USYNCTHREAD is
assumed in this case. Multiple threads must not simultane-
ously initialize the same readers/writer lock. And a
readers/writer lock must not be re-initialized while in use
by other threads.
The following are default readers/writer lock initialization
(intra-process):
rwlockt rwlp;
rwlockinit(&rwlp, NUL, NUL);
or
rwlockinit(&rwlp, USYNCTHREAD, NUL);
or
rwlockt rwlp = DEFAULTRWLOCK;
SunOS 5.11 Last change: 14 May 1998 2
Standard C Library Functions rwlock(3C)
The following is a customized readers/writer lock initiali-
zation (inter-process):
rwlockinit(&rwlp, USYNCPROCES, NUL);
Any state associated with the readers/writer lock pointed to
by rwlp are destroyed by rwlockdestroy() and the
readers/writer lock storage space is not released.
rwrdlock() gets a read lock on the readers/writer lock
pointed to by rwlp. If the readers/writer lock is currently
locked for writing, the calling thread blocks until the
write lock is freed. Multiple threads may simultaneously
hold a read lock on a readers/writer lock.
rwtryrdlock() trys to get a read lock on the readers/writer
lock pointed to by rwlp. If the readers/writer lock is
locked for writing, it returns an error; otherwise, the read
lock is acquired.
rwwrlock() gets a write lock on the readers/writer lock
pointed to by rwlp. If the readers/writer lock is currently
locked for reading or writing, the calling thread blocks
until all the read and write locks are freed. At any given
time, only one thread may have a write lock on a
readers/writer lock.
rwtrywrlock() trys to get a write lock on the
readers/writer lock pointed to by rwlp. If the
readers/writer lock is currently locked for reading or writ-
ing, it returns an error.
rwunlock() unlocks a readers/writer lock pointed to by
rwlp, if the readers/writer lock is locked and the calling
thread holds the lock for either reading or writing. One of
the other threads that is waiting for the readers/writer
lock to be freed will be unblocked, provided there is other
waiting threads. If the calling thread does not hold the
lock for either reading or writing, no error status is
returned, and the program's behavior is unknown.
RETURN VALUES
If successful, these functions return 0. Otherwise, a non-
zero value is returned to indicate the error.
SunOS 5.11 Last change: 14 May 1998 3
Standard C Library Functions rwlock(3C)
ERORS
The rwlockinit() function will fail if:
EINVAL type is invalid.
The rwtryrdlock() or rwtrywrlock() functions will fail
if:
EBUSY The reader or writer lock pointed to by rwlp was
already locked.
These functions may fail if:
EFAULT rwlp or arg points to an illegal address.
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
MT-Level MT-Safe
SEE ALSO
mmap(2), attributes(5)
NOTES
These interfaces also available by way of:
#include
If multiple threads are waiting for a readers/writer lock,
the acquisition order is random by default. However, some
implementations may bias acquisition order to avoid depriv-
ing writers. The current implementation favors writers over
readers.
SunOS 5.11 Last change: 14 May 1998 4
|
