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