Manpages - hwlocality_distances_add.3

Table of Contents

NAME

hwlocality_distances_add - Add distances between objects

SYNOPSIS


Typedefs

typedef void * hwloc_distances_add_handle_t

Enumerations

enum hwloc_distances_add_flag_e { HWLOC_DISTANCES_ADD_FLAG_GROUP, HWLOC_DISTANCES_ADD_FLAG_GROUP_INACCURATE }

Functions

hwloc_distances_add_handle_t hwloc_distances_add_create (hwloc_topology_t topology, const char *name, unsigned long kind, unsigned long flags)

int hwloc_distances_add_values (hwloc_topology_t topology, hwloc_distances_add_handle_t handle, unsigned nbobjs, hwloc_obj_t *objs, hwloc_uint64_t *values, unsigned long flags)

int hwloc_distances_add_commit (hwloc_topology_t topology, hwloc_distances_add_handle_t handle, unsigned long flags)

Detailed Description

The usual way to add distances is:

  hwloc_distances_add_handle_t handle;
  int err = -1;
  handle = hwloc_distances_add_create(topology, "name", kind, 0);
  if (handle) {
    err = hwloc_distances_add_values(topology, handle, nbobjs, objs, values, 0);
    if (!err)
      err = hwloc_distances_add_commit(topology, handle, flags);
  }

If err is 0 at the end, then addition was successful.

Typedef Documentation

typedef void* hwloc_distances_add_handle_t

Handle to a new distances structure during its addition to the topology.

Enumeration Type Documentation

enum hwloc_distances_add_flag_e

Flags for adding a new distances to a topology.

Enumerator

/HWLOC_DISTANCES_ADD_FLAG_GROUP /
Try to group objects based on the newly provided distance information. This is ignored for distances between objects of different types.
/HWLOC_DISTANCES_ADD_FLAG_GROUP_INACCURATE /
If grouping, consider the distance values as inaccurate and relax the comparisons during the grouping algorithms. The actual accuracy may be modified through the HWLOC_GROUPING_ACCURACY environment variable (see *Environment Variables*/). /

Function Documentation

int hwloc_distances_add_commit (*hwloc_topology_t*/ topology,

hwloc_distances_add_handle_t handle, unsigned long flags)/ Commit a new distances structure. This function finalizes the distances structure and inserts in it the topology.

Parameter =handle=/ was previously returned by hwloc_distances_add_create(). Then objects and values were specified with hwloc_distances_add_values()./

=flags=/ configures the behavior of the function using an optional OR’ed set of hwloc_distances_add_flag_e. It may be used to request the grouping of existing objects based on distances./

On error, the temporary distances structure and its content are destroyed.

Returns

=0=/ on success. /

=-1=/ on error. /

*hwloc_distances_add_handle_t*/ hwloc_distances_add_create

(hwloc_topology_t topology, const char * name, unsigned long kind, unsigned long flags)/ Create a new empty distances structure. Create an empty distances structure to be filled with *hwloc_distances_add_values()*/ and then committed with hwloc_distances_add_commit()./

Parameter =name=/ is optional, it may be NULL. Otherwise, it will be copied internally and may later be freed by the caller./

=kind=/ specifies the kind of distance as a OR’ed set of hwloc_distances_kind_e. Kind HWLOC_DISTANCES_KIND_HETEROGENEOUS_TYPES will be automatically set according to objects having different types in hwloc_distances_add_values()./

=flags=/ must be 0 for now./

Returns

A hwloc_distances_add_handle_t that should then be passed to *hwloc_distances_add_values()*/ and hwloc_distances_add_commit()./

=NULL=/ on error. /

int hwloc_distances_add_values (*hwloc_topology_t*/ topology,

hwloc_distances_add_handle_t handle, unsigned nbobjs, hwloc_obj_t * objs, hwloc_uint64_t * values, unsigned long flags)/ Specify the objects and values in a new empty distances structure. Specify the objects and values for a new distances structure that was returned as a handle by *hwloc_distances_add_create()*/. The structure must then be committed with hwloc_distances_add_commit()./

The number of objects is =nbobjs=/ and the array of objects is objs. Distance values are stored as a one-dimension array in values. The distance from object i to object j is in slot i*nbobjs+j./

=nbobjs=/ must be at least 2./

Arrays =objs=/ and values will be copied internally, they may later be freed by the caller./

On error, the temporary distances structure and its content are destroyed.

=flags=/ must be 0 for now./

Returns

=0=/ on success. /

=-1=/ on error. /

Author

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

Author: dt

Created: 2022-02-20 Sun 16:39