.TH "hwlocality_memattrs" 3 "Version 2.12.0" "Hardware Locality (hwloc)" \" -*- nroff -*-
.ad l
.nh
.SH NAME
hwlocality_memattrs \- Comparing memory node attributes for finding where to allocate on
.SH SYNOPSIS
.br
.PP
.SS "Data Structures"

.in +1c
.ti -1c
.RI "struct \fBhwloc_location\fP"
.br
.in -1c
.SS "Typedefs"

.in +1c
.ti -1c
.RI "typedef unsigned \fBhwloc_memattr_id_t\fP"
.br
.in -1c
.SS "Enumerations"

.in +1c
.ti -1c
.RI "enum \fBhwloc_memattr_id_e\fP { \fBHWLOC_MEMATTR_ID_CAPACITY\fP, \fBHWLOC_MEMATTR_ID_LOCALITY\fP, \fBHWLOC_MEMATTR_ID_BANDWIDTH\fP, \fBHWLOC_MEMATTR_ID_READ_BANDWIDTH\fP, \fBHWLOC_MEMATTR_ID_WRITE_BANDWIDTH\fP, \fBHWLOC_MEMATTR_ID_LATENCY\fP, \fBHWLOC_MEMATTR_ID_READ_LATENCY\fP, \fBHWLOC_MEMATTR_ID_WRITE_LATENCY\fP, \fBHWLOC_MEMATTR_ID_MAX\fP }"
.br
.ti -1c
.RI "enum \fBhwloc_location_type_e\fP { \fBHWLOC_LOCATION_TYPE_CPUSET\fP, \fBHWLOC_LOCATION_TYPE_OBJECT\fP }"
.br
.ti -1c
.RI "enum \fBhwloc_local_numanode_flag_e\fP { \fBHWLOC_LOCAL_NUMANODE_FLAG_LARGER_LOCALITY\fP, \fBHWLOC_LOCAL_NUMANODE_FLAG_SMALLER_LOCALITY\fP, \fBHWLOC_LOCAL_NUMANODE_FLAG_ALL\fP }"
.br
.in -1c
.SS "Functions"

