manpagez: man pages & more
man hwloc_get_membind_nodeset(3)
Home | html | info | man
hwlocality_membinding(3)    Hardware Locality (hwloc)   hwlocality_membinding(3)




NAME

       hwlocality_membinding - Memory binding


SYNOPSIS

   Enumerations
       enum hwloc_membind_policy_t { HWLOC_MEMBIND_DEFAULT,
           HWLOC_MEMBIND_FIRSTTOUCH, HWLOC_MEMBIND_BIND,
           HWLOC_MEMBIND_INTERLEAVE, HWLOC_MEMBIND_NEXTTOUCH,
           HWLOC_MEMBIND_MIXED }
       enum hwloc_membind_flags_t { HWLOC_MEMBIND_PROCESS, HWLOC_MEMBIND_THREAD,
           HWLOC_MEMBIND_STRICT, HWLOC_MEMBIND_MIGRATE, HWLOC_MEMBIND_NOCPUBIND,
           HWLOC_MEMBIND_BYNODESET }

   Functions
       int hwloc_set_membind (hwloc_topology_t topology, hwloc_const_bitmap_t
           set, hwloc_membind_policy_t policy, int flags)
       int hwloc_get_membind (hwloc_topology_t topology, hwloc_bitmap_t set,
           hwloc_membind_policy_t *policy, int flags)
       int hwloc_set_proc_membind (hwloc_topology_t topology, hwloc_pid_t pid,
           hwloc_const_bitmap_t set, hwloc_membind_policy_t policy, int flags)
       int hwloc_get_proc_membind (hwloc_topology_t topology, hwloc_pid_t pid,
           hwloc_bitmap_t set, hwloc_membind_policy_t *policy, int flags)
       int hwloc_set_area_membind (hwloc_topology_t topology, const void *addr,
           size_t len, hwloc_const_bitmap_t set, hwloc_membind_policy_t policy,
           int flags)
       int hwloc_get_area_membind (hwloc_topology_t topology, const void *addr,
           size_t len, hwloc_bitmap_t set, hwloc_membind_policy_t *policy, int
           flags)
       int hwloc_get_area_memlocation (hwloc_topology_t topology, const void
           *addr, size_t len, hwloc_bitmap_t set, int flags)
       void * hwloc_alloc (hwloc_topology_t topology, size_t len)
       void * hwloc_alloc_membind (hwloc_topology_t topology, size_t len,
           hwloc_const_bitmap_t set, hwloc_membind_policy_t policy, int flags)
       static void * hwloc_alloc_membind_policy (hwloc_topology_t topology,
           size_t len, hwloc_const_bitmap_t set, hwloc_membind_policy_t policy,
           int flags)
       int hwloc_free (hwloc_topology_t topology, void *addr, size_t len)


Detailed Description

       Memory binding can be done three ways:

       o explicit memory allocation thanks to hwloc_alloc_membind() and friends:
         the binding will have effect on the memory allocated by these
         functions.

       o implicit memory binding through binding policy: hwloc_set_membind() and
         friends only define the current policy of the process, which will be
         applied to the subsequent calls to malloc() and friends.

       o migration of existing memory ranges, thanks to hwloc_set_area_membind()
         and friends, which move already-allocated data.

       Not all operating systems support all three ways.
       hwloc_topology_get_support() may be used to query about the actual memory
       binding support in the currently used operating system.

       When the requested binding operation is not available and the
       HWLOC_MEMBIND_STRICT flag was passed, the function returns -1. errno will
       be set to ENOSYS when the system does support the specified action or
       policy (e.g., some systems only allow binding memory on a per-thread
       basis, whereas other systems only allow binding memory for all threads in
       a process). errno will be set to EXDEV when the requested set can not be
       enforced (e.g., some systems only allow binding memory to a single NUMA
       node).

       If HWLOC_MEMBIND_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 form that should be preferred over the others whenever
       possible is as follows. It allocates some memory hopefully bound to the
       specified set. To do so, hwloc will possibly have to change the current
       memory binding policy in order to actually get the memory bound, if the
       OS does not provide any other way to simply allocate bound memory without
       changing the policy for all allocations. That is the difference with
       hwloc_alloc_membind(), which will never change the current memory binding
       policy.

       hwloc_alloc_membind_policy(topology, size, set,
                                  HWLOC_MEMBIND_BIND, 0);

       Each hwloc memory binding function takes a bitmap argument that is a CPU
       set by default, or a NUMA memory node set if the flag
       HWLOC_MEMBIND_BYNODESET is specified. See Object Sets (hwloc_cpuset_t and
       hwloc_nodeset_t) and The bitmap API for a discussion of CPU sets and NUMA
       memory node sets. It is also possible to convert between CPU set and node
       set using hwloc_cpuset_to_nodeset() or hwloc_cpuset_from_nodeset().

       Memory binding by CPU set cannot work for CPU-less NUMA memory nodes.
       Binding by nodeset should therefore be preferred whenever possible.

       See also
           Some example codes are available under doc/examples/ in the source
           tree.

       Note
           On some operating systems, memory binding affects the CPU binding;
           see HWLOC_MEMBIND_NOCPUBIND


