/ 
Forks-Super-0.40
River stage one • 1 direct dependent • 1 total dependent
/ Sys::CpuAffinity

NAME

Sys::CpuAffinity - Set CPU affinity for processes

VERSION

Version 0.96

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, the vast majority of 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.

RECOMMENDED MODULES

No modules are required by Sys::CpuAffinity, but there are several 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 [*bsd]

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 is explicitly not supported, as there does not appear to be any public interface for specifying the CPU affinity of a process directly.

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-vector of the CPUs that the process has affinity for, with the least significant bit denoting CPU #0.

In array 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-CPU machine had affinity for CPU's # 2, 6, and 7, then in scalar context, getAffinity() would return

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

and in array context, it would return

(2, 6, 7)

The function may return 0 or undef in case of 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 procesors 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.

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

Returns the module's best guess about the number of processors on this system.

AUTHOR

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

BUGS AND LIMITATIONS

This module may not work or produce undefined results on systems with more than 32 CPUs.

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.

SUPPORT

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

perldoc Sys::CpuAffinity

You can also look for information at:

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.

LICENSE AND COPYRIGHT

Copyright (c) 2010, Marty O'Brien.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.8 or, at your option, any later version of Perl 5 you may have available.

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