.in +1c
.ti -1c
.RI "int \fBhwloc_memattr_get_by_name\fP (\fBhwloc_topology_t\fP topology, const char *name, \fBhwloc_memattr_id_t\fP *id)"
.br
.ti -1c
.RI "int \fBhwloc_get_local_numanode_objs\fP (\fBhwloc_topology_t\fP topology, struct \fBhwloc_location\fP *location, unsigned *nr, \fBhwloc_obj_t\fP *nodes, unsigned long flags)"
.br
.ti -1c
.RI "int \fBhwloc_topology_get_default_nodeset\fP (\fBhwloc_topology_t\fP topology, \fBhwloc_nodeset_t\fP nodeset, unsigned long flags)"
.br
.ti -1c
.RI "int \fBhwloc_memattr_get_value\fP (\fBhwloc_topology_t\fP topology, \fBhwloc_memattr_id_t\fP attribute, \fBhwloc_obj_t\fP target_node, struct \fBhwloc_location\fP *initiator, unsigned long flags, hwloc_uint64_t *value)"
.br
.ti -1c
.RI "int \fBhwloc_memattr_get_best_target\fP (\fBhwloc_topology_t\fP topology, \fBhwloc_memattr_id_t\fP attribute, struct \fBhwloc_location\fP *initiator, unsigned long flags, \fBhwloc_obj_t\fP *best_target, hwloc_uint64_t *value)"
.br
.ti -1c
.RI "int \fBhwloc_memattr_get_best_initiator\fP (\fBhwloc_topology_t\fP topology, \fBhwloc_memattr_id_t\fP attribute, \fBhwloc_obj_t\fP target_node, unsigned long flags, struct \fBhwloc_location\fP *best_initiator, hwloc_uint64_t *value)"
.br
.ti -1c
.RI "int \fBhwloc_memattr_get_targets\fP (\fBhwloc_topology_t\fP topology, \fBhwloc_memattr_id_t\fP attribute, struct \fBhwloc_location\fP *initiator, unsigned long flags, unsigned *nr, \fBhwloc_obj_t\fP *targets, hwloc_uint64_t *values)"
.br
.ti -1c
.RI "int \fBhwloc_memattr_get_initiators\fP (\fBhwloc_topology_t\fP topology, \fBhwloc_memattr_id_t\fP attribute, \fBhwloc_obj_t\fP target_node, unsigned long flags, unsigned *nr, struct \fBhwloc_location\fP *initiators, hwloc_uint64_t *values)"
.br
.in -1c
.SH "Detailed Description"
.PP 
Platforms with heterogeneous memory require ways to decide whether a buffer should be allocated on 'fast' memory (such as HBM), 'normal' memory (DDR) or even 'slow' but large-capacity memory (non-volatile memory)\&. These memory nodes are called 'Targets' while the CPU accessing them is called the 'Initiator'\&. Access performance depends on their locality (NUMA platforms) as well as the intrinsic performance of the targets (heterogeneous platforms)\&.
.PP
The following attributes describe the performance of memory accesses from an Initiator to a memory Target, for instance their latency or bandwidth\&. Initiators performing these memory accesses are usually some PUs or Cores (described as a CPU set)\&. Hence a Core may choose where to allocate a memory buffer by comparing the attributes of different target memory nodes nearby\&.
.PP
There are also some attributes that are system-wide\&. Their value does not depend on a specific initiator performing an access\&. The memory node Capacity is an example of such attribute without initiator\&.
.PP
One way to use this API is to start with a cpuset describing the Cores where a program is bound\&. The best target NUMA node for allocating memory in this program on these Cores may be obtained by passing this cpuset as an initiator to \fBhwloc_memattr_get_best_target()\fP with the relevant memory attribute\&. For instance, if the code is latency limited, use the Latency attribute\&.
.PP
A more flexible approach consists in getting the list of local NUMA nodes by passing this cpuset to \fBhwloc_get_local_numanode_objs()\fP\&. Attribute values for these nodes, if any, may then be obtained with \fBhwloc_memattr_get_value()\fP and manually compared with the desired criteria\&.
.PP
Memory attributes are also used internally to build Memory Tiers which provide an easy way to distinguish NUMA nodes of different kinds, as explained in \fBHeterogeneous Memory\fP\&.
.PP
Beside tiers, hwloc defines a set of 'default' nodes where normal memory allocations should be made from (see \fBhwloc_topology_get_default_nodeset()\fP)\&. This is also useful for dividing the machine into a set of non-overlapping NUMA domains, for instance for binding tasks per domain\&.
.PP
\fBSee also\fP
.RS 4
An example is available in doc/examples/memory-attributes\&.c in the source tree\&.
.RE
.PP
\fBNote\fP
.RS 4
The API also supports specific objects as initiator, but it is currently not used internally by hwloc\&. Users may for instance use it to provide custom performance values for host memory accesses performed by GPUs\&.
.PP
The interface actually also accepts targets that are not NUMA nodes\&. 
.RE
.PP

.SH "Typedef Documentation"
.PP 
.SS "typedef unsigned \fBhwloc_memattr_id_t\fP"

.PP
A memory attribute identifier\&. hwloc predefines some commonly-used attributes in \fBhwloc_memattr_id_e\fP\&. One may then dynamically register custom ones with \fBhwloc_memattr_register()\fP, they will be assigned IDs immediately after the predefined ones\&. See \fBManaging memory attributes\fP for more information about existing attribute IDs\&. 
.SH "Enumeration Type Documentation"
.PP 
.SS "enum \fBhwloc_local_numanode_flag_e\fP"

