Sys::CpuAffinity(3pm) User Contributed Perl DocumentationSys::CpuAffinity(3pm)
NAME
Sys::CpuAffinity - Set CPU affinity for processes
VERSION
Version 1.13_03
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
The details of getting and setting process CPU affinities varies
greatly from system to system. Even among the different flavors of Unix
there is very little in the way of a common interface to CPU
affinities. The existing tools and libraries for setting CPU affinities
are not very standardized, so that a technique for setting CPU
affinities on one system may not work on another system with the same
architecture.
This module seeks 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.
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.
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]
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).
If $ENV{DEBUG} is set to a true value, this module will produce some
output that may or may not be good for debugging.
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.
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.
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]);
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.
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.
"$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.
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.
"$ncpu = Sys::CpuAffinity::getNumCpus()"
Returns the module's best guess about the number of processors on
this system.
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.
For some systems (darwin, OpenBSD) there are no currently known ways to
affect process CPU affinity.
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.
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.
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.
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/>
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.
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.
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.
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.
perl v5.36.0 2022-10-19 Sys::CpuAffinity(3pm)
Generated by dwww version 1.15 on Wed Jun 26 04:50:15 CEST 2024.