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

       Returns
           0 on success, -1 on error.

   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.

       Returns
           0 on success, -1 on error.

   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.

       Returns
           0 on success, -1 on error.

       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.

       Returns
           0 on success, -1 on error.

       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.

       Returns
           0 on success, -1 on error.

       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
           0 on success.

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

       Returns
           0 on success, -1 on error.

       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.

       Returns
           0 on success, -1 on error.

       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.