.PP
Flags for selecting target NUMA nodes\&. 
.PP
\fBEnumerator\fP
.in +1c
.TP
\fB\fIHWLOC_LOCAL_NUMANODE_FLAG_LARGER_LOCALITY \fP\fP
Select NUMA nodes whose locality is larger than the given cpuset\&. For instance, if a single PU (or its cpuset) is given in \fCinitiator\fP, select all nodes close to the package that contains this PU\&. 
.TP
\fB\fIHWLOC_LOCAL_NUMANODE_FLAG_SMALLER_LOCALITY \fP\fP
Select NUMA nodes whose locality is smaller than the given cpuset\&. For instance, if a package (or its cpuset) is given in \fCinitiator\fP, also select nodes that are attached to only a half of that package\&. 
.TP
\fB\fIHWLOC_LOCAL_NUMANODE_FLAG_ALL \fP\fP
Select all NUMA nodes in the topology\&. The initiator \fCinitiator\fP is ignored\&. 
.SS "enum \fBhwloc_location_type_e\fP"

.PP
Type of location\&. 
.PP
\fBEnumerator\fP
.in +1c
.TP
\fB\fIHWLOC_LOCATION_TYPE_CPUSET \fP\fP
Location is given as a cpuset, in the location cpuset union field\&. 
.TP
\fB\fIHWLOC_LOCATION_TYPE_OBJECT \fP\fP
Location is given as an object, in the location object union field\&. 
.SS "enum \fBhwloc_memattr_id_e\fP"

.PP
Predefined memory attribute IDs\&. See \fBhwloc_memattr_id_t\fP for the generic definition of IDs for predefined or custom attributes\&. 
.PP
\fBEnumerator\fP
.in +1c
.TP
\fB\fIHWLOC_MEMATTR_ID_CAPACITY \fP\fP
The "Capacity" is returned in bytes (local_memory attribute in objects)\&. Best capacity nodes are nodes with \fBhigher capacity\fP\&.
.PP
No initiator is involved when looking at this attribute\&. The corresponding attribute flags are \fBHWLOC_MEMATTR_FLAG_HIGHER_FIRST\fP\&.
.PP
Capacity values may not be modified using \fBhwloc_memattr_set_value()\fP\&. 
.TP
\fB\fIHWLOC_MEMATTR_ID_LOCALITY \fP\fP
The "Locality" is returned as the number of PUs in that locality (e\&.g\&. the weight of its cpuset)\&. Best locality nodes are nodes with \fBsmaller locality\fP (nodes that are local to very few PUs)\&. Poor locality nodes are nodes with larger locality (nodes that are local to the entire machine)\&.
.PP
No initiator is involved when looking at this attribute\&. The corresponding attribute flags are \fBHWLOC_MEMATTR_FLAG_HIGHER_FIRST\fP\&.
.PP
Locality values may not be modified using \fBhwloc_memattr_set_value()\fP\&. 
.TP
\fB\fIHWLOC_MEMATTR_ID_BANDWIDTH \fP\fP
The "Bandwidth" is returned in MiB/s, as seen from the given initiator location\&. Best bandwidth nodes are nodes with \fBhigher bandwidth\fP\&.
.PP
The corresponding attribute flags are \fBHWLOC_MEMATTR_FLAG_HIGHER_FIRST\fP and \fBHWLOC_MEMATTR_FLAG_NEED_INITIATOR\fP\&.
.PP
This is the average bandwidth for read and write accesses\&. If the platform provides individual read and write bandwidths but no explicit average value, hwloc computes and returns the average\&. 
.TP
\fB\fIHWLOC_MEMATTR_ID_READ_BANDWIDTH \fP\fP
The "ReadBandwidth" is returned in MiB/s, as seen from the given initiator location\&. Best bandwidth nodes are nodes with \fBhigher bandwidth\fP\&.
.PP
The corresponding attribute flags are \fBHWLOC_MEMATTR_FLAG_HIGHER_FIRST\fP and \fBHWLOC_MEMATTR_FLAG_NEED_INITIATOR\fP\&. 
.TP
\fB\fIHWLOC_MEMATTR_ID_WRITE_BANDWIDTH \fP\fP
The "WriteBandwidth" is returned in MiB/s, as seen from the given initiator location\&. Best bandwidth nodes are nodes with \fBhigher bandwidth\fP\&.
.PP
The corresponding attribute flags are \fBHWLOC_MEMATTR_FLAG_HIGHER_FIRST\fP and \fBHWLOC_MEMATTR_FLAG_NEED_INITIATOR\fP\&. 
.TP
\fB\fIHWLOC_MEMATTR_ID_LATENCY \fP\fP
The "Latency" is returned as nanoseconds, as seen from the given initiator location\&. Best latency nodes are nodes with \fBsmaller latency\fP\&.
.PP
The corresponding attribute flags are \fBHWLOC_MEMATTR_FLAG_LOWER_FIRST\fP and \fBHWLOC_MEMATTR_FLAG_NEED_INITIATOR\fP\&.
.PP
This is the average latency for read and write accesses\&. If the platform provides individual read and write latencies but no explicit average value, hwloc computes and returns the average\&. 
.TP
\fB\fIHWLOC_MEMATTR_ID_READ_LATENCY \fP\fP
The "ReadLatency" is returned as nanoseconds, as seen from the given initiator location\&. Best latency nodes are nodes with \fBsmaller latency\fP\&.
.PP
The corresponding attribute flags are \fBHWLOC_MEMATTR_FLAG_LOWER_FIRST\fP and \fBHWLOC_MEMATTR_FLAG_NEED_INITIATOR\fP\&. 
.TP
\fB\fIHWLOC_MEMATTR_ID_WRITE_LATENCY \fP\fP
The "WriteLatency" is returned as nanoseconds, as seen from the given initiator location\&. Best latency nodes are nodes with \fBsmaller latency\fP\&.
.PP
The corresponding attribute flags are \fBHWLOC_MEMATTR_FLAG_LOWER_FIRST\fP and \fBHWLOC_MEMATTR_FLAG_NEED_INITIATOR\fP\&. 
.SH "Function Documentation"
.PP 
.SS "int hwloc_get_local_numanode_objs (\fBhwloc_topology_t\fP topology, struct \fBhwloc_location\fP * location, unsigned * nr, \fBhwloc_obj_t\fP * nodes, unsigned long flags)"

