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