xref: /freebsd/share/man/man9/mutex.9 (revision ae83180158c4c937f170e31eff311b18c0286a93)
1.\"
2.\" Copyright (c) 1998 Berkeley Software Design, Inc. 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.\" 1. Redistributions of source code must retain the above copyright
8.\"    notice, this list of conditions and the following disclaimer.
9.\" 2. Redistributions in binary form must reproduce the above copyright
10.\"    notice, this list of conditions and the following disclaimer in the
11.\"    documentation and/or other materials provided with the distribution.
12.\" 3. Berkeley Software Design Inc's name may not be used to endorse or
13.\"    promote products derived from this software without specific prior
14.\"    written permission.
15.\"
16.\"  THIS SOFTWARE IS PROVIDED BY BERKELEY SOFTWARE DESIGN INC ``AS IS'' AND
17.\"  ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18.\"  IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19.\"  ARE DISCLAIMED.  IN NO EVENT SHALL BERKELEY SOFTWARE DESIGN INC BE LIABLE
20.\"  FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
21.\"  DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
22.\"  OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
23.\"  HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
24.\"  LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
25.\"  OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
26.\"  SUCH DAMAGE.
27.\"
28.\"	from BSDI $Id: mutex.4,v 1.1.2.3 1998/04/27 22:53:13 ewv Exp $
29.\" $FreeBSD$
30.\"
31.Dd February 12, 2001
32.Dt MUTEX 9
33.Os
34.Sh NAME
35.Nm mutex ,
36.Nm mtx_init ,
37.Nm mtx_lock ,
38.Nm mtx_lock_spin ,
39.Nm mtx_lock_flags ,
40.Nm mtx_lock_spin_flags ,
41.Nm mtx_trylock ,
42.Nm mtx_trylock_flags ,
43.Nm mtx_unlock ,
44.Nm mtx_unlock_spin ,
45.Nm mtx_unlock_flags ,
46.Nm mtx_unlock_spin_flags ,
47.Nm mtx_destroy ,
48.Nm mtx_initialized ,
49.Nm mtx_owned ,
50.Nm mtx_recursed ,
51.Nm mtx_assert,
52.Nm MTX_SYSINIT
53.Nd kernel synchronization primitives
54.Sh SYNOPSIS
55.In sys/param.h
56.In sys/lock.h
57.In sys/mutex.h
58.Ft void
59.Fn mtx_init "struct mtx *mutex" "const char *name" "const char *type" "int opts"
60.Ft void
61.Fn mtx_lock "struct mtx *mutex"
62.Ft void
63.Fn mtx_lock_spin "struct mtx *mutex"
64.Ft void
65.Fn mtx_lock_flags "struct mtx *mutex" "int flags"
66.Ft void
67.Fn mtx_lock_spin_flags "struct mtx *mutex" "int flags"
68.Ft int
69.Fn mtx_trylock "struct mtx *mutex"
70.Ft int
71.Fn mtx_trylock_flags "struct mtx *mutex" "int flags"
72.Ft void
73.Fn mtx_unlock "struct mtx *mutex"
74.Ft void
75.Fn mtx_unlock_spin "struct mtx *mutex"
76.Ft void
77.Fn mtx_unlock_flags "struct mtx *mutex" "int flags"
78.Ft void
79.Fn mtx_unlock_spin_flags "struct mtx *mutex" "int flags"
80.Ft void
81.Fn mtx_destroy "struct mtx *mutex"
82.Ft int
83.Fn mtx_initialized "struct mtx *mutex"
84.Ft int
85.Fn mtx_owned "struct mtx *mutex"
86.Ft int
87.Fn mtx_recursed "struct mtx *mutex"
88.Ft void
89.Fn mtx_assert "struct mtx *mutex" "int what"
90.Fn MTX_SYSINIT "name" "struct mutex *mtx" "const char *description" "int opts"
91.Sh DESCRIPTION
92Mutexes are the most basic and primary method of process synchronization.
93The major design considerations for mutexes are:
94.Bl -enum
95.It
96Acquiring and releasing uncontested mutexes should be as cheap
97as possible.
98.It
99They must have the information and storage space to support
100priority propagation.
101.It
102A process must be able to recursively acquire a mutex,
103provided that the mutex is initialized to support recursion.
104.El
105.Pp
106There are currently two flavors of mutexes, those that context switch
107when they block and those that do not.
108.Pp
109By default,
110.Dv MTX_DEF
111mutexes will context switch when they are already held.
112As a machine dependent optimization they may spin for some amount
113of time before context switching.
114It is important to remember that since a process may be preempted at any time,
115the possible context switch introduced by acquiring a mutex is guaranteed
116to not break anything that isn't already broken.
117.Pp
118Mutexes which do not context switch are
119.Dv MTX_SPIN
120mutexes.
121These should only be used to protect data shared with any devices that
122require non-preemptive interrupts, and low level scheduling code.
123In most/all architectures both acquiring and releasing of a
124uncontested spin mutex is more expensive than the same operation
125on a non spin mutex.
126In order to protect an interrupt service routine from blocking
127against itself all interrupts are blocked on a processor while
128holding a spin lock.
129It is permissible to hold multiple spin mutexes.
130In this case it is a required that they be released in the opposite
131order to that which they were acquired.
132.Pp
133Once a spin mutex has been acquired it is not permissible to acquire a
134blocking mutex.
135.Pp
136The storage needed to implement a mutex is provided by a
137.Vt struct mtx .
138In general this should be treated as an opaque object and
139referenced only with the mutex primitives.
140.Pp
141The
142.Fn mtx_init
143function must be used to initialize a mutex
144before it can be passed to
145.Fn mtx_lock .
146The
147.Fa name
148option is used to identify the lock in debugging output etc.
149The
150.Fa type
151option is used by the witness code to classify a mutex when doing checks
152of lock ordering.
153If
154.Fa type
155is
156.Dv NULL ,
157.Fa name
158is used in its place.
159The pointer passed in as
160.Fa name
161and
162.Fa type
163is saved rather than the data it points to.
164The data pointed to must remain stable
165until the mutex is destroyed.
166The
167.Fa opts
168argument is used to set the type of mutex.
169It may contain either
170.Dv MTX_DEF
171or
172.Dv MTX_SPIN
173but not both.
174See below for additional initialization options.
175It is not permissible to pass the same
176.Fa mutex
177to
178.Fn mtx_init
179multiple times without intervening calls to
180.Fn mtx_destroy .
181.Pp
182The
183.Fn mtx_lock
184function acquires a
185.Dv MTX_DEF
186mutual exclusion lock
187on behalf of the currently running kernel thread.
188If another kernel thread is holding the mutex,
189the caller will be disconnected from the CPU
190until the mutex is available
191(i.e. it will sleep).
192.Pp
193The
194.Fn mtx_lock_spin
195function acquires a
196.Dv MTX_SPIN
197mutual exclusion lock
198on behalf of the currently running kernel thread.
199If another kernel thread is holding the mutex,
200the caller will spin until the mutex becomes available.
201Interrupts are disabled during the spin and remain disabled
202following the acquiring of the lock.
203.Pp
204It is possible for the same thread to recursively acquire a mutex
205with no ill effects, provided that the
206.Dv MTX_RECURSE
207bit was passed to
208.Fn mtx_init
209during the initialization of the mutex.
210.Pp
211The
212.Fn mtx_lock_flags
213and
214.Fn mtx_lock_spin_flags
215functions acquire a
216.Dv MTX_DEF
217or
218.Dv MTX_SPIN
219lock, respectively, and also accept a
220.Fa flags
221argument.
222In both cases, the only flag presently available for lock acquires is
223.Dv MTX_QUIET .
224If the
225.Dv MTX_QUIET
226bit is turned on in the
227.Fa flags
228argument, then if
229.Dv KTR_LOCK
230tracing is being done,
231it will be silenced during the lock acquire.
232.Pp
233The
234.Fn mtx_trylock
235function is used to acquire exclusive access
236to those objects protected by the mutex
237pointed to by
238.Fa mutex .
239If the mutex cannot be immediately acquired
240.Fn mtx_trylock
241will return 0,
242otherwise the mutex will be acquired
243and a non-zero value will be returned.
244.Pp
245The
246.Fn mtx_trylock_flags
247function has the same behavior as
248.Fn mtx_trylock
249but should be used when the caller desires to pass in a
250.Fa flags
251value.
252Presently, the only valid value in the
253.Fn mtx_trylock
254case is
255.Dv MTX_QUIET ,
256and its effects are identical to those described for
257.Fn mtx_lock
258and
259.Fn mtx_lock_spin
260above.
261.Pp
262The
263.Fn mtx_unlock
264function releases a
265.Dv MTX_DEF
266mutual exclusion lock;
267if a higher priority thread is waiting for the mutex,
268the releasing thread will be disconnected
269to allow the higher priority thread to acquire the mutex and run.
270.Pp
271The
272.Fn mtx_unlock_spin
273function releases a
274.Dv MTX_SPIN
275mutual exclusion lock;
276interrupt state prior to the acquiring of the lock is restored.
277.Pp
278The
279.Fn mtx_unlock_flags
280and
281.Fn mtx_unlock_spin_flags
282functions behave in exactly the same way as do the standard mutex
283unlock routines above, while also allowing a
284.Fa flags
285argument which may only be
286.Dv MTX_QUIET
287in the
288.Fn mtx_unlock_spin_flags
289case, and may be one or more of
290.Dv MTX_QUIET
291and
292.Dv MTX_NOSWITCH
293in the
294.Fn mtx_unlock_flags
295case.
296The behavior of
297.Dv MTX_QUIET
298is identical to its behavior in the mutex lock routines.
299The
300.Dv MTX_NOSWITCH
301flag bit signifies,
302for a
303.Dv MTX_DEF
304mutex only,
305that the releasing thread is not to be disconnected from the CPU following
306the release of the mutex.
307.Pp
308The
309.Fn mtx_destroy
310function is used to destroy
311.Fa mutex
312so the data associated with it may be freed
313or otherwise overwritten.
314Any mutex which is destroyed
315must previously have been initialized with
316.Fn mtx_init .
317It is permissible to have a single hold count
318on a mutex when it is destroyed.
319It is not permissible to hold the mutex recursively,
320or have another process blocked on the mutex
321when it is destroyed.
322.Pp
323The
324.Fn mtx_initialized
325function returns non-zero if
326.Fa mutex
327has been initialized and zero otherwise.
328.Pp
329The
330.Fn mtx_owned
331function returns non-zero
332if the current process holds
333.Fa mutex .
334If the current process does not hold
335.Fa mutex
336zero is returned.
337.Pp
338The
339.Fn mtx_recursed
340function returns non-zero if the
341.Fa mutex
342is recursed.
343This check should only be made if the running thread already owns
344.Fa mutex .
345.Pp
346The
347.Fn mtx_assert
348function allows assertions to be made about
349.Fa mutex .
350If the assertions are not true and the kernel is compiled with
351.Dv INVARIANTS
352then the kernel will panic.
353Currently the following assertions are supported:
354.Bl -tag -width MA_NOTRECURSED
355.It Dv MA_OWNED
356Assert that the current thread
357holds the mutex
358pointed to by the first argument.
359.It Dv MA_NOTOWNED
360Assert that the current thread
361does not hold the mutex
362pointed to by the first argument.
363.It Dv MA_RECURSED
364Assert that the current thread has recursed on the mutex
365pointed to by the first argument.
366This assertion is only valid in conjunction with
367.Dv MA_OWNED .
368.It Dv MA_NOTRECURSED
369Assert that the current thread has not recursed on the mutex
370pointed to by the first argument.
371This assertion is only valid in conjunction with
372.Dv MA_OWNED .
373.El
374.Pp
375The
376.Fn MTX_SYSINIT
377macro is used to generate a call to the
378.Fn mtx_sysinit
379routine at system startup in order to initialize a given mutex lock.
380The parameters are the same as
381.Fn mtx_init
382but with an additional argument,
383.Fa name ,
384that is used in generating unique variable names for the related structures associated with the lock and the sysinit routine.
385.Ss The Default Mutex Type
386Most kernel code should use the default lock type,
387.Dv MTX_DEF ;
388the default lock type will allow the thread
389to be disconnected from the CPU
390if it cannot get the lock.
391The machine dependent implementation
392may treat the lock as a short term spin lock
393under some circumstances.
394However, it is always safe to use these forms of locks
395in an interrupt thread
396without fear of deadlock
397against an interrupted thread on the same CPU.
398.Ss The Spin Mutex Type
399A
400.Dv MTX_SPIN
401mutex will not relinquish the CPU
402when it cannot immediately get the requested lock,
403but will loop, waiting for the mutex to be released by another CPU.
404This could result in deadlock
405if a thread interrupted the thread which held a mutex
406and then tried to acquire the mutex;
407for this reason spin locks will disable all interrupts
408(on the local CPU only).
409.Pp
410Spin locks are fairly specialized locks
411that are intended to be held for very short periods of time;
412their primary purpose is to protect portions of the code
413that implement default (i.e. sleep) locks.
414.Ss Initialization Options
415The options passed in the
416.Fa opts
417argument of
418.Fn mtx_init
419specify the mutex type.
420The possibilities are:
421.Bl -tag -width MTX_NOWITNESS
422.It Dv MTX_DEF
423Default lock type;
424will always allow the current thread to be suspended
425to avoid deadlock conditions against interrupt threads.
426The machine dependent implementation of this lock type
427may spin for a while before suspending the current thread.
428If this flag is specified, clearly
429.Dv MTX_SPIN
430must NOT be specified.
431.It Dv MTX_SPIN
432Spin lock type;
433will never relinquish the CPU.
434All interrupts are disabled on the local CPU
435while any spin lock is held.
436.It Dv MTX_RECURSE
437Recursion option bit;
438specifies that the initialized mutex is allowed to recurse.
439This bit must be present if the mutex is going to be permitted to recurse.
440.It Dv MTX_QUIET
441Do not log any mutex operations for this lock.
442.It Dv MTX_NOWITNESS
443Instruct
444.Xr witness 4
445to ignore this lock.
446.It Dv MTX_DUPOK
447Witness should not log messages about duplicate locks being acquired.
448.El
449.Ss Lock and Unlock Flags
450The flags passed to the
451.Fn mtx_lock_flags ,
452.Fn mtx_lock_spin_flags ,
453.Fn mtx_unlock_flags ,
454and
455.Fn mtx_unlock_spin_flags
456functions provide some basic options to the caller,
457and are often used only under special circumstances to modify lock or
458unlock behavior.
459Standard locking and unlocking should be performed with the
460.Fn mtx_lock ,
461.Fn mtx_lock_spin ,
462.Fn mtx_unlock ,
463and
464.Fn mtx_unlock_spin
465functions.
466If one of these flags is required then, and only then,
467should the corresponding flags-accepting routines be used.
468.Pp
469Options that modify mutex behavior:
470.Bl -tag -width MTX_NOSWITCH
471.It Dv MTX_NOSWITCH
472When releasing a
473.Dv MTX_DEF
474mutex,
475this flag prevents a thread switch that might occur
476if another higher priority thread was waiting for the mutex.
477This may cause priority inversion and should be used carefully.
478This flag can only be passed to
479.Fn mtx_unlock_flags .
480.Pp
481This flag is used internally by the lock code.
482It should not be used in general kernel code
483and is documented here for completeness only.
484.It Dv MTX_QUIET
485This option is used to quiet logging messages during individual mutex
486operations.
487This can be used to trim superfluous logging messages for debugging purposes.
488.El
489.Sh SEE ALSO
490.Xr condvar 9 ,
491.Xr msleep 9 ,
492.Xr mtx_pool 9 ,
493.Xr sema 9 ,
494.Xr sx 9
495.Sh HISTORY
496These
497functions appeared in
498.Bsx 4.1
499and
500.Fx 5.0 .
501