FreeBSD Manual Pages
KERN_YIELD(9) Kernel Developer's Manual KERN_YIELD(9) NAME kern_yield, maybe_yield, should_yield -- functions for yielding execution of the current thread SYNOPSIS void kern_yield(int prio); void maybe_yield(); bool should_yield(); DESCRIPTION The kern_yield() function causes the currently running thread to voluntar- ily, but unconditionally, surrender its execution to the scheduler. The 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 val- ues for prio are any of the PRI_* values defined in <sys/priority.h>, as well as the following special values: PRI_USER Schedule the thread with its base user priority; the value corresponding to setpriority(2)/ nice(3). PRI_UNCHANGED Yield the thread without changing its priority. The should_yield() function checks if sufficient time has passed since the thread's last voluntary context switch that yielding would be a useful ser- vice to other threads. It returns true when this is the case. See "USAGE NOTES" for an elaboration of what this means. The maybe_yield() function is a helper function for the common task of op- tionally yielding the processor. Internally, kern_yield(PRI_USER) will be called if should_yield() returns true. USAGE NOTES Although the kernel supports preemption, this is usually reserved for high- priority realtime or interrupt threads. Kernel worker threads and time- sharing 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 ex- ample: maybe_yield() is called by the vlnru process each time it reclaims a vnode. 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 sur- prising effect of this is that, depending on the disposition of other threads on the CPU's runqueue, a call to kern_yield() does not guarantee that the yielding thread will be taken off the CPU. With the above considerations in mind, it is advised that code written us- ing kern_yield() be measured to confirm that its use has a positive effect on relevant performance or responsiveness metrics. Switching thread con- texts has a non-zero cost, and thus yielding the processor too eagerly could have a negative impact on performance. Additionally, since yielding is a cooperative action, it is advised that the yielding thread release any locks that it may be holding, when possi- ble. 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. SEE ALSO setpriority(2), nice(3), mi_switch(9) AUTHORS This manual page was written by Mitchell Horne <mhorne@FreeBSD.org>. FreeBSD ports 15.quarterly January 30, 2023 KERN_YIELD(9)
NAME | SYNOPSIS | DESCRIPTION | USAGE NOTES | SEE ALSO | AUTHORS
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=kern_yield&sektion=9&manpath=FreeBSD+15.1-RELEASE+and+Ports.quarterly>