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 155189 2006-02-01 19:39:25Z glebius $
.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 n sys/param.h n sys/lock.h n 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"
p .Cd "options INVARIANTS" .Cd "options INVARIANT_SUPPORT" .Ft void .Fn rw_assert "struct rwlock *rwlock" "int what" n 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.
p 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 l -tag -width indent t 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. t 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" . t 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. t Fn rw_runlock "struct rwlock *rwlock" This function releases shared lock, previously acquired by .Fn rw_rlock . t Fn rw_wunlock "struct rwlock *rwlock" This function releases exclusive lock, previously acquired by .Fn rw_wlock . t Fn rw_initialized "struct rwlock *rwlock" This function returns non-zero if the .Fa rwlock has been initialized, and zero otherwise. t Fn rw_destroy "struct rwlock *rwlock" This functions destroys a lock previously initialized with .Fn rw_init . The .Fa rwlock must be unlocked. t 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: l -tag -width ".Dv RA_UNLOCKED" t Dv RA_LOCKED Assert that current thread is either shared or exclusive owner of the .Nm pointed to by the first argument. t Dv RA_RLOCKED Assert that current thread is shared owner of the .Nm pointed to by the first argument. t Dv RA_WLOCKED Assert that current thread is exclusive owner of the .Nm pointed to by the first argument. t 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" .