Provided by: libsys-cpuaffinity-perl_1.12-1build2_amd64 bug

NAME

       Sys::CpuAffinity - Set CPU affinity for processes

VERSION

       Version 1.12

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 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.

       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 2010-2017 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.