.\"
.\" Copyright (c) 2014 Markus Pfeiffer
.\" 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.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``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 THE AUTHOR OR CONTRIBUTORS 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.
.\"
.\"
.Dd June 5, 2014
.Dt LOCKING 9
.Os
.Sh NAME
.Nm locking
.Nd introduction to kernel locking primitives
.Sh DESCRIPTION
The
.Dx
kernel provides several locking and synchronisation primitives, each with
different characteristics and purposes.
This manpage aims at giving an
overview of the available locking primitives and their use cases, as well
as pointers towards further information.
.Ss Condition Variables
Condition variables are used to wait for conditions to occur.
In
.Dx
condition variables use a
.Xr spinlock 9
internally.
Threads that wait on a condition variable are called waiters.
Either just one or all waiters can be notified of changes to a
condition variable.
A condition variable can
.Xr tsleep_interlock 9
when given a
.Xr lockmgr 9
lock to avoid missing changes to it, or use regular
.Xr tsleep 9 .
.Pp
See
.Xr condvar 9 .
.Ss Critical Sections
A critical section changes the priority of the current thread to
.Dv TDPRIT_CRIT ,
effectively avoiding preemption of the thread.
Critical sections are a per-cpu primitive, and there is no synchronisation
or locking between CPUs.
.Pp
See
.Xr crit_enter 9 .
.Ss Lockmgr Locks
.Xr Lockmgr 9
locks are the kitchen sink locking primitive for the
.Dx
kernel, and the most heavyweight locking mechanism.
.Xr lockmgr 9
locks can be shared/exclusive and recursive.
Lockmgr locks should be used for
.Fx
compatibility when porting drivers that use
.Fx Ap s
mutexes.
.Pp
See
.Xr lockmgr 9 .
.Ss LWKT Messages
LWKT messages can be used to pass messages between light weight kernel
threads in the
.Dx
kernel.
LWKT mesages are sent to message ports. Every light weight kernel thread
possesses a message port, but more can be created if necessary.
.Pp
See
.Xr msgport 9 .
.Ss LWKT Serializers
LWKT serializers provide a fast locked-bus-cycle-based serialization
facility.
They are used to serialize access to hardware and other subsystems.
Serializers were designed to provide low level exclusive locks.
.Pp
See
.Xr serializer 9 .
.Ss LWKT Tokens
LWKT tokens use
.Xr atomic_cmpset 9
internally and are integrated with the LWKT scheduler.
The scheduler takes care of acquiring a token before
rescheduling, so a thread will not be run unless all tokens for it can be
acquired.
Tokens are not owned by a thread, but by the CPU, and threads are only given
references to tokens.
.Pp
See
.Xr token 9 .
.Ss MPLOCK
The mplock is an API wrapper for the MP token. The use of this should be
avoided at all cost, because there is only one MP token for the whole system.
.Ss MTX Mutexes
Mtx mutexes are a locking primitive that is based around
.Xr atomic_cmpset_int 9
instead of spinlocks.
They are much faster and use less memory than
.Xr lockmgr 9
locks.
Mtx mutexes can always be recursive, shared/exclusive and can be held
across blocking calls and sleeps.
They are also capable of passing ownership directly to a new owner
without wakeup.
.Pp
See
.Xr mutex 9 .
.Ss Spinlocks
Spinlocks employ a busy wait loop to acquire a lock.
This means that this type of lock is very lightweight,
but should only be held for a very short time, since all contenders
will be spinning and not sleeping.
No wakeup is necessary, because a waiter will be spinning already.
If a thread tries to sleep while holding a spinlock, the kernel will panic.
Spinlocks cannot recurse.
.Pp
They are mainly used to protect kernel structures, and to
implement higher level locking primitives.
.Pp
See
.Xr spinlock 9 .
.Sh SEE ALSO
.Xr atomic 9 ,
.Xr condvar 9 ,
.Xr crit_enter 9 ,
.Xr lockmgr 9 ,
.Xr mutex 9 ,
.Xr serializer 9 ,
.Xr spinlock 9 ,
.Xr tsleep 9
.Sh AUTHORS
.An -nosplit
This manual page was written by
.An Markus Pfeiffer Aq Mt markus.pfeiffer@morphism.de ,
based on comments by various
.Dx
authors.