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. This manpage aims at giving an
  38 overview of the available locking primitives and their usecases.
  39 .Sh CONDITION VARIABLES
  40 Condition variables are used to wait for conditions to occur. In
  41 .Dx
  42 condition variables use spinlocks internally.
  43 Threads that wait on a condition variable are called waiters. Either just
  44 one or all waiters can be notified of changes to a condition variable.
  45 A condition variable can interlock sleep when given a lockmgr lock to
  46 avoid missing changes to it, or regular tsleep.
  47 .Pp
  48 See
  49 .Xr condvar 9
  50
  51 .Sh CRITICAL SECTIONS
  52 A critical section changes the priority of the current thread to
  53 TDPRIT_CRIT, effectively avoiding preemption of the thread.
  54 Critical sections are a per-cpu primitive, and there is no synchronisation
  55 or locking between CPUs.
  56 .Ss Use cases
  57 .Ss See also
  58 .Xr crit_enter 9
  59 .Sh LOCKMGR LOCKS
  60 Lockmgr locks are the kitchen sink locking primitive for the
  61 .Dx
  62 kernel. See
  63 .Xr lockmgr 9
  64 for more information. Lockmgr locks should be used for FreeBSD compatibility when porting drivers that use FreeBSD's mutexes.
  65 .Pp
  66 See
  67 .Xr lockmgr 9
  68
  69 .Sh LWKT SERIALIZING TOKENS
  70
  71 Lwkt serializing tokens use atomic_cmpset internally and are integrated with
  72 the lwkt serializer. The scheduler takes care of acquiring a token before
  73 rescheduling, so a thread will not be run unless all tokens for it can be
  74 acquired.
  75
  76 Tokens are not owned by a thread, but by the CPU, and threads are only given
  77 references to tokens.
  78
  79 .Sh LWKT MESSAGES
  80
  81 .Sh MPLOCK
  82 The mplock is an API wrapper for the MP token. The use of this should be
  83 avoided at all cost, because there is only one MP token for the whole system.
  84 .Ss Use cases
  85 .Sh MTX
  86 Mtx mutexes are a locking primitive that is based around atomic_cmpset_int instead
  87 of spinlocks. They are much faster and use less memory than than lockmgr locks.
  88 Mtx can always be recursive, shared/exclusive and can be held across blocking calls
  89 and sleeps.
  90 Mtx are also capable of passing ownership directly to a new owner without wakeup.
  91
  92 See
  93 .Sh SERIALIZERS
  94 Serializers are used to serialize access to hardware and other subsystems.
  95 Serializers are deprecated, and should not be used in new code.
  96
  97 .Sh SPINLOCKS
  98 Spinlocks employ a busy wait loop to acquire a lock. This means that this type of lock
  99 is very lightweight, but should only be held for a very short time, since all contenders
 100 will be spinning and not sleeping. No wakeup is necessary, because a waiter will be
 101 spinning already.
 102 If a thread tries to sleep while holding a spinlock, the kernel will panic.
 103 Spinlocks cannot recurse.
 104
 105 .Ss Use cases
 106 Spinlocks are mainly used to protect kernel structures, and to implement higher level
 107 locking primitives.
 108 .Ss See also
 109
 110 .Sh AUTHORS
 111 .An -nosplit
 112 This manual page was written by
 113 .An Markus Pfeiffer Aq Mt markus.pfeiffer@morphism.de ,
 114 based on comments by various
 115 .Dx
 116 authors.