Sys::CpuAffinity(3pm)

✨ NAME ✨

Sys::CpuAffinity — Set CPU affinity for processes 💅

okay so quick vibe check: this is the Perl module Sys::CpuAffinity, and its whole entire personality is telling your processes which CPUs they're allowed to hang out on. slay.

🎀 VERSION 🎀

Version 1.13_03 — yes bestie, that's a dev release number, underscore and all, we don't make the rules 🫶

🌸 SYNOPSIS 🌸

use Sys::CpuAffinity;

$num_cpus = Sys::CpuAffinity::getNumCpus();

$mask = 1 | 4 | 8 | 16;   # prefer CPU's # 0, 2, 3, 4
$success = Sys::CpuAffinity::setAffinity($pid,$mask);
$success = Sys::CpuAffinity::setAffinity($pid, \@preferred_cpus);

$mask = Sys::CpuAffinity::getAffinity($pid);
@cpus = Sys::CpuAffinity::getAffinity($pid);

💖 DESCRIPTION 💖

so like. the way that CPU affinity works is wildly different from system to system 😭. even between different flavors of Unix there's basically no common interface for it. the tools and libraries that exist for setting CPU affinities are not standardized at all, which means a technique that works on one system might just fully not work on another system with the same architecture. it's giving chaos.

This module is here to do one thing and do it well: manipulate CPU affinities through a common interface on as many systems as possible, by any means necessary. periodt.

The module is composed of several subroutines, each one implementing a different technique to perform a CPU affinity operation. A technique might try to import a Perl module, run an external program that might be installed on your system, or invoke some C code to access your system libraries. Usually, a technique is applicable to only a single or small group of operating systems, and on any particular system, most of the techniques would fail. Regardless of your particular system and configuration, it is hoped that at least one of the techniques will work and you will be able to get and set the CPU affinities of your processes. it's like a little fleet of techniques and one of them is gonna come through for you 💪

🦋 DEPENDENCIES 🦋

No modules are required by Sys::CpuAffinity, but there are techniques for manipulating CPU affinities in other existing modules, and Sys::CpuAffinity will use these modules if they are available:

Win32::API, Win32::Process   [MSWin32, cygwin]
BSD::Process::Affinity       [FreeBSD]

ngl "zero required deps but optional ones if you got 'em" is such an iconic design choice 👑

🌈 CONFIGURATION AND ENVIRONMENT 🌈

It is important that your "PATH" variable is set correctly so that this module can find any external programs on your system that can help it to manipulate CPU affinities (for example, "taskset" on Linux, "cpuset" on FreeBSD). bestie please set your PATH, don't do this to the module 🙈

If $ENV{DEBUG} is set to a true value, this module will produce some output that may or may not be good for debugging. no promises on the quality of that output, it's a vibe not a guarantee 💀

⭐ SUPPORTED SYSTEMS ⭐

The techniques for manipulating CPU affinities for Windows (including Cygwin) and Linux have been refined and tested pretty well. Some techniques applicable to BSD systems (particularly FreeBSD) and Solaris have been tested a little bit. The hope is that this module will include more techniques for more systems in future releases. See the "NOTE TO DEVELOPERS" below for information about how you can help. (yes that's a real section, scroll down, it's your moment 👀)

MacOS, OpenBSD are explicitly not supported, as there does not appear to be any public interface for specifying the CPU affinity of a process directly on those platforms. not "we forgot", genuinely no public interface exists. nothing to hook into. RIP 🪦

On NetBSD, getting and setting CPU affinity is supported only for the calling process, and, AFAICT, only when run as the super-user. Which is to say, you can do this:

use Sys::CpuAffinity;
# run this process on CPUs 0, 1, 3
Sys::CpuAffinity::setAffinity($$, [0, 1, 3]);

but not this:

use Sys::CpuAffinity;
$pid = `ps | grep emacs` + 0;
# run another process on CPUs 0, 1, 3
Sys::CpuAffinity::setAffinity($pid, [0, 1, 3]);

so like. you yourself? yes. your emacs? absolutely not. NetBSD said know your limits ✋

💜 SUBROUTINES/METHODS 💜

"$bitmask = Sys::CpuAffinity::getAffinity($pid)"

"@preferred_cpus = Sys::CpuAffinity::getAffinity($pid)"

Retrieves the current CPU affinity for the process with the specified process ID. In scalar context, returns a bit-mask of the CPUs that the process has affinity for, with the least significant bit denoting CPU #0. The return value is actually a Math::BigInt value, so it can store a bit mask on systems with an arbitrarily high number of CPUs. big cpu count? handled, no cap.

In list context, returns a list of integers indicating the indices of the CPU that the process has affinity for.

So for example, if a process in an 8 core machine had affinity for cores # 2, 6, and 7, then in scalar context, getAffinity() would return

    (1 << 2) | (1 << 6) | (1 << 7) ==> 196

and in list context, it would return

    (2, 6, 7)

