<commit_before>.\"
.\" Copyright (c) 1998 Berkeley Software Design, Inc. All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. Berkeley Software Design Inc's name may not be used to endorse or
.\"    promote products derived from this software without specific prior
.\"    written permission.
.\"
.\"  THIS SOFTWARE IS PROVIDED BY BERKELEY SOFTWARE DESIGN INC ``AS IS'' AND
.\"  ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\"  IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\"  ARE DISCLAIMED.  IN NO EVENT SHALL BERKELEY SOFTWARE DESIGN INC BE LIABLE
.\"  FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\"  DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\"  OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\"  HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\"  LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\"  OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\"  SUCH DAMAGE.
.\"
.\"	from BSDI $Id: mutex.4,v 1.1.2.3 1998/04/27 22:53:13 ewv Exp $
.\" $FreeBSD$
.\"
.Dd February 12, 2001
.Dt MUTEX 9
.Os
.Sh NAME
.Nm mutex ,
.Nm mtx_init ,
.Nm mtx_lock ,
.Nm mtx_lock_spin ,
.Nm mtx_lock_flags ,
.Nm mtx_lock_spin_flags ,
.Nm mtx_trylock ,
.Nm mtx_trylock_flags ,
.Nm mtx_unlock ,
.Nm mtx_unlock_spin ,
.Nm mtx_unlock_flags ,
.Nm mtx_unlock_spin_flags ,
.Nm mtx_destroy ,
.Nm mtx_initialized ,
.Nm mtx_owned ,
.Nm mtx_recursed ,
.Nm mtx_assert,
.Nm MTX_SYSINIT
.Nd kernel synchronization primitives
.Sh SYNOPSIS
.In sys/param.h
.In sys/lock.h
.In sys/mutex.h
.Ft void
.Fn mtx_init "struct mtx *mutex" "const char *description" "int opts"
.Ft void
.Fn mtx_lock "struct mtx *mutex"
.Ft void
.Fn mtx_lock_spin "struct mtx *mutex"
.Ft void
.Fn mtx_lock_flags "struct mtx *mutex" "int flags"
.Ft void
.Fn mtx_lock_spin_flags "struct mtx *mutex" "int flags"
.Ft int
.Fn mtx_trylock "struct mtx *mutex"
.Ft int
.Fn mtx_trylock_flags "struct mtx *mutex" "int flags"
.Ft void
.Fn mtx_unlock "struct mtx *mutex"
.Ft void
.Fn mtx_unlock_spin "struct mtx *mutex"
.Ft void
.Fn mtx_unlock_flags "struct mtx *mutex" "int flags"
.Ft void
.Fn mtx_unlock_spin_flags "struct mtx *mutex" "int flags"
.Ft void
.Fn mtx_destroy "struct mtx *mutex"
.Ft int
.Fn mtx_initialized "struct mtx *mutex"
.Ft int
.Fn mtx_owned "struct mtx *mutex"
.Ft int
.Fn mtx_recursed "struct mtx *mutex"
.Ft void
.Fn mtx_assert "struct mtx *mutex" "int what"
.Fn MTX_SYSINIT "name" "struct mutex *mtx" "const char *description" "int opts"
.Sh DESCRIPTION
Mutexes are the most basic and primary method of process synchronization.
The major design considerations for mutexes are:
.Bl -enum
.It
Acquiring and releasing uncontested mutexes should be as cheap
as possible.
.It
They must have the information and storage space to support
priority propagation.
.It
A process must be able to recursively acquire a mutex,
provided that the mutex is initialized to support recursion.
.El
.Pp
There are currently two flavors of mutexes, those that context switch
when they block and those that do not.
.Pp
By default,
.Dv MTX_DEF
mutexes will context switch when they are already held.
As a machine dependent optimization they may spin for some amount
of time before context switching.
It is important to remember that since a process may be preempted at any time,
the possible context switch introduced by acquiring a mutex is guaranteed
to not break anything that isn't already broken.
.Pp
Mutexes which do not context switch are
.Dv MTX_SPIN
mutexes.
These should only be used to protect data shared with any devices that
require non-preemptive interrupts, and low level scheduling code.
In most/all architectures both acquiring and releasing of a
uncontested spin mutex is more expensive than the same operation
on a non spin mutex.
In order to protect an interrupt service routine from blocking
against itself all interrupts are blocked on a processor while
holding a spin lock.
It is permissible to hold multiple spin mutexes.
In this case it is a required that they be released in the opposite
order to that which they were acquired.
.Pp
Once a spin mutex has been acquired it is not permissible to acquire a
blocking mutex.
.Pp
The storage needed to implement a mutex is provided by a
.Vt struct mtx .
In general this should be treated as an opaque object and
referenced only with the mutex primitives.
.Pp
The
.Fn mtx_init
function must be used to initialize a mutex
before it can be passed to
.Fn mtx_lock .
The
.Fa description
argument is used by the witness code
to classify a mutex when doing checks of lock ordering.
The pointer passed in as the
.Fa description
is saved rather than the data it points to.
The data pointed to must remain stable
until the mutex is destroyed.
The
.Fa opts
argument is used to set the type of mutex.
It may contain either
.Dv MTX_DEF
or
.Dv MTX_SPIN
but not both.
Optionally, it may also contain the<commit_msg>Document the lock type argument of mtx_init().<commit_after>.\"
.\" Copyright (c) 1998 Berkeley Software Design, Inc. All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. Berkeley Software Design Inc's name may not be used to endorse or
.\"    promote products derived from this software without specific prior
.\"    written permission.
.\"
.\"  THIS SOFTWARE IS PROVIDED BY BERKELEY SOFTWARE DESIGN INC ``AS IS'' AND
.\"  ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\"  IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\"  ARE DISCLAIMED.  IN NO EVENT SHALL BERKELEY SOFTWARE DESIGN INC BE LIABLE
.\"  FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\"  DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\"  OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\"  HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\"  LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\"  OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\"  SUCH DAMAGE.
.\"
.\"	from BSDI $Id: mutex.4,v 1.1.2.3 1998/04/27 22:53:13 ewv Exp $
.\" $FreeBSD$
.\"
.Dd February 12, 2001
.Dt MUTEX 9
.Os
.Sh NAME
.Nm mutex ,
.Nm mtx_init ,
.Nm mtx_lock ,
.Nm mtx_lock_spin ,
.Nm mtx_lock_flags ,
.Nm mtx_lock_spin_flags ,
.Nm mtx_trylock ,
.Nm mtx_trylock_flags ,
.Nm mtx_unlock ,
.Nm mtx_unlock_spin ,
.Nm mtx_unlock_flags ,
.Nm mtx_unlock_spin_flags ,
.Nm mtx_destroy ,
.Nm mtx_initialized ,
.Nm mtx_owned ,
.Nm mtx_recursed ,
.Nm mtx_assert,
.Nm MTX_SYSINIT
.Nd kernel synchronization primitives
.Sh SYNOPSIS
.In sys/param.h
.In sys/lock.h
.In sys/mutex.h
.Ft void
.Fn mtx_init "struct mtx *mutex" "const char *description" "const char *type" "int opts"
.Ft void
.Fn mtx_lock "struct mtx *mutex"
.Ft void
.Fn mtx_lock_spin "struct mtx *mutex"
.Ft void
.Fn mtx_lock_flags "struct mtx *mutex" "int flags"
.Ft void
.Fn mtx_lock_spin_flags "struct mtx *mutex" "int flags"
.Ft int
.Fn mtx_trylock "struct mtx *mutex"
.Ft int
.Fn mtx_trylock_flags "struct mtx *mutex" "int flags"
.Ft void
.Fn mtx_unlock "struct mtx *mutex"
.Ft void
.Fn mtx_unlock_spin "struct mtx *mutex"
.Ft void
.Fn mtx_unlock_flags "struct mtx *mutex" "int flags"
.Ft void
.Fn mtx_unlock_spin_flags "struct mtx *mutex" "int flags"
.Ft void
.Fn mtx_destroy "struct mtx *mutex"
.Ft int
.Fn mtx_initialized "struct mtx *mutex"
.Ft int
.Fn mtx_owned "struct mtx *mutex"
.Ft int
.Fn mtx_recursed "struct mtx *mutex"
.Ft void
.Fn mtx_assert "struct mtx *mutex" "int what"
.Fn MTX_SYSINIT "name" "struct mutex *mtx" "const char *description" "int opts"
.Sh DESCRIPTION
Mutexes are the most basic and primary method of process synchronization.
The major design considerations for mutexes are:
.Bl -enum
.It
Acquiring and releasing uncontested mutexes should be as cheap
as possible.
.It
They must have the information and storage space to support
priority propagation.
.It
A process must be able to recursively acquire a mutex,
provided that the mutex is initialized to support recursion.
.El
.Pp
There are currently two flavors of mutexes, those that context switch
when they block and those that do not.
.Pp
By default,
.Dv MTX_DEF
mutexes will context switch when they are already held.
As a machine dependent optimization they may spin for some amount
of time before context switching.
It is important to remember that since a process may be preempted at any time,
the possible context switch introduced by acquiring a mutex is guaranteed
to not break anything that isn't already broken.
.Pp
Mutexes which do not context switch are
.Dv MTX_SPIN
mutexes.
These should only be used to protect data shared with any devices that
require non-preemptive interrupts, and low level scheduling code.
In most/all architectures both acquiring and releasing of a
uncontested spin mutex is more expensive than the same operation
on a non spin mutex.
In order to protect an interrupt service routine from blocking
against itself all interrupts are blocked on a processor while
holding a spin lock.
It is permissible to hold multiple spin mutexes.
In this case it is a required that they be released in the opposite
order to that which they were acquired.
.Pp
Once a spin mutex has been acquired it is not permissible to acquire a
blocking mutex.
.Pp
The storage needed to implement a mutex is provided by a
.Vt struct mtx .
In general this should be treated as an opaque object and
referenced only with the mutex primitives.
.Pp
The
.Fn mtx_init
function must be used to initialize a mutex
before it can be passed to
.Fn mtx_lock .
The
.Fa description
argument is used by the witness code
to classify a mutex when doing checks of lock ordering.
The pointer passed in as the
.Fa description
is saved rather than the data it points to.
The data pointed to must remain stable
until the mutex is destroyed.
The
.Fa type
argument is the generic lock type for use with witness.  If this argument is
NULL then the lock name is used as the lock type.
The
.Fa opts
argument is used to set the type of mutex.
It may contain either
.Dv MTX_DEF
or
.Dv MTX_SPIN
but not both.
Optionally, it may also contain the
{'fraction_non_alphanumeric': 0.06639928698752229, 'fraction_numerical': 0.0058823529411764705, 'mean_word_length': 4.0026749888542135, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 2, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1643524', 'n_tokens_mistral': 3616, 'n_tokens_neox': 3376, 'n_words': 1706}