NAME
rwlock, rw_init,
rw_enter, rw_exit,
rw_enter_read,
rw_enter_write,
rw_exit_read, rw_exit_write
— interface to read/write
locks
SYNOPSIS
#include
<sys/rwlock.h>
void
rw_init(struct
rwlock *rwl, const char
*name);
int
rw_enter(struct
rwlock *rwl, int
flags);
void
rw_exit(struct
rwlock *rwl);
void
rw_enter_read(struct
rwlock *rwl);
void
rw_enter_write(struct
rwlock *rwl);
void
rw_exit_read(struct
rwlock *rwl);
void
rw_exit_write(struct
rwlock *rwl);
void
rw_assert_wrlock(struct
rwlock *rwl);
void
rw_assert_rdlock(struct
rwlock *rwl);
void
rw_assert_unlocked(struct
rwlock *rwl);
DESCRIPTION
The rwlock set of functions provides a
multiple-reader, single-writer locking mechanism to ensure mutual exclusion
between different processes.
The
rw_init()
function is used to initiate the lock pointed to by
rwl. The name argument specifies
the name of the lock, which is used as the wait message if the process needs
to sleep.
The
rw_enter()
function acquires a lock. The flags argument specifies
what kind of lock should be obtained and also modifies the operation. The
possible flags are:
RW_READ- Acquire a shared lock.
RW_WRITE- Acquire an exclusive lock.
RW_DOWNGRADE- Safely release an exclusive lock and acquire a shared lock without letting other exclusive locks in between.
RW_INTR- When waiting for a lock, allow signals to interrupt the sleep.
RW_NOSLEEP- Do not wait for busy locks, fail with
EBUSYinstead. RW_SLEEPFAIL- Wait for busy locks, but do not obtain them, fail with
EAGAINinstead.
The
rw_exit()
function is used to release a held lock.
The
rw_enter_read()
function acquires a read lock, sleeping if necessary.
The
rw_enter_write()
function acquires a write lock, sleeping if necessary.
The
rw_exit_read()
function releases a read lock.
The
rw_exit_write()
function releases a write lock.
Read locks can be acquired while the write lock is not held, and may coexist in distinct processes at any time. A write lock, however, can only be acquired when there are no read locks held, granting exclusive access to a single process.
The
rw_assert_wrlock(),
rw_assert_rdlock(),
and
rw_assert_unlocked()
functions check the status rwl, panicking if it is not
write-, read-, or unlocked, respectively.
SEE ALSO
HISTORY
The rwlock functions first appeared in
OpenBSD 3.5.
AUTHORS
The rwlock functions were written by
Artur Grabowski ⟨art@openbsd.org⟩.
CAVEATS
While it is safe to sleep with an rwlock held, they cannot be used in an interrupt handler as an rwlock is bound to a process.