Hardware Locality (hwloc): distances.h Source File

Hardware Locality (hwloc) 2.14.0rc1

distances.h
1/*
2 * SPDX-License-Identifier: BSD-3-Clause
3 * Copyright © 2010-2025 Inria. All rights reserved.
4 * See COPYING in top-level directory.
5 */
6
10
11#ifndef HWLOC_DISTANCES_H
12#define HWLOC_DISTANCES_H
13
14#ifndef HWLOC_H
15#error Please include the main hwloc.h instead
16#endif
17
18
19#ifdef __cplusplus
20extern "C" {
21#elif 0
22}
23#endif
24
25
29
54 struct hwloc_distances_s {
55 unsigned nbobjs;
56 hwloc_obj_t *objs;
61 unsigned long kind;
62 hwloc_uint64_t *values;
67};
68
79 enum hwloc_distances_kind_e {
83 HWLOC_DISTANCES_KIND_FROM_OS = (1UL<<0),
87 HWLOC_DISTANCES_KIND_FROM_USER = (1UL<<1),
88
95 HWLOC_DISTANCES_KIND_MEANS_LATENCY = (1UL<<2),
102 HWLOC_DISTANCES_KIND_MEANS_BANDWIDTH = (1UL<<3),
103
109 HWLOC_DISTANCES_KIND_HETEROGENEOUS_TYPES = (1UL<<4)
110};
111
137HWLOC_DECLSPEC int
138hwloc_distances_get(hwloc_topology_t topology,
139 unsigned *nr, struct hwloc_distances_s **distances,
140 unsigned long kind, unsigned long flags);
141
148HWLOC_DECLSPEC int
149hwloc_distances_get_by_depth(hwloc_topology_t topology, int depth,
150 unsigned *nr, struct hwloc_distances_s **distances,
151 unsigned long kind, unsigned long flags);
152
159HWLOC_DECLSPEC int
160hwloc_distances_get_by_type(hwloc_topology_t topology, hwloc_obj_type_t type,
161 unsigned *nr, struct hwloc_distances_s **distances,
162 unsigned long kind, unsigned long flags);
163
174HWLOC_DECLSPEC int
175hwloc_distances_get_by_name(hwloc_topology_t topology, const char *name,
176 unsigned *nr, struct hwloc_distances_s **distances,
177 unsigned long flags);
178
189HWLOC_DECLSPEC const char *
190hwloc_distances_get_name(hwloc_topology_t topology, struct hwloc_distances_s *distances);
191
196HWLOC_DECLSPEC void
197hwloc_distances_release(hwloc_topology_t topology, struct hwloc_distances_s *distances);
198
200 enum hwloc_distances_transform_e {
214 HWLOC_DISTANCES_TRANSFORM_REMOVE_NULL = 0,
215
228 HWLOC_DISTANCES_TRANSFORM_LINKS = 1,
229
241 HWLOC_DISTANCES_TRANSFORM_MERGE_SWITCH_PORTS = 2,
242
251 HWLOC_DISTANCES_TRANSFORM_TRANSITIVE_CLOSURE = 3
252};
253
282HWLOC_DECLSPEC int hwloc_distances_transform(hwloc_topology_t topology, struct hwloc_distances_s *distances,
283 enum hwloc_distances_transform_e transform,
284 void *transform_attr,
285 unsigned long flags);
286
288
289
290
294
300static __hwloc_inline int
301hwloc_distances_obj_index(struct hwloc_distances_s *distances, hwloc_obj_t obj)
302{
303 unsigned i;
304 for(i=0; i<distances->nbobjs; i++)
305 if (distances->objs[i] == obj)
306 return (int)i;
307 return -1;
308}
309
318static __hwloc_inline int
319hwloc_distances_obj_pair_values(struct hwloc_distances_s *distances,
320 hwloc_obj_t obj1, hwloc_obj_t obj2,
321 hwloc_uint64_t *value1to2, hwloc_uint64_t *value2to1)
322{
323 int i1 = hwloc_distances_obj_index(distances, obj1);
324 int i2 = hwloc_distances_obj_index(distances, obj2);
325 if (i1 < 0 || i2 < 0)
326 return -1;
327 *value1to2 = distances->values[i1 * distances->nbobjs + i2];
328 *value2to1 = distances->values[i2 * distances->nbobjs + i1];
329 return 0;
330}
331
333
334
335
353
355 typedef void * hwloc_distances_add_handle_t;
356
379HWLOC_DECLSPEC hwloc_distances_add_handle_t
380hwloc_distances_add_create(hwloc_topology_t topology,
381 const char *name, unsigned long kind,
382 unsigned long flags);
383
406HWLOC_DECLSPEC int hwloc_distances_add_values(hwloc_topology_t topology,
407 hwloc_distances_add_handle_t handle,
408 unsigned nbobjs, hwloc_obj_t *objs,
409 hwloc_uint64_t *values,
410 unsigned long flags);
411
413 enum hwloc_distances_add_flag_e {
419 HWLOC_DISTANCES_ADD_FLAG_GROUP = (1UL<<0),
425 HWLOC_DISTANCES_ADD_FLAG_GROUP_INACCURATE = (1UL<<1)
426};
427
444HWLOC_DECLSPEC int hwloc_distances_add_commit(hwloc_topology_t topology,
445 hwloc_distances_add_handle_t handle,
446 unsigned long flags);
447
449
450
451
455
466HWLOC_DECLSPEC int hwloc_distances_remove(hwloc_topology_t topology);
467
474HWLOC_DECLSPEC int hwloc_distances_remove_by_depth(hwloc_topology_t topology, int depth);
475
482static __hwloc_inline int
483hwloc_distances_remove_by_type(hwloc_topology_t topology, hwloc_obj_type_t type)
484{
485 int depth = hwloc_get_type_depth(topology, type);
486 if (depth == HWLOC_TYPE_DEPTH_UNKNOWN || depth == HWLOC_TYPE_DEPTH_MULTIPLE)
487 return 0;
488 return hwloc_distances_remove_by_depth(topology, depth);
489}
490
497HWLOC_DECLSPEC int hwloc_distances_release_remove(hwloc_topology_t topology, struct hwloc_distances_s *distances);
498
500
501
502#ifdef __cplusplus
503} /* extern "C" */
504#endif
505
506
507#endif /* HWLOC_DISTANCES_H */
hwloc_obj_type_t
hwloc_obj_type_t
Type of topology object.
Definition hwloc.h:202
hwloc_obj_t
struct hwloc_obj * hwloc_obj_t
Convenience typedef; a pointer to a struct hwloc_obj.
Definition hwloc.h:637
hwloc_topology_t
struct hwloc_topology * hwloc_topology_t
Topology context.
Definition hwloc.h:748
hwloc_get_type_depth
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
@ HWLOC_TYPE_DEPTH_UNKNOWN
No object of given type exists in the topology.
Definition hwloc.h:885
HWLOC_TYPE_DEPTH_MULTIPLE
@ HWLOC_TYPE_DEPTH_MULTIPLE
Objects of given type exist at different depth in the topology (only for Groups).
Definition hwloc.h:886
hwloc_distances_release
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
hwloc_distances_transform_e
Transformations of distances structures.
Definition distances.h:200
hwloc_distances_get_by_depth
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.
hwloc_distances_get
int hwloc_distances_get(hwloc_topology_t topology, unsigned *nr, struct hwloc_distances_s **distances, unsigned long kind, unsigned long flags)
Retrieve distance matrices.
hwloc_distances_get_by_name
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.
hwloc_distances_get_by_type
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
hwloc_distances_kind_e
Kinds of distance matrices.
Definition distances.h:79
hwloc_distances_transform
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.
hwloc_distances_get_name
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
@ HWLOC_DISTANCES_TRANSFORM_TRANSITIVE_CLOSURE
Apply a transitive closure to the matrix to connect objects across switches.
Definition distances.h:251
HWLOC_DISTANCES_TRANSFORM_MERGE_SWITCH_PORTS
@ HWLOC_DISTANCES_TRANSFORM_MERGE_SWITCH_PORTS
Merge switches with multiple ports into a single object.
Definition distances.h:241
HWLOC_DISTANCES_TRANSFORM_LINKS
@ HWLOC_DISTANCES_TRANSFORM_LINKS
Replace bandwidth values with a number of links.
Definition distances.h:228
HWLOC_DISTANCES_TRANSFORM_REMOVE_NULL
@ HWLOC_DISTANCES_TRANSFORM_REMOVE_NULL
Remove NULL objects from the distances structure.
Definition distances.h:214
HWLOC_DISTANCES_KIND_FROM_USER
@ HWLOC_DISTANCES_KIND_FROM_USER
These distances were provided by the user.
Definition distances.h:87
HWLOC_DISTANCES_KIND_MEANS_BANDWIDTH
@ HWLOC_DISTANCES_KIND_MEANS_BANDWIDTH
Distance values are similar to bandwidths between objects. Values are higher for closer objects,...
Definition distances.h:102
HWLOC_DISTANCES_KIND_FROM_OS
@ HWLOC_DISTANCES_KIND_FROM_OS
These distances were obtained from the operating system or hardware.
Definition distances.h:83
HWLOC_DISTANCES_KIND_HETEROGENEOUS_TYPES
@ HWLOC_DISTANCES_KIND_HETEROGENEOUS_TYPES
This distances structure covers objects of different types. This may apply to the "NVLinkBandwidth" s...
Definition distances.h:109
HWLOC_DISTANCES_KIND_MEANS_LATENCY
@ HWLOC_DISTANCES_KIND_MEANS_LATENCY
Distance values are similar to latencies between objects. Values are smaller for closer objects,...
Definition distances.h:95
hwloc_distances_obj_pair_values
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:319
hwloc_distances_obj_index
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:301
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_flag_e
hwloc_distances_add_flag_e
Flags for adding a new distances to a topology.
Definition distances.h:413
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:355
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.
HWLOC_DISTANCES_ADD_FLAG_GROUP_INACCURATE
@ HWLOC_DISTANCES_ADD_FLAG_GROUP_INACCURATE
If grouping, consider the distance values as inaccurate and relax the comparisons during the grouping...
Definition distances.h:425
HWLOC_DISTANCES_ADD_FLAG_GROUP
@ HWLOC_DISTANCES_ADD_FLAG_GROUP
Try to group objects based on the newly provided distance information. Grouping is only performed whe...
Definition distances.h:419
hwloc_distances_release_remove
int hwloc_distances_release_remove(hwloc_topology_t topology, struct hwloc_distances_s *distances)
Release and remove the given distance matrice from the topology.
hwloc_distances_remove_by_depth
int hwloc_distances_remove_by_depth(hwloc_topology_t topology, int depth)
Remove distance matrices for objects at a specific depth in the topology.
hwloc_distances_remove
int hwloc_distances_remove(hwloc_topology_t topology)
Remove all distance matrices from a topology.
hwloc_distances_remove_by_type
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:483
hwloc_distances_s
Matrix of distances between a set of objects.
Definition distances.h:54
hwloc_distances_s::nbobjs
unsigned nbobjs
Number of objects described by the distance matrix.
Definition distances.h:55
hwloc_distances_s::values
hwloc_uint64_t * values
Matrix of distances between objects, stored as a one-dimension array.
Definition distances.h:62
hwloc_distances_s::kind
unsigned long kind
OR'ed set of hwloc_distances_kind_e.
Definition distances.h:61
hwloc_distances_s::objs
hwloc_obj_t * objs
Array of objects described by the distance matrix. These objects are not in any particular order,...
Definition distances.h:56