Document read/write locks.

Reviewed by:	jhb, ru

2 files changed, 201 insertions, 0 deletions

diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile
index 3ecff81..ed0eed1 100644
--- a/share/man/man9/Makefile
+++ b/share/man/man9/Makefile
@@ -196,6 +196,7 @@ MAN=	accept_filter.9 \
 	rtalloc.9 \
 	rtentry.9 \
 	runqueue.9 \
+	rwlock.9 \
 	sbuf.9 \
 	scheduler.9 \
 	securelevel_gt.9 \
diff --git a/share/man/man9/rwlock.9 b/share/man/man9/rwlock.9
new file mode 100644
index 0000000..7dae9d8
--- /dev/null
+++ b/share/man/man9/rwlock.9
@@ -0,0 +1,200 @@
+.\" 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" .