LOCKING(9)

NAME
locking - introduction to kernel locking primitives

DESCRIPTION
The DragonFly 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.

  Condition Variables
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).

See condvar(9).

  Critical Sections
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.

See crit_enter(9).

  Lockmgr Locks
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.

See lockmgr(9).

  LWKT Messages
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.

See msgport(9).

  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.

See serializer(9).

  LWKT Tokens
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.

See token(9).

  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.

  MTX Mutexes
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 wakeup.

See mutex(9).

  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.

They are mainly used to protect kernel structures, and to implement higher level locking primitives.

See spinlock(9).

SEE ALSO
atomic(9), condvar(9), crit_enter(9), lockmgr(9), mutex(9), serializer(9), spinlock(9), tsleep(9)

AUTHORS
-nosplit This manual page was written by Markus Pfeiffer <markus.pfeiffer@morphism.de>, based on comments by various DragonFly authors.