Open MPI logo

Portable Hardware Locality (hwloc) Documentation: v2.11.2

  |   Home   |   Support   |   FAQ   |  
distances.h
1/*
2 * Copyright © 2010-2024 Inria. All rights reserved.
3 * See COPYING in top-level directory.
4 */
5
10#ifndef HWLOC_DISTANCES_H
11#define HWLOC_DISTANCES_H
12
13#ifndef HWLOC_H
14#error Please include the main hwloc.h instead
15#endif
16
17
18#ifdef __cplusplus
19extern "C" {
20#elif 0
21}
22#endif
23
24
54 unsigned nbobjs;
60 unsigned long kind;
61 hwloc_uint64_t *values;
66};
67
110
136HWLOC_DECLSPEC int
138 unsigned *nr, struct hwloc_distances_s **distances,
139 unsigned long kind, unsigned long flags);
140
147HWLOC_DECLSPEC int
149 unsigned *nr, struct hwloc_distances_s **distances,
150 unsigned long kind, unsigned long flags);
151
158HWLOC_DECLSPEC int
160 unsigned *nr, struct hwloc_distances_s **distances,
161 unsigned long kind, unsigned long flags);
162
173HWLOC_DECLSPEC int
175 unsigned *nr, struct hwloc_distances_s **distances,
176 unsigned long flags);
177
188HWLOC_DECLSPEC const char *
190
195HWLOC_DECLSPEC void
197
245
274HWLOC_DECLSPEC int hwloc_distances_transform(hwloc_topology_t topology, struct hwloc_distances_s *distances,
275 enum hwloc_distances_transform_e transform,
276 void *transform_attr,
277 unsigned long flags);
278
292static __hwloc_inline int
294{
295 unsigned i;
296 for(i=0; i<distances->nbobjs; i++)
297 if (distances->objs[i] == obj)
298 return (int)i;
299 return -1;
300}
301
310static __hwloc_inline int
312 hwloc_obj_t obj1, hwloc_obj_t obj2,
313 hwloc_uint64_t *value1to2, hwloc_uint64_t *value2to1)
314{
315 int i1 = hwloc_distances_obj_index(distances, obj1);
316 int i2 = hwloc_distances_obj_index(distances, obj2);
317 if (i1 < 0 || i2 < 0)
318 return -1;
319 *value1to2 = distances->values[i1 * distances->nbobjs + i2];
320 *value2to1 = distances->values[i2 * distances->nbobjs + i1];
321 return 0;
322}
323
348
371HWLOC_DECLSPEC hwloc_distances_add_handle_t
373 const char *name, unsigned long kind,
374 unsigned long flags);
375
400 unsigned nbobjs, hwloc_obj_t *objs,
401 hwloc_uint64_t *values,
402 unsigned long flags);
403
419
438 unsigned long flags);
439
458HWLOC_DECLSPEC int hwloc_distances_remove(hwloc_topology_t topology);
459
466HWLOC_DECLSPEC int hwloc_distances_remove_by_depth(hwloc_topology_t topology, int depth);
467
474static __hwloc_inline int
476{
477 int depth = hwloc_get_type_depth(topology, type);
479 return 0;
480 return hwloc_distances_remove_by_depth(topology, depth);
481}
482
489HWLOC_DECLSPEC int hwloc_distances_release_remove(hwloc_topology_t topology, struct hwloc_distances_s *distances);
490
494#ifdef __cplusplus
495} /* extern "C" */
496#endif
497
498
499#endif /* HWLOC_DISTANCES_H */
hwloc_obj_type_t
Type of topology object.
Definition hwloc.h:197
struct hwloc_topology * hwloc_topology_t
Topology context.
Definition hwloc.h:742
int hwloc_get_type_depth(hwloc_topology_t topology, hwloc_obj_type_t type)
Returns the depth of objects of type type.
@ HWLOC_TYPE_DEPTH_UNKNOWN
No object of given type exists in the topology.
Definition hwloc.h:879
@ HWLOC_TYPE_DEPTH_MULTIPLE
Objects of given type exist at different depth in the topology (only for Groups).
Definition hwloc.h:880
void hwloc_distances_release(hwloc_topology_t topology, struct hwloc_distances_s *distances)
Release a distance matrix structure previously returned by hwloc_distances_get().
hwloc_distances_transform_e
Transformations of distances structures.
Definition distances.h:199
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.
int hwloc_distances_get(hwloc_topology_t topology, unsigned *nr, struct hwloc_distances_s **distances, unsigned long kind, unsigned long flags)
Retrieve distance matrices.
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.
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.
hwloc_distances_kind_e
Kinds of distance matrices.
Definition distances.h:78
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)
Apply a transformation to a distances structure.
const char * hwloc_distances_get_name(hwloc_topology_t topology, struct hwloc_distances_s *distances)
Get a description of what a distances structure contains.
@ HWLOC_DISTANCES_TRANSFORM_TRANSITIVE_CLOSURE
Apply a transitive closure to the matrix to connect objects across switches. This currently only appl...
Definition distances.h:243
@ HWLOC_DISTANCES_TRANSFORM_MERGE_SWITCH_PORTS
Merge switches with multiple ports into a single object. This currently only applies to NVSwitches wh...
Definition distances.h:236
@ HWLOC_DISTANCES_TRANSFORM_LINKS
Replace bandwidth values with a number of links.
Definition distances.h:227
@ HWLOC_DISTANCES_TRANSFORM_REMOVE_NULL
Remove NULL objects from the distances structure.
Definition distances.h:213
@ HWLOC_DISTANCES_KIND_FROM_USER
These distances were provided by the user.
Definition distances.h:86
@ HWLOC_DISTANCES_KIND_MEANS_BANDWIDTH
Distance values are similar to bandwidths between objects. Values are higher for closer objects,...
Definition distances.h:101
@ HWLOC_DISTANCES_KIND_FROM_OS
These distances were obtained from the operating system or hardware.
Definition distances.h:82
@ HWLOC_DISTANCES_KIND_HETEROGENEOUS_TYPES
This distances structure covers objects of different types. This may apply to the "NVLinkBandwidth" s...
Definition distances.h:108
@ HWLOC_DISTANCES_KIND_MEANS_LATENCY
Distance values are similar to latencies between objects. Values are smaller for closer objects,...
Definition distances.h:94
static int hwloc_distances_obj_pair_values(struct hwloc_distances_s *distances, hwloc_obj_t obj1, hwloc_obj_t obj2, hwloc_uint64_t *value1to2, hwloc_uint64_t *value2to1)
Find the values between two objects in a distance matrices.
Definition distances.h:311
static int hwloc_distances_obj_index(struct hwloc_distances_s *distances, hwloc_obj_t obj)
Find the index of an object in a distances structure.
Definition distances.h:293
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_flag_e
Flags for adding a new distances to a topology.
Definition distances.h:405
void * hwloc_distances_add_handle_t
Handle to a new distances structure during its addition to the topology.
Definition distances.h:347
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.
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.
@ HWLOC_DISTANCES_ADD_FLAG_GROUP_INACCURATE
If grouping, consider the distance values as inaccurate and relax the comparisons during the grouping...
Definition distances.h:417
@ HWLOC_DISTANCES_ADD_FLAG_GROUP
Try to group objects based on the newly provided distance information. Grouping is only performed whe...
Definition distances.h:411
int hwloc_distances_release_remove(hwloc_topology_t topology, struct hwloc_distances_s *distances)
Release and remove the given distance matrice from the topology.
static int hwloc_distances_remove_by_type(hwloc_topology_t topology, hwloc_obj_type_t type)
Remove distance matrices for objects of a specific type in the topology.
Definition distances.h:475
int hwloc_distances_remove_by_depth(hwloc_topology_t topology, int depth)
Remove distance matrices for objects at a specific depth in the topology.
int hwloc_distances_remove(hwloc_topology_t topology)
Remove all distance matrices from a topology.
Structure of a topology object.
Definition hwloc.h:431
Matrix of distances between a set of objects.
Definition distances.h:53
unsigned nbobjs
Number of objects described by the distance matrix.
Definition distances.h:54
hwloc_uint64_t * values
Matrix of distances between objects, stored as a one-dimension array.
Definition distances.h:61
unsigned long kind
OR'ed set of hwloc_distances_kind_e.
Definition distances.h:60
hwloc_obj_t * objs
Array of objects described by the distance matrix. These objects are not in any particular order,...
Definition distances.h:55