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 February 14, 2019 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" "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 213is specified in the flags. 214.Pp 215The 216.Fn mtx_spinlock 217function attempts to lock the mutex in exclusive mode and spins until it is 218able to do so. 219.Pp 220The 221.Fn mtx_lock_ex_try 222and 223.Fn mtx_lock_sh_try 224functions attempt to lock the mutex in exclusive or shared mode, respectively. 225If they are not able to, they return 226.Er EAGAIN . 227The 228.Fn mtx_spinlock_try 229function does the same but for spin mutexes. 230.Pp 231The 232.Fn mtx_downgrade 233function converts an exclusively held lock to a shared lock. 234The lock must be held by the calling thread. 235If the lock is already shared, this call is a no-op. 236.Pp 237The 238.Fn mtx_upgrade_try 239function attempts to convert a shared lock to an exclusive one. 240The mutex must be held by the caller in the shared state. 241If the upgrade is successful, this function returns 0; otherwise, it returns 242.Er EDEADLK . 243.Pp 244The 245.Fn mtx_unlock 246function releases a held mutex; 247it works on both exclusive and shared mutexes. 248The 249.Fn mtx_unlock_ex 250and 251.Fn mtx_unlock_sh 252functions are optimized unlock paths, used when it is known that a lock is held 253exclusively or in shared state. 254.Pp 255The 256.Fn mtx_spinunlock 257function releases a held spin mutex. 258.Pp 259The 260.Fn mtx_islocked 261function returns non-zero if the mutex is locked in either shared of 262exclusive state by any thread. 263.Fn mtx_islocked_ex 264returns non-zero if the mutex is locked exclusively by any thread. 265The 266.Fn mtx_notlocked 267function returns non-zero if the mutex is not locked. 268The 269.Fn mtx_owned 270function returns non-zero if the mutex is exclusively locked by the calling 271thread. 272The 273.Fn mtx_notowned 274function returns non-zero if the mutex is not exclusively locked by the 275calling thread. 276The 277.Fn mtx_lockrefs 278function returns the number of shared or exclusive locks on the mutex. 279.Sh FILES 280The uncontended path of the 281.Nm 282implementation is in 283.Pa /sys/sys/mutex2.h . 284The data structures are in 285.Pa /sys/sys/mutex.h . 286The core of the spinlock implementation is in 287.Pa /sys/kern/kern_mutex.c . 288.Sh SEE ALSO 289.Xr crit_enter 9 , 290.Xr locking 9 , 291.Xr lockmgr 9 , 292.Xr serializer 9 , 293.Xr sleep 9 , 294.Xr spinlock 9 295.Sh HISTORY 296Mutexes first appeared in 297.Dx 2.3 . 298.Sh AUTHORS 299.An -nosplit 300The 301.Nm 302implementation was written by 303.An Matthew Dillon . 304