.PP
Return an array of local NUMA nodes\&. By default only select the NUMA nodes whose locality is exactly the given \fClocation\fP\&. More nodes may be selected if additional flags are given as a OR'ed set of \fBhwloc_local_numanode_flag_e\fP\&.
.PP
If \fClocation\fP is given as an explicit object, its CPU set is used to find NUMA nodes with the corresponding locality\&. If the object does not have a CPU set (e\&.g\&. I/O object), the CPU parent (where the I/O object is attached) is used\&.
.PP
On input, \fCnr\fP points to the number of nodes that may be stored in the \fCnodes\fP array\&. On output, \fCnr\fP will be changed to the number of stored nodes, or the number of nodes that would have been stored if there were enough room\&.
.PP
\fBReturns\fP
.RS 4
0 on success or -1 on error\&.
.RE
.PP
\fBNote\fP
.RS 4
Some of these NUMA nodes may not have any memory attribute values and hence not be reported as actual targets in other functions\&.
.PP
The number of NUMA nodes in the topology (obtained by \fBhwloc_bitmap_weight()\fP on the root object nodeset) may be used to allocate the \fCnodes\fP array\&.
.PP
When an object CPU set is given as locality, for instance a Package, and when flags contain both \fBHWLOC_LOCAL_NUMANODE_FLAG_LARGER_LOCALITY\fP and \fBHWLOC_LOCAL_NUMANODE_FLAG_SMALLER_LOCALITY\fP, the returned array corresponds to the nodeset of that object\&. 
.RE
.PP

