1.\" $OpenBSD: rwlock.9,v 1.25 2019/11/04 18:16:27 anton Exp $ 2.\" 3.\" Copyright (c) 2006 Pedro Martelletto <pedro@ambientworks.net> 4.\" All rights reserved. 5.\" 6.\" Permission to use, copy, modify, and distribute this software for any 7.\" purpose with or without fee is hereby granted, provided that the above 8.\" copyright notice and this permission notice appear in all copies. 9.\" 10.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 11.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 12.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 13.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 14.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 15.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 16.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 17.\" 18.Dd $Mdocdate: November 4 2019 $ 19.Dt RWLOCK 9 20.Os 21.Sh NAME 22.Nm rwlock , 23.Nm rw_init , 24.Nm rw_init_flags , 25.Nm rw_enter , 26.Nm rw_exit , 27.Nm rw_enter_read , 28.Nm rw_enter_write , 29.Nm rw_exit_read , 30.Nm rw_exit_write , 31.Nm rw_assert_wrlock , 32.Nm rw_assert_rdlock , 33.Nm rw_assert_anylock , 34.Nm rw_assert_unlocked , 35.Nm rw_status , 36.Nm RWLOCK_INITIALIZER , 37.Nm rrw_init , 38.Nm rrw_init_flags , 39.Nm rrw_enter , 40.Nm rrw_exit , 41.Nm rrw_status 42.Nd interface to read/write locks 43.Sh SYNOPSIS 44.In sys/rwlock.h 45.Ft void 46.Fn rw_init "struct rwlock *rwl" "const char *name" 47.Ft void 48.Fn rw_init_flags "struct rwlock *rwl" "const char *name" "int flags" 49.Ft int 50.Fn rw_enter "struct rwlock *rwl" "int flags" 51.Ft void 52.Fn rw_exit "struct rwlock *rwl" 53.Ft void 54.Fn rw_enter_read "struct rwlock *rwl" 55.Ft void 56.Fn rw_enter_write "struct rwlock *rwl" 57.Ft void 58.Fn rw_exit_read "struct rwlock *rwl" 59.Ft void 60.Fn rw_exit_write "struct rwlock *rwl" 61.Ft int 62.Fn rw_assert_wrlock "struct rwlock *rwl" 63.Ft void 64.Fn rw_assert_rdlock "struct rwlock *rwl" 65.Ft void 66.Fn rw_assert_anylock "struct rwlock *rwl" 67.Ft void 68.Fn rw_assert_unlocked "struct rwlock *rwl" 69.Ft int 70.Fn rw_status "struct rwlock *rwl" 71.Fn RWLOCK_INITIALIZER "const char *name" 72.Ft void 73.Fn rrw_init "struct rrwlock *rrwl" "const char *name" 74.Ft void 75.Fn rrw_init_flags "struct rrwlock *rrwl" "const char *name" "int flags" 76.Ft int 77.Fn rrw_enter "struct rrwlock *rrwl" "int flags" 78.Ft void 79.Fn rrw_exit "struct rrwlock *rrwl" 80.Ft int 81.Fn rrw_status "struct rrwlock *rrwl" 82.Sh DESCRIPTION 83The 84.Nm 85set of functions provides a multiple-reader, single-writer locking mechanism to 86ensure mutual exclusion between different threads. 87.Pp 88Read locks can be acquired while the write lock is not held, and may coexist in 89distinct threads at any time. 90A write lock, however, can only be acquired when there are no read locks held, 91granting exclusive access to a single thread. 92.Pp 93The 94.Fn rw_init 95function is used to initiate the lock pointed to by 96.Fa rwl . 97The 98.Fa name 99argument specifies the name of the lock, which is used as the wait message 100if the thread needs to sleep. 101.Pp 102The 103.Fn rw_init_flags 104macro is similar to 105.Fn rw_init , 106but it additionally accepts a bitwise OR of the following flags: 107.Bl -tag -width RWL_NOWITNESS -offset indent 108.It Dv RWL_DUPOK 109Prevents 110.Xr witness 4 111from logging when a thread acquires more than one lock of this lock type. 112.It Dv RWL_IS_VNODE 113Make 114.Xr witness 4 115ignore lock order issues between this lock type and any other lock type 116tagged with the 117.Dv RWL_IS_VNODE 118flag. 119.It Dv RWL_NOWITNESS 120Instructs 121.Xr witness 4 122to ignore this lock. 123.El 124.Pp 125The 126.Fn rw_enter 127function acquires a lock. 128The 129.Fa flags 130argument specifies what kind of lock should be obtained and also 131modifies the operation. 132The possible flags are: 133.Pp 134.Bl -tag -offset indent -width RW_DOWNGRADEXXX -compact 135.It Dv RW_READ 136Acquire a shared lock. 137.It Dv RW_WRITE 138Acquire an exclusive lock. 139.It Dv RW_DOWNGRADE 140Safely release an exclusive lock and acquire a shared lock without 141letting other exclusive locks in between. 142.It Dv RW_INTR 143When waiting for a lock, allow signals to interrupt the sleep. 144.It Dv RW_NOSLEEP 145Do not wait for busy locks, fail with 146.Dv EBUSY 147instead. 148.It Dv RW_SLEEPFAIL 149Wait for busy locks, but do not obtain them, fail with 150.Dv EAGAIN 151instead. 152.It Dv RW_DUPOK 153Prevents 154.Xr witness 4 , 155for just this 156.Fn rw_enter , 157from logging when this thread already has a lock of this lock type. 158.El 159.Pp 160The 161.Fn rw_exit 162function is used to release a held lock. 163.Pp 164The 165.Fn rw_enter_read 166function acquires a read lock, sleeping if necessary. 167.Pp 168The 169.Fn rw_enter_write 170function acquires a write lock, sleeping if necessary. 171.Pp 172The 173.Fn rw_exit_read 174function releases a read lock. 175.Pp 176The 177.Fn rw_exit_write 178function releases a write lock. 179.Pp 180The 181.Fn rw_assert_wrlock , 182.Fn rw_assert_rdlock , 183.Fn rw_assert_anylock , 184and 185.Fn rw_assert_unlocked 186functions check the status 187.Fa rwl , 188panicking if it is not write-, read-, any-, or unlocked, respectively. 189.Pp 190.Nm rw_status 191returns the current state of the lock. 192.Pp 193A lock declaration may be initialised with the 194.Fn RWLOCK_INITIALIZER 195macro. 196The 197.Fa name 198argument specifies the name of the lock, which is used as the wait message 199if the thread needs to sleep. 200.Pp 201The 202.Nm rrwlock 203functions support recursive write locking by the same process. 204They otherwise behave the same as their rwlock counterparts. 205.Sh CONTEXT 206.Fn rw_init , 207.Fn rw_init_flags , 208.Fn rrw_init 209and 210.Fn rrw_init_flags 211can be called during autoconf, from process context, or from interrupt context. 212.Pp 213All other functions can be called during autoconf or from process context. 214.Sh RETURN VALUES 215.Nm rw_enter 216and 217.Nm rrw_enter 218return 0 on success, or an 219.Xr errno 2 220style value on failure. 221.Pp 222.Nm rw_status 223and 224.Nm rrw_status 225return the state of the lock: 226.Pp 227.Bl -tag -width "RW_WRITE_OTHER" -offset indent -compact 228.It Dv RW_WRITE 229Lock is write locked by the calling thread. 230.It Dv RW_WRITE_OTHER 231Lock is write locked by a different thread. 232.It Dv RW_READ 233Lock is read locked. 234The current thread may be one of the threads that has it locked. 235.It 0 236Lock is not locked. 237.El 238.Sh SEE ALSO 239.Xr witness 4 , 240.Xr mutex 9 , 241.Xr rwsleep 9 , 242.Xr spl 9 243.Sh HISTORY 244The 245.Nm 246functions first appeared in 247.Ox 3.5 . 248.Sh AUTHORS 249The 250.Nm 251functions were written by 252.An Artur Grabowski Aq Mt art@openbsd.org . 253