man/man9/rwlock.9

.\" Copyright (c) 2006 Gleb Smirnoff <glebius@FreeBSD.org>
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" $FreeBSD$
.\"
.Dd January 30, 2006
.Dt RWLOCK 9
.Os
.Sh NAME
.Nm rwlock
.Nm rw_init ,
.Nm rw_rlock ,
.Nm rw_wlock ,
.Nm rw_assert ,
.Nm rw_runlock ,
.Nm rw_wunlock ,
.Nm rw_initialized ,
.Nm rw_destroy ,
.Nm RW_SYSINIT ,
.Nd kernel synchronization primitives
.Sh SYNOPSIS
.In sys/param.h
.In sys/lock.h
.In sys/rwlock.h
.Ft void
.Fn rw_init "struct rwlock *rwlock" "const char *name"
.Ft void
.Fn rw_rlock "struct rwlock *rwlock"
.Ft void
.Fn rw_wlock "struct rwlock *rwlock"
.Ft void
.Fn rw_runlock "struct rwlock *rwlock"
.Ft void
.Fn rw_wunlock "struct rwlock *rwlock"
.Ft int
.Fn rw_initialized "struct rwlock *rwlock"
.Ft void
.Fn rw_destroy "struct rwlock *rwlock"
.Pp
.Cd "options INVARIANTS"
.Cd "options INVARIANT_SUPPORT"
.Ft void
.Fn rw_assert "struct rwlock *rwlock" "int what"
.In sys/kernel.h
.Fn RW_SYSINIT "name" "struct rwlock *rwlock" "const char *description"
.Sh DESCRIPTION
Read/write locks are a method of thread synchronization, which
allows several threads have shared access to protected data, or
one thread have exclusive access.
The threads that share access are known as
.Em readers
since they should only read the protected data, while thread
with exclusive access is known as a
.Em writer
since it can modify protected data.
.Pp
Although the description of read/write locks looks very similar
to description of
.Xr sx 9
locks, their usage pattern is different.
The read/write locks can be treated as mutexes (see
.Xr mutex 9 )
with shared/exclusive semantics.
Unlike
.Xr sx 9 ,
an
.Nm
can be locked while holding a non-spin mutex;
.Nm
cannot be held while sleeping.
The
.Nm
locks have priority propagation like mutexes, but priority
can be propagated only to exclusive holder.
This limitation comes from the fact that shared owners
are anonymous.
Another important property is that shared holder of
.Nm
can recurse on it.
.Ss Macros and Functions
.Bl -tag -width indent
.It Fn rw_init "struct rwlock *rwlock" "const char *name"
Initialize structure located at
.Fa rwlock
as read/write lock, described by name
.Fa name .
The description is used solely for debugging purposes.
This function must be used before any other manipulations
with the lock.
.It Fn rw_rlock "struct rwlock *rwlock"
Lock the
.Fa rwlock
as reader.
If any thread holds this lock exclusively, the current thread blocks,
and its priority is propagated to exclusive holder.
The
.Fn rw_rlock
function can be called when the thread has already acquired reader
access on
.Fa rwlock .
This is called
.Dq "recursing on a lock" .
.It Fn rw_wlock "struct rwlock *rwlock"
Lock the
.Fa rwlock
as writer.
If there are any shared owners of the lock, the current thread blocks.
The
.Fn rw_wlock
function cannot be called recursively.
.It Fn rw_runlock "struct rwlock *rwlock"
This function releases shared lock, previously acquired by
.Fn rw_rlock .
.It Fn rw_wunlock "struct rwlock *rwlock"
This function releases exclusive lock, previously acquired by
.Fn rw_wlock .
.It Fn rw_initialized "struct rwlock *rwlock"
This function returns non-zero if the
.Fa rwlock
has been initialized, and zero otherwise.
.It Fn rw_destroy "struct rwlock *rwlock"
This functions destroys a lock previously initialized with
.Fn rw_init .
The
.Fa rwlock
must be unlocked.
.It Fn rw_assert "struct rwlock *rwlock" "int what"
This function allows assertions specified in
.Fa what
to be made about
.Fa rwlock .
If the assertions are not true and the kernel is compiled
with
.Cd "options INVARIANTS"
and
.Cd "options INVARIANT_SUPPORT" ,
the kernel will panic.
Currently the following assertions are supported:
.Bl -tag -width ".Dv RA_UNLOCKED"
.It Dv RA_LOCKED
Assert that current thread is either shared or exclusive owner
of the
.Nm
pointed to by the first argument.
.It Dv RA_RLOCKED
Assert that current thread is shared owner of the
.Nm
pointed
to by the first argument.
.It Dv RA_WLOCKED
Assert that current thread is exclusive owner of the
.Nm
pointed
to by the first argument.
.It Dv RA_UNLOCKED
Assert that current thread is neither shared nor exclusive owner
of the
.Nm
pointed to by the first argument.
.El
.El
.Sh SEE ALSO
.Xr condvar 9 ,
.Xr mutex 9 ,
.Xr panic 9 ,
.Xr sema 9 ,
.Xr sx 9
.Sh HISTORY
These
functions appeared in
.Fx 7.0 .
.Sh AUTHORS
.An -nosplit
The
.Nm
facility was written by
.An "John Baldwin" .
This manual page was written by
.An "Gleb Smirnoff" .