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 April 10, 2015
  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_link ,
  40 .Nm mtx_lock_sh_quick ,
  41 .Nm mtx_lock_ex ,
  42 .\".Nm mtx_lock_ex_link ,
  43 .Nm mtx_lock_ex_quick ,
  44 .Nm mtx_lock ,
  45 .Nm mtx_spinlock ,
  46 .Nm mtx_lock_ex_try ,
  47 .Nm mtx_lock_sh_try ,
  48 .Nm mtx_spinlock_try ,
  49 .Nm mtx_downgrade ,
  50 .Nm mtx_upgrade_try ,
  51 .Nm mtx_unlock ,
  52 .Nm mtx_unlock_ex ,
  53 .Nm mtx_unlock_sh ,
  54 .Nm mtx_spinunlock ,
  55 .Nm mtx_islocked ,
  56 .Nm mtx_islocked_ex ,
  57 .Nm mtx_notlocked ,
  58 .Nm mtx_notlocked_ex ,
  59 .Nm mtx_owned ,
  60 .Nm mtx_notowned ,
  61 .Nm mtx_lockrefs
  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 "mtx_t *mtx, const char *ident"
  68 .Ft void
  69 .Fn mtx_uninit "mtx_t *mtx"
  70 .Ft int
  71 .Fn mtx_lock_sh "mtx_t *mtx" "int flags" "int to"
  72 .\".Ft int
  73 .\".Fn mtx_lock_sh_link "mtx_t *mtx" "mtx_link_t *link" "int flags" "int to"
  74 .Ft int
  75 .Fn mtx_lock_sh_quick "mtx_t *mtx"
  76 .Ft int
  77 .Fn mtx_lock_ex "mtx_t *mtx" "int flags" "int to"
  78 .\".Ft int
  79 .\".Fn mtx_lock_ex_link "mtx_t *mtx" "mtx_link_t *link" "int flags" "int to"
  80 .Ft int
  81 .Fn mtx_lock_ex_quick "mtx_t *mtx"
  82 .Ft void
  83 .Fn mtx_lock "mtx_t *mtx"
  84 .Ft void
  85 .Fn mtx_spinlock "mtx_t *mtx"
  86 .Ft int
  87 .Fn mtx_lock_ex_try "mtx_t *mtx"
  88 .Ft int
  89 .Fn mtx_lock_sh_try "mtx_t *mtx"
  90 .Ft int
  91 .Fn mtx_spinlock_try "mtx_t *mtx"
  92 .Ft void
  93 .Fn mtx_downgrade "mtx_t *mtx"
  94 .Ft int
  95 .Fn mtx_upgrade_try "mtx_t *mtx"
  96 .Ft void
  97 .Fn mtx_unlock "mtx_t *mtx"
  98 .Ft void
  99 .Fn mtx_unlock_ex "mtx_t *mtx"
 100 .Ft void
 101 .Fn mtx_unlock_sh "mtx_t *mtx"
 102 .Ft void
 103 .Fn mtx_spinunlock "mtx_t *mtx"
 104 .Ft int
 105 .Fn mtx_islocked "mtx_t *mtx"
 106 .Ft int
 107 .Fn mtx_islocked_ex "mtx_t *mtx"
 108 .Ft int
 109 .Fn mtx_notlocked "mtx_t *mtx"
 110 .Ft int
 111 .Fn mtx_notlocked_ex "mtx_t *mtx"
 112 .Ft int
 113 .Fn mtx_owned "mtx_t *mtx"
 114 .Ft int
 115 .Fn mtx_notowned "mtx_t *mtx"
 116 .Ft int
 117 .Fn mtx_lockrefs "mtx_t *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 The
 146 .Fa ident
 147 parameter is as in
 148 .Xr tsleep 9 ,
 149 it is a string describing the reason for a thread to be blocked.
 150 .Pp
 151 The
 152 .Fn mtx_uninit
 153 function deinitializes a mutex.
 154 .Pp
 155 The
 156 .Fn mtx_lock_sh
 157 function attempts to lock a mutex in shared mode and blocks the current
 158 thread until it is able to do so.
 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 The
 172 .Fn mtx_lock_sh
 173 and
 174 .Fn mtx_lock_sh_quick
 175 functions return 0 on success, or the
 176 .Fn tsleep
 177 return code on failure.
 178 An error can only be returned if
 179 .Dv PCATCH
 180 is specified in the flags.
 181 .Pp
 182 The
 183 .Fn mtx_lock_ex
 184 function attempts to lock a mutex exclusively and blocks the current thread
 185 until it is able to do so.
 186 The
 187 .Fa flags
 188 parameter is as in
 189 .Xr tsleep 9 .
 190 The
 191 .Fa to
 192 parameter is a timeout on the sleep.
 193 The
 194 .Fn mtx_lock_ex_quick
 195 function is a version of
 196 .Fn mtx_lock_ex
 197 without flags or a timeout.
 198 The
 199 .Fn mtx_lock
 200 function is a yet shorter form for exclusively locking a mutex, blocking the
 201 current thread until acquired.
 202 It is equivalent to
 203 .Fn mtx_lock_ex "mtx" \&"mtxex\&" "0" "0" .
 204 The
 205 .Fn mtx_lock_ex
 206 and
 207 .Fn mtx_lock_ex_quick
 208 functions return 0 on success, or the
 209 .Fn tsleep
 210 return code on failure.
 211 An error can only be returned if
 212 .Dv PCATCH is specified in the flags.
 213 .Pp
 214 The
 215 .Fn mtx_spinlock
 216 function attempts to lock the mutex in exclusive mode and spins until it is
 217 able to do so.
 218 .Pp
 219 The
 220 .Fn mtx_lock_ex_try
 221 and
 222 .Fn mtx_lock_sh_try
 223 functions attempt to lock the mutex in exclusive or shared mode, respectively.
 224 If they are not able to, they return
 225 .Er EAGAIN .
 226 The
 227 .Fn mtx_spinlock_try
 228 function does the same but for spin mutexes.
 229 .Pp
 230 The
 231 .Fn mtx_downgrade
 232 function converts an exclusively held lock to a shared lock.
 233 The lock must be held by the calling thread.
 234 If the lock is already shared, this call is a no-op.
 235 .Pp
 236 The
 237 .Fn mtx_upgrade_try
 238 function attempts to convert a shared lock to an exclusive one.
 239 The mutex must be held by the caller in the shared state.
 240 If the upgrade is successful, this function returns 0; otherwise, it returns
 241 .Er EDEADLK .
 242 .Pp
 243 The
 244 .Fn mtx_unlock
 245 function releases a held mutex;
 246 it works on both exclusive and shared mutexes.
 247 The
 248 .Fn mtx_unlock_ex
 249 and
 250 .Fn mtx_unlock_sh
 251 functions are optimized unlock paths, used when it is known that a lock is held
 252 exclusively or in shared state.
 253 .Pp
 254 The
 255 .Fn mtx_spinunlock
 256 function releases a held spin mutex.
 257 .Pp
 258 The
 259 .Fn mtx_islocked
 260 function returns non-zero if the mutex is locked in either shared of
 261 exclusive state by any thread.
 262 .Fn mtx_islocked_ex
 263 returns non-zero if the mutex is locked exclusively by any thread.
 264 The
 265 .Fn mtx_notlocked
 266 function returns non-zero if the mutex is not locked.
 267 The
 268 .Fn mtx_owned
 269 function returns non-zero if the mutex is exclusively locked by the calling
 270 thread.
 271 The
 272 .Fn mtx_notowned
 273 function returns non-zero if the mutex is not exclusively locked by the
 274 calling thread.
 275 The
 276 .Fn mtx_lockrefs
 277 function returns the number of shared or exclusive locks on the mutex.
 278 .Sh FILES
 279 The uncontended path of the
 280 .Nm
 281 implementation is in
 282 .Pa /sys/sys/mutex2.h .
 283 The data structures are in
 284 .Pa /sys/sys/mutex.h .
 285 The core of the spinlock implementation is in
 286 .Pa /sys/kern/kern_mutex.c .
 287 .Sh SEE ALSO
 288 .Xr crit_enter 9 ,
 289 .Xr locking 9 ,
 290 .Xr lockmgr 9 ,
 291 .Xr serializer 9 ,
 292 .Xr sleep 9 ,
 293 .Xr spinlock 9
 294 .Sh HISTORY
 295 Mutexes first appeared in
 296 .Dx 2.3 .
 297 .Sh AUTHORS
 298 .An -nosplit
 299 The
 300 .Nm
 301 implementation was written by
 302 .An Matthew Dillon .