Hardware Locality (hwloc)
1.7.2
|
Memory binding can be done three ways:
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).
Each hwloc memory binding function is available in two forms: one that takes a CPU set argument and another that takes a NUMA memory node set argument (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). The names of the latter form end with _nodeset. It is also possible to convert between CPU set and node set using hwloc_cpuset_to_nodeset() or hwloc_cpuset_from_nodeset().
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.
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).
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.
void* hwloc_alloc_membind | ( | hwloc_topology_t | topology, |
size_t | len, | ||
hwloc_const_cpuset_t | cpuset, | ||
hwloc_membind_policy_t | policy, | ||
int | flags | ||
) |
Allocate some memory on memory nodes near the given physical cpuset cpuset
.
void* hwloc_alloc_membind_nodeset | ( | hwloc_topology_t | topology, |
size_t | len, | ||
hwloc_const_nodeset_t | nodeset, | ||
hwloc_membind_policy_t | policy, | ||
int | flags | ||
) |
Allocate some memory on the given physical nodeset nodeset
.
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_cpuset_t | cpuset, | ||
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
).
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.
int hwloc_get_area_membind_nodeset | ( | hwloc_topology_t | topology, |
const void * | addr, | ||
size_t | len, | ||
hwloc_nodeset_t | nodeset, | ||
hwloc_membind_policy_t * | policy, | ||
int | flags | ||
) |
Query the physical 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.
int hwloc_get_membind | ( | hwloc_topology_t | topology, |
hwloc_cpuset_t | cpuset, | ||
hwloc_membind_policy_t * | policy, | ||
int | flags | ||
) |
Query the default memory binding policy and physical 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.
int hwloc_get_membind_nodeset | ( | hwloc_topology_t | topology, |
hwloc_nodeset_t | nodeset, | ||
hwloc_membind_policy_t * | policy, | ||
int | flags | ||
) |
Query the default memory binding policy and physical 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.
int hwloc_get_proc_membind | ( | hwloc_topology_t | topology, |
hwloc_pid_t | pid, | ||
hwloc_cpuset_t | cpuset, | ||
hwloc_membind_policy_t * | policy, | ||
int | flags | ||
) |
Query the default memory binding policy and physical 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.
hwloc_pid_t
is pid_t
on Unix platforms, and HANDLE
on native Windows platforms. int hwloc_get_proc_membind_nodeset | ( | hwloc_topology_t | topology, |
hwloc_pid_t | pid, | ||
hwloc_nodeset_t | nodeset, | ||
hwloc_membind_policy_t * | policy, | ||
int | flags | ||
) |
Query the default memory binding policy and physical 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.
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_cpuset_t | cpuset, | ||
hwloc_membind_policy_t | policy, | ||
int | flags | ||
) |
Bind the already-allocated memory identified by (addr, len) to the NUMA node(s) near physical cpuset
.
int hwloc_set_area_membind_nodeset | ( | hwloc_topology_t | topology, |
const void * | addr, | ||
size_t | len, | ||
hwloc_const_nodeset_t | nodeset, | ||
hwloc_membind_policy_t | policy, | ||
int | flags | ||
) |
Bind the already-allocated memory identified by (addr, len) to the NUMA node(s) in physical nodeset
.
int hwloc_set_membind | ( | hwloc_topology_t | topology, |
hwloc_const_cpuset_t | cpuset, | ||
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) near the specified physical 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.
int hwloc_set_membind_nodeset | ( | hwloc_topology_t | topology, |
hwloc_const_nodeset_t | nodeset, | ||
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 physical 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.
int hwloc_set_proc_membind | ( | hwloc_topology_t | topology, |
hwloc_pid_t | pid, | ||
hwloc_const_cpuset_t | cpuset, | ||
hwloc_membind_policy_t | policy, | ||
int | flags | ||
) |
Set the default memory binding policy of the specified process to prefer the NUMA node(s) near the specified physical cpuset
.
hwloc_pid_t
is pid_t
on Unix platforms, and HANDLE
on native Windows platforms. int hwloc_set_proc_membind_nodeset | ( | hwloc_topology_t | topology, |
hwloc_pid_t | pid, | ||
hwloc_const_nodeset_t | nodeset, | ||
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 physical nodeset
.
hwloc_pid_t
is pid_t
on Unix platforms, and HANDLE
on native Windows platforms.