DragonFly On-Line Manual Pages
LOCKING(9) DragonFly Kernel Developer's Manual LOCKING(9)
locking -- introduction to kernel locking primitives
The DragonFly kernel provides several locking and synchronisation primi-
tives, 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.
Condition variables are used to wait for conditions to occur. In
DragonFly condition variables use a 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 tsleep_interlock(9) when given a lockmgr(9) lock to avoid
missing changes to it, or use regular tsleep(9).
A critical section changes the priority of the current thread to
TDPRIT_CRIT, effectively avoiding preemption of the thread. Critical
sections are a per-cpu primitive, and there is no synchronisation or
locking between CPUs.
Lockmgr(9) locks are the kitchen sink locking primitive for the DragonFly
kernel, and the most heavyweight locking mechanism. lockmgr(9) locks can
be shared/exclusive and recursive. Lockmgr locks should be used for
FreeBSD compatibility when porting drivers that use FreeBSD's mutexes.
LWKT messages can be used to pass messages between light weight kernel
threads in the DragonFly kernel. LWKT mesages are sent to message ports.
Every light weight kernel thread possesses a message port, but more can
be created if necessary.
LWKT serializers provide a fast locked-bus-cycle-based serialization
facility. They are used to serialize access to hardware and other sub-
systems. Serializers were designed to provide low level exclusive locks.
LWKT tokens use 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.
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
Mtx mutexes are a locking primitive that is based around
atomic_cmpset_int(9) instead of spinlocks. They are much faster and use
less memory than 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
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.
They are mainly used to protect kernel structures, and to implement
higher level locking primitives.
atomic(9), condvar(9), crit_enter(9), lockmgr(9), mutex(9),
serializer(9), spinlock(9), tsleep(9)
This manual page was written by Markus Pfeiffer
<email@example.com>, based on comments by various DragonFly
DragonFly 4.1 June 5, 2014 DragonFly 4.1