hwlocality_distances_get(3) Library Functions Manual
NAME
hwlocality_distances_get - Retrieve distances between objects
SYNOPSIS
Data Structures
struct hwloc_distances_s
Enumerations
enum hwloc_distances_kind_e { HWLOC_DISTANCES_KIND_FROM_OS,
HWLOC_DISTANCES_KIND_FROM_USER, HWLOC_DISTANCES_KIND_MEANS_LATENCY,
HWLOC_DISTANCES_KIND_MEANS_BANDWIDTH,
HWLOC_DISTANCES_KIND_HETEROGENEOUS_TYPES }
enum hwloc_distances_transform_e {
HWLOC_DISTANCES_TRANSFORM_REMOVE_NULL,
HWLOC_DISTANCES_TRANSFORM_LINKS,
HWLOC_DISTANCES_TRANSFORM_MERGE_SWITCH_PORTS,
HWLOC_DISTANCES_TRANSFORM_TRANSITIVE_CLOSURE }
Functions
int hwloc_distances_get (hwloc_topology_t topology, unsigned *nr,
struct hwloc_distances_s **distances, unsigned long kind, unsigned
long flags)
int hwloc_distances_get_by_depth (hwloc_topology_t topology, int depth,
unsigned *nr, struct hwloc_distances_s **distances, unsigned long
kind, unsigned long flags)
int hwloc_distances_get_by_type (hwloc_topology_t topology,
hwloc_obj_type_t type, unsigned *nr, struct hwloc_distances_s
**distances, unsigned long kind, unsigned long flags)
int hwloc_distances_get_by_name (hwloc_topology_t topology, const char
*name, unsigned *nr, struct hwloc_distances_s **distances, unsigned
long flags)
const char * hwloc_distances_get_name (hwloc_topology_t topology,
struct hwloc_distances_s *distances)
void hwloc_distances_release (hwloc_topology_t topology, struct
hwloc_distances_s *distances)
int hwloc_distances_transform (hwloc_topology_t topology, struct
hwloc_distances_s *distances, enum hwloc_distances_transform_e
transform, void *transform_attr, unsigned long flags)
Detailed Description
Enumeration Type Documentation
enum hwloc_distances_kind_e
Kinds of distance matrices. The kind attribute of struct
hwloc_distances_s is a OR'ed set of kinds.
Each distance matrix may have only one kind among
HWLOC_DISTANCES_KIND_FROM_* specifying where distance information comes
from, and one kind among HWLOC_DISTANCES_KIND_MEANS_* specifying
whether values are latencies or bandwidths.
Enumerator
HWLOC_DISTANCES_KIND_FROM_OS
These distances were obtained from the operating system or
hardware.
HWLOC_DISTANCES_KIND_FROM_USER
These distances were provided by the user.
HWLOC_DISTANCES_KIND_MEANS_LATENCY
Distance values are similar to latencies between objects. Values
are smaller for closer objects, hence minimal on the diagonal of
the matrix (distance between an object and itself). It could
also be the number of network hops between objects, etc.
HWLOC_DISTANCES_KIND_MEANS_BANDWIDTH
Distance values are similar to bandwidths between objects.
Values are higher for closer objects, hence maximal on the
diagonal of the matrix (distance between an object and itself).
Such values are currently ignored for distance-based grouping.
HWLOC_DISTANCES_KIND_HETEROGENEOUS_TYPES
This distances structure covers objects of different types. This
may apply to the 'NVLinkBandwidth' structure in presence of a
NVSwitch or POWER processor NVLink port.
enum hwloc_distances_transform_e
Transformations of distances structures.
Enumerator
HWLOC_DISTANCES_TRANSFORM_REMOVE_NULL
Remove NULL objects from the distances structure. Every object
that was replaced with NULL in the objs array is removed and the
values array is updated accordingly.
At least 2 objects must remain, otherwise hwloc_distances_transform()
will return -1 with errno set to EINVAL.
kind will be updated with or without
HWLOC_DISTANCES_KIND_HETEROGENEOUS_TYPES according to the remaining
objects.
HWLOC_DISTANCES_TRANSFORM_LINKS
Replace bandwidth values with a number of links. Usually all
values will be either 0 (no link) or 1 (one link). However some
matrices could get larger values if some pairs of peers are
connected by different numbers of links.
Values on the diagonal are set to 0.
This transformation only applies to bandwidth matrices.
HWLOC_DISTANCES_TRANSFORM_MERGE_SWITCH_PORTS
Merge switches with multiple ports into a single object. This
currently only applies to NVSwitches where GPUs seem connected
to different switch ports. Switch ports must be objects with
subtype 'NVSwitch' as in the NVLinkBandwidth matrix.
This transformation will replace all ports with only the first one, now
connected to all GPUs. Other ports are removed by applying
HWLOC_DISTANCES_TRANSFORM_REMOVE_NULL internally.
HWLOC_DISTANCES_TRANSFORM_TRANSITIVE_CLOSURE
Apply a transitive closure to the matrix to connect objects
across switches. All pairs of GPUs will be reported as directly
connected instead GPUs being only connected to switches.
Switch ports must be objects with subtype 'NVSwitch' as in the
NVLinkBandwidth matrix.
Function Documentation
int hwloc_distances_get (hwloc_topology_t topology, unsigned * nr, struct
hwloc_distances_s ** distances, unsigned long kind, unsigned long
flags)
Retrieve distance matrices. Retrieve distance matrices from the
topology into the distances array.
flags is currently unused, should be 0.
kind serves as a filter. If 0, all distance matrices are returned. If
it contains some HWLOC_DISTANCES_KIND_FROM_*, only distance matrices
whose kind matches one of these are returned. If it contains some
HWLOC_DISTANCES_KIND_MEANS_*, only distance matrices whose kind matches
one of these are returned.
On input, nr points to the number of distance matrices that may be
stored in distances. On output, nr points to the number of distance
matrices that were actually found, even if some of them couldn't be
stored in distances. Distance matrices that couldn't be stored are
ignored, but the function still returns success (0). The caller may
find out by comparing the value pointed by nr before and after the
function call.
Each distance matrix returned in the distances array should be released
by the caller using hwloc_distances_release().
Returns
0 on success, -1 on error.
int hwloc_distances_get_by_depth (hwloc_topology_t topology, int depth,
unsigned * nr, struct hwloc_distances_s ** distances, unsigned long
kind, unsigned long flags)
Retrieve distance matrices for object at a specific depth in the
topology. Identical to hwloc_distances_get() with the additional depth
filter.
Returns
0 on success, -1 on error.
int hwloc_distances_get_by_name (hwloc_topology_t topology, const char *
name, unsigned * nr, struct hwloc_distances_s ** distances, unsigned
long flags)
Retrieve a distance matrix with the given name. Usually only one
distances structure may match a given name.
The name of the most common structure is 'NUMALatency'. Others include
'XGMIBandwidth', 'XGMIHops', 'XeLinkBandwidth', and 'NVLinkBandwidth'.
Returns
0 on success, -1 on error.
int hwloc_distances_get_by_type (hwloc_topology_t topology,
hwloc_obj_type_t type, unsigned * nr, struct hwloc_distances_s **
distances, unsigned long kind, unsigned long flags)
Retrieve distance matrices for object of a specific type. Identical to
hwloc_distances_get() with the additional type filter.
Returns
0 on success, -1 on error.
const char * hwloc_distances_get_name (hwloc_topology_t topology, struct
hwloc_distances_s * distances)
Get a description of what a distances structure contains. For instance
'NUMALatency' for hardware-provided NUMA distances (ACPI SLIT), or NULL
if unknown.
Returns
the constant string with the name of the distance structure.
Note
The returned name should not be freed by the caller, it belongs to
the hwloc library.
void hwloc_distances_release (hwloc_topology_t topology, struct
hwloc_distances_s * distances)
Release a distance matrix structure previously returned by
hwloc_distances_get().
Note
This function is not required if the structure is removed with
hwloc_distances_release_remove().
int hwloc_distances_transform (hwloc_topology_t topology, struct
hwloc_distances_s * distances, enum hwloc_distances_transform_e
transform, void * transform_attr, unsigned long flags)
Apply a transformation to a distances structure. Modify a distances
structure that was previously obtained with hwloc_distances_get() or
one of its variants.
This modifies the local copy of the distances structures but does not
modify the distances information stored inside the topology (retrieved
by another call to hwloc_distances_get() or exported to XML). To do so,
one should add a new distances structure with same name, kind, objects
and values (see Add distances between objects) and then remove this old
one with hwloc_distances_release_remove().
transform must be one of the transformations listed in
hwloc_distances_transform_e.
These transformations may modify the contents of the objs or values
arrays.
transform_attr must be NULL for now.
flags must be 0 for now.
Returns
0 on success, -1 on error for instance if flags are invalid.
Note
Objects in distances array objs may be directly modified in place
without using hwloc_distances_transform(). One may use
hwloc_get_obj_with_same_locality() to easily convert between
similar objects of different types.
Author
Generated automatically by Doxygen for Hardware Locality (hwloc) from
the source code.
Hardware Locality (hwloc) Version 2.12.0 hwlocality_distances_get(3)
hwloc 2.12.0 - Generated Thu May 8 14:51:28 CDT 2025