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