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:
           This function is not required if the structure is removed with hwloc_distances_release_remove().

Author

       Generated automatically by Doxygen for Hardware Locality (hwloc) from the source code.

Version 2.1.0                                    Mon Sep 30 2019                     hwlocality_distances_get(3)