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