CPUSET(2)

📦 version 12.2, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking

✨ cpuset, cpuset_getid, cpuset_setid — manage CPU affinity sets ✨

okay so bestie, welcome to CPUSET(2), straight out of the System Calls Manual (that's section 2, the syscall girlies 💅). this is the page where we learn how to tell your processes and threads exactly which CPUs and memory domains they're allowed to vibe on. it's giving scheduler sleepover party, and you're the one handing out the invites 🎀

💖 LIBRARY 💖

Standard C Library (libc, -lc) — yeah, she's already linked in, no extra work required 🫶

🌸 SYNOPSIS 🌸

#include <sys/param.h>
#include <sys/cpuset.h>

int
cpuset(cpusetid_t *setid);

int
cpuset_setid(cpuwhich_t which, id_t id, cpusetid_t setid);

int
cpuset_getid(cpulevel_t level, cpuwhich_t which, id_t id,
    cpusetid_t *setid);

🦋 DESCRIPTION 🦋

so the cpuset family of system calls lets your app control sets of processors and memory domains and then assign processes and threads to those sets. think of it like making little friend groups, but the friend groups are CPUs 😭

a processor set contains lists of CPUs and domains that its members are allowed to run on, and it exists only as long as some process is a member of the set. no members? she's gone, ghosted, poof 💀

every single process in the system has an assigned set. the default set for all processes in the system is the set numbered 1. threads belong to the same set as the process that contains them — however (and this is the fun part), they can further restrict their set with the anonymous per-thread mask to bind to a specific CPU or a subset of CPUs and memory domains. narrowing down your circle, iconic behavior ✨

sets are referenced by a number of type cpuset_id_t. every thread has three things:

  • a root set
  • an assigned set
  • an anonymous mask

only the root and assigned sets are numbered. the root set is the set of all CPUs and memory domains available in the system, or in the system partition the thread is running in. the assigned set is a subset of the root set and is administratively assignable on a per-process basis. many processes and threads may be members of one numbered set — it's a group chat, not a DM 💬

the anonymous set is a further thread-specific refinement on top of the assigned set. the intended division of labor is:

to select the correct set you pass a value of type cpulevel_t. the following values for level are supported:

  • CPU_LEVEL_ROOT — root set
  • CPU_LEVEL_CPUSET — assigned set
  • CPU_LEVEL_WHICH — the set specified by the which argument

the which argument determines how the value of id gets interpreted, and it's of type cpuwhich_t. which may have the following values:

  • CPU_WHICH_TID — id is lwpid_t (thread id)
  • CPU_WHICH_PID — id is pid_t (process id)
  • CPU_WHICH_JAIL — id is jid (jail id)
  • CPU_WHICH_CPUSET — id is a cpusetid_t (cpuset id)
  • CPU_WHICH_IRQ — id is an irq number
  • CPU_WHICH_INTRHANDLER — id is an irq number for an interrupt handler
  • CPU_WHICH_ITHREAD — id is an irq number for an ithread
  • CPU_WHICH_DOMAIN — id is a NUMA domain

an id of '-1' may be used with a which of CPU_WHICH_TID, CPU_WHICH_PID, or CPU_WHICH_CPUSET to mean the current thread, process, or current thread's cpuset. all cpuset syscalls allow this usage. so convenient, we love a shortcut 🫶

a level argument of CPU_LEVEL_WHICH combined with a which argument other than CPU_WHICH_CPUSET refers to the anonymous mask of the object. this mask does not have an id and may only be manipulated with cpuset_setaffinity(2).

💫 the three calls, one by one 💫

cpuset() — creates a new set containing the same CPUs as the root set of the current process, and stores its id in the space provided by setid. on successful completion the calling process joins the set and is the only member. children inherit this set after a call to fork(2). it's giving "new group chat, just me and my CPUs" 😌

cpuset_setid() — attempts to set the id of the object specified by the which argument. currently CPU_WHICH_PID is the only acceptable value for which, because threads don't have an id distinct from their process and the API does not permit changing the id of an existing set. upon successful completion, all of the threads in the target process will be running on CPUs permitted by the set.

cpuset_getid() — retrieves a set id from the object indicated by which and stores it in the space pointed to by setid. the retrieved id may be that of either the root or the assigned set depending on the value of level. level should be CPU_LEVEL_CPUSET or CPU_LEVEL_ROOT to get the set id from the process or thread specified by the id argument. specifying CPU_LEVEL_WHICH with a process or thread is unsupported, since this references the unnumbered anonymous mask. no id, no entry bestie 🙈

the actual contents of the sets may be retrieved or manipulated using cpuset_getaffinity(2), cpuset_setaffinity(2), cpuset_getdomain(2), and cpuset_setdomain(2). go read those manual pages for more detail, they're the real main characters of this saga 📖✨

⭐ RETURN VALUES ⭐

upon successful completion, the value 0 is returned. otherwise, the value -1 is returned and the global variable errno is set to indicate the error. classic. slay when it works, scream when it doesn't 💀

💅 ERRORS 💅

the following error codes may be set in errno:

  • [EINVAL] — the which or level argument was not a valid value.
  • [EDEADLK] — the cpuset_setid() call would leave a thread without a valid CPU to run on because the set does not overlap with the thread's anonymous mask.
  • [EFAULT] — the setid pointer passed to cpuset_getid() or cpuset() was invalid.
  • [ESRCH] — the object specified by the id and which arguments could not be found.
  • [EPERM] — the calling process did not have the credentials required to complete the operation.
  • [ENFILE] — there was no free cpusetid_t for allocation.
ok real talk, that [EDEADLK] one? that's the "you just locked your thread out of every CPU it could run on" error. dramatic, but deserved. don't do that 💀

🌈 SEE ALSO 🌈

🕰️ HISTORY 🕰️

the cpuset family of system calls first appeared in FreeBSD 7.1. a legend was born ✨

👑 AUTHORS 👑

Jeffrey Roberson <jeff@FreeBSD.org> — thank you for your service, king 🫡💖

and that's the whole page, bestie!! this cutie comes to you from Debian, dated May 3, 2017 — go forth and pin your threads to exactly the right CPU, you've got this 💅🦋🎀💜

📦 where this page comes from