1.\" Copyright (c) 2006 Gleb Smirnoff <glebius@FreeBSD.org> 2.\" All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 13.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 14.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 15.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 16.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 17.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 18.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 19.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 20.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 21.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 22.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 23.\" SUCH DAMAGE. 24.\" 25.\" $FreeBSD$ 26.\" 27.Dd April 19, 2006 28.Dt RWLOCK 9 29.Os 30.Sh NAME 31.Nm rwlock , 32.Nm rw_init , 33.Nm rw_rlock , 34.Nm rw_wlock , 35.Nm rw_assert , 36.Nm rw_runlock , 37.Nm rw_wunlock , 38.Nm rw_initialized , 39.Nm rw_destroy , 40.Nm RW_SYSINIT 41.Nd kernel reader/writer lock 42.Sh SYNOPSIS 43.In sys/param.h 44.In sys/lock.h 45.In sys/rwlock.h 46.Ft void 47.Fn rw_init "struct rwlock *rw" "const char *name" 48.Ft void 49.Fn rw_rlock "struct rwlock *rw" 50.Ft void 51.Fn rw_wlock "struct rwlock *rw" 52.Ft void 53.Fn rw_runlock "struct rwlock *rw" 54.Ft void 55.Fn rw_wunlock "struct rwlock *rw" 56.Ft int 57.Fn rw_try_upgrade "struct rwlock *rw" 58.Ft void 59.Fn rw_downgrade "struct rwlock *rw" 60.Ft int 61.Fn rw_initialized "struct rwlock *rw" 62.Ft void 63.Fn rw_destroy "struct rwlock *rw" 64.Ft int 65.Fn rw_wowned "struct rwlock *rw" 66.Pp 67.Cd "options INVARIANTS" 68.Cd "options INVARIANT_SUPPORT" 69.Ft void 70.Fn rw_assert "struct rwlock *rw" "int what" 71.In sys/kernel.h 72.Fn RW_SYSINIT "name" "struct rwlock *rw" "const char *desc" 73.Sh DESCRIPTION 74Reader/writer locks allow shared access to protected data by multiple threads, 75or exclusive access by a single thread. 76The threads with shared access are known as 77.Em readers 78since they only read the protected data. 79A thread with exclusive access is known as a 80.Em writer 81since it can modify protected data. 82.Pp 83Although reader/writer locks look very similar to 84.Xr sx 9 85locks, their usage pattern is different. 86Reader/writer locks can be treated as mutexes (see 87.Xr mutex 9 ) 88with shared/exclusive semantics. 89Unlike 90.Xr sx 9 , 91an 92.Nm 93can be locked while holding a non-spin mutex, and an 94.Nm 95cannot be held while sleeping. 96The 97.Nm 98locks have priority propagation like mutexes, but priority 99can be propagated only to an exclusive holder. 100This limitation comes from the fact that shared owners 101are anonymous. 102Another important property is that shared holders of 103.Nm 104can recurse, 105but exclusive locks are not allowed to recurse. 106.Ss Macros and Functions 107.Bl -tag -width indent 108.It Fn rw_init "struct rwlock *rw" "const char *name" 109Initialize structure located at 110.Fa rw 111as reader/writer lock, described by name 112.Fa name . 113The description is used solely for debugging purposes. 114This function must be called before any other operations 115on the lock. 116.It Fn rw_rlock "struct rwlock *rw" 117Lock 118.Fa rw 119as a reader. 120If any thread holds this lock exclusively, the current thread blocks, 121and its priority is propagated to the exclusive holder. 122The 123.Fn rw_rlock 124function can be called when the thread has already acquired reader 125access on 126.Fa rw . 127This is called 128.Dq "recursing on a lock" . 129.It Fn rw_wlock "struct rwlock *rw" 130Lock 131.Fa rw 132as a writer. 133If there are any shared owners of the lock, the current thread blocks. 134The 135.Fn rw_wlock 136function cannot be called recursively. 137.It Fn rw_runlock "struct rwlock *rw" 138This function releases a shared lock previously acquired by 139.Fn rw_rlock . 140.It Fn rw_wunlock "struct rwlock *rw" 141This function releases an exclusive lock previously acquired by 142.Fn rw_wlock . 143.It Fn rw_try_upgrade "struct rwlock *rw" 144Attempt to upgrade a single shared lock to an exclusive lock. 145The current thread must hold a shared lock of 146.Fa rw . 147This will only succeed if the current thread holds the only shared lock on 148.Fa rw , 149and it only holds a single shared lock. 150If the attempt succeeds 151.Fn rw_try_upgrade 152will return a non-zero value, 153and the current thread will hold an exclusive lock. 154If the attempt fails 155.Fn rw_try_upgrade 156will return zero, 157and the current thread will still hold a shared lock. 158.It Fn rw_downgrade "struct rwlock *rw" 159Convert an exclusive lock into a single shared lock. 160The current thread must hold an exclusive lock of 161.Fa rw . 162.It Fn rw_initialized "struct rwlock *rw" 163This function returns non-zero if 164.Fa rw 165has been initialized, and zero otherwise. 166.It Fn rw_destroy "struct rwlock *rw" 167This functions destroys a lock previously initialized with 168.Fn rw_init . 169The 170.Fa rw 171lock must be unlocked. 172.It Fn rw_wowned "struct rwlock *rw" 173This function returns a non-zero value if the current thread owns an 174exclusive lock on 175.Fa rw . 176.It Fn rw_assert "struct rwlock *rw" "int what" 177This function allows assertions specified in 178.Fa what 179to be made about 180.Fa rw . 181If the assertions are not true and the kernel is compiled 182with 183.Cd "options INVARIANTS" 184and 185.Cd "options INVARIANT_SUPPORT" , 186the kernel will panic. 187Currently the following assertions are supported: 188.Bl -tag -width ".Dv RA_UNLOCKED" 189.It Dv RA_LOCKED 190Assert that current thread holds either a shared or exclusive lock 191of 192.Fa rw . 193.It Dv RA_RLOCKED 194Assert that current thread holds a shared lock of 195.Fa rw . 196.It Dv RA_WLOCKED 197Assert that current thread holds an exclusive lock of 198.Fa rw . 199.It Dv RA_UNLOCKED 200Assert that current thread holds neither a shared nor exclusive lock of 201.Fa rw . 202.El 203.El 204.Sh SEE ALSO 205.Xr mutex 9 , 206.Xr panic 9 , 207.Xr sema 9 , 208.Xr sx 9 209.Sh HISTORY 210These 211functions appeared in 212.Fx 7.0 . 213.Sh AUTHORS 214.An -nosplit 215The 216.Nm 217facility was written by 218.An "John Baldwin" . 219This manual page was written by 220.An "Gleb Smirnoff" . 221.Sh BUGS 222If 223.Dv WITNESS 224is not included in the kernel, 225then it is impossible to assert that the current thread does or does not 226hold a shared lock. 227In the 228.Pf non- Dv WITNESS 229case, the 230.Dv RA_LOCKED 231and 232.Dv RA_RLOCKED 233assertions merely check that some thread holds a shared lock. 234.Pp 235Reader/writer is a bit of an awkward name. 236An 237.Nm 238can also be called a 239.Dq Robert Watson 240lock if desired. 241