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 .Ss Critical Sections
  61 A critical section changes the priority of the current thread to
  62 .Dv TDPRIT_CRIT ,
  63 effectively avoiding preemption of the thread.
  64 Critical sections are a per-cpu primitive, and there is no synchronisation
  65 or locking between CPUs.
  66 .Pp
  67 See
  68 .Xr crit_enter 9 .
  69 .Ss Lockmgr Locks
  70 .Xr Lockmgr 9
  71 locks are the kitchen sink locking primitive for the
  72 .Dx
  73 kernel, and the most heavyweight locking mechanism.
  74 .Xr lockmgr 9
  75 locks can be shared/exclusive and recursive.
  76 Lockmgr locks should be used for
  77 .Fx
  78 compatibility when porting drivers that use
  79 .Fx Ap s
  80 mutexes.
  81 .Pp
  82 See
  83 .Xr lockmgr 9 .
  84 .Ss LWKT Messages
  85 LWKT messages can be used to pass messages between light weight kernel
  86 threads in the
  87 .Dx
  88 kernel.
  89 LWKT mesages are sent to message ports. Every light weight kernel thread
  90 possesses a message port, but more can be created if necessary.
  91 .Pp
  92 See
  93 .Xr msgport 9 .
  94 .Ss LWKT Serializers
  95 LWKT serializers provide a fast locked-bus-cycle-based serialization
  96 facility.
  97 They are used to serialize access to hardware and other subsystems.
  98 Serializers were designed to provide low level exclusive locks.
  99 .Pp
 100 See
 101 .Xr serializer 9 .
 102 .Ss LWKT Tokens
 103 LWKT tokens use
 104 .Xr atomic_cmpset 9
 105 internally and are integrated with the LWKT scheduler.
 106 The scheduler takes care of acquiring a token before
 107 rescheduling, so a thread will not be run unless all tokens for it can be
 108 acquired.
 109 Tokens are not owned by a thread, but by the CPU, and threads are only given
 110 references to tokens.
 111 .Pp
 112 See
 113 .Xr token 9 .
 114 .Ss MPLOCK
 115 The mplock is an API wrapper for the MP token. The use of this should be
 116 avoided at all cost, because there is only one MP token for the whole system.
 117 .Ss MTX Mutexes
 118 Mtx mutexes are a locking primitive that is based around
 119 .Xr atomic_cmpset_int 9
 120 instead of spinlocks.
 121 They are much faster and use less memory than
 122 .Xr lockmgr 9
 123 locks.
 124 Mtx mutexes can always be recursive, shared/exclusive and can be held
 125 across blocking calls and sleeps.
 126 They are also capable of passing ownership directly to a new owner
 127 without wakeup.
 128 .Pp
 129 See
 130 .Xr mutex 9 .
 131 .Ss Spinlocks
 132 Spinlocks employ a busy wait loop to acquire a lock.
 133 This means that this type of lock is very lightweight,
 134 but should only be held for a very short time, since all contenders
 135 will be spinning and not sleeping.
 136 No wakeup is necessary, because a waiter will be spinning already.
 137 If a thread tries to sleep while holding a spinlock, the kernel will panic.
 138 Spinlocks cannot recurse.
 139 .Pp
 140 They are mainly used to protect kernel structures, and to
 141 implement higher level locking primitives.
 142 .Pp
 143 See
 144 .Xr spinlock 9 .
 145 .Sh SEE ALSO
 146 .Xr atomic 9 ,
 147 .Xr condvar 9 ,
 148 .Xr crit_enter 9 ,
 149 .Xr lockmgr 9 ,
 150 .Xr mutex 9 ,
 151 .Xr serializer 9 ,
 152 .Xr spinlock 9 ,
 153 .Xr tsleep 9
 154 .Sh AUTHORS
 155 .An -nosplit
 156 This manual page was written by
 157 .An Markus Pfeiffer Aq Mt markus.pfeiffer@morphism.de ,
 158 based on comments by various
 159 .Dx
 160 authors.