KERN_YIELD(9)

💅 KERN_YIELD(9) — the kernel developer's manual, but make it cute

okay bestie, so this page is KERN_YIELD(9) from the Kernel Developer's Manual, and it's literally all about the three little functions that let a thread go "k, my turn's done, someone else can have the CPU now" 🫶

---

✨ NAME ✨

kern_yield, maybe_yield, should_yield — the functions for yielding execution of the current thread. that's the whole vibe. thread says "i'll share the processor", periodt 💅

---

🌸 SYNOPSIS 🌸

void
kern_yield(int prio);

void
maybe_yield();

bool
should_yield();

look at them. three little icons. no cap 🌈

---

💖 DESCRIPTION 💖

🎀 kern_yield()

okay so kern_yield() makes the currently running thread voluntarily, but unconditionally, surrender its execution to the scheduler. voluntarily and unconditionally — it's not asking, it's just handing over the aux cord 🔥

the prio argument is the scheduling priority assigned before the context switch, and it lowkey decides when execution will resume. heads up though: the requested priority takes effect until the thread returns to usermode, after which its base user priority gets restored. that's the deal 🙈

valid values for prio are any of the PRI_* values defined in <sys/priority.h>, plus these special ones:

• 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. no touchy, just yield 🦋

🧚 should_yield()

should_yield() checks if sufficient time has passed since the thread's last voluntary context switch that yielding would actually be a useful service to other threads. it returns true when that's the case ✨

and if you want the elaboration of what "useful service" means, go read USAGE NOTES below, i'm not retyping it twice 💀

🍓 maybe_yield()

maybe_yield() is the helper function for the super common task of optionally yielding the processor. internally, kern_yield(PRI_USER) gets called if should_yield() returns true. it's giving "will i? won't i?" energy and honestly? iconic 👑

---

🌟 USAGE NOTES 🌟

so here's the situation. even though the kernel supports preemption, it's usually reserved for high-priority realtime or interrupt threads. kernel worker threads and timesharing threads are not guaranteed to preempt each other. so threads executing in the kernel are expected to behave cooperatively with respect to other threads in the system 🫶

the yield functions are mostly meant for threads that do a lot of work inside the kernel. for example: maybe_yield() is called by the vlnru process each time it reclaims a vnode. see? real ones use it 😌

the scheduler is out here trying to identify threads that monopolize the CPU, and it'll schedule them with decreased priority. meanwhile, threads that regularly yield the processor get the chance to run more often. and here's the possibly-surprising part: 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. yeah. it yields and might just... stay. the audacity 💀

with all that in mind, the advice is: measure your code if you're using kern_yield(), and confirm its use has a positive effect on relevant performance or responsiveness metrics. switching thread contexts has a non-zero cost, and yielding the processor too eagerly could genuinely have a negative impact on performance. don't be that thread 🙈

additionally, since yielding is a cooperative action, it's advised that the yielding thread release any locks it may be holding, when possible. otherwise, threads that got the chance to run could end up waiting on the yielding thread to release the lock — which largely defeats the whole purpose of the yield. like babe you didn't actually free anything up 😭

---

🔍 SEE ALSO 🔍

• setpriority(2)
• nice(3)
• mi_switch(9)

go read them, iykyk 📚

---

👑 AUTHORS 👑

this manual page was written by Mitchell Horne <mhorne@FreeBSD.org>. thank you mitchell, you ate 🫡

---

and that's the whole page bestie!! this one's from the Debian crew, dated January 30, 2023 — go yield responsibly, release your locks, and measure your metrics. mwah 💜🎀🦋