Detailed Description

Note:

Not all operating systems support all ways to bind existing allocated memory (e.g., migration), future memory allocation, explicit memory allocation, etc. Using a binding flag or policy that is not supported by the underlying OS will cause hwloc's binding functions to fail and return -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 cpuset can not be enforced (e.g., some systems only allow binding memory to a single NUMA node).

The most portable form that should be preferred over the others whenever possible is as follows:

This will allocate 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. Note that since HWLOC_MEMBIND_STRICT was not specified, failures to bind will not be reported -- generally, only memory allocation failures will be reported (e.g., even a plain malloc() would have failed with ENOMEM).

Enumeration Type Documentation

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.

Note:

Not all systems support all kinds of binding. 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.

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

Note:

Not all systems support all kinds of binding. 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.

HWLOC_MEMBIND_FIRSTTOUCH

Allocate memory but do not immediately bind it to a specific locality. Instead, each page in the allocation is bound only when it is first touched. Pages are individually bound to the local NUMA node of the first thread that touches it.

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_REPLICATE

Replicate memory on the given nodes; reads from this memory will attempt to be serviced from the NUMA node local to the reading thread. Replicating can be useful when multiple threads from the specified NUMA nodes will be sharing the same read-only data.

This policy can only be used with existing memory allocations (i.e., the hwloc_set_*membind*() functions); it cannot be used with functions that allocate new memory (i.e., the hwloc_alloc*() functions).

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 hwloc_get_membind*() functions when multiple threads or parts of a memory area have differing memory binding policies.

Query the CPUs near the NUMA node(s) and binding policy of the memory identified by (addr, len ).

This function has two output parameters: cpuset 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 policy is returned in policy. cpuset is set to the union of CPUs near the NUMA node(s) in the nodeset.

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

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

Query the NUMA node(s) and binding policy of the memory identified by (addr, len ).

This function has two output parameters: nodeset 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 nodeset and policy are returned in nodeset and policy, respectively.

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

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

Query the default memory binding policy and locality of the current process or thread (the locality is returned in cpuset as CPUs near the locality's actual NUMA node(s)).

This function has two output parameters: cpuset 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 policy is returned in policy. cpuset is set to the union of CPUs near the NUMA node(s) in the nodeset.

Otherwise, if HWLOC_MEMBIND_PROCESS is specified (and HWLOC_MEMBIND_STRICT is not specified), the default nodeset from each thread is logically OR'ed together. cpuset is set to the union of CPUs near the NUMA node(s) in the resulting nodeset. 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 nodeset and policy. The policy is returned in policy; cpuset is set to the union of CPUs near the NUMA node(s) in the nodeset.

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

Query the default memory binding policy and locality of the current process or thread.

This function has two output parameters: nodeset 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 nodeset and policy.

Otherwise, if HWLOC_MEMBIND_PROCESS is specified (and HWLOC_MEMBIND_STRICT is not specified), nodeset is set to the logical OR of all threads' default nodeset. 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 nodeset and policy; they are returned in nodeset and policy, respectively.

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

Query the default memory binding policy and locality of the specified process (the locality is returned in cpuset as CPUs near the locality's actual NUMA node(s)).

This function has two output parameters: cpuset 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 policy is returned in policy. cpuset is set to the union of CPUs near the NUMA node(s) in the nodeset.

Otherwise, the default nodeset from each thread is logically OR'ed together. cpuset is set to the union of CPUs near the NUMA node(s) in the resulting nodeset. 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 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.

Query the default memory binding policy and locality of the specified process.

This function has two output parameters: nodeset 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 nodeset and policy.

Otherwise, nodeset is set to the logical OR of all threads' default nodeset. 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 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.

Set the default memory binding policy of the current process or thread to prefer the NUMA node(s) near the specified cpuset.

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.

Set the default memory binding policy of the current process or thread to prefer the NUMA node(s) specified by nodeset.

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.