DragonFly On-Line Manual Pages
MUTEX(9) DragonFly Kernel Developer's Manual MUTEX(9)
mutex, mtx_init, mtx_uninit, mtx_lock_sh, mtx_lock_sh_quick, mtx_lock_ex,
mtx_lock_ex_quick, mtx_lock, mtx_spinlock, mtx_lock_ex_try,
mtx_lock_sh_try, mtx_spinlock_try, mtx_downgrade, mtx_upgrade_try,
mtx_unlock, mtx_unlock_ex, mtx_unlock_sh, mtx_spinunlock, mtx_islocked,
mtx_islocked_ex, mtx_notlocked, mtx_notlocked_ex, mtx_owned,
mtx_notowned, mtx_lockrefs -- general blocking/spinnable mutex functions
mtx_lock_sh(mtx_t *mtx, const char *ident, int flags, int to);
mtx_lock_sh_quick(mtx_t *mtx, const char *ident);
mtx_lock_ex(mtx_t *mtx, const char *ident, int flags, int to);
mtx_lock_ex_quick(mtx_t *mtx, const char *ident);
Mutexes are used to implement mutual exclusion between threads. Mutexes
can be locked in shared or exclusive mode; they can also block or spin
the current thread when there is contention.
Mutexes also have an associated reference count, independent of the lock.
System-wide mutex contention statistics can be found in the
kern.mtx_contention_count, kern.mtx_collision_count, and
kern.mtx_wakeup_count variables. kern.mtx_contention_count is incre-
mented each time an attempt to acquire a mutex fails due to contention.
kern.mtx_wakeup_count is incremented each time an exclusive lock is con-
verted to either a shared or unlocked state an waiters for the shared
state are woken.
The mutex functions are similar to the lockmgr(9) functions.
The mtx_init() function initializes a mutex to the unlocked state. It is
an error to use a mutex without initializing it.
The mtx_uninit() function deinitializes a mutex.
The mtx_lock_sh() function attempts to lock a mutex in shared mode and
blocks the current thread until it is able to do so. The ident parameter
is as in tsleep(9), it is a string describing the reason for a thread to
be blocked. The flags parameter is passed to tsleep(9) if the thread
must block; the to parameter is a timeout for the sleep. The
mtx_lock_sh_quick() function is a version of mtx_lock_sh() without flags
or a timeout. The mtx_lock_sh() and mtx_lock_sh_quick() functions return
0 on success, or the tsleep() return code on failure. An error can only
be returned if PCATCH is specified in the flags.
The mtx_lock_ex() function attempts to lock a mutex exclusively and
blocks the current thread until it is able to do so. The ident and flags
parameters are as in tsleep(9). The to parameter is a timeout on the
sleep. The mtx_lock_ex_quick() function is a version of mtx_lock_ex()
without flags or a timeout. The mtx_lock() function is a yet shorter
form for exclusively locking a mutex, blocking the current thread until
acquired. It is equivalent to mtx_lock_ex(mtx, "mtxex", 0, 0). The
mtx_lock_ex() and mtx_lock_ex_quick() functions return 0 on success, or
the tsleep() return code on failure. An error can only be returned if
PCATCH is specified in the flags.
The mtx_spinlock() function attempts to lock the mutex in exclusive mode
and spins until it is able to do so.
The mtx_lock_ex_try() and mtx_lock_sh_try() functions attempt to lock the
mutex in exclusive or shared mode, respectively. If they are not able
to, they return EAGAIN. The mtx_spinlock_try() function does the same
but for spin mutexes.
The mtx_downgrade() function converts an exclusively held lock to a
shared lock. The lock must be held by the calling thread. If the lock
is already shared, this call is a no-op.
The mtx_upgrade_try() function attempts to convert a shared lock to an
exclusive one. The mutex must be held by the caller in the shared state.
If the upgrade is successful, this function returns 0; otherwise, it
The mtx_unlock() function releases a held mutex; it works on both exclu-
sive and shared mutexes. The mtx_unlock_ex() and mtx_unlock_sh() func-
tions are optimized unlock paths, used when it is known that a lock is
held exclusively or in shared state.
The mtx_spinunlock() function releases a held spin mutex.
The mtx_islocked() function returns non-zero if the mutex is locked in
either shared of exclusive state by any thread. mtx_islocked_ex()
returns non-zero if the mutex is locked exclusively by any thread. The
mtx_notlocked() function returns non-zero if the mutex is not locked.
The mtx_owned() function returns non-zero if the mutex is exclusively
locked by the calling thread. The mtx_notowned() function returns non-
zero if the mutex is not exclusively locked by the calling thread. The
mtx_lockrefs() function returns the number of shared or exclusive locks
on the mutex.
The uncontended path of the mutex implementation is in /sys/sys/mutex2.h.
The data structures are in /sys/sys/mutex.h. The core of the spinlock
implementation is in /sys/kern/kern_mutex.c.
crit_enter(9), locking(9), lockmgr(9), serializer(9), sleep(9),
Mutexes first appeared in DragonFly 2.3.
The mutex implementation was written by Matthew Dillon.
DragonFly 4.1 March 19, 2015 DragonFly 4.1