A return value of 0 or "undef" indicates an error such as an invalid process ID. so if you get 0 back, that's not "your process has zero CPU love", that's an error, ok? two very different things 🫠

"$success = Sys::CpuAffinity::setAffinity($pid, $bitmask)"

"$success = Sys::CpuAffinity::setAffinity($pid, \@preferred_cpus)"

Sets the CPU affinity of a process to the specified processors. First argument is the process ID. The second argument is either a bitmask of the desired processors to assign to the PID, or an array reference with the index values of processors to assign to the PID.

    # two ways to assign to CPU #'s 1 and 4:
    Sys::CpuAffinity::setAffinity($pid, 0x12); # 0x12 = (1<<1) | (1<<4)
    Sys::CpuAffinity::setAffinity($pid, [1,4]);

As a special case, using a $bitmask value of -1 will clear the CPU affinities of a process — setting the affinity to all available processors. -1 is the "actually, let them roam free" button 🌈

On some platforms, notably AIX and Irix, it is only possible to bind a process to a single CPU. If the processor mask argument to "setAffinity" specifies more than one processor (but less than the total number of processors in your system), then this function might only bind the process to one of the specified processors.

so you asked for a group and it might just pick one member of that group. it's giving "you get a CPU, not the CPUs" 😭

"$ncpu = Sys::CpuAffinity::getNumCpus()"

Returns the module's best guess about the number of processors on this system. best guess!! it's doing its best and honestly that's enough 💖

💀 BUGS AND LIMITATIONS 💀

This module may not work or produce undefined results on systems with more than 32 CPUs, though support for these larger systems has improved with v1.07. undefined results!! respect the 32-CPU line, or at least know you're living dangerously.

For some systems (darwin, OpenBSD) there are no currently known ways to affect process CPU affinity. none. zero. the technique shelf is empty 🕳️

On some systems (aix, irix, Solaris < 11.2), it may only be possible to bind a process to either a single processor or to all processors, and not to an arbitrary subset of processors. so it's "one" or "everyone", no in-between, very all-or-nothing of them.

On NetBSD, it is believed that it is only possible to get/set the CPU affinity on the calling process, and only by the root user.

On Windows, updating CPU affinity of a thread can generally only be done on threads within the calling process, but not with an arbitrary Win32 thread.

Please report any bugs or feature requests to "bug-sys-cpuaffinity at rt.cpan.org", or through the web interface at <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Sys-CpuAffinity>. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes. so you literally get updates back, that's a whole relationship 🫶

🙈 INCOMPATIBILITIES 🙈

None known, but they are likely to arise as this module makes a lot of assumptions about how to provide input and interpret output for many different system utilities on many different platforms. Please report a bug if you suspect this module of misusing any system utilities. "none known but probably incoming" is such a mood honestly — if you catch it being rude to a system utility, say something 💅

🌸 SUPPORT 🌸

You can find documentation for this module with the perldoc command.

    perldoc Sys::CpuAffinity

You can also look for information at:

• RT: CPAN's request tracker

<http://rt.cpan.org/NoAuth/Bugs.html?Dist=Sys-CpuAffinity>

• AnnoCPAN: Annotated CPAN documentation

<http://annocpan.org/dist/Sys-CpuAffinity>

• CPAN Ratings

<http://cpanratings.perl.org/d/Sys-CpuAffinity>

• Search CPAN

<http://search.cpan.org/dist/Sys-CpuAffinity/>

four whole links, pick your fave, they're all valid 🎀

👑 NOTE TO DEVELOPERS 👑

This module seeks to work for as many systems in as many configurations as possible. If you know of a tool, a function, a technique to set CPU affinities on a system — any system, — then let's include it in this module. ANY SYSTEM. if you know a way, that knowledge belongs in here, bestie 🧚

Feel free to submit code through this module's request tracker:

<http://rt.cpan.org/NoAuth/Bugs.html?Dist=Sys-CpuAffinity>

or directly to me at "<mob at cpan.org>" and it will be included in the next release. yes, directly. sliding into the author's inbox with a patch is fully welcome here 💌

🍓 ACKNOWLEDGEMENTS 🍓

• BSD::Process::Affinity for demonstrating how to get/set affinities on BSD systems.
• Test::Smoke::SysInfo has some fairly portable code for detecting the number of processors.
• <http://devio.us/> provided a free OpenBSD account that allowed this module to be tested on that platform.

shoutout to the people who lent code and to devio.us for lending a whole OpenBSD box, that's community right there 💖

💅 AUTHOR 💅

Marty O'Brien, "<mob at cpan.org>"

🎀 LICENSE AND COPYRIGHT 🎀

Copyright (c) 2010-2020 Marty O'Brien.

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.

---

aaaand that's the whole thing! ✨ this page lives in the Sys::CpuAffinity(3pm) man page, shipped with perl v5.42.3, dated 2026-08-19. go forth and pin your processes to CPUs, bestie, you got this 🦋💖