RWLOCK(9)

NAME
rwlock, rw_init, rw_init_flags, rw_init_flags_trace, rw_enter, rw_exit, rw_enter_read, rw_enter_write, rw_exit_read, rw_exit_write, rw_assert_wrlock, rw_assert_rdlock, rw_assert_anylock, rw_assert_unlocked, rw_status, RWLOCK_INITIALIZER, RWLOCK_INITIALIZER_TRACE, rrw_init, rrw_init_flags, rrw_enter, rrw_exit, rrw_status - interface to read/write locks

SYNOPSIS
#include <sys/rwlock.h>
void
rw_init(struct rwlock *rwl, const char *name);
void
rw_init_flags(struct rwlock *rwl, const char *name, int flags);
void
rw_init_flags_trace(struct rwlock *rwl, const char *name, int flags, int trace);
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_anylock(struct rwlock *rwl);
void
rw_assert_unlocked(struct rwlock *rwl);
int
rw_status(struct rwlock *rwl);
RWLOCK_INITIALIZER(const char *name);
RWLOCK_INITIALIZER_TRACE(const char *name, int trace);
void
rrw_init(struct rrwlock *rrwl, const char *name);
void
rrw_init_flags(struct rrwlock *rrwl, const char *name, int flags);
int
rrw_enter(struct rrwlock *rrwl, int flags);
void
rrw_exit(struct rrwlock *rrwl);
int
rrw_status(struct rrwlock *rrwl);

DESCRIPTION
The rwlock set of functions provides a multiple-reader, single-writer locking mechanism to ensure mutual exclusion between different threads.

Read locks can be acquired while the write lock is not held, and may coexist in distinct threads at any time. A write lock, however, can only be acquired when there are no read locks held, granting exclusive access to a single thread.

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 thread needs to sleep.

The rw_init_flags() macro is similar to rw_init(), but it additionally accepts a bitwise OR of the following flags:

RWL_DUPOK
    Prevents witness(4) from logging when a thread acquires more than one lock of this lock type.

RWL_IS_VNODE
    Make witness(4) ignore lock order issues between this lock type and any other lock type tagged with the RWL_IS_VNODE flag.

RWL_NOWITNESS
    Instructs witness(4) to ignore this lock.
rw_init_flags_trace() additionally accepts a dt(4) static probe index.

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_UPGRADE
    Upgrade a shared lock into an exclusive one. Must be combined with RW_NOSLEEP.
RW_INTR
    When waiting for a lock, allow signals to interrupt the sleep.
RW_NOSLEEP
    Do not wait for busy locks, fail with EBUSY instead.
RW_DUPOK
    Prevents witness(4), for just this rw_enter(), from logging when this thread already has a lock of this lock type.

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.

The rw_assert_wrlock(), rw_assert_rdlock(), rw_assert_anylock(), and rw_assert_unlocked() functions check the status rwl, panicking if it is not write-, read-, any-, or unlocked, respectively.

rw_status returns the current state of the lock.

A lock declaration may be initialised with the RWLOCK_INITIALIZER() macro. The name argument specifies the name of the lock, which is used as the wait message if the thread needs to sleep. RWLOCK_INITIALIZER_TRACE() additionally accepts a dt(4) static probe index.

The rrwlock functions support recursive write locking by the same process. They otherwise behave the same as their rwlock counterparts.

CONTEXT
rw_init(), rw_init_flags(), rw_init_flags_trace(), rrw_init() and rrw_init_flags() can be called during autoconf, from process context, or from interrupt context.

All other functions can be called during autoconf or from process context.

RETURN VALUES
rw_enter and rrw_enter return 0 on success, or an errno(2) style value on failure.

rw_status and rrw_status return the state of the lock:

RW_WRITE
    Lock is write locked by the calling thread.
RW_WRITE_OTHER
    Lock is write locked by a different thread.
RW_READ
    Lock is read locked. The current thread may be one of the threads that has it locked.
0   Lock is not locked.

SEE ALSO
witness(4), mutex(9), rwsleep(9), spl(9)

HISTORY
The rwlock functions first appeared in OpenBSD 3.5.

AUTHORS
The rwlock functions were written by Artur Grabowski <art@openbsd.org>.