Enumeration Type Documentation

   enum hwloc_membind_flags_t
       Memory binding flags. These flags can be used to refine the binding
       policy. All flags can be logically OR'ed together with the exception of
       HWLOC_MEMBIND_PROCESS and HWLOC_MEMBIND_THREAD; these two flags are
       mutually exclusive.

       Not all systems support all kinds of binding.
       hwloc_topology_get_support() may be used to query about the actual memory
       binding support in the currently used operating system. See the 'Detailed
       Description' section of Memory binding for a description of errors that
       can occur.

       Enumerator

       HWLOC_MEMBIND_PROCESS
              Set policy for all threads of the specified (possibly
              multithreaded) process. This flag is mutually exclusive with
              HWLOC_MEMBIND_THREAD.

       HWLOC_MEMBIND_THREAD
              Set policy for a specific thread of the current process. This flag
              is mutually exclusive with HWLOC_MEMBIND_PROCESS.

       HWLOC_MEMBIND_STRICT
              Request strict binding from the OS. The function will fail if the
              binding can not be guaranteed / completely enforced.

       This flag has slightly different meanings depending on which function it
       is used with.

       HWLOC_MEMBIND_MIGRATE
              Migrate existing allocated memory. If the memory cannot be
              migrated and the HWLOC_MEMBIND_STRICT flag is passed, an error
              will be returned.

       HWLOC_MEMBIND_NOCPUBIND
              Avoid any effect on CPU binding. On some operating systems, some
              underlying memory binding functions also bind the application to
              the corresponding CPU(s). Using this flag will cause hwloc to
              avoid using OS functions that could potentially affect CPU
              bindings. Note, however, that using NOCPUBIND may reduce hwloc's
              overall memory binding support. Specifically: some of hwloc's
              memory binding functions may fail with errno set to ENOSYS when
              used with NOCPUBIND.

       HWLOC_MEMBIND_BYNODESET
              Consider the bitmap argument as a nodeset. The bitmap argument is
              considered a nodeset if this flag is given, or a cpuset otherwise
              by default.

       Memory binding by CPU set cannot work for CPU-less NUMA memory nodes.
       Binding by nodeset should therefore be preferred whenever possible.

   enum hwloc_membind_policy_t
       Memory binding policy. These constants can be used to choose the binding
       policy. Only one policy can be used at a time (i.e., the values cannot be
       OR'ed together).

       Not all systems support all kinds of binding.
       hwloc_topology_get_support() may be used to query about the actual memory
       binding policy support in the currently used operating system. See the
       'Detailed Description' section of Memory binding for a description of
       errors that can occur.

       Enumerator

       HWLOC_MEMBIND_DEFAULT
              Reset the memory allocation policy to the system default.
              Depending on the operating system, this may correspond to
              HWLOC_MEMBIND_FIRSTTOUCH (Linux, FreeBSD), or HWLOC_MEMBIND_BIND
              (AIX, HP-UX, Solaris, Windows). This policy is never returned by
              get membind functions. The nodeset argument is ignored.

       HWLOC_MEMBIND_FIRSTTOUCH
              Allocate each memory page individually on the local NUMA node of
              the thread that touches it. The given nodeset should usually be
              hwloc_topology_get_topology_nodeset() so that the touching thread
              may run and allocate on any node in the system.

       On AIX, if the nodeset is smaller, pages are allocated locally (if the
       local node is in the nodeset) or from a random non-local node
       (otherwise).

       HWLOC_MEMBIND_BIND
              Allocate memory on the specified nodes.

       HWLOC_MEMBIND_INTERLEAVE
              Allocate memory on the given nodes in an interleaved / round-robin
              manner. The precise layout of the memory across multiple NUMA
              nodes is OS/system specific. Interleaving can be useful when
              threads distributed across the specified NUMA nodes will all be
              accessing the whole memory range concurrently, since the
              interleave will then balance the memory references.

       HWLOC_MEMBIND_NEXTTOUCH
              For each page bound with this policy, by next time it is touched
              (and next time only), it is moved from its current location to the
              local NUMA node of the thread where the memory reference occurred
              (if it needs to be moved at all).

       HWLOC_MEMBIND_MIXED
              Returned by get_membind() functions when multiple threads or parts
              of a memory area have differing memory binding policies. Also
              returned when binding is unknown because binding hooks are empty
              when the topology is loaded from XML without HWLOC_THISSYSTEM=1,
              etc.


Function Documentation

   void* hwloc_alloc (hwloc_topology_t topology, size_t len)
       Allocate some memory. This is equivalent to malloc(), except that it
       tries to allocate page-aligned memory from the OS.

       Note
           The allocated memory should be freed with hwloc_free().

   void* hwloc_alloc_membind (hwloc_topology_t topology, size_t len,
       hwloc_const_bitmap_t set, hwloc_membind_policy_t policy, int flags)
       Allocate some memory on NUMA memory nodes specified by set.

       Returns
           NULL with errno set to ENOSYS if the action is not supported and
           HWLOC_MEMBIND_STRICT is given

           NULL with errno set to EXDEV if the binding cannot be enforced and
           HWLOC_MEMBIND_STRICT is given

           NULL with errno set to ENOMEM if the memory allocation failed even
           before trying to bind.

       If HWLOC_MEMBIND_BYNODESET is specified, set is considered a nodeset.
       Otherwise it's a cpuset.

       Note
           The allocated memory should be freed with hwloc_free().

   static void* hwloc_alloc_membind_policy (hwloc_topology_t topology, size_t
       len, hwloc_const_bitmap_t set, hwloc_membind_policy_t policy, int flags)
       [inline],  [static]
       Allocate some memory on NUMA memory nodes specified by set. First, try to
       allocate properly with hwloc_alloc_membind(). On failure, the current
       process or thread memory binding policy is changed with
       hwloc_set_membind() before allocating memory. Thus this function works in
       more cases, at the expense of changing the current state (possibly
       affecting future allocations that would not specify any policy).

       If HWLOC_MEMBIND_BYNODESET is specified, set is considered a nodeset.
       Otherwise it's a cpuset.

   int hwloc_free (hwloc_topology_t topology, void * addr, size_t len)
       Free memory that was previously allocated by hwloc_alloc() or
       hwloc_alloc_membind().

   int hwloc_get_area_membind (hwloc_topology_t topology, const void * addr,
       size_t len, hwloc_bitmap_t set, hwloc_membind_policy_t * policy, int
       flags)
       Query the CPUs near the physical NUMA node(s) and binding policy of the
       memory identified by (addr, len ). The bitmap set (previously allocated
       by the caller) is filled with the memory area binding.

       This function has two output parameters: set and policy. The values
       returned in these parameters depend on both the flags passed in and the
       memory binding policies and nodesets of the pages in the address range.

       If HWLOC_MEMBIND_STRICT is specified, the target pages are first checked
       to see if they all have the same memory binding policy and nodeset. If
       they do not, -1 is returned and errno is set to EXDEV. If they are
       identical across all pages, the set and policy are returned in set and
       policy, respectively.

       If HWLOC_MEMBIND_STRICT is not specified, the union of all NUMA node(s)
       containing pages in the address range is calculated. If all pages in the
       target have the same policy, it is returned in policy. Otherwise, policy
       is set to HWLOC_MEMBIND_MIXED.

       If HWLOC_MEMBIND_BYNODESET is specified, set is considered a nodeset.
       Otherwise it's a cpuset.

       If any other flags are specified, -1 is returned and errno is set to
       EINVAL.

       If len is 0, -1 is returned and errno is set to EINVAL.

   int hwloc_get_area_memlocation (hwloc_topology_t topology, const void * addr,
       size_t len, hwloc_bitmap_t set, int flags)
       Get the NUMA nodes where memory identified by (addr, len ) is physically
       allocated. The bitmap set (previously allocated by the caller) is filled
       according to the NUMA nodes where the memory area pages are physically
       allocated. If no page is actually allocated yet, set may be empty.

       If pages spread to multiple nodes, it is not specified whether they
       spread equitably, or whether most of them are on a single node, etc.

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

       If HWLOC_MEMBIND_BYNODESET is specified in flags, set is considered a
       nodeset. Otherwise it's a cpuset.

       If len is 0, set is emptied.

   int hwloc_get_membind (hwloc_topology_t topology, hwloc_bitmap_t set,
       hwloc_membind_policy_t * policy, int flags)
       Query the default memory binding policy and physical locality of the
       current process or thread. The bitmap set (previously allocated by the
       caller) is filled with the process or thread memory binding.

       This function has two output parameters: set and policy. The values
       returned in these parameters depend on both the flags passed in and the
       current memory binding policies and nodesets in the queried target.

       Passing the HWLOC_MEMBIND_PROCESS flag specifies that the query target is
       the current policies and nodesets for all the threads in the current
       process. Passing HWLOC_MEMBIND_THREAD specifies that the query target is
       the current policy and nodeset for only the thread invoking this
       function.

       If neither of these flags are passed (which is the most portable method),
       the process is assumed to be single threaded. This allows hwloc to use
       either process-based OS functions or thread-based OS functions, depending
       on which are available.

       HWLOC_MEMBIND_STRICT is only meaningful when HWLOC_MEMBIND_PROCESS is
       also specified. In this case, hwloc will check the default memory
       policies and nodesets for all threads in the process. If they are not
       identical, -1 is returned and errno is set to EXDEV. If they are
       identical, the values are returned in set and policy.

       Otherwise, if HWLOC_MEMBIND_PROCESS is specified (and
       HWLOC_MEMBIND_STRICT is not specified), the default set from each thread
       is logically OR'ed together. If all threads' default policies are the
       same, policy is set to that policy. If they are different, policy is set
       to HWLOC_MEMBIND_MIXED.

       In the HWLOC_MEMBIND_THREAD case (or when neither HWLOC_MEMBIND_PROCESS
       or HWLOC_MEMBIND_THREAD is specified), there is only one set and policy;
       they are returned in set and policy, respectively.

       If HWLOC_MEMBIND_BYNODESET is specified, set is considered a nodeset.
       Otherwise it's a cpuset.

       If any other flags are specified, -1 is returned and errno is set to
       EINVAL.

   int hwloc_get_proc_membind (hwloc_topology_t topology, hwloc_pid_t pid,
       hwloc_bitmap_t set, hwloc_membind_policy_t * policy, int flags)
       Query the default memory binding policy and physical locality of the
       specified process. The bitmap set (previously allocated by the caller) is
       filled with the process memory binding.

       This function has two output parameters: set and policy. The values
       returned in these parameters depend on both the flags passed in and the
       current memory binding policies and nodesets in the queried target.

       Passing the HWLOC_MEMBIND_PROCESS flag specifies that the query target is
       the current policies and nodesets for all the threads in the specified
       process. If HWLOC_MEMBIND_PROCESS is not specified (which is the most
       portable method), the process is assumed to be single threaded. This
       allows hwloc to use either process-based OS functions or thread-based OS
       functions, depending on which are available.

       Note that it does not make sense to pass HWLOC_MEMBIND_THREAD to this
       function.

       If HWLOC_MEMBIND_STRICT is specified, hwloc will check the default memory
       policies and nodesets for all threads in the specified process. If they
       are not identical, -1 is returned and errno is set to EXDEV. If they are
       identical, the values are returned in set and policy.

       Otherwise, set is set to the logical OR of all threads' default set. If
       all threads' default policies are the same, policy is set to that policy.
       If they are different, policy is set to HWLOC_MEMBIND_MIXED.

       If HWLOC_MEMBIND_BYNODESET is specified, set is considered a nodeset.
       Otherwise it's a cpuset.

       If any other flags are specified, -1 is returned and errno is set to
       EINVAL.

       Note
           hwloc_pid_t is pid_t on Unix platforms, and HANDLE on native Windows
           platforms.

   int hwloc_set_area_membind (hwloc_topology_t topology, const void * addr,
       size_t len, hwloc_const_bitmap_t set, hwloc_membind_policy_t policy, int
       flags)
       Bind the already-allocated memory identified by (addr, len) to the NUMA
       node(s) specified by set. If HWLOC_MEMBIND_BYNODESET is specified, set is
       considered a nodeset. Otherwise it's a cpuset.

       Returns
           0 if len is 0.

           -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_membind (hwloc_topology_t topology, hwloc_const_bitmap_t set,
       hwloc_membind_policy_t policy, int flags)
       Set the default memory binding policy of the current process or thread to
       prefer the NUMA node(s) specified by set. If neither
       HWLOC_MEMBIND_PROCESS nor HWLOC_MEMBIND_THREAD is specified, the current
       process is assumed to be single-threaded. This is the most portable form
       as it permits hwloc to use either process-based OS functions or
       thread-based OS functions, depending on which are available.

       If HWLOC_MEMBIND_BYNODESET is specified, set is considered a nodeset.
       Otherwise it's a cpuset.

       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_membind (hwloc_topology_t topology, hwloc_pid_t pid,
       hwloc_const_bitmap_t set, hwloc_membind_policy_t policy, int flags)
       Set the default memory binding policy of the specified process to prefer
       the NUMA node(s) specified by set. If HWLOC_MEMBIND_BYNODESET is
       specified, set is considered a nodeset. Otherwise it's a cpuset.

       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

       Note
           hwloc_pid_t is pid_t on Unix platforms, and HANDLE on native Windows
           platforms.


Author

       Generated automatically by Doxygen for Hardware Locality (hwloc) from the
       source code.



Version 2.7.1                    Sun Mar 20 2022        hwlocality_membinding(3)

hwloc 2.7.1 - Generated Tue Jun 14 08:53:18 CDT 2022
© manpagez.com 2000-2024
Individual documents may contain additional copyright information.