## table of contents

- experimental 2.1.0+dfsg-1

hwlocality_distances_get(3) | Hardware Locality (hwloc) | hwlocality_distances_get(3) |

# NAME¶

hwlocality_distances_get# 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**}

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

# 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.**

A kind of format HWLOC_DISTANCES_KIND_FROM_* specifies where the distance information comes from, if known.

A kind of format HWLOC_DISTANCES_KIND_MEANS_* specifies whether values are latencies or bandwidths, if applicable.

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

# 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()****.**

## 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.**

## 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.## 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.**

## 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.## 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:**

**hwloc_distances_release_remove()**.

# Author¶

Generated automatically by Doxygen for Hardware Locality (hwloc) from the source code.Mon Sep 30 2019 | Version 2.1.0 |