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