Updated: 2022/Sep/29
Please read Privacy Policy. It's for your privacy.
MUTEX(9) Kernel Developer's Manual MUTEX(9)
NAME
mutex, mutex_init, mutex_destroy, mutex_enter, mutex_exit, mutex_ownable,
mutex_owned, mutex_spin_enter, mutex_spin_exit, mutex_tryenter - mutual
exclusion primitives
SYNOPSIS
#include <sys/mutex.h>
void
mutex_init(kmutex_t *mtx, kmutex_type_t type, int ipl);
void
mutex_destroy(kmutex_t *mtx);
void
mutex_enter(kmutex_t *mtx);
void
mutex_exit(kmutex_t *mtx);
int
mutex_ownable(kmutex_t *mtx);
int
mutex_owned(kmutex_t *mtx);
void
mutex_spin_enter(kmutex_t *mtx);
void
mutex_spin_exit(kmutex_t *mtx);
int
mutex_tryenter(kmutex_t *mtx);
options DIAGNOSTIC
options LOCKDEBUG
DESCRIPTION
Mutexes are used in the kernel to implement mutual exclusion among LWPs
(lightweight processes) and interrupt handlers.
The kmutex_t type provides storage for the mutex object. This should be
treated as an opaque object and not examined directly by consumers.
Mutexes replace the spl(9) system traditionally used to provide
synchronization between interrupt handlers and LWPs.
OPTIONS
options DIAGNOSTIC
Kernels compiled with the DIAGNOSTIC option perform basic sanity
checks on mutex operations.
options LOCKDEBUG
Kernels compiled with the LOCKDEBUG option perform potentially CPU
intensive sanity checks on mutex operations.
FUNCTIONS
mutex_init(mtx, type, ipl)
Dynamically initialize a mutex for use.
No other operations can be performed on a mutex until it has been
initialized. Once initialized, all types of mutex are manipulated
using the same interface. Note that mutex_init() may block in
order to allocate memory.
The type argument must be given as MUTEX_DEFAULT. Other constants
are defined but are for low-level system use and are not an
endorsed, stable part of the interface.
The type of mutex returned depends on the ipl argument:
IPL_NONE, or one of the IPL_SOFT* constants
An adaptive mutex will be returned. Adaptive mutexes provide
mutual exclusion between LWPs, and between LWPs and soft
interrupt handlers.
Adaptive mutexes cannot be acquired from a hardware interrupt
handler. An LWP may either sleep or busy-wait when
attempting to acquire an adaptive mutex that is already held.
IPL_VM, IPL_SCHED, IPL_HIGH
A spin mutex will be returned. Spin mutexes provide mutual
exclusion between LWPs, and between LWPs and interrupt
handlers.
The ipl argument is used to pass a system interrupt priority
level (IPL) that will block all interrupt handlers that may
try to acquire the mutex.
LWPs that own spin mutexes may not sleep, and therefore must
not try to acquire adaptive mutexes or other sleep locks.
A processor will always busy-wait when attempting to acquire
a spin mutex that is already held.
Note: Releasing a spin mutex may not lower the IPL to what it
was when entered. If other spin mutexes are held, the IPL
will not be lowered until the last one is released.
This is usually not a problem because spin mutexes should
held only for very short durations anyway, so blocking
higher-priority interrupts a little longer doesn't hurt much.
But it interferes with writing assertions that the IPL is no
higher than a specified level.
See spl(9) for further information on interrupt priority levels
(IPLs).
mutex_destroy(mtx)
Release resources used by a mutex. The mutex may not be used after
it has been destroyed. mutex_destroy() may block in order to free
memory.
mutex_enter(mtx)
Acquire a mutex. If the mutex is already held, the caller will
block and not return until the mutex is acquired.
All loads and stores after mutex_enter() will not be reordered
before it or served from a prior cache, and hence will happen after
any prior mutex_exit() to release the mutex even on another CPU or
in an interrupt. Thus, there is a global total ordering on all
loads and stores under the same mutex.
Mutexes and other types of locks must always be acquired in a
consistent order with respect to each other. Otherwise, the
potential for system deadlock exists.
Adaptive mutexes and other types of lock that can sleep may not be
acquired while a spin mutex is held by the caller.
When acquiring a spin mutex, the IPL of the current CPU will be
raised to the level set in mutex_init() if it is not already equal
or higher.
mutex_exit(mtx)
Release a mutex. The mutex must have been previously acquired by
the caller. Mutexes may be released out of order as needed.
All loads and stores before mutex_exit() will not be reordered
after it or delayed in a write buffer, and hence will
happen(before) any subsequent mutex_enter() to acquire the mutex
even on another CPU or in an interrupt. Thus, there is a global
total ordering on all loads and stores under the same mutex.
mutex_ownable(mtx)
When compiled with LOCKDEBUG (see options(4)), ensure that the
current process can successfully acquire mtx. If mtx is already
owned by the current process, the system will panic with a "locking
against myself" error.
This function is needed because mutex_owned() does not
differentiate if a spin mutex is owned by the current process vs
owned by another process. mutex_ownable() is reasonably heavy-
weight, and should only be used with KDASSERT(9).
mutex_owned(mtx)
For adaptive mutexes, return non-zero if the current LWP holds the
mutex. For spin mutexes, return non-zero if the mutex is held,
potentially by the current processor. Otherwise, return zero.
mutex_owned() is provided for making diagnostic checks to verify
that a lock is held. For example:
KASSERT(mutex_owned(&driver_lock));
It should not be used to make locking decisions at run time. For
spin mutexes, it must not be used to verify that a lock is not
held.
mutex_spin_enter(mtx)
Equivalent to mutex_enter(), but may only be used when it is known
that mtx is a spin mutex. Implies the same memory ordering as
mutex_enter(). On some architectures, this can substantially
reduce the cost of acquiring a spin mutex.
mutex_spin_exit(mtx)
Equivalent to mutex_exit(), but may only be used when it is known
that mtx is a spin mutex. Implies the same memory ordering as
mutex_exit(). On some architectures, this can substantially reduce
the cost of releasing a spin mutex.
mutex_tryenter(mtx)
Try to acquire a mutex, but do not block if the mutex is already
held. Returns non-zero if the mutex was acquired, or zero if the
mutex was already held.
mutex_tryenter() can be used as an optimization when acquiring
locks in the wrong order. For example, in a setting where the
convention is that first_lock must be acquired before second_lock,
the following can be used to optimistically lock in reverse order:
/* We hold second_lock, but not first_lock. */
KASSERT(mutex_owned(&second_lock));
if (!mutex_tryenter(&first_lock)) {
/* Failed to get it - lock in the correct order. */
mutex_exit(&second_lock);
mutex_enter(&first_lock);
mutex_enter(&second_lock);
/*
* We may need to recheck any conditions the code
* path depends on, as we released second_lock
* briefly.
*/
}
CODE REFERENCES
The core of the mutex implementation is in sys/kern/kern_mutex.c.
The header file sys/sys/mutex.h describes the public interface, and
interfaces that machine-dependent code must provide to support mutexes.
SEE ALSO
atomic_ops(3), membar_ops(3), lockstat(8), condvar(9), kpreempt(9),
rwlock(9), spl(9)
Jim Mauro and Richard McDougall, Solaris Internals: Core Kernel
Architecture, Prentice Hall, 2001, ISBN 0-13-022496-0.
HISTORY
The mutex primitives first appeared in NetBSD 5.0.
NetBSD 9.99 December 8, 2017 NetBSD 9.99