Debian Codegraph @

doc/doxygen-doc/man/man3/hwlocality_distances_get.3

raw
1 .TH "hwlocality_distances_get" 3 "Version 2.14.0" "Hardware Locality (hwloc)" \" -*- nroff -*-
2 .ad l
3 .nh
4 .SH NAME
5 hwlocality_distances_get \- Retrieve distances between objects
6 .SH SYNOPSIS
7 .br
8 .PP
9 .SS "Data Structures"
10
11 .in +1c
12 .ti -1c
13 .RI "struct \fBhwloc_distances_s\fP"
14 .br
15 .in -1c
16 .SS "Enumerations"
17
18 .in +1c
19 .ti -1c
20 .RI "enum \fBhwloc_distances_kind_e\fP { \fBHWLOC_DISTANCES_KIND_FROM_OS\fP, \fBHWLOC_DISTANCES_KIND_FROM_USER\fP, \fBHWLOC_DISTANCES_KIND_MEANS_LATENCY\fP, \fBHWLOC_DISTANCES_KIND_MEANS_BANDWIDTH\fP, \fBHWLOC_DISTANCES_KIND_HETEROGENEOUS_TYPES\fP }"
21 .br
22 .ti -1c
23 .RI "enum \fBhwloc_distances_transform_e\fP { \fBHWLOC_DISTANCES_TRANSFORM_REMOVE_NULL\fP, \fBHWLOC_DISTANCES_TRANSFORM_LINKS\fP, \fBHWLOC_DISTANCES_TRANSFORM_MERGE_SWITCH_PORTS\fP, \fBHWLOC_DISTANCES_TRANSFORM_TRANSITIVE_CLOSURE\fP }"
24 .br
25 .in -1c
26 .SS "Functions"
27
28 .in +1c
29 .ti -1c
30 .RI "int \fBhwloc_distances_get\fP (\fBhwloc_topology_t\fP topology, unsigned *nr, struct \fBhwloc_distances_s\fP **distances, unsigned long kind, unsigned long flags)"
31 .br
32 .ti -1c
33 .RI "int \fBhwloc_distances_get_by_depth\fP (\fBhwloc_topology_t\fP topology, int depth, unsigned *nr, struct \fBhwloc_distances_s\fP **distances, unsigned long kind, unsigned long flags)"
34 .br
35 .ti -1c
36 .RI "int \fBhwloc_distances_get_by_type\fP (\fBhwloc_topology_t\fP topology, \fBhwloc_obj_type_t\fP type, unsigned *nr, struct \fBhwloc_distances_s\fP **distances, unsigned long kind, unsigned long flags)"
37 .br
38 .ti -1c
39 .RI "int \fBhwloc_distances_get_by_name\fP (\fBhwloc_topology_t\fP topology, const char *name, unsigned *nr, struct \fBhwloc_distances_s\fP **distances, unsigned long flags)"
40 .br
41 .ti -1c
42 .RI "const char * \fBhwloc_distances_get_name\fP (\fBhwloc_topology_t\fP topology, struct \fBhwloc_distances_s\fP *distances)"
43 .br
44 .ti -1c
45 .RI "void \fBhwloc_distances_release\fP (\fBhwloc_topology_t\fP topology, struct \fBhwloc_distances_s\fP *distances)"
46 .br
47 .ti -1c
48 .RI "int \fBhwloc_distances_transform\fP (\fBhwloc_topology_t\fP topology, struct \fBhwloc_distances_s\fP *distances, enum \fBhwloc_distances_transform_e\fP transform, void *transform_attr, unsigned long flags)"
49 .br
50 .in -1c
51 .SH "Detailed Description"
52 .PP
53
54 .SH "Enumeration Type Documentation"
55 .PP
56 .SS "enum \fBhwloc_distances_kind_e\fP"
57
58 .PP
59 Kinds of distance matrices\&. The \fRkind\fP attribute of struct \fBhwloc_distances_s\fP is a OR'ed set of kinds\&.
60
61 .PP
62 Each distance matrix may have only one kind among HWLOC_DISTANCES_KIND_FROM_* specifying where distance information comes from, and one kind among HWLOC_DISTANCES_KIND_MEANS_* specifying whether values are latencies or bandwidths\&.
63 .PP
64 \fBEnumerator\fP
65 .in +1c
66 .TP
67 \f(BIHWLOC_DISTANCES_KIND_FROM_OS \fP
68 These distances were obtained from the operating system or hardware\&.
69 .TP
70 \f(BIHWLOC_DISTANCES_KIND_FROM_USER \fP
71 These distances were provided by the user\&.
72 .TP
73 \f(BIHWLOC_DISTANCES_KIND_MEANS_LATENCY \fP
74 Distance values are similar to latencies between objects\&. Values are smaller for closer objects, hence minimal on the diagonal of the matrix (distance between an object and itself)\&. It could also be the number of network hops between objects, etc\&.
75 .TP
76 \f(BIHWLOC_DISTANCES_KIND_MEANS_BANDWIDTH \fP
77 Distance values are similar to bandwidths between objects\&. Values are higher for closer objects, hence maximal on the diagonal of the matrix (distance between an object and itself)\&. Such values are currently ignored for distance-based grouping\&.
78 .TP
79 \f(BIHWLOC_DISTANCES_KIND_HETEROGENEOUS_TYPES \fP
80 This distances structure covers objects of different types\&. This may apply to the "NVLinkBandwidth" structure in presence of a NVSwitch or POWER processor NVLink port\&.
81 .SS "enum \fBhwloc_distances_transform_e\fP"
82
83 .PP
84 Transformations of distances structures\&.
85 .PP
86 \fBEnumerator\fP
87 .in +1c
88 .TP
89 \f(BIHWLOC_DISTANCES_TRANSFORM_REMOVE_NULL \fP
90 Remove \fRNULL\fP objects from the distances structure\&. Every object that was replaced with \fRNULL\fP in the \fRobjs\fP array is removed and the \fRvalues\fP array is updated accordingly\&.
91
92 .PP
93 At least \fR2\fP objects must remain, otherwise \fBhwloc_distances_transform()\fP will return \fR-1\fP with \fRerrno\fP set to \fREINVAL\fP\&.
94
95 .PP
96 \fRkind\fP will be updated with or without \fBHWLOC_DISTANCES_KIND_HETEROGENEOUS_TYPES\fP according to the remaining objects\&.
97 .TP
98 \f(BIHWLOC_DISTANCES_TRANSFORM_LINKS \fP
99 Replace bandwidth values with a number of links\&. Usually all values will be either \fR0\fP (no link) or \fR1\fP (one link)\&. However some matrices could get larger values if some pairs of peers are connected by different numbers of links\&.
100
101 .PP
102 Values on the diagonal are set to \fR0\fP\&.
103
104 .PP
105 This transformation only applies to bandwidth matrices\&.
106 .TP
107 \f(BIHWLOC_DISTANCES_TRANSFORM_MERGE_SWITCH_PORTS \fP
108 Merge switches with multiple ports into a single object\&. This currently only applies to NVSwitches where GPUs seem connected to different switch ports\&. Switch ports must be objects with subtype "NVSwitch" as in the NVLinkBandwidth matrix\&.
109
110 .PP
111 This transformation will replace all ports with only the first one, now connected to all GPUs\&. Other ports are removed by applying \fBHWLOC_DISTANCES_TRANSFORM_REMOVE_NULL\fP internally\&.
112 .TP
113 \f(BIHWLOC_DISTANCES_TRANSFORM_TRANSITIVE_CLOSURE \fP
114 Apply a transitive closure to the matrix to connect objects across switches\&. All pairs of GPUs will be reported as directly connected instead GPUs being only connected to switches\&.
115
116 .PP
117 Switch ports must be objects with subtype "NVSwitch" as in the NVLinkBandwidth matrix\&.
118 .SH "Function Documentation"
119 .PP
120 .SS "int hwloc_distances_get (\fBhwloc_topology_t\fP topology, unsigned * nr, struct \fBhwloc_distances_s\fP ** distances, unsigned long kind, unsigned long flags)"
121
122 .PP
123 Retrieve distance matrices\&. Retrieve distance matrices from the topology into the \fRdistances\fP array\&.
124
125 .PP
126 \fRflags\fP is currently unused, should be \fR0\fP\&.
127
128 .PP
129 \fRkind\fP serves as a filter\&. If \fR0\fP, all distance matrices are returned\&. If it contains some HWLOC_DISTANCES_KIND_FROM_*, only distance matrices whose kind matches one of these are returned\&. If it contains some HWLOC_DISTANCES_KIND_MEANS_*, only distance matrices whose kind matches one of these are returned\&.
130
131 .PP
132 On input, \fRnr\fP points to the number of distance matrices that may be stored in \fRdistances\fP\&. On output, \fRnr\fP points to the number of distance matrices that were actually found, even if some of them couldn't be stored in \fRdistances\fP\&. Distance matrices that couldn't be stored are ignored, but the function still returns success (\fR0\fP)\&. The caller may find out by comparing the value pointed by \fRnr\fP before and after the function call\&.
133
134 .PP
135 Each distance matrix returned in the \fRdistances\fP array should be released by the caller using \fBhwloc_distances_release()\fP\&.
136
137 .PP
138 \fBReturns\fP
139 .RS 4
140 0 on success, -1 on error\&.
141 .RE
142 .PP
143
144 .SS "int hwloc_distances_get_by_depth (\fBhwloc_topology_t\fP topology, int depth, unsigned * nr, struct \fBhwloc_distances_s\fP ** distances, unsigned long kind, unsigned long flags)"
145
146 .PP
147 Retrieve distance matrices for object at a specific depth in the topology\&. Identical to \fBhwloc_distances_get()\fP with the additional \fRdepth\fP filter\&.
148
149 .PP
150 \fBReturns\fP
151 .RS 4
152 0 on success, -1 on error\&.
153 .RE
154 .PP
155
156 .SS "int hwloc_distances_get_by_name (\fBhwloc_topology_t\fP topology, const char * name, unsigned * nr, struct \fBhwloc_distances_s\fP ** distances, unsigned long flags)"
157
158 .PP
159 Retrieve a distance matrix with the given name\&. Usually only one distances structure may match a given name\&.
160
161 .PP
162 The name of the most common structure is "NUMALatency"\&. Others include "XGMIBandwidth", "XGMIHops", "XeLinkBandwidth", and "NVLinkBandwidth"\&.
163
164 .PP
165 \fBReturns\fP
166 .RS 4
167 0 on success, -1 on error\&.
168 .RE
169 .PP
170
171 .SS "int hwloc_distances_get_by_type (\fBhwloc_topology_t\fP topology, \fBhwloc_obj_type_t\fP type, unsigned * nr, struct \fBhwloc_distances_s\fP ** distances, unsigned long kind, unsigned long flags)"
172
173 .PP
174 Retrieve distance matrices for object of a specific type\&. Identical to \fBhwloc_distances_get()\fP with the additional \fRtype\fP filter\&.
175
176 .PP
177 \fBReturns\fP
178 .RS 4
179 0 on success, -1 on error\&.
180 .RE
181 .PP
182
183 .SS "const char * hwloc_distances_get_name (\fBhwloc_topology_t\fP topology, struct \fBhwloc_distances_s\fP * distances)"
184
185 .PP
186 Get a description of what a distances structure contains\&. For instance "NUMALatency" for hardware-provided NUMA distances (ACPI SLIT), or \fRNULL\fP if unknown\&.
187
188 .PP
189 \fBReturns\fP
190 .RS 4
191 the constant string with the name of the distance structure\&.
192 .RE
193 .PP
194 \fBNote\fP
195 .RS 4
196 The returned name should not be freed by the caller, it belongs to the hwloc library\&.
197 .RE
198 .PP
199
200 .SS "void hwloc_distances_release (\fBhwloc_topology_t\fP topology, struct \fBhwloc_distances_s\fP * distances)"
201
202 .PP
203 Release a distance matrix structure previously returned by \fBhwloc_distances_get()\fP\&.
204 .PP
205 \fBNote\fP
206 .RS 4
207 This function is not required if the structure is removed with \fBhwloc_distances_release_remove()\fP\&.
208 .RE
209 .PP
210
211 .SS "int hwloc_distances_transform (\fBhwloc_topology_t\fP topology, struct \fBhwloc_distances_s\fP * distances, enum \fBhwloc_distances_transform_e\fP transform, void * transform_attr, unsigned long flags)"
212
213 .PP
214 Apply a transformation to a distances structure\&. Modify a distances structure that was previously obtained with \fBhwloc_distances_get()\fP or one of its variants\&.
215
216 .PP
217 This modifies the local copy of the distances structures but does not modify the distances information stored inside the topology (retrieved by another call to \fBhwloc_distances_get()\fP or exported to XML)\&. To do so, one should add a new distances structure with same name, kind, objects and values (see \fBAdd distances between objects\fP) and then remove this old one with \fBhwloc_distances_release_remove()\fP\&.
218
219 .PP
220 \fRtransform\fP must be one of the transformations listed in \fBhwloc_distances_transform_e\fP\&.
221
222 .PP
223 These transformations may modify the contents of the \fRobjs\fP or \fRvalues\fP arrays\&.
224
225 .PP
226 \fRtransform_attr\fP must be \fRNULL\fP for now\&.
227
228 .PP
229 \fRflags\fP must be \fR0\fP for now\&.
230
231 .PP
232 \fBReturns\fP
233 .RS 4
234 0 on success, -1 on error for instance if flags are invalid\&.
235 .RE
236 .PP
237 \fBNote\fP
238 .RS 4
239 Objects in distances array \fRobjs\fP may be directly modified in place without using \fBhwloc_distances_transform()\fP\&. One may use \fBhwloc_get_obj_with_same_locality()\fP to easily convert between similar objects of different types\&.
240 .RE
241 .PP
242
243 .SH "Author"
244 .PP
245 Generated automatically by Doxygen for Hardware Locality (hwloc) from the source code\&.