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_destroy , 34.Nm rw_rlock , 35.Nm rw_wlock , 36.Nm rw_runlock , 37.Nm rw_wunlock , 38.Nm rw_try_upgrade , 39.Nm rw_downgrade , 40.Nm rw_sleep , 41.Nm rw_initialized , 42.Nm rw_wowned , 43.Nm rw_assert , 44.Nm RW_SYSINIT 45.Nd kernel reader/writer lock 46.Sh SYNOPSIS 47.In sys/param.h 48.In sys/lock.h 49.In sys/rwlock.h 50.Ft void 51.Fn rw_init "struct rwlock *rw" "const char *name" 52.Ft void 53.Fn rw_destroy "struct rwlock *rw" 54.Ft void 55.Fn rw_rlock "struct rwlock *rw" 56.Ft void 57.Fn rw_wlock "struct rwlock *rw" 58.Ft void 59.Fn rw_runlock "struct rwlock *rw" 60.Ft void 61.Fn rw_wunlock "struct rwlock *rw" 62.Ft int 63.Fn rw_try_upgrade "struct rwlock *rw" 64.Ft void 65.Fn rw_downgrade "struct rwlock *rw" 66.Ft int 67.Fn rw_sleep "void *chan" "struct rwlock *rw" "int priority" "const char *wmesg" "int timo" 68.Ft int 69.Fn rw_initialized "struct rwlock *rw" 70.Ft int 71.Fn rw_wowned "struct rwlock *rw" 72.Pp 73.Cd "options INVARIANTS" 74.Cd "options INVARIANT_SUPPORT" 75.Ft void 76.Fn rw_assert "struct rwlock *rw" "int what" 77.In sys/kernel.h 78.Fn RW_SYSINIT "name" "struct rwlock *rw" "const char *desc" 79.Sh DESCRIPTION 80Reader/writer locks allow shared access to protected data by multiple threads, 81or exclusive access by a single thread. 82The threads with shared access are known as 83.Em readers 84since they only read the protected data. 85A thread with exclusive access is known as a 86.Em writer 87since it can modify protected data. 88.Pp 89Although reader/writer locks look very similar to 90.Xr sx 9 91locks, their usage pattern is different. 92Reader/writer locks can be treated as mutexes (see 93.Xr mutex 9 ) 94with shared/exclusive semantics. 95Unlike 96.Xr sx 9 , 97an 98.Nm 99can be locked while holding a non-spin mutex, and an 100.Nm 101cannot be held while sleeping. 102The 103.Nm 104locks have priority propagation like mutexes, but priority 105can be propagated only to an exclusive holder. 106This limitation comes from the fact that shared owners 107are anonymous. 108Another important property is that shared holders of 109.Nm 110can recurse, 111but exclusive locks are not allowed to recurse. 112.Ss Macros and Functions 113.Bl -tag -width indent 114.It Fn rw_init "struct rwlock *rw" "const char *name" 115Initialize structure located at 116.Fa rw 117as reader/writer lock, described by name 118.Fa name . 119The description is used solely for debugging purposes. 120This function must be called before any other operations 121on the lock. 122.It Fn rw_rlock "struct rwlock *rw" 123Lock 124.Fa rw 125as a reader. 126If any thread holds this lock exclusively, the current thread blocks, 127and its priority is propagated to the exclusive holder. 128The 129.Fn rw_rlock 130function can be called when the thread has already acquired reader 131access on 132.Fa rw . 133This is called 134.Dq "recursing on a lock" . 135.It Fn rw_wlock "struct rwlock *rw" 136Lock 137.Fa rw 138as a writer. 139If there are any shared owners of the lock, the current thread blocks. 140The 141.Fn rw_wlock 142function cannot be called recursively. 143.It Fn rw_runlock "struct rwlock *rw" 144This function releases a shared lock previously acquired by 145.Fn rw_rlock . 146.It Fn rw_wunlock "struct rwlock *rw" 147This function releases an exclusive lock previously acquired by 148.Fn rw_wlock . 149.It Fn rw_try_upgrade "struct rwlock *rw" 150Attempt to upgrade a single shared lock to an exclusive lock. 151The current thread must hold a shared lock of 152.Fa rw . 153This will only succeed if the current thread holds the only shared lock on 154.Fa rw , 155and it only holds a single shared lock. 156If the attempt succeeds 157.Fn rw_try_upgrade 158will return a non-zero value, 159and the current thread will hold an exclusive lock. 160If the attempt fails 161.Fn rw_try_upgrade 162will return zero, 163and the current thread will still hold a shared lock. 164.It Fn rw_downgrade "struct rwlock *rw" 165Convert an exclusive lock into a single shared lock. 166The current thread must hold an exclusive lock of 167.Fa rw . 168.It Fn rw_sleep "void *chan" "struct rwlock *rw" "int priority" "const char *wmesg" "int timo" 169Atomically release 170.Fa rw 171while waiting for an event. 172For more details on the parameters to this function, 173see 174.Xr sleep 9 . 175.It Fn rw_initialized "struct rwlock *rw" 176This function returns non-zero if 177.Fa rw 178has been initialized, and zero otherwise. 179.It Fn rw_destroy "struct rwlock *rw" 180This functions destroys a lock previously initialized with 181.Fn rw_init . 182The 183.Fa rw 184lock must be unlocked. 185.It Fn rw_wowned "struct rwlock *rw" 186This function returns a non-zero value if the current thread owns an 187exclusive lock on 188.Fa rw . 189.It Fn rw_assert "struct rwlock *rw" "int what" 190This function allows assertions specified in 191.Fa what 192to be made about 193.Fa rw . 194If the assertions are not true and the kernel is compiled 195with 196.Cd "options INVARIANTS" 197and 198.Cd "options INVARIANT_SUPPORT" , 199the kernel will panic. 200Currently the following assertions are supported: 201.Bl -tag -width ".Dv RA_UNLOCKED" 202.It Dv RA_LOCKED 203Assert that current thread holds either a shared or exclusive lock 204of 205.Fa rw . 206.It Dv RA_RLOCKED 207Assert that current thread holds a shared lock of 208.Fa rw . 209.It Dv RA_WLOCKED 210Assert that current thread holds an exclusive lock of 211.Fa rw . 212.It Dv RA_UNLOCKED 213Assert that current thread holds neither a shared nor exclusive lock of 214.Fa rw . 215.El 216.El 217.Sh SEE ALSO 218.Xr locking 9 , 219.Xr mutex 9 , 220.Xr panic 9 , 221.Xr sema 9 , 222.Xr sx 9 223.Sh HISTORY 224These 225functions appeared in 226.Fx 7.0 . 227.Sh AUTHORS 228.An -nosplit 229The 230.Nm 231facility was written by 232.An "John Baldwin" . 233This manual page was written by 234.An "Gleb Smirnoff" . 235.Sh BUGS 236If 237.Dv WITNESS 238is not included in the kernel, 239then it is impossible to assert that the current thread does or does not 240hold a read lock. 241In the 242.Pf non- Dv WITNESS 243case, the 244.Dv RA_LOCKED 245and 246.Dv RA_RLOCKED 247assertions merely check that some thread holds a read lock. 248.Pp 249Reader/writer is a bit of an awkward name. 250An 251.Nm 252can also be called a 253.Dq Robert Watson 254lock if desired. 255