1.\" Copyright (c) 2007 Julian Elischer (julian - freebsd org ) 2.\" All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 13.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 14.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 15.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 16.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 17.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 18.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 19.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 20.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 21.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 22.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 23.\" SUCH DAMAGE. 24.\" 25.Dd December 28, 2025 26.Dt LOCKING 9 27.Os 28.Sh NAME 29.Nm locking 30.Nd kernel synchronization primitives 31.Sh DESCRIPTION 32The 33.Em FreeBSD 34kernel is written to run across multiple CPUs and as such provides 35several different synchronization primitives to allow developers 36to safely access and manipulate many data types. 37.Ss Mutexes 38Mutexes (also called "blocking mutexes") are the most commonly used 39synchronization primitive in the kernel. 40A thread acquires (locks) a mutex before accessing data shared with other 41threads (including interrupt threads), and releases (unlocks) it afterwards. 42If the mutex cannot be acquired, the thread requesting it will wait. 43Mutexes are adaptive by default, meaning that 44if the owner of a contended mutex is currently running on another CPU, 45then a thread attempting to acquire the mutex will spin rather than yielding 46the processor. 47Mutexes fully support priority propagation. 48.Pp 49See 50.Xr mutex 9 51for details. 52.Ss Spin Mutexes 53Spin mutexes are a variation of basic mutexes; the main difference between 54the two is that spin mutexes never block. 55Instead, they spin while waiting for the lock to be released. 56To avoid deadlock, a thread that holds a spin mutex must never yield its CPU. 57Unlike ordinary mutexes, spin mutexes disable interrupts when acquired. 58Since disabling interrupts can be expensive, they are generally slower to 59acquire and release. 60Spin mutexes should be used only when absolutely necessary, 61e.g. to protect data shared 62with interrupt filter code (see 63.Xr bus_setup_intr 9 64for details), 65or for scheduler internals. 66.Ss Mutex Pools 67With most synchronization primitives, such as mutexes, the programmer must 68provide memory to hold the primitive. 69For example, a mutex may be embedded inside the structure it protects. 70Mutex pools provide a preallocated set of mutexes to avoid this 71requirement. 72Note that mutexes from a pool may only be used as leaf locks. 73.Pp 74See 75.Xr mtx_pool 9 76for details. 77.Ss Reader/Writer Locks 78Reader/writer locks allow shared access to protected data by multiple threads 79or exclusive access by a single thread. 80The threads with shared access are known as 81.Em readers 82since they should only read the protected data. 83A thread with exclusive access is known as a 84.Em writer 85since it may modify protected data. 86.Pp 87Reader/writer locks can be treated as mutexes (see above and 88.Xr mutex 9 ) 89with shared/exclusive semantics. 90Reader/writer locks support priority propagation like mutexes, 91but priority is propagated only to an exclusive holder. 92This limitation comes from the fact that shared owners 93are anonymous. 94.Pp 95See 96.Xr rwlock 9 97for details. 98.Ss Read-Mostly Locks 99Read-mostly locks are similar to 100.Em reader/writer 101locks but optimized for very infrequent write locking. 102.Em Read-mostly 103locks implement full priority propagation by tracking shared owners 104using a caller-supplied 105.Em tracker 106data structure. 107.Pp 108See 109.Xr rmlock 9 110for details. 111.Ss Sleepable Read-Mostly Locks 112Sleepable read-mostly locks are a variation on read-mostly locks. 113Threads holding an exclusive lock may sleep, 114but threads holding a shared lock may not. 115Priority is propagated to shared owners but not to exclusive owners. 116.Ss Shared/exclusive locks 117Shared/exclusive locks are similar to reader/writer locks; the main difference 118between them is that shared/exclusive locks may be held during unbounded sleep. 119Acquiring a contested shared/exclusive lock can perform an unbounded sleep. 120These locks do not support priority propagation. 121.Pp 122See 123.Xr sx 9 124for details. 125.Ss Lockmanager locks 126Lockmanager locks are sleepable shared/exclusive locks used mostly in 127.Xr VFS 9 128.Po 129as a 130.Xr vnode 9 131lock 132.Pc 133and in the buffer cache 134.Po 135.Xr BUF_LOCK 9 136.Pc . 137They have features other lock types do not have such as sleep 138timeouts, blocking upgrades, 139writer starvation avoidance, draining, and an interlock mutex, 140but this makes them complicated both to use and to implement; 141for this reason, they should be avoided. 142.Pp 143See 144.Xr lock 9 145for details. 146.Ss Non-blocking synchronization 147The kernel has two facilities, 148.Xr epoch 9 149and 150.Xr smr 9 , 151which can be used to provide read-only access to a data structure while one or 152more writers are concurrently modifying the data structure. 153Specifically, readers using 154.Xr epoch 9 155and 156.Xr smr 9 157to synchronize accesses do not block writers, in contrast with reader/writer 158locks, and they help ensure that memory freed by writers is not reused until 159all readers which may be accessing it have finished. 160Thus, they are a useful building block in the construction of lock-free 161data structures. 162.Pp 163These facilities are difficult to use correctly and should be avoided 164in preference to traditional mutual exclusion-based synchronization, 165except when performance or non-blocking guarantees are a major concern. 166.Pp 167See 168.Xr epoch 9 169and 170.Xr smr 9 171for details. 172.Ss Counting semaphores 173Counting semaphores provide a mechanism for synchronizing access 174to a pool of resources. 175Unlike mutexes, semaphores do not have the concept of an owner, 176so they can be useful in situations where one thread needs 177to acquire a resource, and another thread needs to release it. 178They are largely deprecated. 179.Pp 180See 181.Xr sema 9 182for details. 183.Ss Condition variables 184Condition variables are used in conjunction with locks to wait for 185a condition to become true. 186A thread must hold the associated lock before calling one of the 187.Fn cv_wait , 188functions. 189When a thread waits on a condition, the lock 190is atomically released before the thread yields the processor 191and reacquired before the function call returns. 192Condition variables may be used with blocking mutexes, 193reader/writer locks, read-mostly locks, and shared/exclusive locks. 194.Pp 195See 196.Xr condvar 9 197for details. 198.Ss Sleep/Wakeup 199The functions 200.Fn tsleep , 201.Fn msleep , 202.Fn msleep_spin , 203.Fn pause , 204.Fn wakeup , 205and 206.Fn wakeup_one 207also handle event-based thread blocking. 208If a thread must wait for an external event, it is put to sleep by 209.Fn tsleep , 210.Fn msleep , 211.Fn msleep_spin , 212or 213.Fn pause . 214Threads may also wait using one of the locking primitive sleep routines 215.Xr mtx_sleep 9 , 216.Xr rw_sleep 9 , 217or 218.Xr sx_sleep 9 . 219.Pp 220Unlike condition variables, 221arbitrary addresses may be used as wait channels and a dedicated 222structure does not need to be allocated. 223However, care must be taken to ensure that wait channel addresses are 224unique to an event. 225For example, the memory address of a sleepable lock such as a 226.Xr sx 9 227must not be used as a sleep channel, because the lock implementation 228will internally use the same address as a wait channel. 229.Pp 230The parameter 231.Fa chan 232is an arbitrary address that uniquely identifies the event on which 233the thread is being put to sleep. 234All threads sleeping on a single 235.Fa chan 236are woken up later by 237.Fn wakeup 238.Pq often called from inside an interrupt routine 239to indicate that the 240event the thread was blocking on has occurred. 241.Pp 242Several of the sleep functions including 243.Fn msleep , 244.Fn msleep_spin , 245and the locking primitive sleep routines specify an additional lock 246parameter. 247The lock will be released before sleeping and reacquired 248before the sleep routine returns. 249If 250.Fa priority 251includes the 252.Dv PDROP 253flag, then the lock will not be reacquired before returning. 254The lock is used to ensure that a condition can be checked atomically, 255and that the current thread can be suspended without missing a 256change to the condition or an associated wakeup. 257In addition, all of the sleep routines will fully drop the 258.Va Giant 259mutex 260.Pq even if recursed 261while the thread is suspended and will reacquire the 262.Va Giant 263mutex 264.Pq restoring any recursion 265before the function returns. 266.Pp 267The 268.Fn pause 269function is a special sleep function that waits for a specified 270amount of time to pass before the thread resumes execution. 271This sleep cannot be terminated early by either an explicit 272.Fn wakeup 273or a signal. 274.Pp 275See 276.Xr sleep 9 277for details. 278.Ss Giant 279Giant is a special mutex used to protect data structures that do not 280yet have their own locks. 281Since it provides semantics akin to the old 282.Xr spl 9 283interface, 284Giant has special characteristics: 285.Bl -enum 286.It 287It is recursive. 288.It 289Drivers can request that Giant be locked around them 290by not marking themselves MPSAFE. 291Note that infrastructure to do this is slowly going away as non-MPSAFE 292drivers either became properly locked or disappear. 293.It 294Giant must be locked before other non-sleepable locks. 295.It 296Giant is dropped during unbounded sleeps and reacquired after wakeup. 297.It 298There are places in the kernel that drop Giant and pick it back up 299again. 300Sleep locks will do this before sleeping. 301Parts of the network or VM code may do this as well. 302This means that you cannot count on Giant keeping other code from 303running if your code sleeps, even if you want it to. 304.El 305.Sh INTERACTIONS 306The primitives can interact and have a number of rules regarding how 307they can and can not be combined. 308Many of these rules are checked by 309.Xr witness 4 . 310.Ss Bounded vs. Unbounded Sleep 311In a bounded sleep 312.Po also referred to as 313.Dq blocking 314.Pc 315the only resource needed to resume execution of a thread 316is CPU time for the owner of a lock that the thread is waiting to acquire. 317In an unbounded sleep 318.Po 319often referred to as simply 320.Dq sleeping 321.Pc 322a thread waits for an external event or for a condition 323to become true. 324In particular, 325a dependency chain of threads in bounded sleeps should always make forward 326progress, 327since there is always CPU time available. 328This requires that no thread in a bounded sleep is waiting for a lock held 329by a thread in an unbounded sleep. 330To avoid priority inversions, 331a thread in a bounded sleep lends its priority to the owner of the lock 332that it is waiting for. 333.Pp 334The following primitives perform bounded sleeps: 335mutexes, reader/writer locks and read-mostly locks. 336.Pp 337The following primitives perform unbounded sleeps: 338sleepable read-mostly locks, shared/exclusive locks, lockmanager locks, 339counting semaphores, condition variables, and sleep/wakeup. 340.Ss General Principles 341.Bl -bullet 342.It 343It is an error to do any operation that could result in yielding the processor 344while holding a spin mutex. 345.It 346It is an error to do any operation that could result in unbounded sleep 347while holding any primitive from the 'bounded sleep' group. 348For example, it is an error to try to acquire a shared/exclusive lock while 349holding a mutex, or to try to allocate memory with M_WAITOK while holding a 350reader/writer lock. 351.Pp 352Note that the lock passed to one of the 353.Fn sleep 354or 355.Fn cv_wait 356functions is dropped before the thread enters the unbounded sleep and does 357not violate this rule. 358.It 359It is an error to do any operation that could result in yielding of 360the processor when running inside an interrupt filter. 361.It 362It is an error to do any operation that could result in unbounded sleep when 363running inside an interrupt thread. 364.El 365.Ss Interaction table 366The following table shows what you can and can not do while holding 367one of the locking primitives discussed. 368Note that 369.Dq sleep 370includes 371.Fn sema_wait , 372.Fn sema_timedwait , 373any of the 374.Fn cv_wait 375functions, 376and any of the 377.Fn sleep 378functions. 379.Bl -column " You want:" "spin mtx " "mutex/rw " "rmlock " "sleep rm " "sx/lk " -offset 3n 380.It Em " You want:" Ta spin mtx Ta mutex/rw Ta rmlock Ta sleep rm Ta sx/lk Ta sleep 381.It Em "You have:" Ta -------- Ta -------- Ta ------ Ta -------- Ta ----- Ta ------ 382.It spin mtx Ta \&ok Ta \&no Ta \&no Ta \&no Ta \&no Ta \&no-1 383.It mutex/rw Ta \&ok Ta \&ok Ta \&ok Ta \&no Ta \&no Ta \&no-1 384.It rmlock Ta \&ok Ta \&ok Ta \&ok Ta \&no Ta \&no Ta \&no-1 385.It sleep rm Ta \&ok Ta \&ok Ta \&ok Ta \&ok-2 Ta \&ok-2 Ta \&ok-2/3 386.It sx Ta \&ok Ta \&ok Ta \&ok Ta \&ok Ta \&ok Ta \&ok-3 387.It lockmgr Ta \&ok Ta \&ok Ta \&ok Ta \&ok Ta \&ok Ta \&ok 388.El 389.Pp 390.Em *1 391There are calls that atomically release this primitive when going to sleep 392and reacquire it on wakeup 393.Po 394.Fn mtx_sleep , 395.Fn rw_sleep , 396.Fn msleep_spin , 397etc. 398.Pc . 399.Pp 400.Em *2 401These cases are only allowed while holding a write lock on a sleepable 402read-mostly lock. 403.Pp 404.Em *3 405Though one can sleep while holding this lock, 406one can also use a 407.Fn sleep 408function to atomically release this primitive when going to sleep and 409reacquire it on wakeup. 410.Pp 411Note that non-blocking try operations on locks are always permitted. 412.Ss Context mode table 413The next table shows what can be used in different contexts. 414At this time this is a rather easy to remember table. 415.Bl -column "interrupt filter: " "spin mtx " "mutex/rw " "rmlock " "sleep rm " "sx/lk " -offset 3n 416.It Em "Context:" Ta spin mtx Ta mutex/rw Ta rmlock Ta sleep rm Ta sx/lk Ta sleep 417.It interrupt filter: Ta \&ok Ta \&no Ta \&no Ta \&no Ta \&no Ta \&no 418.It interrupt thread: Ta \&ok Ta \&ok Ta \&ok Ta \&no Ta \&no Ta \&no 419.It callout: Ta \&ok Ta \&ok Ta \&ok Ta \&no Ta \&no Ta \&no 420.It direct callout: Ta \&ok Ta \&no Ta \&no Ta \&no Ta \&no Ta \&no 421.It system call: Ta \&ok Ta \&ok Ta \&ok Ta \&ok Ta \&ok Ta \&ok 422.El 423.Sh SEE ALSO 424.Xr lockstat 1 , 425.Xr witness 4 , 426.Xr atomic 9 , 427.Xr BUS_SETUP_INTR 9 , 428.Xr callout 9 , 429.Xr condvar 9 , 430.Xr epoch 9 , 431.Xr lock 9 , 432.Xr LOCK_PROFILING 9 , 433.Xr mtx_pool 9 , 434.Xr mutex 9 , 435.Xr rmlock 9 , 436.Xr rwlock 9 , 437.Xr sema 9 , 438.Xr sleep 9 , 439.Xr smr 9 , 440.Xr sx 9 441.Sh BUGS 442There are too many locking primitives to choose from. 443