2 .\" Copyright (c) 2010 The DragonFly Project. All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
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
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.
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
39 .Nm mtx_lock_sh_quick ,
41 .Nm mtx_lock_ex_quick ,
46 .Nm mtx_spinlock_try ,
56 .Nm mtx_notlocked_ex ,
62 .Nd general blocking/spinnable mutex functions
67 .Fn mtx_init "struct mtx *mtx"
69 .Fn mtx_uninit "struct mtx *mtx"
71 .Fn mtx_lock_sh "struct mtx *mtx" "const char *ident" "int flags" "int to"
73 .Fn mtx_lock_sh_quick "struct mtx *mtx" "const char *ident"
75 .Fn mtx_lock_ex "struct mtx *mtx" "const char *ident" "int flags" "int to"
77 .Fn mtx_lock_ex_quick "struct mtx *mtx" "const char *ident"
79 .Fn mtx_lock "struct mtx *mtx"
81 .Fn mtx_spinlock "struct mtx *mtx"
83 .Fn mtx_lock_ex_try "struct mtx *mtx"
85 .Fn mtx_lock_sh_try "struct mtx *mtx"
87 .Fn mtx_spinlock_try "struct mtx *mtx"
89 .Fn mtx_downgrade "struct mtx *mtx"
91 .Fn mtx_upgrade_try "struct mtx *mtx"
93 .Fn mtx_unlock "struct mtx *mtx"
95 .Fn mtx_unlock_ex "struct mtx *mtx"
97 .Fn mtx_unlock_sh "struct mtx *mtx"
99 .Fn mtx_spinunlock "struct mtx *mtx"
101 .Fn mtx_islocked "struct mtx *mtx"
103 .Fn mtx_islocked_ex "struct mtx *mtx"
105 .Fn mtx_notlocked "struct mtx *mtx"
107 .Fn mtx_notlocked_ex "struct mtx *mtx"
109 .Fn mtx_owned "struct mtx *mtx"
111 .Fn mtx_notowned "struct mtx *mtx"
113 .Fn mtx_lockrefs "struct mtx *mtx"
115 .Fn mtx_hold "struct mtx *mtx"
117 .Fn mtx_drop "struct mtx *mtx"
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.
123 Mutexes also have an associated reference count, independent of the lock.
125 System-wide mutex contention statistics can be found in the
126 .Va kern.mtx_contention_count ,
127 .Va kern.mtx_collision_count ,
129 .Va kern.mtx_wakeup_count
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.
137 The mutex functions are similar to the
143 function initializes a mutex to the unlocked state.
144 It is an error to use a mutex without initializing it.
148 function deinitializes a mutex.
152 function attempts to lock a mutex in shared mode and blocks the current
153 thread until it is able to do so.
158 it is a string describing the reason for a thread to be blocked.
161 parameter is passed to
163 if the thread must block; the
165 parameter is a timeout for the sleep.
167 .Fn mtx_lock_sh_quick
168 function is a version of
170 without flags or a timeout.
174 function attempts to lock a mutex exclusively and blocks the current thread
175 until it is able to do so.
184 parameter is a timeout on the sleep.
186 .Fn mtx_lock_ex_quick
187 function is a version of
189 without flags or a timeout.
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).
198 function attempts to lock the mutex in exclusive mode and spins until it is
205 functions attempt to lock the mutex in exclusive or shared mode, respectively.
206 If they are not able to, they return
210 function does the same but for spin mutexes.
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.
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
227 function releases a held mutex;
228 it works on both exclusive and shared mutexes.
233 functions are optimized unlock paths, used when it is known that a lock is held
234 exclusively or in shared state.
238 function releases a held spin mutex.
242 function returns non-zero if the mutex is locked in either shared of
243 exclusive state by any thread.
245 returns non-zero if the mutex is locked exclusively by any thread.
248 function returns non-zero if the mutex is not locked.
251 function returns non-zero if the mutex is exclusively locked by the calling
255 function returns non-zero if the mutex is not exclusively locked by the
259 function returns the number of shared or exclusive locks on the mutex.
263 function increments the reference count associated with each mutex.
264 The reference count is independent of the lock field.
267 function decrements the reference count associated with each mutex
268 and returns the old value of the count.
271 means that the current count is
274 The uncontended path of the
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 .
289 Mutexes first appeared in
295 implementation was written by