share/man/man9/critical_enter.9

   1 .\" Copyright (c) 2001,2002 John H. Baldwin <jhb@FreeBSD.org>
   2 .\"
   3 .\" Redistribution and use in source and binary forms, with or without
   4 .\" modification, are permitted provided that the following conditions
   5 .\" are met:
   6 .\" 1. Redistributions of source code must retain the above copyright
   7 .\"    notice, this list of conditions and the following disclaimer.
   8 .\" 2. Redistributions in binary form must reproduce the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer in the
  10 .\"    documentation and/or other materials provided with the distribution.
  11 .\"
  12 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  13 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  14 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  15 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  16 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  17 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  18 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  19 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  20 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  21 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  22 .\" SUCH DAMAGE.
  23 .\"
  24 .\" $FreeBSD$
  25 .\"
  26 .Dd March 20, 2023
  27 .Dt CRITICAL_ENTER 9
  28 .Os
  29 .Sh NAME
  30 .Nm critical_enter ,
  31 .Nm critical_exit
  32 .Nd enter and exit a critical region
  33 .Sh SYNOPSIS
  34 .In sys/param.h
  35 .In sys/systm.h
  36 .Ft void
  37 .Fn critical_enter "void"
  38 .Ft void
  39 .Fn critical_exit "void"
  40 .Fn CRITICAL_ASSERT "struct thread *td"
  41 .Sh DESCRIPTION
  42 These functions are used to prevent preemption in a critical region of code.
  43 All that is guaranteed is that the thread currently executing on a CPU will
  44 not be preempted.
  45 Specifically, a thread in a critical region will not migrate to another CPU
  46 while it is in a critical region, nor will the current CPU switch to a
  47 different thread.
  48 The current CPU may still trigger faults and exceptions during a critical
  49 section; however, these faults are usually fatal.
  50 .Pp
  51 The CPU might also receive and handle interrupts within a critical section.
  52 When this occurs the interrupt exit will not result in a context switch, and
  53 execution will continue in the critical section.
  54 Thus, the net effect of a critical section on the current thread's execution is
  55 similar to running with interrupts disabled, except that timer interrupts and
  56 filtered interrupt handlers do not incur a latency penalty.
  57 .Pp
  58 The
  59 .Fn critical_enter
  60 and
  61 .Fn critical_exit
  62 functions manage a per-thread counter to handle nested critical sections.
  63 If a thread is made runnable that would normally preempt the current thread
  64 while the current thread is in a critical section,
  65 then the preemption will be deferred until the current thread exits the
  66 outermost critical section.
  67 .Pp
  68 Note that these functions do not provide any inter-CPU synchronization, data
  69 protection, or memory ordering guarantees, and thus should
  70 .Em not
  71 be used to protect shared data structures.
  72 .Pp
  73 These functions should be used with care as an unbound or infinite loop within
  74 a critical region will deadlock the CPU.
  75 Also, they should not be interlocked with operations on mutexes, sx locks,
  76 semaphores, or other synchronization primitives, as these primitives may
  77 require a context switch to operate.
  78 One exception to this is that spin mutexes include a critical section,
  79 so in certain cases critical sections may be interlocked with spin mutexes.
  80 .Pp
  81 Critical regions should be only as wide as necessary.
  82 That is, code which does not require the critical section to operate correctly
  83 should be excluded from its bounds whenever possible.
  84 Abuse of critical sections has an effect on overall system latency and timer
  85 precision, since disabling preemption will delay the execution of threaded
  86 interrupt handlers and
  87 .Xr callout 9
  88 events on the current CPU.
  89 .Pp
  90 The
  91 .Fn CRITICAL_ASSERT
  92 macro verifies that the provided thread
  93 .Fa td
  94 is currently executing in a critical section.
  95 It is a wrapper around
  96 .Xr KASSERT 9 .
  97 .Sh SEE ALSO
  98 .Xr callout 9 ,
  99 .Xr KASSERT 9 ,
 100 .Xr locking 9
 101 .Sh HISTORY
 102 These functions were introduced in
 103 .Fx 5.0 .