share/man/man9/mutex.9

   1 .\"
   2 .\" Copyright (c) 2010 The DragonFly Project.  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 .\"
   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
  12 .\"    the documentation and/or other materials provided with the
  13 .\"    distribution.
  14 .\" 3. Neither the name of The DragonFly Project nor the names of its
  15 .\"    contributors may be used to endorse or promote products derived
  16 .\"    from this software without specific, prior written permission.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  19 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  20 .\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
  21 .\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE
  22 .\" COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
  23 .\" INCIDENTAL, SPECIAL, EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING,
  24 .\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  25 .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
  26 .\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
  27 .\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
  28 .\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  29 .\" SUCH DAMAGE.
  30 .\"
  31 .Dd August 24, 2012
  32 .Dt MUTEX 9
  33 .Os
  34 .Sh NAME
  35 .Nm mutex ,
  36 .Nm mtx_init ,
  37 .Nm mtx_uninit ,
  38 .Nm mtx_lock_sh ,
  39 .Nm mtx_lock_sh_quick ,
  40 .Nm mtx_lock_ex ,
  41 .Nm mtx_lock_ex_quick ,
  42 .Nm mtx_lock ,
  43 .Nm mtx_spinlock ,
  44 .Nm mtx_lock_ex_try ,
  45 .Nm mtx_lock_sh_try ,
  46 .Nm mtx_spinlock_try ,
  47 .Nm mtx_downgrade ,
  48 .Nm mtx_upgrade_try ,
  49 .Nm mtx_unlock ,
  50 .Nm mtx_unlock_ex ,
  51 .Nm mtx_unlock_sh ,
  52 .Nm mtx_spinunlock ,
  53 .Nm mtx_islocked ,
  54 .Nm mtx_islocked_ex ,
  55 .Nm mtx_notlocked ,
  56 .Nm mtx_notlocked_ex ,
  57 .Nm mtx_owned ,
  58 .Nm mtx_notowned ,
  59 .Nm mtx_lockrefs ,
  60 .Nm mtx_hold ,
  61 .Nm mtx_drop
  62 .Nd general blocking/spinnable mutex functions
  63 .Sh SYNOPSIS
  64 .In sys/globaldata.h
  65 .In sys/mutex2.h
  66 .Ft void
  67 .Fn mtx_init "struct mtx *mtx"
  68 .Ft void
  69 .Fn mtx_uninit "struct mtx *mtx"
  70 .Ft void
  71 .Fn mtx_lock_sh "struct mtx *mtx" "const char *ident" "int flags" "int to"
  72 .Ft void
  73 .Fn mtx_lock_sh_quick "struct mtx *mtx" "const char *ident"
  74 .Ft void
  75 .Fn mtx_lock_ex "struct mtx *mtx" "const char *ident" "int flags" "int to"
  76 .Ft void
  77 .Fn mtx_lock_ex_quick "struct mtx *mtx" "const char *ident"
  78 .Ft void
  79 .Fn mtx_lock "struct mtx *mtx"
  80 .Ft void
  81 .Fn mtx_spinlock "struct mtx *mtx"
  82 .Ft int
  83 .Fn mtx_lock_ex_try "struct mtx *mtx"
  84 .Ft int
  85 .Fn mtx_lock_sh_try "struct mtx *mtx"
  86 .Ft int
  87 .Fn mtx_spinlock_try "struct mtx *mtx"
  88 .Ft void
  89 .Fn mtx_downgrade "struct mtx *mtx"
  90 .Ft int
  91 .Fn mtx_upgrade_try "struct mtx *mtx"
  92 .Ft void
  93 .Fn mtx_unlock "struct mtx *mtx"
  94 .Ft void
  95 .Fn mtx_unlock_ex "struct mtx *mtx"
  96 .Ft void
  97 .Fn mtx_unlock_sh "struct mtx *mtx"
  98 .Ft void
  99 .Fn mtx_spinunlock "struct mtx *mtx"
 100 .Ft int
 101 .Fn mtx_islocked "struct mtx *mtx"
 102 .Ft int
 103 .Fn mtx_islocked_ex "struct mtx *mtx"
 104 .Ft int
 105 .Fn mtx_notlocked "struct mtx *mtx"
 106 .Ft int
 107 .Fn mtx_notlocked_ex "struct mtx *mtx"
 108 .Ft int
 109 .Fn mtx_owned "struct mtx *mtx"
 110 .Ft int
 111 .Fn mtx_notowned "struct mtx *mtx"
 112 .Ft int
 113 .Fn mtx_lockrefs "struct mtx *mtx"
 114 .Ft void
 115 .Fn mtx_hold "struct mtx *mtx"
 116 .Ft int
 117 .Fn mtx_drop "struct mtx *mtx"
 118 .Sh DESCRIPTION
 119 Mutexes are used to implement mutual exclusion between threads.
 120 Mutexes can be locked in shared or exclusive mode; they can also block
 121 or spin the current thread when there is contention.
 122 .Pp
 123 Mutexes also have an associated reference count, independent of the lock.
 124 .Pp
 125 System-wide mutex contention statistics can be found in the
 126 .Va kern.mtx_contention_count ,
 127 .Va kern.mtx_collision_count ,
 128 and
 129 .Va kern.mtx_wakeup_count
 130 variables.
 131 .Va kern.mtx_contention_count
 132 is incremented each time an attempt to acquire a mutex fails due to contention.
 133 .Va kern.mtx_wakeup_count
 134 is incremented each time an exclusive lock is converted to either a shared or
 135 unlocked state an waiters for the shared state are woken.
 136 .Pp
 137 The mutex functions are similar to the
 138 .Xr lockmgr 9
 139 functions.
 140 .Sh FUNCTIONS
 141 The
 142 .Fn mtx_init
 143 function initializes a mutex to the unlocked state.
 144 It is an error to use a mutex without initializing it.
 145 .Pp
 146 The
 147 .Fn mtx_uninit
 148 function deinitializes a mutex.
 149 .Pp
 150 The
 151 .Fn mtx_lock_sh
 152 function attempts to lock a mutex in shared mode and blocks the current
 153 thread until it is able to do so.
 154 The
 155 .Fa ident
 156 parameter is as in
 157 .Xr tsleep 9 ,
 158 it is a string describing the reason for a thread to be blocked.
 159 The
 160 .Fa flags
 161 parameter is passed to
 162 .Xr tsleep 9
 163 if the thread must block; the
 164 .Fa to
 165 parameter is a timeout for the sleep.
 166 The
 167 .Fn mtx_lock_sh_quick
 168 function is a version of
 169 .Fn mtx_lock_sh
 170 without flags or a timeout.
 171 .Pp
 172 The
 173 .Fn mtx_lock_ex
 174 function attempts to lock a mutex exclusively and blocks the current thread
 175 until it is able to do so.
 176 The
 177 .Fa ident
 178 and
 179 .Fa flags
 180 parameters are as in
 181 .Xr tsleep 9 .
 182 The
 183 .Fa to
 184 parameter is a timeout on the sleep.
 185 The
 186 .Fn mtx_lock_ex_quick
 187 function is is a version of
 188 .Fn mtx_lock_ex
 189 without flags or a timeout.
 190 The
 191 .Fn mtx_lock
 192 function is a yet shorter form for exclusively locking a mutex, blocking the
 193 current thread until acquired.
 194 It is equivalent to mtx_lock_ex(mtx, "mtxex", 0, 0).
 195 .Pp
 196 The
 197 .Fn mtx_spinlock
 198 function attempts to lock the mutex in exclusive mode and spins until it is
 199 able to do so.
 200 .Pp
 201 The
 202 .Fn mtx_lock_ex_try
 203 and
 204 .Fn mtx_lock_sh_try
 205 functions attempt to lock the mutex in exclusive or shared mode, respectively.
 206 If they are not able to, they return
 207 .Er EAGAIN .
 208 The
 209 .Fn mtx_spinlock_try
 210 function does the same but for spin mutexes.
 211 .Pp
 212 The
 213 .Fn mtx_downgrade
 214 function converts an exclusively held lock to a shared lock.
 215 The lock must be held by the calling thread.
 216 If the lock is already shared, this call is a no-op.
 217 .Pp
 218 The
 219 .Fn mtx_upgrade_try
 220 function attempts to convert a shared lock to an exclusive one.
 221 The mutex must be held by the caller in the shared state.
 222 If the upgrade is successful, this function returns 0; otherwise, it returns
 223 .Er EDEADLK .
 224 .Pp
 225 The
 226 .Fn mtx_unlock
 227 function releases a held mutex;
 228 it works on both exclusive and shared mutexes.
 229 The
 230 .Fn mtx_unlock_ex
 231 and
 232 .Fn mtx_unlock_sh
 233 functions are optimized unlock paths, used when it is known that a lock is held
 234 exclusively or in shared state.
 235 .Pp
 236 The
 237 .Fn mtx_spinunlock
 238 function releases a held spin mutex.
 239 .Pp
 240 The
 241 .Fn mtx_islocked
 242 function returns non-zero if the mutex is locked in either shared of
 243 exclusive state by any thread.
 244 .Fn mtx_islocked_ex
 245 returns non-zero if the mutex is locked exclusively by any thread.
 246 The
 247 .Fn mtx_notlocked
 248 function returns non-zero if the mutex is not locked.
 249 The
 250 .Fn mtx_owned
 251 function returns non-zero if the mutex is exclusively locked by the calling
 252 thread.
 253 The
 254 .Fn mtx_notowned
 255 function returns non-zero if the mutex is not exclusively locked by the
 256 calling thread.
 257 The
 258 .Fn mtx_lockrefs
 259 function returns the number of shared or exclusive locks on the mutex.
 260 .Pp
 261 The
 262 .Fn mtx_hold
 263 function increments the reference count associated with each mutex.
 264 The reference count is independent of the lock field.
 265 The
 266 .Fn mtx_drop
 267 function decrements the reference count associated with each mutex
 268 and returns the old value of the count.
 269 A return value of
 270 .Sq 1
 271 means that the current count is
 272 .Sq 0 .
 273 .Sh FILES
 274 The uncontended path of the
 275 .Nm
 276 implementation is in
 277 .Pa /sys/sys/mutex2.h .
 278 The data structures are in
 279 .Pa /sys/sys/mutex.h .
 280 The core of the spinlock implementation is in
 281 .Pa /sys/kern/kern_mutex.c .
 282 .Sh SEE ALSO
 283 .Xr crit_enter 9 ,
 284 .Xr lockmgr 9 ,
 285 .Xr serializer 9 ,
 286 .Xr sleep 9 ,
 287 .Xr spinlock 9
 288 .Sh HISTORY
 289 Mutexes first appeared in
 290 .Dx 2.3 .
 291 .Sh AUTHORS
 292 .An -nosplit
 293 The
 294 .Nm
 295 implementation was written by
 296 .An Matthew Dillon .