yield(9)

📦 version 7.3.1, in nixpkgs unstable

💅 yield(9) — the "don't do it bestie" page of the Kernel API Manual

Okay so before we even start, the vibe check on this one is immaculate chaos. This page is a whole read. The manual name is yield, it lives in section 9, and the entire energy is "I am telling you this exists purely so you never touch it." Buckle up 🎀

✨ NAME ✨

yield — yield the current processor to other threads.

(Yes that's what it says it does. No, that's not what you think it does. Keep reading, bestie 🫶)

🌸 SYNOPSIS 🌸

void yield (void );

That's it. That's the whole signature. Not a single argument. A perfectly innocent-looking little function that the kernel devs have personally come for 😭

🦋 ARGUMENTS 🦋

  • void — no arguments. Zero. None. Nothing to pass, nothing to configure, nothing to blame. It takes nothing and it still manages to be the wrong call. Iconic behaviour, honestly 💀

🔥 DESCRIPTION 🔥

Do not ever use this function, there's a 99% chance you're doing it wrong.

Not me opening the manpage and getting read in the very first paragraph 😭 The original text is crystal clear: do not ever use this function, and there's a 99% chance you're doing it wrong. That's not a gentle suggestion, that's a prophecy.

The scheduler is at all times free to pick the calling task as the most eligible task to run. Read that again. At all times free. So if removing the yield call from your code breaks it, it's already broken — the yield was never holding it together, it was just hiding the crack like a scrunchie over a bad hair day 💅

Typical broken usage is:

while (!event) yield;

where one assumes that yield will let 'the other' process run that will make event true. And here's the plot twist, bestie: if the current task is a SCHED_FIFO task, that will never happen. Never. Not "eventually", not "if you're patient", not "on a full moon" — never.

Never use yield as a progress guarantee!! 🚨

So what should you do? The page is generous enough to hand you the receipts:

  • If you want to use yield to wait for something, use wait_event.
  • If you want to use yield to be 'nice' for others, use cond_resched.
  • If you still want to use yield — do not! 🫠

That's the whole arc. Setup, warning, betrayal, redemption arc via wait_event, and then one last "do not!" because they knew some of y'all would still try it. They were right. 😭

👑 SEE ALSO 👑

Kernel file ./kernel/sched/syscalls.c, plus the whole friend group:

Go read those instead, bestie. They're literally right there. 🧚

✨ sign-off time ✨

This masterpiece of "please don't" ships out of ./kernel/sched, dated October 2026, page yield(9). Read it. Cherish it. Then go use wait_event like the responsible main character you are 💜🦋🌸

📦 where this page comes from