scx_bpf_pick_idle_cpu(9)

📦 version 7.3.1, in nixpkgs unstable

💅 scx_bpf_pick_idle_cpu — Kernel API Manual ✨

okay bestie, welcome to the Kernel API Manual page for scx_bpf_pick_idle_cpu(9) 🎀 this one's short and sweet but there's some real lore in the warnings, so stay with me 🫶

✨ NAME ✨

scx_bpf_pick_idle_cpu — pick and claim an idle cpu 👑 literally it goes shopping for a free CPU and takes it home, no cap

🦋 SYNOPSIS 🦋

__bpf_kfunc s32 scx_bpf_pick_idle_cpu (const struct cpumask
*cpus_allowed , u64 flags , const struct bpf_prog_aux *aux );

🌸 ARGUMENTS 🌸

  • cpus_allowed — the allowed cpumask, i.e. your little menu of CPUs it's allowed to pick from 💖
  • flags — SCX_PICK_IDLE_* flags, the vibe modifiers ✨
  • aux — this one's the implicit BPF argument giving access to bpf_prog_aux, and ngl it's hidden from BPF progs 🙈 so you don't really touch it, she's just there

💜 DESCRIPTION 💜

So the whole gig: it picks and claims an idle cpu inside cpus_allowed. On success you get the picked idle cpu number back, slay 🎉 and if no matching cpu was found you get -EBUSY 😭 that's it, that's the return contract.

⚠️ ok now the important part, do NOT skip this 💀 Idle CPU tracking may race against CPU scheduling state transitions. Like, this function may totally return -EBUSY just because CPUs are in the middle of transitioning into the idle state. And if the caller then assumes there will be dispatch events on those CPUs because they were all busy — the scheduler may end up stalling with CPUs idling while there are pending tasks 😱 so to guarantee there will be at least one dispatch event in the near future, use scx_bpf_pick_any_cpu and scx_bpf_kick_cpu 🔥 fr fr, that's the move.

More things to know, bestie:

  • It's unavailable if ops.update_idle is implemented and SCX_OPS_KEEP_BUILTIN_IDLE is not set 🚫
  • It always returns an error if SCX_OPS_BUILTIN_IDLE_PER_NODE is set — in that case use scx_bpf_pick_idle_cpu_node instead 🧚 periodt

🎀 SEE ALSO 🎀

Kernel file ./kernel/sched/ext/idle.c — and the whole friend group 💜:

🌈 that's the whole page angel, go pick some idle CPUs responsibly 💖

mwah 💋 this one comes from ./kernel/sched/ext, dated October 2026, and yeah it's the scx_bpf_pick_idle_cpu(9) page — see you in the next one bestie 🫶✨

📦 where this page comes from