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 November 10, 2007
  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_wlock ,
  39 .Nm rm_runlock ,
  40 .Nm rm_wunlock ,
  41 .Nm rm_wowned ,
  42 .Nm RM_SYSINIT
  43 .Nd kernel reader/writer lock optimized for mostly read access patterns
  44 .Sh SYNOPSIS
  45 .In sys/param.h
  46 .In sys/lock.h
  47 .In sys/rmlock.h
  48 .Ft void
  49 .Fn rm_init "struct rmlock *rm" "const char *name"
  50 .Ft void
  51 .Fn rm_init_flags "struct rmlock *rm" "const char *name" "int opts"
  52 .Ft void
  53 .Fn rm_destroy "struct rmlock *rm"
  54 .Ft void
  55 .Fn rm_rlock "struct rmlock *rm"  "struct rm_priotracker* tracker"
  56 .Ft void
  57 .Fn rm_wlock "struct rmlock *rm"
  58 .Ft void
  59 .Fn rm_runlock "struct rmlock *rm" "struct rm_priotracker* tracker"
  60 .Ft void
  61 .Fn rm_wunlock "struct rmlock *rm"
  62 .Ft int
  63 .Fn rm_wowned "struct rmlock *rm"
  64 .In sys/kernel.h
  65 .Fn RM_SYSINIT "name" "struct rmlock *rm" "const char *desc" "int opts"
  66 .Sh DESCRIPTION
  67 Mostly reader locks allow shared access to protected data by multiple threads,
  68 or exclusive access by a single thread.
  69 The threads with shared access are known as
  70 .Em readers
  71 since they only read the protected data.
  72 A thread with exclusive access is known as a
  73 .Em writer
  74 since it can modify protected data.
  75 .Pp
  76 Read mostly locks are designed to be efficient for locks almost exclusively
  77 used as reader locks and as such should be used for protecting data that
  78 rarely changes.
  79 Acquiring an exclusive lock after the lock had been locked for shared access
  80 is an expensive operation.
  81 .Pp
  82 Although reader/writer locks look very similar to
  83 .Xr sx 9
  84 locks, their usage pattern is different.
  85 Reader/writer locks can be treated as mutexes (see
  86 .Xr mutex 9 )
  87 with shared/exclusive semantics.
  88 Unlike
  89 .Xr sx 9 ,
  90 an
  91 .Nm
  92 can be locked while holding a non-spin mutex, and an
  93 .Nm
  94 cannot be held while sleeping.
  95 The
  96 .Nm
  97 locks have full priority propagation like mutexes.
  98 The
  99 .Va rm_priotracker
 100 structure argument supplied in
 101 .Fn rm_rlock
 102 and
 103 .Fn rm_runlock
 104 is used to keep track of the read owner(s).
 105 Another important property is that shared holders of
 106 .Nm
 107 can recurse if the lock has been initialized with the
 108 .Dv LO_RECURSABLE
 109 option, however exclusive locks are not allowed to recurse.
 110 .Ss Macros and Functions
 111 .Bl -tag -width indent
 112 .It Fn rm_init "struct rmlock *rm" "const char *name"
 113 Initialize structure located at
 114 .Fa rm
 115 as mostly reader lock, described by
 116 .Fa name .
 117 The name description is used solely for debugging purposes.
 118 This function must be called before any other operations
 119 on the lock.
 120 .It Fn rm_init_flags "struct rmlock *rm" "const char *name" "int opts"
 121 Initialize the rm lock just like the
 122 .Fn rm_init
 123 function, but specifying a set of optional flags to alter the
 124 behaviour of
 125 .Fa rm ,
 126 through the
 127 .Fa opts
 128 argument.
 129 It contains one or more of the following flags:
 130 .Bl -tag -width ".Dv RM_NOWITNESS"
 131 .It Dv RM_NOWITNESS
 132 Instruct
 133 .Xr witness 4
 134 to ignore this lock.
 135 .It Dv RM_RECURSE
 136 Allow threads to recursively acquire exclusive locks for
 137 .Fa rm .
 138 .El
 139 .It Fn rm_rlock "struct rmlock *rm" "struct rm_priotracker* tracker"
 140 Lock
 141 .Fa rm
 142 as a reader.
 143 Using
 144 .Fa tracker
 145 to track read owners of a lock for priority propagation.
 146 This data structure is only used internally by
 147 .Nm
 148 and must persist until
 149 .Fn rm_runlock
 150 has been called.
 151 This data structure can be allocated on the stack since
 152 rmlocks cannot be held while sleeping.
 153 If any thread holds this lock exclusively, the current thread blocks,
 154 and its priority is propagated to the exclusive holder.
 155 If the lock was initialized with the
 156 .Dv LO_RECURSABLE
 157 option the
 158 .Fn rm_rlock
 159 function can be called when the thread has already acquired reader
 160 access on
 161 .Fa rm .
 162 This is called
 163 .Dq "recursing on a lock" .
 164 .It Fn rm_wlock "struct rmlock *rm"
 165 Lock
 166 .Fa rm
 167 as a writer.
 168 If there are any shared owners of the lock, the current thread blocks.
 169 The
 170 .Fn rm_wlock
 171 function cannot be called recursively.
 172 .It Fn rm_runlock "struct rmlock *rm" "struct rm_priotracker* tracker"
 173 This function releases a shared lock previously acquired by
 174 .Fn rm_rlock .
 175 The
 176 .Fa tracker
 177 argument must match the
 178 .Fa tracker
 179 argument used for acquiring the shared lock
 180 .It Fn rm_wunlock "struct rmlock *rm"
 181 This function releases an exclusive lock previously acquired by
 182 .Fn rm_wlock .
 183 .It Fn rm_destroy "struct rmlock *rm"
 184 This functions destroys a lock previously initialized with
 185 .Fn rm_init .
 186 The
 187 .Fa rm
 188 lock must be unlocked.
 189 .It Fn rm_wowned "struct rmlock *rm"
 190 This function returns a non-zero value if the current thread owns an
 191 exclusive lock on
 192 .Fa rm .
 193 .El
 194 .Sh SEE ALSO
 195 .Xr locking 9 ,
 196 .Xr mutex 9 ,
 197 .Xr panic 9 ,
 198 .Xr rwlock 9 ,
 199 .Xr sema 9 ,
 200 .Xr sx 9
 201 .Sh HISTORY
 202 These
 203 functions appeared in
 204 .Fx 7.0 .
 205 .Sh AUTHORS
 206 .An -nosplit
 207 The
 208 .Nm
 209 facility was written by
 210 .An "Stephan Uphoff" .
 211 This manual page was written by
 212 .An "Gleb Smirnoff"
 213 for rwlock and modified to reflect rmlock by
 214 .An "Stephan Uphoff" .
 215 .Sh BUGS
 216 The
 217 .Nm
 218 implementation is currently not optimized for single processor systems.
 219 .Pp
 220 The
 221 .Nm
 222 implementation uses a single per CPU list shared by all
 223 rmlocks in the system.
 224 If rmlocks become popular, hashing to multiple per CPU queues may
 225 be needed to speed up the writer lock process.
 226 .Pp
 227 The
 228 .Nm
 229 can currently not be used as a lock argument for condition variable
 230 wait functions.