kthread_crea...orker_on_cpu(9)

📦 version 7.3.1, in nixpkgs unstable

💖 kthread_create_worker_on_cpu(9) 💖

okay so this is a page out of the Kernel API Manual, and it's literally about spawning a kthread worker and pinning it to a specific CPU bestie. we're talking one CPU, one NUMA node, main character energy only. ✨

✨ NAME ✨

kthread_create_worker_on_cpu — create a kthread worker and bind it to a given CPU and the associated NUMA node. that's the whole vibe. 🎀

🌸 SYNOPSIS 🌸

struct kthread_worker * kthread_create_worker_on_cpu (int cpu , unsigned int flags , const char namefmt[] );

🦋 ARGUMENTS 🦋

  • cpu — the CPU number. just a number. the CPU number. 💅
  • flags — flags that modify the default behavior of the worker, like little tweaks to the whole deal.
  • namefmt — a printf-style name for the thread. and listen, the format is restricted to "name.*u" — that's not a suggestion, that's the rule. the code fills in the cpu number for you. 🔥

👑 DESCRIPTION 👑

use a valid CPU number if you want to bind the kthread worker to the given CPU and the associated NUMA node. that's the deal, that's the assignment. 🫶

good practice? yes bestie, add the cpu number into the worker name too. for example, use:

kthread_create_worker_on_cpu(cpu, "helper/d", cpu)

iconic. self-documenting. ate. 💅

⭐ CPU hotplug ⭐

the kthread worker API is simple and generic — it just gives you a way to create, use, and destroy workers. that's it. that's the whole API. no cap.

how you handle CPU hotplug is on you. the API user decides everything: how to handle pending work items, how to prevent queuing new ones, and how to restore the functionality when the CPU goes off and comes back on. 😭

there are a few catches, and ngl they're real:

  • CPU affinity gets lost when it is scheduled on an offline CPU. 💀
  • the worker might not exist when the CPU was off at the time the user created the workers. 🙈

good practice is to implement two CPU hotplug callbacks and to destroy/create the worker when the CPU goes down/up. two callbacks. down and up. that's the move. ✨

🌈 RETURN 🌈

  • the pointer to the allocated worker on success 🎉
  • ERR_PTR(-ENOMEM) when the needed structures could not get allocated 😭
  • ERR_PTR(-EINTR) when the caller was killed by a fatal signal 💀

🧚 SEE ALSO 🧚

kernel file ./kernel/kthread.c, and literally the whole kthread extended universe:

and that's the page bestie!! 🫶

this one came straight out of ./kernel, dated October 2026, and honestly? she's serving kernel-internals realness. periodt. 💜🎀

📦 where this page comes from