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 January 30, 2006
  28 .Dt RWLOCK 9
  29 .Os
  30 .Sh NAME
  31 .Nm rwlock
  32 .Nm rw_init ,
  33 .Nm rw_rlock ,
  34 .Nm rw_wlock ,
  35 .Nm rw_assert ,
  36 .Nm rw_runlock ,
  37 .Nm rw_wunlock ,
  38 .Nm rw_initialized ,
  39 .Nm rw_destroy ,
  40 .Nm RW_SYSINIT ,
  41 .Nd kernel synchronization primitives
  42 .Sh SYNOPSIS
  43 .In sys/param.h
  44 .In sys/lock.h
  45 .In sys/rwlock.h
  46 .Ft void
  47 .Fn rw_init "struct rwlock *rwlock" "const char *name"
  48 .Ft void
  49 .Fn rw_rlock "struct rwlock *rwlock"
  50 .Ft void
  51 .Fn rw_wlock "struct rwlock *rwlock"
  52 .Ft void
  53 .Fn rw_runlock "struct rwlock *rwlock"
  54 .Ft void
  55 .Fn rw_wunlock "struct rwlock *rwlock"
  56 .Ft int
  57 .Fn rw_initialized "struct rwlock *rwlock"
  58 .Ft void
  59 .Fn rw_destroy "struct rwlock *rwlock"
  60 .Pp
  61 .Cd "options INVARIANTS"
  62 .Cd "options INVARIANT_SUPPORT"
  63 .Ft void
  64 .Fn rw_assert "struct rwlock *rwlock" "int what"
  65 .In sys/kernel.h
  66 .Fn RW_SYSINIT "name" "struct rwlock *rwlock" "const char *description"
  67 .Sh DESCRIPTION
  68 Read/write locks are a method of thread synchronization, which
  69 allows several threads have shared access to protected data, or
  70 one thread have exclusive access.
  71 The threads that share access are known as
  72 .Em readers
  73 since they should only read the protected data, while thread
  74 with exclusive access is known as a
  75 .Em writer
  76 since it can modify protected data.
  77 .Pp
  78 Although the description of read/write locks looks very similar
  79 to description of
  80 .Xr sx 9
  81 locks, their usage pattern is different.
  82 The read/write locks can be treated as mutexes (see
  83 .Xr mutex 9 )
  84 with shared/exclusive semantics.
  85 Unlike
  86 .Xr sx 9 ,
  87 an
  88 .Nm
  89 can be locked while holding a non-spin mutex;
  90 .Nm
  91 cannot be held while sleeping.
  92 The
  93 .Nm
  94 locks have priority propagation like mutexes, but priority
  95 can be propagated only to exclusive holder.
  96 This limitation comes from the fact that shared owners
  97 are anonymous.
  98 Another important property is that shared holder of
  99 .Nm
 100 can recurse on it.
 101 .Ss Macros and Functions
 102 .Bl -tag -width indent
 103 .It Fn rw_init "struct rwlock *rwlock" "const char *name"
 104 Initialize structure located at
 105 .Fa rwlock
 106 as read/write lock, described by name
 107 .Fa name .
 108 The description is used solely for debugging purposes.
 109 This function must be used before any other manipulations
 110 with the lock.
 111 .It Fn rw_rlock "struct rwlock *rwlock"
 112 Lock the
 113 .Fa rwlock
 114 as reader.
 115 If any thread holds this lock exclusively, the current thread blocks,
 116 and its priority is propagated to exclusive holder.
 117 The
 118 .Fn rw_rlock
 119 function can be called when the thread has already acquired reader
 120 access on
 121 .Fa rwlock .
 122 This is called
 123 .Dq "recursing on a lock" .
 124 .It Fn rw_wlock "struct rwlock *rwlock"
 125 Lock the
 126 .Fa rwlock
 127 as writer.
 128 If there are any shared owners of the lock, the current thread blocks.
 129 The
 130 .Fn rw_wlock
 131 function cannot be called recursively.
 132 .It Fn rw_runlock "struct rwlock *rwlock"
 133 This function releases shared lock, previously acquired by
 134 .Fn rw_rlock .
 135 .It Fn rw_wunlock "struct rwlock *rwlock"
 136 This function releases exclusive lock, previously acquired by
 137 .Fn rw_wlock .
 138 .It Fn rw_initialized "struct rwlock *rwlock"
 139 This function returns non-zero if the
 140 .Fa rwlock
 141 has been initialized, and zero otherwise.
 142 .It Fn rw_destroy "struct rwlock *rwlock"
 143 This functions destroys a lock previously initialized with
 144 .Fn rw_init .
 145 The
 146 .Fa rwlock
 147 must be unlocked.
 148 .It Fn rw_assert "struct rwlock *rwlock" "int what"
 149 This function allows assertions specified in
 150 .Fa what
 151 to be made about
 152 .Fa rwlock .
 153 If the assertions are not true and the kernel is compiled
 154 with
 155 .Cd "options INVARIANTS"
 156 and
 157 .Cd "options INVARIANT_SUPPORT" ,
 158 the kernel will panic.
 159 Currently the following assertions are supported:
 160 .Bl -tag -width ".Dv RA_UNLOCKED"
 161 .It Dv RA_LOCKED
 162 Assert that current thread is either shared or exclusive owner
 163 of the
 164 .Nm
 165 pointed to by the first argument.
 166 .It Dv RA_RLOCKED
 167 Assert that current thread is shared owner of the
 168 .Nm
 169 pointed
 170 to by the first argument.
 171 .It Dv RA_WLOCKED
 172 Assert that current thread is exclusive owner of the
 173 .Nm
 174 pointed
 175 to by the first argument.
 176 .It Dv RA_UNLOCKED
 177 Assert that current thread is neither shared nor exclusive owner
 178 of the
 179 .Nm
 180 pointed to by the first argument.
 181 .El
 182 .El
 183 .Sh SEE ALSO
 184 .Xr condvar 9 ,
 185 .Xr mutex 9 ,
 186 .Xr panic 9 ,
 187 .Xr sema 9 ,
 188 .Xr sx 9
 189 .Sh HISTORY
 190 These
 191 functions appeared in
 192 .Fx 7.0 .
 193 .Sh AUTHORS
 194 .An -nosplit
 195 The
 196 .Nm
 197 facility was written by
 198 .An "John Baldwin" .
 199 This manual page was written by
 200 .An "Gleb Smirnoff" .