share/man/man9/rwlock.9

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