share/man/man9/rmlock.9

   1 .\" Copyright (c) 2007 Stephan Uphoff <ups@FreeBSD.org>
   2 .\" Copyright (c) 2006 Gleb Smirnoff <glebius@FreeBSD.org>
   3 .\" All rights reserved.
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\" 1. Redistributions of source code must retain the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer.
  10 .\" 2. Redistributions in binary form must reproduce the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer in the
  12 .\"    documentation and/or other materials provided with the distribution.
  13 .\"
  14 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  15 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  16 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  17 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  18 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  19 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  20 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  21 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  22 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  23 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  24 .\" SUCH DAMAGE.
  25 .\"
  26 .\" $FreeBSD$
  27 .\"
  28 .\" Based on rwlock.9 man page
  29 .Dd December 27, 2019
  30 .Dt RMLOCK 9
  31 .Os
  32 .Sh NAME
  33 .Nm rmlock ,
  34 .Nm rm_init ,
  35 .Nm rm_init_flags ,
  36 .Nm rm_destroy ,
  37 .Nm rm_rlock ,
  38 .Nm rm_try_rlock ,
  39 .Nm rm_wlock ,
  40 .Nm rm_runlock ,
  41 .Nm rm_wunlock ,
  42 .Nm rm_wowned ,
  43 .Nm rm_sleep ,
  44 .Nm rm_assert ,
  45 .Nm RM_SYSINIT ,
  46 .Nm RM_SYSINIT_FLAGS ,
  47 .Nm rms_init ,
  48 .Nm rms_destroy ,
  49 .Nm rms_rlock ,
  50 .Nm rms_wlock ,
  51 .Nm rms_runlock ,
  52 .Nm rms_wunlock
  53 .Nd kernel reader/writer lock optimized for read-mostly access patterns
  54 .Sh SYNOPSIS
  55 .In sys/param.h
  56 .In sys/lock.h
  57 .In sys/rmlock.h
  58 .Ft void
  59 .Fn rm_init "struct rmlock *rm" "const char *name"
  60 .Ft void
  61 .Fn rm_init_flags "struct rmlock *rm" "const char *name" "int opts"
  62 .Ft void
  63 .Fn rm_destroy "struct rmlock *rm"
  64 .Ft void
  65 .Fn rm_rlock "struct rmlock *rm"  "struct rm_priotracker* tracker"
  66 .Ft int
  67 .Fn rm_try_rlock "struct rmlock *rm"  "struct rm_priotracker* tracker"
  68 .Ft void
  69 .Fn rm_wlock "struct rmlock *rm"
  70 .Ft void
  71 .Fn rm_runlock "struct rmlock *rm" "struct rm_priotracker* tracker"
  72 .Ft void
  73 .Fn rm_wunlock "struct rmlock *rm"
  74 .Ft int
  75 .Fn rm_wowned "const struct rmlock *rm"
  76 .Ft int
  77 .Fn rm_sleep "void *wchan" "struct rmlock *rm" "int priority" "const char *wmesg" "int timo"
  78 .Pp
  79 .Cd "options INVARIANTS"
  80 .Cd "options INVARIANT_SUPPORT"
  81 .Ft void
  82 .Fn rm_assert "struct rmlock *rm" "int what"
  83 .In sys/kernel.h
  84 .Fn RM_SYSINIT "name" "struct rmlock *rm" "const char *desc"
  85 .Fn RM_SYSINIT_FLAGS "name" "struct rmlock *rm" "const char *desc" "int flags"
  86 .Ft void
  87 .Fn rms_init "struct rmslock *rms" "const char *name"
  88 .Ft void
  89 .Fn rms_destroy "struct rmslock *rms"
  90 .Ft void
  91 .Fn rms_rlock "struct rmslock *rms"
  92 .Ft void
  93 .Fn rms_wlock "struct rmslock *rms"
  94 .Ft void
  95 .Fn rms_runlock "struct rmslock *rms"
  96 .Ft void
  97 .Fn rms_wunlock "struct rmslock *rms"
  98 .Sh DESCRIPTION
  99 Read-mostly locks allow shared access to protected data by multiple threads,
 100 or exclusive access by a single thread.
 101 The threads with shared access are known as
 102 .Em readers
 103 since they only read the protected data.
 104 A thread with exclusive access is known as a
 105 .Em writer
 106 since it can modify protected data.
 107 .Pp
 108 Read-mostly locks are designed to be efficient for locks almost exclusively
 109 used as reader locks and as such should be used for protecting data that
 110 rarely changes.
 111 Acquiring an exclusive lock after the lock has been locked for shared access
 112 is an expensive operation.
 113 .Pp
 114 Normal read-mostly locks are similar to
 115 .Xr rwlock 9
 116 locks and follow the same lock ordering rules as
 117 .Xr rwlock 9
 118 locks.
 119 Read-mostly locks have full priority propagation like mutexes.
 120 Unlike
 121 .Xr rwlock 9 ,
 122 read-mostly locks propagate priority to both readers and writers.
 123 This is implemented via the
 124 .Va rm_priotracker
 125 structure argument supplied to
 126 .Fn rm_rlock
 127 and
 128 .Fn rm_runlock .
 129 Readers can recurse if the lock is initialized with the
 130 .Dv RM_RECURSE
 131 option;
 132 however, writers are never allowed to recurse.
 133 .Pp
 134 Sleeping for writers can be allowed by passing
 135 .Dv RM_SLEEPABLE
 136 to
 137 .Fn rm_init_flags .
 138 It changes lock ordering rules to the same as for
 139 .Xr sx 9
 140 locks.
 141 They do not propagate priority to writers, but they do propagate priority to
 142 readers. Note that readers are not permitted to sleep regardless of the flag.
 143 .Pp
 144 Sleepable read-mostly locks (created with
 145 .Fn rms_init )
 146 allow sleeping for both readers and writers, but don't do priority propagation
 147 for either. They follow
 148 .Xr sx 9
 149 lock ordering.
 150 .Ss Macros and Functions
 151 .Bl -tag -width indent
 152 .It Fn rm_init "struct rmlock *rm" "const char *name"
 153 Initialize the read-mostly lock
 154 .Fa rm .
 155 The
 156 .Fa name
 157 description is used solely for debugging purposes.
 158 This function must be called before any other operations
 159 on the lock.
 160 .It Fn rm_init_flags "struct rmlock *rm" "const char *name" "int opts"
 161 Similar to
 162 .Fn rm_init ,
 163 initialize the read-mostly lock
 164 .Fa rm
 165 with a set of optional flags.
 166 The
 167 .Fa opts
 168 arguments contains one or more of the following flags:
 169 .Bl -tag -width ".Dv RM_NOWITNESS"
 170 .It Dv RM_NOWITNESS
 171 Instruct
 172 .Xr witness 4
 173 to ignore this lock.
 174 .It Dv RM_RECURSE
 175 Allow threads to recursively acquire shared locks for
 176 .Fa rm .
 177 .It Dv RM_SLEEPABLE
 178 Create a sleepable read-mostly lock.
 179 .It Dv RM_NEW
 180 If the kernel has been compiled with
 181 .Cd "option INVARIANTS" ,
 182 .Fn rm_init_flags
 183 will assert that the
 184 .Fa rm
 185 has not been initialized multiple times without intervening calls to
 186 .Fn rm_destroy
 187 unless this option is specified.
 188 .El
 189 .It Fn rm_rlock "struct rmlock *rm" "struct rm_priotracker* tracker"
 190 Lock
 191 .Fa rm
 192 as a reader using
 193 .Fa tracker
 194 to track read owners of a lock for priority propagation.
 195 This data structure is only used internally by
 196 .Nm
 197 and must persist until
 198 .Fn rm_runlock
 199 has been called.
 200 This data structure can be allocated on the stack since
 201 readers cannot sleep.
 202 If any thread holds this lock exclusively, the current thread blocks,
 203 and its priority is propagated to the exclusive holder.
 204 If the lock was initialized with the
 205 .Dv RM_RECURSE
 206 option the
 207 .Fn rm_rlock
 208 function can be called when the current thread has already acquired reader
 209 access on
 210 .Fa rm .
 211 .It Fn rm_try_rlock "struct rmlock *rm" "struct rm_priotracker* tracker"
 212 Try to lock
 213 .Fa rm
 214 as a reader.
 215 .Fn rm_try_rlock
 216 will return 0 if the lock cannot be acquired immediately;
 217 otherwise,
 218 the lock will be acquired and a non-zero value will be returned.
 219 Note that
 220 .Fn rm_try_rlock
 221 may fail even while the lock is not currently held by a writer.
 222 If the lock was initialized with the
 223 .Dv RM_RECURSE
 224 option,
 225 .Fn rm_try_rlock
 226 will succeed if the current thread has already acquired reader access.
 227 .It Fn rm_wlock "struct rmlock *rm"
 228 Lock
 229 .Fa rm
 230 as a writer.
 231 If there are any shared owners of the lock, the current thread blocks.
 232 The
 233 .Fn rm_wlock
 234 function cannot be called recursively.
 235 .It Fn rm_runlock "struct rmlock *rm" "struct rm_priotracker* tracker"
 236 This function releases a shared lock previously acquired by
 237 .Fn rm_rlock .
 238 The
 239 .Fa tracker
 240 argument must match the
 241 .Fa tracker
 242 argument used for acquiring the shared lock
 243 .It Fn rm_wunlock "struct rmlock *rm"
 244 This function releases an exclusive lock previously acquired by
 245 .Fn rm_wlock .
 246 .It Fn rm_destroy "struct rmlock *rm"
 247 This functions destroys a lock previously initialized with
 248 .Fn rm_init .
 249 The
 250 .Fa rm
 251 lock must be unlocked.
 252 .It Fn rm_wowned "const struct rmlock *rm"
 253 This function returns a non-zero value if the current thread owns an
 254 exclusive lock on
 255 .Fa rm .
 256 .It Fn rm_sleep "void *wchan" "struct rmlock *rm" "int priority" "const char *wmesg" "int timo"
 257 This function atomically releases
 258 .Fa rm
 259 while waiting for an event.
 260 The
 261 .Fa rm
 262 lock must be exclusively locked.
 263 For more details on the parameters to this function,
 264 see
 265 .Xr sleep 9 .
 266 .It Fn rm_assert "struct rmlock *rm" "int what"
 267 This function asserts that the
 268 .Fa rm
 269 lock is in the state specified by
 270 .Fa what .
 271 If the assertions are not true and the kernel is compiled with
 272 .Cd "options INVARIANTS"
 273 and
 274 .Cd "options INVARIANT_SUPPORT" ,
 275 the kernel will panic.
 276 Currently the following base assertions are supported:
 277 .Bl -tag -width ".Dv RA_UNLOCKED"
 278 .It Dv RA_LOCKED
 279 Assert that current thread holds either a shared or exclusive lock
 280 of
 281 .Fa rm .
 282 .It Dv RA_RLOCKED
 283 Assert that current thread holds a shared lock of
 284 .Fa rm .
 285 .It Dv RA_WLOCKED
 286 Assert that current thread holds an exclusive lock of
 287 .Fa rm .
 288 .It Dv RA_UNLOCKED
 289 Assert that current thread holds neither a shared nor exclusive lock of
 290 .Fa rm .
 291 .El
 292 .Pp
 293 In addition, one of the following optional flags may be specified with
 294 .Dv RA_LOCKED ,
 295 .Dv RA_RLOCKED ,
 296 or
 297 .Dv RA_WLOCKED :
 298 .Bl -tag -width ".Dv RA_NOTRECURSED"
 299 .It Dv RA_RECURSED
 300 Assert that the current thread holds a recursive lock of
 301 .Fa rm .
 302 .It Dv RA_NOTRECURSED
 303 Assert that the current thread does not hold a recursive lock of
 304 .Fa rm .
 305 .El
 306 .El
 307 .Bl -tag -width indent
 308 .It Fn rms_init "struct rmslock *rms" "const char *name"
 309 Initialize the sleepable read-mostly lock
 310 .Fa rms .
 311 The
 312 .Fa name
 313 description is used as
 314 .Fa wmesg
 315 parameter to the
 316 .Xr msleep 9
 317 routine.
 318 This function must be called before any other operations on the lock.
 319 .It Fn rms_rlock "struct rmlock *rm"
 320 Lock
 321 .Fa rms
 322 as a reader.
 323 If any thread holds this lock exclusively, the current thread blocks.
 324 .It Fn rms_wlock "struct rmslock *rms"
 325 Lock
 326 .Fa rms
 327 as a writer.
 328 If the lock is already taken, the current thread blocks.
 329 The
 330 .Fn rms_wlock
 331 function cannot be called recursively.
 332 .It Fn rms_runlock "struct rmslock *rms"
 333 This function releases a shared lock previously acquired by
 334 .Fn rms_rlock .
 335 .It Fn rms_wunlock "struct rmslock *rms"
 336 This function releases an exclusive lock previously acquired by
 337 .Fn rms_wlock .
 338 .It Fn rms_destroy "struct rmslock *rms"
 339 This functions destroys a lock previously initialized with
 340 .Fn rms_init .
 341 The
 342 .Fa rms
 343 lock must be unlocked.
 344 .Sh SEE ALSO
 345 .Xr locking 9 ,
 346 .Xr mutex 9 ,
 347 .Xr panic 9 ,
 348 .Xr rwlock 9 ,
 349 .Xr sema 9 ,
 350 .Xr sleep 9 ,
 351 .Xr sx 9
 352 .Sh HISTORY
 353 These
 354 functions appeared in
 355 .Fx 7.0 .
 356 .Sh AUTHORS
 357 .An -nosplit
 358 The
 359 .Nm
 360 facility was written by
 361 .An "Stephan Uphoff" .
 362 This manual page was written by
 363 .An "Gleb Smirnoff"
 364 for rwlock and modified to reflect rmlock by
 365 .An "Stephan Uphoff" .
 366 .Sh BUGS
 367 The
 368 .Nm
 369 implementation is currently not optimized for single processor systems.
 370 .Pp
 371 .Fn rm_try_rlock
 372 can fail transiently even when there is no writer, while another reader
 373 updates the state on the local CPU.
 374 .Pp
 375 The
 376 .Nm
 377 implementation uses a single per CPU list shared by all
 378 rmlocks in the system.
 379 If rmlocks become popular, hashing to multiple per CPU queues may
 380 be needed to speed up the writer lock process.