| 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 . |