DragonFly On-Line Manual Pages


LOCKING(9)	      DragonFly Kernel Developer's Manual	    LOCKING(9)

NAME

locking -- introduction to kernel locking primitives

DESCRIPTION

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 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 sub- systems. 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

This manual page was written by Markus Pfeiffer <markus.pfeiffer@morphism.de>, based on comments by various DragonFly authors. DragonFly 3.9 June 5, 2014 DragonFly 3.9