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