Open MPI logo

Portable Hardware Locality (hwloc) Documentation: v1.1

  |   Home   |   Support   |   FAQ   |  

CPU binding

Enumerations

enum  hwloc_cpubind_flags_t { HWLOC_CPUBIND_PROCESS, HWLOC_CPUBIND_THREAD, HWLOC_CPUBIND_STRICT, HWLOC_CPUBIND_NOMEMBIND }
 

Process/Thread binding flags.

More...

Functions

int hwloc_set_cpubind (hwloc_topology_t topology, hwloc_const_cpuset_t set, int flags)
 Bind current process or thread on cpus given in bitmap set.
int hwloc_get_cpubind (hwloc_topology_t topology, hwloc_cpuset_t set, int flags)
 Get current process or thread binding.
int hwloc_set_proc_cpubind (hwloc_topology_t topology, hwloc_pid_t pid, hwloc_const_cpuset_t set, int flags)
 Bind a process pid on cpus given in bitmap set.
int hwloc_get_proc_cpubind (hwloc_topology_t topology, hwloc_pid_t pid, hwloc_cpuset_t set, int flags)
 Get the current binding of process pid.

Detailed Description

It is often useful to call hwloc_bitmap_singlify() first so that a single CPU remains in the set. This way, the process will not even migrate between different CPUs. Some OSes also only support that kind of binding.

Note:
Some OSes do not provide all ways to bind processes, threads, etc and the corresponding binding functions may fail. -1 is returned and errno is set to ENOSYS when it is not possible to bind the requested kind of object processes/threads. errno is set to EXDEV when the requested cpuset can not be enforced (e.g. some systems only allow one CPU, and some other systems only allow one NUMA node).

The most portable version that should be preferred over the others, whenever possible, is

 hwloc_set_cpubind(topology, set, 0),

as it just binds the current program, assuming it is monothread, or

which binds the current thread of the current program (which may be multithreaded).

Note:
To unbind, just call the binding function with either a full cpuset or a cpuset equal to the system cpuset.
On some OSes, CPU binding may have effects on memory binding, see HWLOC_CPUBIND_NOMEMBIND

Enumeration Type Documentation

Process/Thread binding flags.

These flags can be used to refine the binding policy.

The default (0) is to bind the current process, assumed to be mono-thread, in a non-strict way. This is the most portable way to bind as all OSes usually provide it.

Note:
Not all systems support all kinds of binding.
Enumerator:
HWLOC_CPUBIND_PROCESS 

Bind all threads of the current (possibly) multithreaded process.

HWLOC_CPUBIND_THREAD 

Bind current thread of current process.

HWLOC_CPUBIND_STRICT 

Request for strict binding from the OS.

By default, when the designated CPUs are all busy while other CPUs are idle, OSes may execute the thread/process on those other CPUs instead of the designated CPUs, to let them progress anyway. Strict binding means that the thread/process will _never_ execute on other cpus than the designated CPUs, even when those are busy with other tasks and other CPUs are idle.

Note:
Depending on OSes and implementations, strict binding may not be possible (implementation reason) or not allowed (administrative reasons), and the function will fail in that case.

When retrieving the binding of a process, this flag checks whether all its threads actually have the same binding. If the flag is not given, the binding of each thread will be accumulated.

Note:
This flag is meaningless when retrieving the binding of a thread.
HWLOC_CPUBIND_NOMEMBIND 

Avoid any effect on memory binding.

On some OSes, some CPU binding function would also bind the memory on the corresponding NUMA node. It is often not a problem for the application, but if it is, setting this flag will make hwloc avoid using OS functions that would also bind memory. This will however reduce the support of CPU bindings, i.e. potentially return -1 with errno set to ENOSYS in some cases.


Function Documentation

int hwloc_get_cpubind ( hwloc_topology_t  topology,
hwloc_cpuset_t  set,
int  flags 
)

Get current process or thread binding.

int hwloc_get_proc_cpubind ( hwloc_topology_t  topology,
hwloc_pid_t  pid,
hwloc_cpuset_t  set,
int  flags 
)

Get the current binding of process pid.

Note:
hwloc_pid_t is pid_t on unix platforms, and HANDLE on native Windows platforms
HWLOC_CPUBIND_THREAD can not be used in flags.
int hwloc_set_cpubind ( hwloc_topology_t  topology,
hwloc_const_cpuset_t  set,
int  flags 
)

Bind current process or thread on cpus given in bitmap set.

Returns:
-1 with errno set to ENOSYS if the action is not supported
-1 with errno set to EXDEV if the binding cannot be enforced
int hwloc_set_proc_cpubind ( hwloc_topology_t  topology,
hwloc_pid_t  pid,
hwloc_const_cpuset_t  set,
int  flags 
)

Bind a process pid on cpus given in bitmap set.

Note:
hwloc_pid_t is pid_t on unix platforms, and HANDLE on native Windows platforms
HWLOC_CPUBIND_THREAD can not be used in flags.