hwlocality_distances_get - Man Page

struct hwloc_distances_s

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 }

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)

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

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

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

Retrieve distance matrices for object at a specific depth in the topology​. Identical to hwloc_distances_get() with the additional depth filter​.

Returns

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

Retrieve distance matrices for object of a specific type​. Identical to hwloc_distances_get() with the additional type filter​.

Returns

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

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

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

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