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