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 May 9, 2010
  32 .Os
  33 .Dt MUTEX 9
  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_spinlock_ex ,
  43 .Nm mtx_spinlock_sh ,
  44 .Nm mtx_lock_ex_try ,
  45 .Nm mtx_lock_sh_try ,
  46 .Nm mtx_downgrade ,
  47 .Nm mtx_upgrade_try ,
  48 .Nm mtx_unlock ,
  49 .Nm mtx_unlock_ex ,
  50 .Nm mtx_unlock_sh ,
  51 .Nm mtx_islocked ,
  52 .Nm mtx_islocked_ex ,
  53 .Nm mtx_notlocked ,
  54 .Nm mtx_notlocked_ex ,
  55 .Nm mtx_owned ,
  56 .Nm mtx_notowned ,
  57 .Nm mtx_lockrefs ,
  58 .Nm mtx_hold ,
  59 .Nm mtx_drop
  60 .Nd general blocking/spinnable mutex functions
  61 .Sh SYNOPSIS
  62 .In sys/globaldata.h
  63 .In sys/mutex2.h
  64 .Ft void
  65 .Fn mtx_init "struct mtx *mtx"
  66 .Ft void
  67 .Fn mtx_uninit "struct mtx *mtx"
  68 .Ft void
  69 .Fn mtx_lock_sh "struct mtx *mtx" "const char *ident" "int flags" "int to"
  70 .Ft void
  71 .Fn mtx_lock_sh_quick "struct mtx *mtx" "const char *ident"
  72 .Ft void
  73 .Fn mtx_lock_ex "struct mtx *mtx" "const char *ident" "int flags" "int to"
  74 .Ft void
  75 .Fn mtx_lock_ex_quick "struct mtx *mtx" "const char *ident"
  76 .Ft void
  77 .Fn mtx_spinlock_ex "struct mtx *mtx"
  78 .Ft void
  79 .Fn mtx_spinlock_sh "struct mtx *mtx"
  80 .Ft int
  81 .Fn mtx_lock_ex_try "struct mtx *mtx"
  82 .Ft int
  83 .Fn mtx_lock_sh_try "struct mtx *mtx"
  84 .Ft void
  85 .Fn mtx_downgrade "struct mtx *mtx"
  86 .Ft int
  87 .Fn mtx_upgrade_try "struct mtx *mtx"
  88 .Ft void
  89 .Fn mtx_unlock "struct mtx *mtx"
  90 .Ft void
  91 .Fn mtx_unlock_ex "struct mtx *mtx"
  92 .Ft void
  93 .Fn mtx_unlock_sh "struct mtx *mtx"
  94 .Ft int
  95 .Fn mtx_islocked "struct mtx *mtx"
  96 .Ft int
  97 .Fn mtx_islocked_ex "struct mtx *mtx"
  98 .Ft int
  99 .Fn mtx_notlocked "struct mtx *mtx"
 100 .Ft int
 101 .Fn mtx_notlocked_ex "struct mtx *mtx"
 102 .Ft int
 103 .Fn mtx_owned "struct mtx *mtx"
 104 .Ft int
 105 .Fn mtx_notowned "struct mtx *mtx"
 106 .Ft int
 107 .Fn mtx_lockrefs "struct mtx *mtx"
 108 .Ft void
 109 .Fn mtx_hold "struct mtx *mtx"
 110 .Ft int
 111 .Fn mtx_drop "struct mtx *mtx"
 112 .Sh DESCRIPTION
 113 Mutexes are used to implement mutual exclusion between threads.
 114 Mutexes can be locked in shared or exclusive mode; they can also block
 115 or spin the current thread when there is contention.
 116 .Pp
 117 Mutexes also have an associated reference count, independent of the lock.
 118 .Pp
 119 System-wide mutex contention statistics can be found in the
 120 .Va kern.mtx_contention_count ,
 121 .Va kern.mtx_collision_count ,
 122 and
 123 .Va kern.mtx_wakeup_count
 124 variables.
 125 .Va kern.mtx_contention_count
 126 is incremented each time an attempt to acquire a mutex fails due to contention.
 127 .Va kern.mtx_wakeup_count
 128 is incremented each time an exclusive lock is converted to either a shared or
 129 unlocked state an waiters for the shared state are woken.
 130 .Pp
 131 The mutex functions are similar to the
 132 .Xr lockmgr 9
 133 functions.
 134 .Sh FUNCTIONS
 135 The
 136 .Fn mtx_init
 137 function initializes a mutex to the unlocked state.
 138 It is an error to use a mutex without initializing it.
 139 .Pp
 140 The
 141 .Fn mtx_uninit
 142 function deinitializes a mutex.
 143 .Pp
 144 The
 145 .Fn mtx_lock_sh
 146 function attempts to lock a mutex in shared mode and blocks the current
 147 thread until it is able to do so.
 148 The
 149 .Fa ident
 150 parameter is as in
 151 .Xr tsleep 9 ,
 152 it is a string describing the reason for a thread to be blocked.
 153 The
 154 .Fa flags
 155 parameter is passed to
 156 .Xr tsleep 9
 157 if the thread must block; the to parameter is a timeout for the sleep.
 158 .Fn mtx_lock_sh_quick
 159 is a version without flags or a timeout.
 160 .Pp
 161 The
 162 .Fn mtx_lock_ex
 163 function attempts to lock a mutex exclusively and blocks the current thread
 164 until it is able to do so.
 165 The
 166 .Fa ident
 167 parameter and flags parameters are as in
 168 .Xr tsleep 9 .
 169 The
 170 .Fa to
 171 parameter is a timeout on the sleep.
 172 .Fa mtx_lock_ex_quick
 173 is is a version without flags or a timeout.
 174 .Pp
 175 The
 176 .Fn mtx_spinlock_ex
 177 function attempts to lock the mutex in exclusive mode and spins until it is
 178 able to do so; the
 179 .Fn mtx_spinlock_sh
 180 function attempts to lock the mutex in shared mode and spins until it is
 181 able to do so.
 182 .Pp
 183 The
 184 .Fn mtx_lock_ex_try
 185 and
 186 .Fn mtx_lock_sh_try
 187 functions attempt to lock the mutex in exclusive or shared mode, respectively.
 188 If they are not able to, they return
 189 .Er EAGAIN .
 190 .Pp
 191 The
 192 .Fn mtx_downgrade
 193 function converts an exclusively held lock to a shared lock.
 194 The lock must be held by the calling thread.
 195 If the lock is already shared, this call is a no-op.
 196 .Pp
 197 The
 198 .Fn mtx_upgrade_try
 199 function attempts to convert a shared lock to an exclusive one.
 200 The mutex must be held by the caller in the shared state.
 201 If the upgrade is successful, this function returns 0; otherwise, it returns
 202 .Er EDEADLK .
 203 .Pp
 204 The
 205 .Fn mtx_unlock
 206 function releases a held mutex;
 207 it works on both exclusive and shared mutexes.
 208 The
 209 .Fn mtx_unlock_ex
 210 and
 211 .Fn mtx_unlock_sh
 212 functions are optimized unlock paths, used when it is known that a lock is held
 213 exclusively or in shared state.
 214 .Pp
 215 The
 216 .Fn mtx_islocked
 217 function returns non-zero if the mutex is locked in either shared of
 218 exclusive state by any thread.
 219 .Fn mtx_islocked_ex
 220 returns non-zero if the mutex is locked exclusively by any thread.
 221 The
 222 .Fn mtx_notlocked
 223 function returns non-zero if the mutex is not locked.
 224 The
 225 .Fn mtx_owned
 226 function returns non-zero if the mutex is exclusively locked by the calling
 227 thread.
 228 The
 229 .Fn mtx_notowned
 230 function returns non-zero if the mutex is not exclusively locked by the
 231 calling thread.
 232 The
 233 .Fn mtx_lockrefs
 234 function returns the number of shared or exclusive locks on the mutex.
 235 .Pp
 236 The
 237 .Fn mtx_hold
 238 function increments the reference count associated with each mutex.
 239 The reference count is independent of the lock field.
 240 The
 241 .Fn mtx_drop
 242 function decrements the reference count associated with each mutex
 243 and returns the old value of the count.
 244 A return value of
 245 .Sq 1
 246 means that the current count is
 247 .Sq 0 .
 248 .Sh FILES
 249 The uncontended path of the
 250 .Nm
 251 implementation is in
 252 .Pa /sys/sys/mutex2.h .
 253 The data structures are in
 254 .Pa /sys/sys/mutex.h .
 255 The core of the spinlock implementation is in
 256 .Pa /sys/kern/kern_mutex.c .
 257 .Sh SEE ALSO
 258 .Xr crit_enter 9 ,
 259 .Xr lockmgr 9 ,
 260 .Xr serializer 9 ,
 261 .Xr spinlock 9
 262 .Sh HISTORY
 263 Mutexes first appeared in
 264 .Dx 2.3 .
 265 .Sh AUTHORS
 266 .An -nosplit
 267 The
 268 .Nm
 269 implementation was written by
 270 .An Matthew Dillon .