hwlocality_cpubinding(3) Hardware Locality (hwloc) hwlocality_cpubinding(3)
NAME
hwlocality_cpubinding - CPU binding
SYNOPSIS
Enumerations
enum hwloc_cpubind_flags_t { HWLOC_CPUBIND_PROCESS,
HWLOC_CPUBIND_THREAD, HWLOC_CPUBIND_STRICT, HWLOC_CPUBIND_NOMEMBIND
}
Functions
int hwloc_set_cpubind (hwloc_topology_t topology, hwloc_const_cpuset_t
set, int flags)
int hwloc_get_cpubind (hwloc_topology_t topology, hwloc_cpuset_t set,
int flags)
int hwloc_set_proc_cpubind (hwloc_topology_t topology, hwloc_pid_t pid,
hwloc_const_cpuset_t set, int flags)
int hwloc_get_proc_cpubind (hwloc_topology_t topology, hwloc_pid_t pid,
hwloc_cpuset_t set, int flags)
int hwloc_set_thread_cpubind (hwloc_topology_t topology, hwloc_thread_t
thread, hwloc_const_cpuset_t set, int flags)
int hwloc_get_thread_cpubind (hwloc_topology_t topology, hwloc_thread_t
thread, hwloc_cpuset_t set, int flags)
int hwloc_get_last_cpu_location (hwloc_topology_t topology,
hwloc_cpuset_t set, int flags)
int hwloc_get_proc_last_cpu_location (hwloc_topology_t topology,
hwloc_pid_t pid, hwloc_cpuset_t set, int flags)
Detailed Description
Some operating systems only support binding threads or processes to a
single PU. Others allow binding to larger sets such as entire Cores or
Packages or even random sets of invididual PUs. In such operating
system, the scheduler is free to run the task on one of these PU, then
migrate it to another PU, etc. It is often useful to call
hwloc_bitmap_singlify() on the target CPU set before passing it to the
binding function to avoid these expensive migrations. See the
documentation of hwloc_bitmap_singlify() for details.
Some operating systems do not provide all hwloc-supported mechanisms to
bind processes, threads, etc. hwloc_topology_get_support() may be used
to query about the actual CPU binding support in the currently used
operating system.
When the requested binding operation is not available and the
HWLOC_CPUBIND_STRICT flag was passed, the function returns -1. 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).
If HWLOC_CPUBIND_STRICT was not passed, the function may fail as well,
or the operating system may use a slightly different operation (with
side-effects, smaller binding set, etc.) when the requested operation
is not exactly supported.
The most portable version that should be preferred over the others,
whenever possible, is the following one which just binds the current
program, assuming it is single-threaded:
hwloc_set_cpubind(topology, set, 0),
If the program may be multithreaded, the following one should be
preferred to only bind the current thread:
hwloc_set_cpubind(topology, set, HWLOC_CPUBIND_THREAD),
See also
Some example codes are available under doc/examples/ in the source
tree.
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 or hwloc-ps 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
int hwloc_get_cpubind (hwloc_topology_t topology, hwloc_cpuset_t set, int
flags)
Get current process or thread binding. The CPU-set set (previously
allocated by the caller) is filled with the list of PUs which the
process or thread (according to flags) was last bound to.
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
CPU-set set (previously allocated by the caller) is filled with the
list of PUs which the process or thread (according to flags) last ran
on.
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.
flags can include either HWLOC_CPUBIND_PROCESS or HWLOC_CPUBIND_THREAD
to specify whether the query should be for the whole process (union of
all CPUs on which all threads are running), or only the current thread.
If the process is single-threaded, flags can be set to zero to let
hwloc use whichever method is available on the underlying OS.
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. The CPU-set set
(previously allocated by the caller) is filled with the list of PUs
which the process was last bound to.
Note
hwloc_pid_t is pid_t on Unix platforms, and HANDLE on native
Windows platforms.
As a special case on Linux, if a tid (thread ID) is supplied
instead of a pid (process ID) and HWLOC_CPUBIND_THREAD is passed in
flags, the binding for that specific thread is returned.
On non-Linux systems, HWLOC_CPUBIND_THREAD can not be used in
flags.
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 CPU-set set
(previously allocated by the caller) is filled with the list of PUs
which the process last ran on.
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.
As a special case on Linux, if a tid (thread ID) is supplied
instead of a pid (process ID) and HWLOC_CPUBIND_THREAD is passed in
flags, the last CPU location of that specific thread is returned.
On non-Linux systems, HWLOC_CPUBIND_THREAD can not be used in
flags.
int hwloc_get_thread_cpubind (hwloc_topology_t topology, hwloc_thread_t
thread, hwloc_cpuset_t set, int flags)
Get the current physical binding of thread tid. The CPU-set set
(previously allocated by the caller) is filled with the list of PUs
which the thread was last bound to.
Note
hwloc_thread_t is pthread_t on Unix platforms, and HANDLE on native
Windows platforms.
HWLOC_CPUBIND_PROCESS 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 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
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.
As a special case on Linux, if a tid (thread ID) is supplied
instead of a pid (process ID) and HWLOC_CPUBIND_THREAD is passed in
flags, the binding is applied to that specific thread.
On non-Linux systems, HWLOC_CPUBIND_THREAD can not be used in
flags.
int hwloc_set_thread_cpubind (hwloc_topology_t topology, hwloc_thread_t
thread, hwloc_const_cpuset_t set, int flags)
Bind a thread thread on cpus given in physical bitmap set.
Note
hwloc_thread_t is pthread_t on Unix platforms, and HANDLE on native
Windows platforms.
HWLOC_CPUBIND_PROCESS can not be used in flags.
Author
Generated automatically by Doxygen for Hardware Locality (hwloc) from
the source code.
Version 2.7.0 Thu Jun 16 2022 hwlocality_cpubinding(3)
Generated by dwww version 1.14 on Fri Jan 24 06:00:52 CET 2025.