.SS "int hwloc_memattr_get_best_initiator (\fBhwloc_topology_t\fP topology, \fBhwloc_memattr_id_t\fP attribute, \fBhwloc_obj_t\fP target_node, unsigned long flags, struct \fBhwloc_location\fP * best_initiator, hwloc_uint64_t * value)"

.PP
Return the best initiator for the given attribute and target NUMA node\&. If \fCvalue\fP is non \fCNULL\fP, the corresponding value is returned there\&.
.PP
If multiple initiators have the same attribute values, only one is returned (and there is no way to clarify how that one is chosen)\&. Applications that want to detect initiators with identical/similar values, or that want to look at values for multiple attributes, should rather get all values using \fBhwloc_memattr_get_value()\fP and manually select the initiator they consider the best\&.
.PP
The returned initiator should not be modified or freed, it belongs to the topology\&.
.PP
\fCtarget_node\fP cannot be \fCNULL\fP\&.
.PP
\fCflags\fP must be \fC0\fP for now\&.
.PP
\fBReturns\fP
.RS 4
0 on success\&. 
.PP
-1 with errno set to \fCENOENT\fP if there are no matching initiators\&. 
.PP
-1 with errno set to \fCEINVAL\fP if the attribute does not relate to a specific initiator (it does not have the flag \fBHWLOC_MEMATTR_FLAG_NEED_INITIATOR\fP)\&. 
.RE
.PP

.SS "int hwloc_memattr_get_best_target (\fBhwloc_topology_t\fP topology, \fBhwloc_memattr_id_t\fP attribute, struct \fBhwloc_location\fP * initiator, unsigned long flags, \fBhwloc_obj_t\fP * best_target, hwloc_uint64_t * value)"

.PP
Return the best target NUMA node for the given attribute and initiator\&. If the attribute does not relate to a specific initiator (it does not have the flag \fBHWLOC_MEMATTR_FLAG_NEED_INITIATOR\fP), location \fCinitiator\fP is ignored and may be \fCNULL\fP\&.
.PP
If \fCvalue\fP is non \fCNULL\fP, the corresponding value is returned there\&.
.PP
If multiple targets have the same attribute values, only one is returned (and there is no way to clarify how that one is chosen)\&. Applications that want to detect targets with identical/similar values, or that want to look at values for multiple attributes, should rather get all values using \fBhwloc_memattr_get_value()\fP and manually select the target they consider the best\&.
.PP
\fCflags\fP must be \fC0\fP for now\&.
.PP
\fBReturns\fP
.RS 4
0 on success\&. 
.PP
-1 with errno set to \fCENOENT\fP if there are no matching targets\&. 
.PP
-1 with errno set to \fCEINVAL\fP if flags are invalid, or no such attribute exists\&.
.RE
.PP
\fBNote\fP
.RS 4
The initiator \fCinitiator\fP should be of type \fBHWLOC_LOCATION_TYPE_CPUSET\fP when refering to accesses performed by CPU cores\&. \fBHWLOC_LOCATION_TYPE_OBJECT\fP is currently unused internally by hwloc, but users may for instance use it to provide custom information about host memory accesses performed by GPUs\&. 
.RE
.PP

.SS "int hwloc_memattr_get_by_name (\fBhwloc_topology_t\fP topology, const char * name, \fBhwloc_memattr_id_t\fP * id)"

.PP
Return the identifier of the memory attribute with the given name\&. 
.PP
\fBReturns\fP
.RS 4
0 on success\&. 
.PP
-1 with errno set to \fCEINVAL\fP if no such attribute exists\&. 
.RE
.PP

.SS "int hwloc_memattr_get_initiators (\fBhwloc_topology_t\fP topology, \fBhwloc_memattr_id_t\fP attribute, \fBhwloc_obj_t\fP target_node, unsigned long flags, unsigned * nr, struct \fBhwloc_location\fP * initiators, hwloc_uint64_t * values)"

