Add distances between objects

## 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);
}
hwloc_distances_add_commit
int hwloc_distances_add_commit(hwloc_topology_t topology, hwloc_distances_add_handle_t handle, unsigned long flags)
Commit a new distances structure.
hwloc_distances_add_handle_t
void * hwloc_distances_add_handle_t
Handle to a new distances structure during its addition to the topology.
Definition: distances.h:330
hwloc_distances_add_create
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.
hwloc_distances_add_values
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.

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

## Typedef Documentation

## hwloc_distances_add_handle_t

typedef void* hwloc_distances_add_handle_t

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

## Enumeration Type Documentation

## hwloc_distances_add_flag_e

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

## hwloc_distances_add_commit()

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_create()

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.

## hwloc_distances_add_values()

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.