OpenMPI 0.1.1

- Main Page
- Related Pages
- Modules
- Data Structures
- Files

Enumerations | Functions
CPU binding

It is often useful to call hwloc_bitmap_singlify() first so that a single CPU remains in the set. More...

## Enumerations
enum | hwloc_cpubind_flags_t { HWLOC_CPUBIND_PROCESS, HWLOC_CPUBIND_THREAD, HWLOC_CPUBIND_STRICT, HWLOC_CPUBIND_NOMEMBIND }
| Process/Thread binding flags. More...

## Functions
HWLOC_DECLSPEC int | hwloc_set_cpubind (hwloc_topology_t topology, hwloc_const_cpuset_t set, int flags)
| Bind current process or thread on cpus given in physical bitmap `set`. More...
HWLOC_DECLSPEC int | hwloc_get_cpubind (hwloc_topology_t topology, hwloc_cpuset_t set, int flags)
| Get current process or thread binding. More...
HWLOC_DECLSPEC 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 physical bitmap `set`. More...
HWLOC_DECLSPEC int | hwloc_get_proc_cpubind (hwloc_topology_t topology, hwloc_pid_t pid, hwloc_cpuset_t set, int flags)
| Get the current physical binding of process `pid`. More...
HWLOC_DECLSPEC int | hwloc_get_last_cpu_location (hwloc_topology_t topology, hwloc_cpuset_t set, int flags)
| Get the last physical CPU where the current process or thread ran. More...
HWLOC_DECLSPEC int | hwloc_get_proc_last_cpu_location (hwloc_topology_t topology, hwloc_pid_t pid, hwloc_cpuset_t set, int flags)
| Get the last physical CPU where a process ran. More...

## 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 operating systems also only support that kind of binding.

Note
  Some operating systems do not provide all hwloc-supported mechanisms 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 single-threaded, or

hwloc_set_cpubind(topology, set, HWLOC_CPUBIND_THREAD),

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 operating systems, CPU binding may have effects on memory binding, see HWLOC_CPUBIND_NOMEMBIND

Running lstopo –top can be a very convenient tool to check how binding actually happened.

## Enumeration Type Documentation

enum hwloc_cpubind_flags_t

Process/Thread binding flags.

These bit flags can be used to refine the binding policy.

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

Note
  Not all systems support all kinds of binding. See the "Detailed Description" section of CPU binding for a description of errors that can occur.

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, operating systems 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 the operating system, strict binding may not be possible (e.g., the OS does not implement it) or not allowed (e.g., for an 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 operating systems, 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. This flag is only meaningful when used with functions that set the CPU binding. It is ignored when used with functions that get CPU binding information.

## Function Documentation

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

Get current process or thread binding.

Writes into `set` the physical cpuset which the process or thread (according to flags) was last bound to.

References HWLOC_CPUBIND_PROCESS, and HWLOC_CPUBIND_THREAD.

Referenced by ompi_mpi_init().

HWLOC_DECLSPEC int hwloc_get_last_cpu_location | ( | hwloc_topology_t | topology,
|  | hwloc_cpuset_t | set,
|  | int | flags
| ) |  |

Get the last physical CPU where the current process or thread ran.

The operating system may move some tasks from one processor to another at any time according to their binding, so this function may return something that is already outdated.

References HWLOC_CPUBIND_PROCESS, and HWLOC_CPUBIND_THREAD.

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

Get the current physical 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`.
  As a special case on Linux, if a tid (thread ID) is supplied instead of a pid (process ID), the binding for that specific thread is returned.

HWLOC_DECLSPEC int hwloc_get_proc_last_cpu_location | ( | hwloc_topology_t | topology,
|  | hwloc_pid_t | pid,
|  | hwloc_cpuset_t | set,
|  | int | flags
| ) |  |

Get the last physical CPU where a process ran.

The operating system may move some tasks from one processor to another at any time according to their binding, so this function may return something that is already outdated.

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`.
  As a special case on Linux, if a tid (thread ID) is supplied instead of a pid (process ID), the binding for that specific thread is returned.

HWLOC_DECLSPEC int hwloc_set_cpubind | ( | hwloc_topology_t | topology,
|  | hwloc_const_cpuset_t | set,
|  | int | flags
| ) |  |

Bind current process or thread on cpus given in physical 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

References HWLOC_CPUBIND_PROCESS, and HWLOC_CPUBIND_THREAD.

Referenced by ompi_mpi_init().

HWLOC_DECLSPEC 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 physical 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`.