Hardware Locality (hwloc)  2.10.0
distances.h
1 /*
2  * Copyright © 2010-2023 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
19 extern "C" {
20 #elif 0
21 }
22 #endif
23 
24 
54  unsigned nbobjs;
60  unsigned long kind;
61  hwloc_uint64_t *values;
66 };
67 
88 
103 
110 };
111 
137 HWLOC_DECLSPEC int
139  unsigned *nr, struct hwloc_distances_s **distances,
140  unsigned long kind, unsigned long flags);
141 
148 HWLOC_DECLSPEC int
150  unsigned *nr, struct hwloc_distances_s **distances,
151  unsigned long kind, unsigned long flags);
152 
159 HWLOC_DECLSPEC int
161  unsigned *nr, struct hwloc_distances_s **distances,
162  unsigned long kind, unsigned long flags);
163 
174 HWLOC_DECLSPEC int
175 hwloc_distances_get_by_name(hwloc_topology_t topology, const char *name,
176  unsigned *nr, struct hwloc_distances_s **distances,
177  unsigned long flags);
178 
189 HWLOC_DECLSPEC const char *
190 hwloc_distances_get_name(hwloc_topology_t topology, struct hwloc_distances_s *distances);
191 
196 HWLOC_DECLSPEC void
197 hwloc_distances_release(hwloc_topology_t topology, struct hwloc_distances_s *distances);
198 
215 
229 
238 
245 };
246 
275 HWLOC_DECLSPEC int hwloc_distances_transform(hwloc_topology_t topology, struct hwloc_distances_s *distances,
276  enum hwloc_distances_transform_e transform,
277  void *transform_attr,
278  unsigned long flags);
279 
293 static __hwloc_inline int
295 {
296  unsigned i;
297  for(i=0; i<distances->nbobjs; i++)
298  if (distances->objs[i] == obj)
299  return (int)i;
300  return -1;
301 }
302 
311 static __hwloc_inline int
313  hwloc_obj_t obj1, hwloc_obj_t obj2,
314  hwloc_uint64_t *value1to2, hwloc_uint64_t *value2to1)
315 {
316  int i1 = hwloc_distances_obj_index(distances, obj1);
317  int i2 = hwloc_distances_obj_index(distances, obj2);
318  if (i1 < 0 || i2 < 0)
319  return -1;
320  *value1to2 = distances->values[i1 * distances->nbobjs + i2];
321  *value2to1 = distances->values[i2 * distances->nbobjs + i1];
322  return 0;
323 }
324 
349 
370 HWLOC_DECLSPEC hwloc_distances_add_handle_t
372  const char *name, unsigned long kind,
373  unsigned long flags);
374 
397 HWLOC_DECLSPEC int hwloc_distances_add_values(hwloc_topology_t topology,
398  hwloc_distances_add_handle_t handle,
399  unsigned nbobjs, hwloc_obj_t *objs,
400  hwloc_uint64_t *values,
401  unsigned long flags);
402 
416 };
417 
434 HWLOC_DECLSPEC int hwloc_distances_add_commit(hwloc_topology_t topology,
435  hwloc_distances_add_handle_t handle,
436  unsigned long flags);
437 
456 HWLOC_DECLSPEC int hwloc_distances_remove(hwloc_topology_t topology);
457 
464 HWLOC_DECLSPEC int hwloc_distances_remove_by_depth(hwloc_topology_t topology, int depth);
465 
472 static __hwloc_inline int
474 {
475  int depth = hwloc_get_type_depth(topology, type);
476  if (depth == HWLOC_TYPE_DEPTH_UNKNOWN || depth == HWLOC_TYPE_DEPTH_MULTIPLE)
477  return 0;
478  return hwloc_distances_remove_by_depth(topology, depth);
479 }
480 
487 HWLOC_DECLSPEC int hwloc_distances_release_remove(hwloc_topology_t topology, struct hwloc_distances_s *distances);
488 
492 #ifdef __cplusplus
493 } /* extern "C" */
494 #endif
495 
496 
497 #endif /* HWLOC_DISTANCES_H */
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.
No object of given type exists in the topology.
Definition: hwloc.h:879
Structure of a topology object.
Definition: hwloc.h:431
void hwloc_distances_release(hwloc_topology_t topology, struct hwloc_distances_s *distances)
Release a distance matrix structure previously returned by hwloc_distances_get(). ...
Apply a transitive closure to the matrix to connect objects across switches. This currently only appl...
Definition: distances.h:244
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.
const char * hwloc_distances_get_name(hwloc_topology_t topology, struct hwloc_distances_s *distances)
Get a description of what a distances structure contains.
Objects of given type exist at different depth in the topology (only for Groups). ...
Definition: hwloc.h:880
int hwloc_distances_remove(hwloc_topology_t topology)
Remove all distance matrices from a topology.
hwloc_distances_add_flag_e
Flags for adding a new distances to a topology.
Definition: distances.h:404
Merge switches with multiple ports into a single object. This currently only applies to NVSwitches wh...
Definition: distances.h:237
hwloc_uint64_t * values
Matrix of distances between objects, stored as a one-dimension array.
Definition: distances.h:61
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:473
hwloc_distances_transform_e
Transformations of distances structures.
Definition: distances.h:200
unsigned long kind
OR&#39;ed set of hwloc_distances_kind_e.
Definition: distances.h:60
Try to group objects based on the newly provided distance information. This is ignored for distances ...
Definition: distances.h:409
hwloc_obj_t * objs
Array of objects described by the distance matrix. These objects are not in any particular order...
Definition: distances.h:55
int hwloc_get_type_depth(hwloc_topology_t topology, hwloc_obj_type_t type)
Returns the depth of objects of type type.
These distances were obtained from the operating system or hardware.
Definition: distances.h:83
hwloc_obj_type_t
Type of topology object.
Definition: hwloc.h:197
Replace bandwidth values with a number of links.
Definition: distances.h:228
unsigned nbobjs
Number of objects described by the distance matrix.
Definition: distances.h:54
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:294
int hwloc_distances_release_remove(hwloc_topology_t topology, struct hwloc_distances_s *distances)
Release and remove the given distance matrice from the topology.
int hwloc_distances_add_commit(hwloc_topology_t topology, hwloc_distances_add_handle_t handle, unsigned long flags)
Commit a new distances structure.
Remove NULL objects from the distances structure.
Definition: distances.h:214
Distance values are similar to latencies between objects. Values are smaller for closer objects...
Definition: distances.h:95
This distances structure covers objects of different types. This may apply to the "NVLinkBandwidth" s...
Definition: distances.h:109
struct hwloc_topology * hwloc_topology_t
Topology context.
Definition: hwloc.h:742
If grouping, consider the distance values as inaccurate and relax the comparisons during the grouping...
Definition: distances.h:415
int hwloc_distances_remove_by_depth(hwloc_topology_t topology, int depth)
Remove distance matrices for objects at a specific depth in the topology.
Distance values are similar to bandwidths between objects. Values are higher for closer objects...
Definition: distances.h:102
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.
These distances were provided by the user.
Definition: distances.h:87
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_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.
Matrix of distances between a set of objects.
Definition: distances.h:53
hwloc_distances_kind_e
Kinds of distance matrices.
Definition: distances.h:79
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_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.
void * hwloc_distances_add_handle_t
Handle to a new distances structure during its addition to the topology.
Definition: distances.h:348
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:312