.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Sys::CpuAffinity 3pm"
.TH Sys::CpuAffinity 3pm 2024-03-07 "perl v5.38.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
Sys::CpuAffinity \- Set CPU affinity for processes
.SH VERSION
.IX Header "VERSION"
Version 1.13_03
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 1
\&    use Sys::CpuAffinity;
\&
\&    $num_cpus = Sys::CpuAffinity::getNumCpus();
\&
\&    $mask = 1 | 4 | 8 | 16;   # prefer CPU\*(Aqs # 0, 2, 3, 4
\&    $success = Sys::CpuAffinity::setAffinity($pid,$mask);
\&    $success = Sys::CpuAffinity::setAffinity($pid, \e@preferred_cpus);
\&
\&    $mask = Sys::CpuAffinity::getAffinity($pid);
\&    @cpus = Sys::CpuAffinity::getAffinity($pid);
.Ve
.SH DESCRIPTION
.IX Header "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.
.PP
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.
.PP
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.
.SH DEPENDENCIES
.IX Header "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:
.PP
.Vb 2
\&    Win32::API, Win32::Process   [MSWin32, cygwin]
\&    BSD::Process::Affinity       [FreeBSD]
.Ve
.SH "CONFIGURATION AND ENVIRONMENT"
.IX Header "CONFIGURATION AND ENVIRONMENT"
It is important that your \f(CW\*(C`PATH\*(C'\fR 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, \f(CW\*(C`taskset\*(C'\fR on Linux,
\&\f(CW\*(C`cpuset\*(C'\fR on FreeBSD).
.PP
If \f(CW$ENV{DEBUG}\fR is set to a true value, this module will produce
some output that may or may not be good for debugging.
.SH "SUPPORTED SYSTEMS"
.IX Header "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.
.PP
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.
.PP
On NetBSD, getting and setting CPU affinity is supported \fBonly for
the calling process\fR, and, AFAICT, \fBonly when run as the super-user\fR.
Which is to say, you can do this:
.PP
.Vb 3
\&    use Sys::CpuAffinity;
\&    # run this process on CPUs 0, 1, 3
\&    Sys::CpuAffinity::setAffinity($$, [0, 1, 3]);
.Ve
.PP
but not this:
.PP
.Vb 4
\&    use Sys::CpuAffinity;
\&    $pid = \`ps | grep emacs\` + 0;
\&    # run another process on CPUs 0, 1, 3
\&    Sys::CpuAffinity::setAffinity($pid, [0, 1, 3]);
.Ve
.SH SUBROUTINES/METHODS
.IX Header "SUBROUTINES/METHODS"
.ie n .IP """$bitmask = Sys::CpuAffinity::getAffinity($pid)""" 4
.el .IP "\f(CW$bitmask = Sys::CpuAffinity::getAffinity($pid)\fR" 4
.IX Item "$bitmask = Sys::CpuAffinity::getAffinity($pid)"
.PD 0
.ie n .IP """@preferred_cpus = Sys::CpuAffinity::getAffinity($pid)""" 4
.el .IP "\f(CW@preferred_cpus = Sys::CpuAffinity::getAffinity($pid)\fR" 4
.IX Item "@preferred_cpus = Sys::CpuAffinity::getAffinity($pid)"
.PD
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.
.Sp
In list context, returns a list of integers indicating the
indices of the CPU that the process has affinity for.
.Sp
So for example, if a process in an 8 core machine
had affinity for cores # 2, 6, and 7, then
in scalar context, \f(CWgetAffinity()\fR would return
.Sp
.Vb 1
\&    (1 << 2) | (1 << 6) | (1 << 7) ==> 196
.Ve
.Sp
and in list context, it would return
.Sp
.Vb 1
\&    (2, 6, 7)
.Ve
.Sp
A return value of 0 or \f(CW\*(C`undef\*(C'\fR indicates an error
such as an invalid process ID.
.ie n .IP """$success = Sys::CpuAffinity::setAffinity($pid, $bitmask)""" 4
.el .IP "\f(CW$success = Sys::CpuAffinity::setAffinity($pid, $bitmask)\fR" 4
.IX Item "$success = Sys::CpuAffinity::setAffinity($pid, $bitmask)"
.PD 0
.ie n .IP """$success = Sys::CpuAffinity::setAffinity($pid, \e@preferred_cpus)""" 4
.el .IP "\f(CW$success = Sys::CpuAffinity::setAffinity($pid, \e@preferred_cpus)\fR" 4
.IX Item "$success = Sys::CpuAffinity::setAffinity($pid, @preferred_cpus)"
.PD
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.
.Sp
.Vb 3
\&    # two ways to assign to CPU #\*(Aqs 1 and 4:
\&    Sys::CpuAffinity::setAffinity($pid, 0x12); # 0x12 = (1<<1) | (1<<4)
\&    Sys::CpuAffinity::setAffinity($pid, [1,4]);
.Ve
.Sp
As a special case, using a \f(CW$bitmask\fR value of \f(CW\-1\fR will clear
the CPU affinities of a process \-\- setting the affinity to all
available processors.
.Sp
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
\&\f(CW\*(C`setAffinity\*(C'\fR 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.
.ie n .IP """$ncpu = Sys::CpuAffinity::getNumCpus()""" 4
.el .IP "\f(CW$ncpu = Sys::CpuAffinity::getNumCpus()\fR" 4
.IX Item "$ncpu = Sys::CpuAffinity::getNumCpus()"
Returns the module's best guess about the number of
processors on this system.
.SH "BUGS AND LIMITATIONS"
.IX Header "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.
.PP
For some systems (darwin, OpenBSD) there are no currently
known ways to affect process CPU affinity.
.PP
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.
.PP
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.
.PP
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.
.PP
Please report any bugs or feature requests to
\&\f(CW\*(C`bug\-sys\-cpuaffinity at rt.cpan.org\*(C'\fR, 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.
.SH INCOMPATIBILITIES
.IX Header "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.
.SH SUPPORT
.IX Header "SUPPORT"
You can find documentation for this module with the perldoc command.
.PP
.Vb 1
\&    perldoc Sys::CpuAffinity
.Ve
.PP
You can also look for information at:
.IP \(bu 4
RT: CPAN's request tracker
.Sp
<http://rt.cpan.org/NoAuth/Bugs.html?Dist=Sys\-CpuAffinity>
.IP \(bu 4
AnnoCPAN: Annotated CPAN documentation
.Sp
<http://annocpan.org/dist/Sys\-CpuAffinity>
.IP \(bu 4
CPAN Ratings
.Sp
<http://cpanratings.perl.org/d/Sys\-CpuAffinity>
.IP \(bu 4
Search CPAN
.Sp
<http://search.cpan.org/dist/Sys\-CpuAffinity/>
.SH "NOTE TO DEVELOPERS"
.IX Header "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.
.PP
Feel free to submit code through this module's request tracker:
.PP
<http://rt.cpan.org/NoAuth/Bugs.html?Dist=Sys\-CpuAffinity>
.PP
or directly to me at \f(CW\*(C`<mob at cpan.org>\*(C'\fR and it will
be included in the next release.
.SH ACKNOWLEDGEMENTS
.IX Header "ACKNOWLEDGEMENTS"
BSD::Process::Affinity for demonstrating
how to get/set affinities on BSD systems.
.PP
Test::Smoke::SysInfo has some fairly portable
code for detecting the number of processors.
.PP
<http://devio.us/> provided a free OpenBSD account that allowed
this module to be tested on that platform.
.SH AUTHOR
.IX Header "AUTHOR"
Marty O'Brien, \f(CW\*(C`<mob at cpan.org>\*(C'\fR
.SH "LICENSE AND COPYRIGHT"
.IX Header "LICENSE AND COPYRIGHT"
Copyright (c) 2010\-2020 Marty O'Brien.
.PP
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.
.PP
See http://dev.perl.org/licenses/ for more information.