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 119Mutexes are used to implement mutual exclusion between threads. 120Mutexes can be locked in shared or exclusive mode; they can also block 121or spin the current thread when there is contention. 122.Pp 123Mutexes also have an associated reference count, independent of the lock. 124.Pp 125System-wide mutex contention statistics can be found in the 126.Va kern.mtx_contention_count , 127.Va kern.mtx_collision_count , 128and 129.Va kern.mtx_wakeup_count 130variables. 131.Va kern.mtx_contention_count 132is incremented each time an attempt to acquire a mutex fails due to contention. 133.Va kern.mtx_wakeup_count 134is incremented each time an exclusive lock is converted to either a shared or 135unlocked state an waiters for the shared state are woken. 136.Pp 137The mutex functions are similar to the 138.Xr lockmgr 9 139functions. 140.Sh FUNCTIONS 141The 142.Fn mtx_init 143function initializes a mutex to the unlocked state. 144It is an error to use a mutex without initializing it. 145The 146.Fa ident 147parameter is as in 148.Xr tsleep 9 , 149it is a string describing the reason for a thread to be blocked. 150.Pp 151The 152.Fn mtx_uninit 153function deinitializes a mutex. 154.Pp 155The 156.Fn mtx_lock_sh 157function attempts to lock a mutex in shared mode and blocks the current 158thread until it is able to do so. 159The 160.Fa flags 161parameter is passed to 162.Xr tsleep 9 163if the thread must block; the 164.Fa to 165parameter is a timeout for the sleep. 166The 167.Fn mtx_lock_sh_quick 168function is a version of 169.Fn mtx_lock_sh 170without flags or a timeout. 171The 172.Fn mtx_lock_sh 173and 174.Fn mtx_lock_sh_quick 175functions return 0 on success, or the 176.Fn tsleep 177return code on failure. 178An error can only be returned if 179.Dv PCATCH 180is specified in the flags. 181.Pp 182The 183.Fn mtx_lock_ex 184function attempts to lock a mutex exclusively and blocks the current thread 185until it is able to do so. 186The 187.Fa flags 188parameter is as in 189.Xr tsleep 9 . 190The 191.Fa to 192parameter is a timeout on the sleep. 193The 194.Fn mtx_lock_ex_quick 195function is a version of 196.Fn mtx_lock_ex 197without flags or a timeout. 198The 199.Fn mtx_lock 200function is a yet shorter form for exclusively locking a mutex, blocking the 201current thread until acquired. 202It is equivalent to 203.Fn mtx_lock_ex "mtx" \&"mtxex\&" "0" "0" . 204The 205.Fn mtx_lock_ex 206and 207.Fn mtx_lock_ex_quick 208functions return 0 on success, or the 209.Fn tsleep 210return code on failure. 211An error can only be returned if 212.Dv PCATCH is specified in the flags. 213.Pp 214The 215.Fn mtx_spinlock 216function attempts to lock the mutex in exclusive mode and spins until it is 217able to do so. 218.Pp 219The 220.Fn mtx_lock_ex_try 221and 222.Fn mtx_lock_sh_try 223functions attempt to lock the mutex in exclusive or shared mode, respectively. 224If they are not able to, they return 225.Er EAGAIN . 226The 227.Fn mtx_spinlock_try 228function does the same but for spin mutexes. 229.Pp 230The 231.Fn mtx_downgrade 232function converts an exclusively held lock to a shared lock. 233The lock must be held by the calling thread. 234If the lock is already shared, this call is a no-op. 235.Pp 236The 237.Fn mtx_upgrade_try 238function attempts to convert a shared lock to an exclusive one. 239The mutex must be held by the caller in the shared state. 240If the upgrade is successful, this function returns 0; otherwise, it returns 241.Er EDEADLK . 242.Pp 243The 244.Fn mtx_unlock 245function releases a held mutex; 246it works on both exclusive and shared mutexes. 247The 248.Fn mtx_unlock_ex 249and 250.Fn mtx_unlock_sh 251functions are optimized unlock paths, used when it is known that a lock is held 252exclusively or in shared state. 253.Pp 254The 255.Fn mtx_spinunlock 256function releases a held spin mutex. 257.Pp 258The 259.Fn mtx_islocked 260function returns non-zero if the mutex is locked in either shared of 261exclusive state by any thread. 262.Fn mtx_islocked_ex 263returns non-zero if the mutex is locked exclusively by any thread. 264The 265.Fn mtx_notlocked 266function returns non-zero if the mutex is not locked. 267The 268.Fn mtx_owned 269function returns non-zero if the mutex is exclusively locked by the calling 270thread. 271The 272.Fn mtx_notowned 273function returns non-zero if the mutex is not exclusively locked by the 274calling thread. 275The 276.Fn mtx_lockrefs 277function returns the number of shared or exclusive locks on the mutex. 278.Sh FILES 279The uncontended path of the 280.Nm 281implementation is in 282.Pa /sys/sys/mutex2.h . 283The data structures are in 284.Pa /sys/sys/mutex.h . 285The 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 295Mutexes first appeared in 296.Dx 2.3 . 297.Sh AUTHORS 298.An -nosplit 299The 300.Nm 301implementation was written by 302.An Matthew Dillon . 303