.PP
Return the initiators that have values for a given attribute for a specific target NUMA node\&. Return initiators for the given attribute and target node in the \fCinitiators\fP array\&. If \fCvalues\fP is not \fCNULL\fP, the corresponding attribute values are stored in the array it points to\&.
.PP
On input, \fCnr\fP points to the number of initiators that may be stored in the array \fCinitiators\fP (and \fCvalues\fP)\&. On output, \fCnr\fP points to the number of initiators (and values) that were actually found, even if some of them couldn't be stored in the array\&. Initiators that couldn't be stored are ignored, but the function still returns success (\fC0\fP)\&. The caller may find out by comparing the value pointed by \fCnr\fP before and after the function call\&.
.PP
The returned initiators should not be modified or freed, they belong to the topology\&.
.PP
\fCtarget_node\fP cannot be \fCNULL\fP\&.
.PP
\fCflags\fP must be \fC0\fP for now\&.
.PP
If the attribute does not relate to a specific initiator (it does not have the flag \fBHWLOC_MEMATTR_FLAG_NEED_INITIATOR\fP), no initiator is returned\&.
.PP
\fBReturns\fP
.RS 4
0 on success or -1 on error\&.
.RE
.PP
\fBNote\fP
.RS 4
This function is meant for tools and debugging (listing internal information) rather than for application queries\&. Applications should rather select useful NUMA nodes with \fBhwloc_get_local_numanode_objs()\fP and then look at their attribute values for some relevant initiators\&. 
.RE
.PP

.SS "int hwloc_memattr_get_targets (\fBhwloc_topology_t\fP topology, \fBhwloc_memattr_id_t\fP attribute, struct \fBhwloc_location\fP * initiator, unsigned long flags, unsigned * nr, \fBhwloc_obj_t\fP * targets, hwloc_uint64_t * values)"

.PP
Return the target NUMA nodes that have some values for a given attribute\&. Return targets for the given attribute in the \fCtargets\fP array (for the given initiator if any)\&. If \fCvalues\fP is not \fCNULL\fP, the corresponding attribute values are stored in the array it points to\&.
.PP
On input, \fCnr\fP points to the number of targets that may be stored in the array \fCtargets\fP (and \fCvalues\fP)\&. On output, \fCnr\fP points to the number of targets (and values) that were actually found, even if some of them couldn't be stored in the array\&. Targets that couldn't be stored are ignored, but the function still returns success (\fC0\fP)\&. The caller may find out by comparing the value pointed by \fCnr\fP before and after the function call\&.
.PP
The returned targets should not be modified or freed, they belong to the topology\&.
.PP
Argument \fCinitiator\fP is ignored if the attribute does not relate to a specific initiator (it does not have the flag \fBHWLOC_MEMATTR_FLAG_NEED_INITIATOR\fP)\&. Otherwise \fCinitiator\fP may be non \fCNULL\fP to report only targets that have a value for that initiator\&.
.PP
\fCflags\fP must be \fC0\fP for now\&.
.PP
\fBNote\fP
.RS 4
This function is meant for tools and debugging (listing internal information) rather than for application queries\&. Applications should rather select useful NUMA nodes with \fBhwloc_get_local_numanode_objs()\fP and then look at their attribute values\&.
.RE
.PP
\fBReturns\fP
.RS 4
0 on success or -1 on error\&.
.RE
.PP
\fBNote\fP
.RS 4
The initiator \fCinitiator\fP should be of type \fBHWLOC_LOCATION_TYPE_CPUSET\fP when referring to accesses performed by CPU cores\&. \fBHWLOC_LOCATION_TYPE_OBJECT\fP is currently unused internally by hwloc, but users may for instance use it to provide custom information about host memory accesses performed by GPUs\&. 
.RE
.PP

.SS "int hwloc_memattr_get_value (\fBhwloc_topology_t\fP topology, \fBhwloc_memattr_id_t\fP attribute, \fBhwloc_obj_t\fP target_node, struct \fBhwloc_location\fP * initiator, unsigned long flags, hwloc_uint64_t * value)"

