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: head/share/man/man9/rwlock.9 157881 2006-04-19 20:43:35Z jhb $
.Dd April 19, 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 reader/writer lock .Sh SYNOPSIS n sys/param.h n sys/lock.h n sys/rwlock.h .Ft void .Fn rw_init "struct rwlock *rw" "const char *name" .Ft void .Fn rw_rlock "struct rwlock *rw" .Ft void .Fn rw_wlock "struct rwlock *rw" .Ft void .Fn rw_runlock "struct rwlock *rw" .Ft void .Fn rw_wunlock "struct rwlock *rw" .Ft int .Fn rw_initialized "struct rwlock *rw" .Ft void .Fn rw_destroy "struct rwlock *rw"
p .Cd "options INVARIANTS" .Cd "options INVARIANT_SUPPORT" .Ft void .Fn rw_assert "struct rwlock *rw" "int what" n sys/kernel.h .Fn RW_SYSINIT "name" "struct rwlock *rw" "const char *desc" .Sh DESCRIPTION Reader/writer locks allow shared access to protected data by multiple threads, or exclusive access by a single thread. The threads with shared access are known as .Em readers since they only read the protected data. A thread with exclusive access is known as a .Em writer since it can modify protected data.
p Although reader/writeer locks look very similar to .Xr sx 9 locks, their usage pattern is different. Reader/writer 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, and an .Nm cannot be held while sleeping. The .Nm locks have priority propagation like mutexes, but priority can be propagated only to an exclusive holder. This limitation comes from the fact that shared owners are anonymous. Another important property is that shared holders of .Nm can recurse, but exclusive locks are not allowed to recurse. .Ss Macros and Functions l -tag -width indent t Fn rw_init "struct rwlock *rw" "const char *name" Initialize structure located at .Fa rw as reader/writer lock, described by name .Fa name . The description is used solely for debugging purposes. This function must be called before any other operations on the lock. t Fn rw_rlock "struct rwlock *rw" Lock .Fa rw as a reader. If any thread holds this lock exclusively, the current thread blocks, and its priority is propagated to the exclusive holder. The .Fn rw_rlock function can be called when the thread has already acquired reader access on .Fa rw . This is called .Dq "recursing on a lock" . t Fn rw_wlock "struct rwlock *rw" Lock .Fa rw as a writer. If there are any shared owners of the lock, the current thread blocks. The .Fn rw_wlock function cannot be called recursively. t Fn rw_runlock "struct rwlock *rw" This function releases a shared lock previously acquired by .Fn rw_rlock . t Fn rw_wunlock "struct rwlock *rw" This function releases an exclusive lock previously acquired by .Fn rw_wlock . t Fn rw_initialized "struct rwlock *rw" This function returns non-zero if .Fa rw has been initialized, and zero otherwise. t Fn rw_destroy "struct rwlock *rw" This functions destroys a lock previously initialized with .Fn rw_init . The .Fa rw lock must be unlocked. t Fn rw_assert "struct rwlock *rw" "int what" This function allows assertions specified in .Fa what to be made about .Fa rw . 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: l -tag -width ".Dv RA_UNLOCKED" t Dv RA_LOCKED Assert that current thread holds either a shared or exclusive lock of .Fa rw . t Dv RA_RLOCKED Assert that current thread holds a shared lock of .Fa rw . t Dv RA_WLOCKED Assert that current thread holds an exclusive lock of .Fa rw . t Dv RA_UNLOCKED Assert that current thread holds neither a shared nor exclusive lock of .Fa rw . .El .El .Sh SEE ALSO .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" . .Sh BUGS If .Dv WITNESS is not included in the kernel, then it is impossible to assert that the current thread does or does not hold a shared lock. In the .No non - Ns Dv WITNESS case, the .Dv RA_LOCKED and .Dv RA_RLOCKED assertions merely check that some thread holds a shared lock.
p Reader/writer is a bit of an awkward name. An .Nm can also be called a .Dq Robert Watson lock if desired.