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