docs/developer/Locking_and_Synchronization/index.mdwn

   1 ## Lockmgr
   2
   3 Lockmgr locks used to be heavy-weight locks but have since been optimized and will run almost as fast as spinlocks and faster than mtx locks in the critical path.  Lockmgr locks block formally and will not be as fast as spin-locks for very short highly-contending bits of code.  Lockmgr locks are the go-to lock for DragonFly and should be used if you are not sure what to use.
   4
   5 ### Internals
   6 * Uses atomic_cmpset*()
   7 * Both shared and exclusive locks are supported.
   8 * Locks are held across blocking conditions.
   9 * Exclusive priority over shared for SMP performance.
  10 * Always a procedure call but fast-paths operations internally.
  11 * Will formally block when acquiring (if LK_NOWAIT not used).
  12 * Can unblock and return an error on signal received.
  13 * Has many general purpose features.
  14 * Easy to debug.
  15 * Easy wakeup() semantics with numerous cpu management features.
  16 * Most portable.
  17
  18 ----
  19
  20 ## Spinlocks
  21
  22 Kernel spinlocks are optimized for fast inlining but should generally only be used if tokens, lockmgr, or mtx locks are not appropriate.  The most common use case is when you are holding a token but do not want to break its atomicy by potentially blocking on a deeper lock.  It is far more difficult to debug issues with spinlocks than it is for blockable locks.
  23
  24 ### Internals
  25 * Non-recursive by design.
  26 * Both shared and exclusive spinlocks are supported.
  27 * Thread spins to wait, does not sleep or block.
  28 * Uses atomic_cmpset*(), fast-path is inlined.
  29 * Any held tokens will not be temporarily released.
  30 * Automatic critical section while a spinlock is held.
  31 * Exclusive spinlocks have priority over shared spinlocks to reduce SMP lag.
  32 * Should only be used for very short segments of code.
  33 * Should not wrap long or complex pieces of code or anything that can block.
  34 * Should not wrap kernel calls, even simple ones.
  35 * Nesting is not recommended.
  36 * Do not use unless you are very familiar with how spinlocks work as misuse can lead to a kernel deadlock.
  37
  38 ----
  39
  40 ## LWKT serializing tokens
  41
  42 LWKT tokens are commonly used to loosely lock very broad, deep, or complex sections of code which might block at times.  You can acquire tokens in any order without worrying about deadlocks, however any blocking condition (including blocking when acquiring additional tokens) will temporarily release ALL held tokens while the thread is blocked.  Tokens have the property of serializing code execution for the token held while the thread is runnable.
  43
  44 Preemption by another thread (typically an interrupt thread) will not break the tokens you are holding.  Preemption is still allowed... tokens do not enter a critical section.  If the preempting thread tries to obtain the same token it will reschedule normally and return to the original thread.
  45
  46 The kernel thread scheduler will try to spin a bit on a token that cannot be acquired before giving up and blocking for real.
  47
  48 ### Internals
  49 * Uses atomic_cmpset*() internally
  50 * Spins in scheduler instead of blocking but counts as 'blocking' because scheduler is allowed to switch to other threads.
  51 * Easy to debug, all held tokens are tracked on a thread-by-thread basis.
  52 * Recursion is always allowed.
  53 * Both exclusive and shared tokens are supported
  54 * Shared tokens must be used with caution, mixed use on the same token in the same thread will panic.
  55 * Optimal for ping-ponging between two threads.
  56
  57 ----
  58
  59 ## MTX
  60
  61 Mtx locks in DragonFly should not be confused with mtx locks in FreeBSD.  Mtx locks in DragonFly are a very different beast.  Generally these locks work similarly to lockmgr locks but provide two additional features which also make them heavier-weight in the face of contention.
  62
  63 ### Internals
  64 * Also uses atomic_cmpset*() internally.
  65 * Implements lock chaining internally, round-robin for exclusive locks.
  66 * Exclusive locks have priority over shared locks for SMP performance.
  67 * Always recursive.
  68 * The fast-path is inlined.
  69 * Easy to debug due to internal chaining structures.
  70 * Locks are held across blocking conditions.
  71 * Supports shared and exclusive locks and most features of lockmgr locks.
  72 * Supports callback-based asynchronous lock acquisition.
  73 * Supports lock aborts (for both synchronous and asynchronous).
  74
  75 ----
  76
  77 ## MPLock
  78
  79 The mplock has been deprecated and should no longer be used.  It is still used in a few non-critical places in DragonFly but has been removed from nearly all major and minor kernel subsystems.
  80
  81 ### Internals
  82 * API is a wrapper for mp_token
  83
  84 ----
  85
  86 ## LWKT Messages
  87
  88 DragonFly implements a light weight message-and-port subsystem which is primarily used to shove packets around in bulk in the network subsystem and to cpu-localize network operations.  The disk subsystem also uses LWKT messages to sequence disk probes and synchronize devfs.
  89
  90 ### Internals
  91 * Message passing and queueing.
  92 * End-point mechanics can be customized.
  93 * Very light-weight.
  94
  95 ----
  96
  97 ## Critical Sections
  98
  99 Critical sections are a form of cpu-localized locking that prevents a thread from being preempted by another thread or an IPI or clock interrupt.
 100
 101 Critical sections do not protect a thread from threads or interrupts which might run on other cpus and should generally not be used to protect the frontend of a chipset driver from the backend (since the frontend can run on any cpu).  Critical sections are primarily used to protect against IPIs, allowing cpu localized code to run very efficiently.
 102
 103 A critical section can be used if you want to avoid code latency but is not recommended for this purpose any more.  A critical section cannot prevent SMIs from occurring and also do not prevent the actual hard interrupt from interrupting the cpu, it simply causes the interrupt to immediately return and delay execution until the critical section is exited.
 104
 105 ### Internals
 106 * Prevents preemption by an interrupt thread
 107 * Prevents preemption by an IPI or clock interrupt
 108 * Critical section holder can still block if desired, the critical section is simply set aside and then restored when the thread unblocks.
 109
 110 ----
 111
 112 ## Condvars
 113
 114 Condvars are only used when porting code from FreeBSD and should not generally be used for native DragonFly code.
 115
 116 ### Internals
 117
 118 * Generally used for simple interlocked event/wait loops, but tends to obfuscate what is happening.
 119 * Uses a spinlock internally.
 120 * Not inline-optimized.
 121 * Not optimized for heavy SMP contention.
 122 * Lockmgr locks are generally easier to understand and should be used instead.
 123
 124 ----
 125
 126 ## Serializers
 127
 128 DragonFly currently implements a LWKT serializer abstraction which should not be used generally.  This abstraction is heavily integrated into the network interface device driver subsystem.
 129