mutex.9: Fix typo.
[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.\"
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
dd7fb6d2 198function attempts to convert a shared lock to an exclusive one.
493c9781
SW
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 .