1.\" 2.\" Copyright (c) 2023 The FreeBSD Foundation 3.\" 4.\" This documentation was written by Mitchell Horne <mhorne@FreeBSD.org> under 5.\" sponsorship from the FreeBSD Foundation. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 26.\" SUCH DAMAGE. 27.\" 28.Dd January 30, 2023 29.Dt KERN_YIELD 9 30.Os 31.Sh NAME 32.Nm kern_yield , 33.Nm maybe_yield , 34.Nm should_yield 35.Nd "functions for yielding execution of the current thread" 36.Sh SYNOPSIS 37.Ft void 38.Fn kern_yield "int prio" 39.Ft void 40.Fn maybe_yield 41.Ft bool 42.Fn should_yield 43.Sh DESCRIPTION 44The 45.Fn kern_yield 46function causes the currently running thread to voluntarily, but 47unconditionally, surrender its execution to the scheduler. 48The 49.Va prio 50argument specifies the scheduling priority to be assigned before the context 51switch, which has an influence on when execution will resume. 52Note that the requested priority will take effect until the thread returns to 53usermode, after which its base user priority will be restored. 54Valid values for 55.Va prio 56are any of the 57.Dv PRI_* 58values defined in 59.In sys/priority.h , 60as well as the following special values: 61.Bl -tag -width "PRI_UNCHANGED" 62.It Dv PRI_USER 63Schedule the thread with its base user priority; the value corresponding to 64.Xr setpriority 2 / 65.Xr nice 3 . 66.It Dv PRI_UNCHANGED 67Yield the thread without changing its priority. 68.El 69.Pp 70The 71.Fn should_yield 72function checks if sufficient time has passed since the thread's last voluntary 73context switch that yielding would be a useful service to other threads. 74It returns 75.Va true 76when this is the case. 77See 78.Sx USAGE NOTES 79for an elaboration of what this means. 80.Pp 81The 82.Fn maybe_yield 83function is a helper function for the common task of optionally yielding the 84processor. 85Internally, 86.Fn kern_yield "PRI_USER" 87will be called if 88.Fn should_yield 89returns 90.Va true . 91.Sh USAGE NOTES 92Although the kernel supports preemption, this is usually reserved for 93high-priority realtime or interrupt threads. 94Kernel worker threads and timesharing threads are not guaranteed to preempt 95each another. 96Thus, threads executing in the kernel are expected to behave cooperatively 97with respect to other threads in the system. 98The yield functions are mostly intended to be used by threads which perform a 99lot of work inside the kernel. 100For example: 101.Fn maybe_yield 102is called by the 103.Dv vlnru 104process each time it reclaims a vnode. 105.Pp 106The scheduler aims to identify threads which monopolize the CPU, and will 107schedule them with decreased priority. 108Threads which regularly yield the processor will be given the chance to run 109more often. 110The possibly surprising effect of this is that, depending on the disposition of 111other threads on the CPU's runqueue, a call to 112.Fn kern_yield 113does not guarantee that the yielding thread will be taken off the CPU. 114.Pp 115With the above considerations in mind, it is advised that code written using 116.Fn kern_yield 117be measured to confirm that its use has a positive effect on relevant 118performance or responsiveness metrics. 119Switching thread contexts has a non-zero cost, and thus yielding the processor 120too eagerly could have a negative impact on performance. 121.Pp 122Additionally, since yielding is a cooperative action, it is advised that the 123yielding thread release any locks that it may be holding, when possible. 124Otherwise, threads which have been given the chance to run could end up waiting 125on the yielding thread to release the lock, largely defeating the purpose of 126the yield. 127.Sh SEE ALSO 128.Xr setpriority 2 , 129.Xr nice 3 , 130.Xr mi_switch 9 131.Sh AUTHORS 132.An -nosplit 133This manual page was written by 134.An Mitchell Horne Aq Mt mhorne@FreeBSD.org . 135