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
     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
     This manual page was written by Markus Pfeiffer
     <markus.pfeiffer@morphism.de>, based on comments by various DragonFly
     authors.

DragonFly 3.7                    June 5, 2014                    DragonFly 3.7