Copyright (c) 2023 The FreeBSD Foundation

This documentation was written by Mitchell Horne <mhorne@FreeBSD.org> under
sponsorship from the FreeBSD Foundation.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
SUCH DAMAGE.

.Dd January 30, 2023 .Dt KERN_YIELD 9 .Os .Sh NAME .Nm kern_yield , .Nm maybe_yield , .Nm should_yield .Nd "functions for yielding execution of the current thread" .Sh SYNOPSIS .Ft void .Fn kern_yield "int prio" .Ft void .Fn maybe_yield .Ft bool .Fn should_yield .Sh DESCRIPTION The .Fn kern_yield function causes the currently running thread to voluntarily, but unconditionally, surrender its execution to the scheduler. The .Va prio argument specifies the scheduling priority to be assigned before the context switch, which has an influence on when execution will resume. Note that the requested priority will take effect until the thread returns to usermode, after which its base user priority will be restored. Valid values for .Va prio are any of the .Dv PRI_* values defined in n sys/priority.h , as well as the following special values: l -tag -width "PRI_UNCHANGED" t Dv PRI_USER Schedule the thread with its base user priority; the value corresponding to .Xr setpriority 2 / .Xr nice 3 . t Dv PRI_UNCHANGED Yield the thread without changing its priority. .El

p The .Fn should_yield function checks if sufficient time has passed since the thread's last voluntary context switch that yielding would be a useful service to other threads. It returns .Va true when this is the case. See .Sx USAGE NOTES for an elaboration of what this means.

p The .Fn maybe_yield function is a helper function for the common task of optionally yielding the processor. Internally, .Fn kern_yield "PRI_USER" will be called if .Fn should_yield returns .Va true . .Sh USAGE NOTES Although the kernel supports preemption, this is usually reserved for high-priority realtime or interrupt threads. Kernel worker threads and timesharing threads are not guaranteed to preempt each another. Thus, threads executing in the kernel are expected to behave cooperatively with respect to other threads in the system. The yield functions are mostly intended to be used by threads which perform a lot of work inside the kernel. For example: .Fn maybe_yield is called by the .Dv vlnru process each time it reclaims a vnode.

p The scheduler aims to identify threads which monopolize the CPU, and will schedule them with decreased priority. Threads which regularly yield the processor will be given the chance to run more often. The possibly surprising effect of this is that, depending on the disposition of other threads on the CPU's runqueue, a call to .Fn kern_yield does not guarantee that the yielding thread will be taken off the CPU.

p With the above considerations in mind, it is advised that code written using .Fn kern_yield be measured to confirm that its use has a positive effect on relevant performance or responsiveness metrics. Switching thread contexts has a non-zero cost, and thus yielding the processor too eagerly could have a negative impact on performance.

p Additionally, since yielding is a cooperative action, it is advised that the yielding thread release any locks that it may be holding, when possible. Otherwise, threads which have been given the chance to run could end up waiting on the yielding thread to release the lock, largely defeating the purpose of the yield. .Sh SEE ALSO .Xr setpriority 2 , .Xr nice 3 , .Xr mi_switch 9 .Sh AUTHORS .An -nosplit This manual page was written by .An Mitchell Horne Aq Mt mhorne@FreeBSD.org .