share/man/man9/locking.9

   1 .\"
   2 .\" Copyright (c) 2014 Markus Pfeiffer
   3 .\" All rights reserved.
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\" 1. Redistributions of source code must retain the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer.
  10 .\" 2. Redistributions in binary form must reproduce the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer in the
  12 .\"    documentation and/or other materials provided with the distribution.
  13 .\"
  14 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  15 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  16 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  17 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  18 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  19 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  20 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  21 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  22 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  23 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  24 .\" SUCH DAMAGE.
  25 .\"
  26 .\"
  27 .Dd June 5, 2014
  28 .Dt LOCKING 9
  29 .Os
  30 .Sh NAME
  31 .Nm locking
  32 .Nd introduction to kernel locking primitives
  33 .Sh DESCRIPTION
  34 The
  35 .Dx
  36 kernel provides several locking and synchronisation primitives, each with
  37 different characteristics and purposes.
  38 This manpage aims at giving an
  39 overview of the available locking primitives and their use cases, as well
  40 as pointers towards further information.
  41 .Ss Condition Variables
  42 Condition variables are used to wait for conditions to occur.
  43 In
  44 .Dx
  45 condition variables use a
  46 .Xr spinlock 9
  47 internally.
  48 Threads that wait on a condition variable are called waiters.
  49 Either just one or all waiters can be notified of changes to a
  50 condition variable.
  51 A condition variable can
  52 .Xr tsleep_interlock 9
  53 when given a
  54 .Xr lockmgr 9
  55 lock to avoid missing changes to it, or use regular
  56 .Xr tsleep 9 .
  57 .Pp
  58 See
  59 .Xr condvar 9
  60 for further information.
  61 .Ss Critical Sections
  62 A critical section changes the priority of the current thread to
  63 .Dv TDPRIT_CRIT ,
  64 effectively avoiding preemption of the thread.
  65 Critical sections are a per-cpu primitive, and there is no synchronisation
  66 or locking between CPUs.
  67 .Pp
  68 See
  69 .Xr crit_enter 9 .
  70 for further information.
  71 .Ss Lockmgr Locks
  72 .Xr Lockmgr 9
  73 locks are the kitchen sink locking primitive for the
  74 .Dx
  75 kernel, and the most heavyweight locking mechanism.
  76 .Xr lockmgr 9
  77 locks can be shared/exclusive and recursive.
  78 Lockmgr locks should be used for
  79 .Fx
  80 compatibility when porting drivers that use
  81 .Fx Ap s
  82 mutexes.
  83 .Pp
  84 See
  85 .Xr lockmgr 9
  86 for more information.
  87 .Ss LWKT Messages
  88 LWKT messages can be used to pass messages between light weight kernel
  89 threads in the
  90 .Dx
  91 kernel.
  92 LWKT mesages are sent to message ports. Every light weight kernel thread
  93 possesses a message port, but more can be created if necessary.
  94 .Pp
  95 See
  96 .Xr msgport 9
  97 for more information.
  98 .Ss LWKT Serializers
  99 LWKT serializers provide a fast locked-bus-cycle-based serialization
 100 facility.
 101 They are used to serialize access to hardware and other subsystems.
 102 Serializers were designed to provide low level exclusive locks.
 103 .Pp
 104 See
 105 .Xr serializer 9 .
 106 for more information.
 107 .Ss LWKT Tokens
 108 LWKT tokens use
 109 .Xr atomic_cmpset 9
 110 internally and are integrated with the LWKT scheduler.
 111 The scheduler takes care of acquiring a token before
 112 rescheduling, so a thread will not be run unless all tokens for it can be
 113 acquired.
 114 Tokens are not owned by a thread, but by the CPU, and threads are only given
 115 references to tokens.
 116 See
 117 .Xr serializer 9 .
 118 .Ss MPLOCK
 119 The mplock is an API wrapper for the MP token. The use of this should be
 120 avoided at all cost, because there is only one MP token for the whole system.
 121 .Ss MTX Mutexes
 122 Mtx mutexes are a locking primitive that is based around
 123 .Xr atomic_cmpset_int 9
 124 instead of spinlocks.
 125 They are much faster and use less memory than
 126 .Xr lockmgr 9
 127 locks.
 128 Mtx mutexes can always be recursive, shared/exclusive and can be held
 129 across blocking calls and sleeps.
 130 They are also capable of passing ownership directly to a new owner
 131 without wakeup.
 132 See
 133 .Xr mutex 9 .
 134 .Ss Spinlocks
 135 Spinlocks employ a busy wait loop to acquire a lock.
 136 This means that this type of lock is very lightweight,
 137 but should only be held for a very short time, since all contenders
 138 will be spinning and not sleeping.
 139 No wakeup is necessary, because a waiter will be spinning already.
 140 If a thread tries to sleep while holding a spinlock, the kernel will panic.
 141 Spinlocks cannot recurse.
 142 .Pp
 143 They are mainly used to protect kernel structures, and to
 144 implement higher level locking primitives.
 145 See
 146 .Xr spinlock 9 .
 147 .Sh SEE ALSO
 148 .Xr atomic 9 ,
 149 .Xr condvar 9 ,
 150 .Xr crit_enter 9 ,
 151 .Xr lockmgr 9 ,
 152 .Xr mutex 9 ,
 153 .Xr serializer 9 ,
 154 .Xr spinlock 9 ,
 155 .Xr tsleep 9
 156 .Sh AUTHORS
 157 .An -nosplit
 158 This manual page was written by
 159 .An Markus Pfeiffer Aq Mt markus.pfeiffer@morphism.de ,
 160 based on comments by various
 161 .Dx
 162 authors.