mutex.9: Misc updates and minor improvements.
[dragonfly.git] / share / man / man9 / mutex.9
CommitLineData
493c9781
SW
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.\"
dcece5c7 31.Dd August 24, 2012
493c9781 32.Dt MUTEX 9
fb5b3747 33.Os
493c9781 34.Sh NAME
b8e54b97 35.Nm mutex ,
493c9781
SW
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 ,
dcece5c7
NA
42.Nm mtx_lock ,
43.Nm mtx_spinlock ,
493c9781
SW
44.Nm mtx_lock_ex_try ,
45.Nm mtx_lock_sh_try ,
dcece5c7 46.Nm mtx_spinlock_try ,
493c9781
SW
47.Nm mtx_downgrade ,
48.Nm mtx_upgrade_try ,
49.Nm mtx_unlock ,
50.Nm mtx_unlock_ex ,
51.Nm mtx_unlock_sh ,
dcece5c7 52.Nm mtx_spinunlock ,
493c9781
SW
53.Nm mtx_islocked ,
54.Nm mtx_islocked_ex ,
55.Nm mtx_notlocked ,
56.Nm mtx_notlocked_ex ,
51ee83e2
SW
57.Nm mtx_owned ,
58.Nm mtx_notowned ,
493c9781
SW
59.Nm mtx_lockrefs ,
60.Nm mtx_hold ,
61.Nm mtx_drop
62.Nd general blocking/spinnable mutex functions
63.Sh SYNOPSIS
e7c86b60 64.In sys/globaldata.h
493c9781
SW
65.In sys/mutex2.h
66.Ft void
67.Fn mtx_init "struct mtx *mtx"
68.Ft void
69.Fn mtx_uninit "struct mtx *mtx"
70.Ft void
71.Fn mtx_lock_sh "struct mtx *mtx" "const char *ident" "int flags" "int to"
72.Ft void
73.Fn mtx_lock_sh_quick "struct mtx *mtx" "const char *ident"
74.Ft void
75.Fn mtx_lock_ex "struct mtx *mtx" "const char *ident" "int flags" "int to"
76.Ft void
77.Fn mtx_lock_ex_quick "struct mtx *mtx" "const char *ident"
78.Ft void
dcece5c7 79.Fn mtx_lock "struct mtx *mtx"
493c9781 80.Ft void
dcece5c7 81.Fn mtx_spinlock "struct mtx *mtx"
493c9781
SW
82.Ft int
83.Fn mtx_lock_ex_try "struct mtx *mtx"
84.Ft int
85.Fn mtx_lock_sh_try "struct mtx *mtx"
dcece5c7
NA
86.Ft int
87.Fn mtx_spinlock_try "struct mtx *mtx"
493c9781
SW
88.Ft void
89.Fn mtx_downgrade "struct mtx *mtx"
90.Ft int
91.Fn mtx_upgrade_try "struct mtx *mtx"
92.Ft void
93.Fn mtx_unlock "struct mtx *mtx"
94.Ft void
95.Fn mtx_unlock_ex "struct mtx *mtx"
96.Ft void
97.Fn mtx_unlock_sh "struct mtx *mtx"
dcece5c7
NA
98.Ft void
99.Fn mtx_spinunlock "struct mtx *mtx"
493c9781
SW
100.Ft int
101.Fn mtx_islocked "struct mtx *mtx"
102.Ft int
103.Fn mtx_islocked_ex "struct mtx *mtx"
104.Ft int
105.Fn mtx_notlocked "struct mtx *mtx"
106.Ft int
107.Fn mtx_notlocked_ex "struct mtx *mtx"
108.Ft int
51ee83e2 109.Fn mtx_owned "struct mtx *mtx"
493c9781 110.Ft int
51ee83e2 111.Fn mtx_notowned "struct mtx *mtx"
493c9781
SW
112.Ft int
113.Fn mtx_lockrefs "struct mtx *mtx"
114.Ft void
115.Fn mtx_hold "struct mtx *mtx"
116.Ft int
117.Fn mtx_drop "struct mtx *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.
145.Pp
146The
147.Fn mtx_uninit
148function deinitializes a mutex.
149.Pp
150The
151.Fn mtx_lock_sh
152function attempts to lock a mutex in shared mode and blocks the current
153thread until it is able to do so.
154The
155.Fa ident
156parameter is as in
157.Xr tsleep 9 ,
158it is a string describing the reason for a thread to be blocked.
159The
160.Fa flags
161parameter is passed to
162.Xr tsleep 9
dcece5c7
NA
163if the thread must block; the
164.Fa to
165parameter is a timeout for the sleep.
166The
493c9781 167.Fn mtx_lock_sh_quick
dcece5c7
NA
168function is a version of
169.Fn mtx_lock_sh
170without flags or a timeout.
493c9781
SW
171.Pp
172The
173.Fn mtx_lock_ex
174function attempts to lock a mutex exclusively and blocks the current thread
175until it is able to do so.
176The
177.Fa ident
dcece5c7
NA
178and
179.Fa flags
180parameters are as in
493c9781
SW
181.Xr tsleep 9 .
182The
183.Fa to
184parameter is a timeout on the sleep.
dcece5c7
NA
185The
186.Fn mtx_lock_ex_quick
187function is is a version of
188.Fn mtx_lock_ex
189without flags or a timeout.
190The
191.Fn mtx_lock
192function is a yet shorter form for exclusively locking a mutex, blocking the
193current thread until acquired.
194It is equivalent to mtx_lock_ex(mtx, "mtxex", 0, 0).
493c9781
SW
195.Pp
196The
dcece5c7 197.Fn mtx_spinlock
493c9781 198function attempts to lock the mutex in exclusive mode and spins until it is
493c9781
SW
199able to do so.
200.Pp
201The
202.Fn mtx_lock_ex_try
203and
204.Fn mtx_lock_sh_try
205functions attempt to lock the mutex in exclusive or shared mode, respectively.
206If they are not able to, they return
207.Er EAGAIN .
dcece5c7
NA
208The
209.Fn mtx_spinlock_try
210function does the same but for spin mutexes.
493c9781
SW
211.Pp
212The
213.Fn mtx_downgrade
214function converts an exclusively held lock to a shared lock.
215The lock must be held by the calling thread.
216If the lock is already shared, this call is a no-op.
217.Pp
218The
219.Fn mtx_upgrade_try
dd7fb6d2 220function attempts to convert a shared lock to an exclusive one.
493c9781
SW
221The mutex must be held by the caller in the shared state.
222If the upgrade is successful, this function returns 0; otherwise, it returns
223.Er EDEADLK .
224.Pp
225The
226.Fn mtx_unlock
227function releases a held mutex;
228it works on both exclusive and shared mutexes.
229The
230.Fn mtx_unlock_ex
231and
232.Fn mtx_unlock_sh
233functions are optimized unlock paths, used when it is known that a lock is held
234exclusively or in shared state.
235.Pp
236The
dcece5c7
NA
237.Fn mtx_spinunlock
238function releases a held spin mutex.
239.Pp
240The
493c9781
SW
241.Fn mtx_islocked
242function returns non-zero if the mutex is locked in either shared of
243exclusive state by any thread.
244.Fn mtx_islocked_ex
245returns non-zero if the mutex is locked exclusively by any thread.
246The
247.Fn mtx_notlocked
248function returns non-zero if the mutex is not locked.
249The
250.Fn mtx_owned
251function returns non-zero if the mutex is exclusively locked by the calling
252thread.
253The
254.Fn mtx_notowned
255function returns non-zero if the mutex is not exclusively locked by the
256calling thread.
257The
258.Fn mtx_lockrefs
259function returns the number of shared or exclusive locks on the mutex.
260.Pp
261The
262.Fn mtx_hold
263function increments the reference count associated with each mutex.
264The reference count is independent of the lock field.
265The
266.Fn mtx_drop
267function decrements the reference count associated with each mutex
268and returns the old value of the count.
269A return value of
270.Sq 1
271means that the current count is
272.Sq 0 .
273.Sh FILES
b8e54b97
SW
274The uncontended path of the
275.Nm
276implementation is in
493c9781
SW
277.Pa /sys/sys/mutex2.h .
278The data structures are in
279.Pa /sys/sys/mutex.h .
280The core of the spinlock implementation is in
281.Pa /sys/kern/kern_mutex.c .
282.Sh SEE ALSO
283.Xr crit_enter 9 ,
284.Xr lockmgr 9 ,
285.Xr serializer 9 ,
dcece5c7 286.Xr sleep 9 ,
493c9781
SW
287.Xr spinlock 9
288.Sh HISTORY
289Mutexes first appeared in
290.Dx 2.3 .
291.Sh AUTHORS
292.An -nosplit
293The
b8e54b97 294.Nm
493c9781
SW
295implementation was written by
296.An Matthew Dillon .