.PP
Return an attribute value for a specific target NUMA node\&. If the attribute does not relate to a specific initiator (it does not have the flag \fBHWLOC_MEMATTR_FLAG_NEED_INITIATOR\fP), location \fCinitiator\fP is ignored and may be \fCNULL\fP\&.
.PP
\fCtarget_node\fP cannot be \fCNULL\fP\&. If \fCattribute\fP is \fBHWLOC_MEMATTR_ID_CAPACITY\fP, \fCtarget_node\fP must be a NUMA node\&. If it is \fBHWLOC_MEMATTR_ID_LOCALITY\fP, \fCtarget_node\fP must have a CPU set\&.
.PP
\fCflags\fP must be \fC0\fP for now\&.
.PP
\fBReturns\fP
.RS 4
0 on success\&. 
.PP
-1 on error, for instance with errno set to \fCEINVAL\fP if flags are invalid or no such attribute exists\&.
.RE
.PP
\fBNote\fP
.RS 4
The initiator \fCinitiator\fP should be of type \fBHWLOC_LOCATION_TYPE_CPUSET\fP when refering to accesses performed by CPU cores\&. \fBHWLOC_LOCATION_TYPE_OBJECT\fP is currently unused internally by hwloc, but users may for instance use it to provide custom information about host memory accesses performed by GPUs\&. 
.RE
.PP

.SS "int hwloc_topology_get_default_nodeset (\fBhwloc_topology_t\fP topology, \fBhwloc_nodeset_t\fP nodeset, unsigned long flags)"

.PP
Return the set of default NUMA nodes\&. In machines with heterogeneous memory, some NUMA nodes are considered the default ones, i\&.e\&. where basic allocations should be made from\&. These are usually DRAM nodes\&.
.PP
Other nodes may be reserved for specific use (I/O device memory, e\&.g\&. GPU memory), small but high performance (HBM), large but slow memory (NVM), etc\&. Buffers should usually not be allocated from there unless explicitly required\&.
.PP
This function fills \fCnodeset\fP with the bits of NUMA nodes considered default\&.
.PP
It is guaranteed that these nodes have non-intersecting CPU sets, i\&.e\&. cores may not have multiple local NUMA nodes anymore\&. Hence this may be used to iterate over the platform divided into separate NUMA localities, for instance for binding one task per NUMA domain\&.
.PP
Any core that had some local NUMA node(s) in the initial topology should still have one in the default nodeset\&. Corner cases where this would be wrong consist in asymmetric platforms with missing DRAM nodes, or topologies that were already restricted to less NUMA nodes\&.
.PP
The returned nodeset may be passed to \fBhwloc_topology_restrict()\fP with \fBHWLOC_RESTRICT_FLAG_BYNODESET\fP to remove all non-default nodes from the topology\&. The resulting topology will be easier to use when iterating over (now homogeneous) NUMA nodes\&.
.PP
The heuristics for finding default nodes relies on memory tiers and subtypes (see \fBHeterogeneous Memory\fP) as well as the assumption that hardware vendors list default nodes first in hardware tables\&.
.PP
\fCflags\fP must be \fC0\fP for now\&.
.PP
\fBReturns\fP
.RS 4
0 on success\&. 
.PP
-1 on error\&.
.RE
.PP
\fBNote\fP
.RS 4
The returned nodeset usually contains all nodes from a single memory tier, likely the DRAM one\&.
.PP
The returned nodeset is included in the list of available nodes returned by \fBhwloc_topology_get_topology_nodeset()\fP\&. It is strictly smaller if the machine has heterogeneous memory\&.
.PP
The heuristics may return a suboptimal set of nodes if hwloc could not guess memory types and/or if some default nodes were removed earlier from the topology (e\&.g\&. with \fBhwloc_topology_restrict()\fP)\&. 
.RE
.PP

.SH "Author"
.PP 
Generated automatically by Doxygen for Hardware Locality (hwloc) from the source code\&.