Debian Codegraph @

doc/doxygen-doc/html/a00191.html

raw
1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
2 <html xmlns="http://www.w3.org/1999/xhtml" lang="en-US">
3 <head>
4 <meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
5 <meta http-equiv="X-UA-Compatible" content="IE=11"/>
6 <meta name="generator" content="Doxygen 1.15.0"/>
7 <meta name="viewport" content="width=device-width, initial-scale=1"/>
8 <title>Hardware Locality (hwloc): Retrieve distances between objects</title>
9 <link href="tabs.css" rel="stylesheet" type="text/css"/>
10 <script type="text/javascript" src="jquery.js"></script>
11 <script type="text/javascript" src="dynsections.js"></script>
12 <script type="text/javascript" src="clipboard.js"></script>
13 <link href="doxygen.css" rel="stylesheet" type="text/css" />
14 </head>
15 <body>
16 <div id="top"><!-- do not remove this div, it is closed by doxygen! -->
17 <div id="titlearea">
18 <table cellspacing="0" cellpadding="0">
19 <tbody>
20 <tr id="projectrow">
21 <td id="projectalign">
22 <div id="projectname">Hardware Locality (hwloc)<span id="projectnumber">&#160;2.14.0</span>
23 </div>
24 </td>
25 </tr>
26 </tbody>
27 </table>
28 </div>
29 <!-- end header part -->
30 <!-- Generated by Doxygen 1.15.0 -->
31 <script type="text/javascript">
32 $(function() { codefold.init(); });
33 </script>
34 <script type="text/javascript" src="menudata.js"></script>
35 <script type="text/javascript" src="menu.js"></script>
36 <script type="text/javascript">
37 $(function() {
38 initMenu('',false,false,'search.php','Search',false);
39 });
40 </script>
41 <div id="main-nav"></div>
42 </div><!-- top -->
43 <div id="doc-content">
44 <div class="header">
45 <div class="summary">
46 <a href="#nested-classes">Data Structures</a> &#124;
47 <a href="#enum-members">Enumerations</a> &#124;
48 <a href="#func-members">Functions</a> </div>
49 <div class="headertitle"><div class="title">Retrieve distances between objects </div></div>
50 </div><!--header-->
51 <div class="contents">
52 <table class="memberdecls">
53 <tr class="heading"><td colspan="2"><h2 id="header-nested-classes" class="groupheader"><a id="nested-classes" name="nested-classes"></a>
54 Data Structures</h2></td></tr>
55 <tr class="memitem:hwloc_5Fdistances_5Fs" id="r_hwloc_5Fdistances_5Fs"><td class="memItemLeft" align="right" valign="top">struct &#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="a00296.html">hwloc_distances_s</a></td></tr>
56 </table><table class="memberdecls">
57 <tr class="heading"><td colspan="2"><h2 id="header-enum-members" class="groupheader"><a id="enum-members" name="enum-members"></a>
58 Enumerations</h2></td></tr>
59 <tr class="memitem:gab1bb10d3adb85b52cdc6fe5a7f74f108" id="r_gab1bb10d3adb85b52cdc6fe5a7f74f108"><td class="memItemLeft" align="right" valign="top">enum &#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="#gab1bb10d3adb85b52cdc6fe5a7f74f108">hwloc_distances_kind_e</a> { <br />
60 &#160;&#160;<a class="el" href="#ggab1bb10d3adb85b52cdc6fe5a7f74f108a90dc38248c8d5392d4dd3e88f391e984">HWLOC_DISTANCES_KIND_FROM_OS</a>
61 , <a class="el" href="#ggab1bb10d3adb85b52cdc6fe5a7f74f108a0148d7f9be833a04f5a55455437c227b">HWLOC_DISTANCES_KIND_FROM_USER</a>
62 , <a class="el" href="#ggab1bb10d3adb85b52cdc6fe5a7f74f108afd6a3503fbc8f7c1a31235373cefc4c6">HWLOC_DISTANCES_KIND_MEANS_LATENCY</a>
63 , <a class="el" href="#ggab1bb10d3adb85b52cdc6fe5a7f74f108a41b19f141a3c0ffe85f9affaca4b0293">HWLOC_DISTANCES_KIND_MEANS_BANDWIDTH</a>
64 , <br />
65 &#160;&#160;<a class="el" href="#ggab1bb10d3adb85b52cdc6fe5a7f74f108aa6cf2b6dfcf148b65952f811814efbe1">HWLOC_DISTANCES_KIND_HETEROGENEOUS_TYPES</a>
66 <br />
67 }</td></tr>
68 <tr class="memitem:ga42859b651adec5ef0aaacb53ff220b00" id="r_ga42859b651adec5ef0aaacb53ff220b00"><td class="memItemLeft" align="right" valign="top">enum &#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="#ga42859b651adec5ef0aaacb53ff220b00">hwloc_distances_transform_e</a> { <a class="el" href="#gga42859b651adec5ef0aaacb53ff220b00a4b7bdb7e3ccca30e03b7ae671e7f6dc1">HWLOC_DISTANCES_TRANSFORM_REMOVE_NULL</a>
69 , <a class="el" href="#gga42859b651adec5ef0aaacb53ff220b00a441e6bb393558319af3bb1f89f51f44d">HWLOC_DISTANCES_TRANSFORM_LINKS</a>
70 , <a class="el" href="#gga42859b651adec5ef0aaacb53ff220b00a3d2aaf03e17be54eddbb94aab327fded">HWLOC_DISTANCES_TRANSFORM_MERGE_SWITCH_PORTS</a>
71 , <a class="el" href="#gga42859b651adec5ef0aaacb53ff220b00a1264abf9b9463f252995f37eb1057047">HWLOC_DISTANCES_TRANSFORM_TRANSITIVE_CLOSURE</a>
72 }</td></tr>
73 </table><table class="memberdecls">
74 <tr class="heading"><td colspan="2"><h2 id="header-func-members" class="groupheader"><a id="func-members" name="func-members"></a>
75 Functions</h2></td></tr>
76 <tr class="memitem:ga613e6b2a5d0f06626ee8d0c12fa46691" id="r_ga613e6b2a5d0f06626ee8d0c12fa46691"><td class="memItemLeft" align="right" valign="top">int&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="#ga613e6b2a5d0f06626ee8d0c12fa46691">hwloc_distances_get</a> (<a class="el" href="a00169.html#ga9d1e76ee15a7dee158b786c30b6a6e38">hwloc_topology_t</a> topology, unsigned *nr, struct <a class="el" href="a00296.html">hwloc_distances_s</a> **distances, unsigned long kind, unsigned long flags)</td></tr>
77 <tr class="memitem:ga5d1d35eccfcc2ebcef71a10972ce9b03" id="r_ga5d1d35eccfcc2ebcef71a10972ce9b03"><td class="memItemLeft" align="right" valign="top">int&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="#ga5d1d35eccfcc2ebcef71a10972ce9b03">hwloc_distances_get_by_depth</a> (<a class="el" href="a00169.html#ga9d1e76ee15a7dee158b786c30b6a6e38">hwloc_topology_t</a> topology, int depth, unsigned *nr, struct <a class="el" href="a00296.html">hwloc_distances_s</a> **distances, unsigned long kind, unsigned long flags)</td></tr>
78 <tr class="memitem:gaaa6bfbc20072a4f4de132eec859067f6" id="r_gaaa6bfbc20072a4f4de132eec859067f6"><td class="memItemLeft" align="right" valign="top">int&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="#gaaa6bfbc20072a4f4de132eec859067f6">hwloc_distances_get_by_type</a> (<a class="el" href="a00169.html#ga9d1e76ee15a7dee158b786c30b6a6e38">hwloc_topology_t</a> topology, <a class="el" href="a00167.html#gacd37bb612667dc437d66bfb175a8dc55">hwloc_obj_type_t</a> type, unsigned *nr, struct <a class="el" href="a00296.html">hwloc_distances_s</a> **distances, unsigned long kind, unsigned long flags)</td></tr>
79 <tr class="memitem:gaa457f35b8745ca41ec17797c0d7b20f0" id="r_gaa457f35b8745ca41ec17797c0d7b20f0"><td class="memItemLeft" align="right" valign="top">int&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="#gaa457f35b8745ca41ec17797c0d7b20f0">hwloc_distances_get_by_name</a> (<a class="el" href="a00169.html#ga9d1e76ee15a7dee158b786c30b6a6e38">hwloc_topology_t</a> topology, const char *name, unsigned *nr, struct <a class="el" href="a00296.html">hwloc_distances_s</a> **distances, unsigned long flags)</td></tr>
80 <tr class="memitem:gaff5366e26178f77d5e8dc3ac8863f2ed" id="r_gaff5366e26178f77d5e8dc3ac8863f2ed"><td class="memItemLeft" align="right" valign="top">const char *&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="#gaff5366e26178f77d5e8dc3ac8863f2ed">hwloc_distances_get_name</a> (<a class="el" href="a00169.html#ga9d1e76ee15a7dee158b786c30b6a6e38">hwloc_topology_t</a> topology, struct <a class="el" href="a00296.html">hwloc_distances_s</a> *distances)</td></tr>
81 <tr class="memitem:ga1dd78c1f9acd54f26aba0e284e97e51d" id="r_ga1dd78c1f9acd54f26aba0e284e97e51d"><td class="memItemLeft" align="right" valign="top">void&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="#ga1dd78c1f9acd54f26aba0e284e97e51d">hwloc_distances_release</a> (<a class="el" href="a00169.html#ga9d1e76ee15a7dee158b786c30b6a6e38">hwloc_topology_t</a> topology, struct <a class="el" href="a00296.html">hwloc_distances_s</a> *distances)</td></tr>
82 <tr class="memitem:gabcadd041f3072999d68f2d94e38670f7" id="r_gabcadd041f3072999d68f2d94e38670f7"><td class="memItemLeft" align="right" valign="top">int&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="#gabcadd041f3072999d68f2d94e38670f7">hwloc_distances_transform</a> (<a class="el" href="a00169.html#ga9d1e76ee15a7dee158b786c30b6a6e38">hwloc_topology_t</a> topology, struct <a class="el" href="a00296.html">hwloc_distances_s</a> *distances, enum <a class="el" href="#ga42859b651adec5ef0aaacb53ff220b00">hwloc_distances_transform_e</a> transform, void *transform_attr, unsigned long flags)</td></tr>
83 </table>
84 <a name="details" id="details"></a><h2 id="header-details" class="groupheader">Detailed Description</h2>
85 <a name="doc-enum-members" id="doc-enum-members"></a><h2 id="header-doc-enum-members" class="groupheader">Enumeration Type Documentation</h2>
86 <a id="gab1bb10d3adb85b52cdc6fe5a7f74f108" name="gab1bb10d3adb85b52cdc6fe5a7f74f108"></a>
87 <h2 class="memtitle"><span class="permalink"><a href="#gab1bb10d3adb85b52cdc6fe5a7f74f108">&#9670;&#160;</a></span>hwloc_distances_kind_e</h2>
88
89 <div class="memitem">
90 <div class="memproto">
91 <table class="memname">
92 <tr>
93 <td class="memname">enum <a class="el" href="#gab1bb10d3adb85b52cdc6fe5a7f74f108">hwloc_distances_kind_e</a></td>
94 </tr>
95 </table>
96 </div><div class="memdoc">
97
98 <p>Kinds of distance matrices. </p>
99 <p>The <code class="param">kind</code> attribute of struct <a class="el" href="a00296.html" title="Matrix of distances between a set of objects.">hwloc_distances_s</a> is a OR'ed set of kinds.</p>
100 <p>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. </p>
101 <table class="fieldtable">
102 <tr><th colspan="2">Enumerator</th></tr><tr><td class="fieldname"><a id="ggab1bb10d3adb85b52cdc6fe5a7f74f108a90dc38248c8d5392d4dd3e88f391e984" name="ggab1bb10d3adb85b52cdc6fe5a7f74f108a90dc38248c8d5392d4dd3e88f391e984"></a>HWLOC_DISTANCES_KIND_FROM_OS&#160;</td><td class="fielddoc"><p>These distances were obtained from the operating system or hardware. </p>
103 </td></tr>
104 <tr><td class="fieldname"><a id="ggab1bb10d3adb85b52cdc6fe5a7f74f108a0148d7f9be833a04f5a55455437c227b" name="ggab1bb10d3adb85b52cdc6fe5a7f74f108a0148d7f9be833a04f5a55455437c227b"></a>HWLOC_DISTANCES_KIND_FROM_USER&#160;</td><td class="fielddoc"><p>These distances were provided by the user. </p>
105 </td></tr>
106 <tr><td class="fieldname"><a id="ggab1bb10d3adb85b52cdc6fe5a7f74f108afd6a3503fbc8f7c1a31235373cefc4c6" name="ggab1bb10d3adb85b52cdc6fe5a7f74f108afd6a3503fbc8f7c1a31235373cefc4c6"></a>HWLOC_DISTANCES_KIND_MEANS_LATENCY&#160;</td><td class="fielddoc"><p>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. </p>
107 </td></tr>
108 <tr><td class="fieldname"><a id="ggab1bb10d3adb85b52cdc6fe5a7f74f108a41b19f141a3c0ffe85f9affaca4b0293" name="ggab1bb10d3adb85b52cdc6fe5a7f74f108a41b19f141a3c0ffe85f9affaca4b0293"></a>HWLOC_DISTANCES_KIND_MEANS_BANDWIDTH&#160;</td><td class="fielddoc"><p>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. </p>
109 </td></tr>
110 <tr><td class="fieldname"><a id="ggab1bb10d3adb85b52cdc6fe5a7f74f108aa6cf2b6dfcf148b65952f811814efbe1" name="ggab1bb10d3adb85b52cdc6fe5a7f74f108aa6cf2b6dfcf148b65952f811814efbe1"></a>HWLOC_DISTANCES_KIND_HETEROGENEOUS_TYPES&#160;</td><td class="fielddoc"><p>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. </p>
111 </td></tr>
112 </table>
113
114 </div>
115 </div>
116 <a id="ga42859b651adec5ef0aaacb53ff220b00" name="ga42859b651adec5ef0aaacb53ff220b00"></a>
117 <h2 class="memtitle"><span class="permalink"><a href="#ga42859b651adec5ef0aaacb53ff220b00">&#9670;&#160;</a></span>hwloc_distances_transform_e</h2>
118
119 <div class="memitem">
120 <div class="memproto">
121 <table class="memname">
122 <tr>
123 <td class="memname">enum <a class="el" href="#ga42859b651adec5ef0aaacb53ff220b00">hwloc_distances_transform_e</a></td>
124 </tr>
125 </table>
126 </div><div class="memdoc">
127
128 <p>Transformations of distances structures. </p>
129 <table class="fieldtable">
130 <tr><th colspan="2">Enumerator</th></tr><tr><td class="fieldname"><a id="gga42859b651adec5ef0aaacb53ff220b00a4b7bdb7e3ccca30e03b7ae671e7f6dc1" name="gga42859b651adec5ef0aaacb53ff220b00a4b7bdb7e3ccca30e03b7ae671e7f6dc1"></a>HWLOC_DISTANCES_TRANSFORM_REMOVE_NULL&#160;</td><td class="fielddoc"><p>Remove <code>NULL</code> objects from the distances structure. </p>
131 <p>Every object that was replaced with <code>NULL</code> in the <code class="param">objs</code> array is removed and the <code class="param">values</code> array is updated accordingly.</p>
132 <p>At least <code>2</code> objects must remain, otherwise <a class="el" href="#gabcadd041f3072999d68f2d94e38670f7" title="Apply a transformation to a distances structure.">hwloc_distances_transform()</a> will return <code>-1</code> with <code class="param">errno</code> set to <code>EINVAL</code>.</p>
133 <p><code class="param">kind</code> will be updated with or without <a class="el" href="#ggab1bb10d3adb85b52cdc6fe5a7f74f108aa6cf2b6dfcf148b65952f811814efbe1" title="This distances structure covers objects of different types. This may apply to the &quot;NVLinkBandwidth&quot; s...">HWLOC_DISTANCES_KIND_HETEROGENEOUS_TYPES</a> according to the remaining objects. </p>
134 </td></tr>
135 <tr><td class="fieldname"><a id="gga42859b651adec5ef0aaacb53ff220b00a441e6bb393558319af3bb1f89f51f44d" name="gga42859b651adec5ef0aaacb53ff220b00a441e6bb393558319af3bb1f89f51f44d"></a>HWLOC_DISTANCES_TRANSFORM_LINKS&#160;</td><td class="fielddoc"><p>Replace bandwidth values with a number of links. </p>
136 <p>Usually all values will be either <code>0</code> (no link) or <code>1</code> (one link). However some matrices could get larger values if some pairs of peers are connected by different numbers of links.</p>
137 <p>Values on the diagonal are set to <code>0</code>.</p>
138 <p>This transformation only applies to bandwidth matrices. </p>
139 </td></tr>
140 <tr><td class="fieldname"><a id="gga42859b651adec5ef0aaacb53ff220b00a3d2aaf03e17be54eddbb94aab327fded" name="gga42859b651adec5ef0aaacb53ff220b00a3d2aaf03e17be54eddbb94aab327fded"></a>HWLOC_DISTANCES_TRANSFORM_MERGE_SWITCH_PORTS&#160;</td><td class="fielddoc"><p>Merge switches with multiple ports into a single object. </p>
141 <p>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.</p>
142 <p>This transformation will replace all ports with only the first one, now connected to all GPUs. Other ports are removed by applying <a class="el" href="#gga42859b651adec5ef0aaacb53ff220b00a4b7bdb7e3ccca30e03b7ae671e7f6dc1" title="Remove NULL objects from the distances structure.">HWLOC_DISTANCES_TRANSFORM_REMOVE_NULL</a> internally. </p>
143 </td></tr>
144 <tr><td class="fieldname"><a id="gga42859b651adec5ef0aaacb53ff220b00a1264abf9b9463f252995f37eb1057047" name="gga42859b651adec5ef0aaacb53ff220b00a1264abf9b9463f252995f37eb1057047"></a>HWLOC_DISTANCES_TRANSFORM_TRANSITIVE_CLOSURE&#160;</td><td class="fielddoc"><p>Apply a transitive closure to the matrix to connect objects across switches. </p>
145 <p>All pairs of GPUs will be reported as directly connected instead GPUs being only connected to switches.</p>
146 <p>Switch ports must be objects with subtype "NVSwitch" as in the NVLinkBandwidth matrix. </p>
147 </td></tr>
148 </table>
149
150 </div>
151 </div>
152 <a name="doc-func-members" id="doc-func-members"></a><h2 id="header-doc-func-members" class="groupheader">Function Documentation</h2>
153 <a id="ga613e6b2a5d0f06626ee8d0c12fa46691" name="ga613e6b2a5d0f06626ee8d0c12fa46691"></a>
154 <h2 class="memtitle"><span class="permalink"><a href="#ga613e6b2a5d0f06626ee8d0c12fa46691">&#9670;&#160;</a></span>hwloc_distances_get()</h2>
155
156 <div class="memitem">
157 <div class="memproto">
158 <table class="memname">
159 <tr>
160 <td class="memname">int hwloc_distances_get </td>
161 <td>(</td>
162 <td class="paramtype"><a class="el" href="a00169.html#ga9d1e76ee15a7dee158b786c30b6a6e38">hwloc_topology_t</a></td> <td class="paramname"><span class="paramname"><em>topology</em></span>, </td>
163 </tr>
164 <tr>
165 <td class="paramkey"></td>
166 <td></td>
167 <td class="paramtype">unsigned *</td> <td class="paramname"><span class="paramname"><em>nr</em></span>, </td>
168 </tr>
169 <tr>
170 <td class="paramkey"></td>
171 <td></td>
172 <td class="paramtype">struct <a class="el" href="a00296.html">hwloc_distances_s</a> **</td> <td class="paramname"><span class="paramname"><em>distances</em></span>, </td>
173 </tr>
174 <tr>
175 <td class="paramkey"></td>
176 <td></td>
177 <td class="paramtype">unsigned long</td> <td class="paramname"><span class="paramname"><em>kind</em></span>, </td>
178 </tr>
179 <tr>
180 <td class="paramkey"></td>
181 <td></td>
182 <td class="paramtype">unsigned long</td> <td class="paramname"><span class="paramname"><em>flags</em></span>&#160;)</td>
183 </tr>
184 </table>
185 </div><div class="memdoc">
186
187 <p>Retrieve distance matrices. </p>
188 <p>Retrieve distance matrices from the topology into the <code class="param">distances</code> array.</p>
189 <p><code class="param">flags</code> is currently unused, should be <code>0</code>.</p>
190 <p><code class="param">kind</code> serves as a filter. If <code>0</code>, 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.</p>
191 <p>On input, <code class="param">nr</code> points to the number of distance matrices that may be stored in <code class="param">distances</code>. On output, <code class="param">nr</code> points to the number of distance matrices that were actually found, even if some of them couldn't be stored in <code class="param">distances</code>. Distance matrices that couldn't be stored are ignored, but the function still returns success (<code>0</code>). The caller may find out by comparing the value pointed by <code class="param">nr</code> before and after the function call.</p>
192 <p>Each distance matrix returned in the <code class="param">distances</code> array should be released by the caller using <a class="el" href="#ga1dd78c1f9acd54f26aba0e284e97e51d" title="Release a distance matrix structure previously returned by hwloc_distances_get().">hwloc_distances_release()</a>.</p>
193 <dl class="section return"><dt>Returns</dt><dd>0 on success, -1 on error. </dd></dl>
194
195 </div>
196 </div>
197 <a id="ga5d1d35eccfcc2ebcef71a10972ce9b03" name="ga5d1d35eccfcc2ebcef71a10972ce9b03"></a>
198 <h2 class="memtitle"><span class="permalink"><a href="#ga5d1d35eccfcc2ebcef71a10972ce9b03">&#9670;&#160;</a></span>hwloc_distances_get_by_depth()</h2>
199
200 <div class="memitem">
201 <div class="memproto">
202 <table class="memname">
203 <tr>
204 <td class="memname">int hwloc_distances_get_by_depth </td>
205 <td>(</td>
206 <td class="paramtype"><a class="el" href="a00169.html#ga9d1e76ee15a7dee158b786c30b6a6e38">hwloc_topology_t</a></td> <td class="paramname"><span class="paramname"><em>topology</em></span>, </td>
207 </tr>
208 <tr>
209 <td class="paramkey"></td>
210 <td></td>
211 <td class="paramtype">int</td> <td class="paramname"><span class="paramname"><em>depth</em></span>, </td>
212 </tr>
213 <tr>
214 <td class="paramkey"></td>
215 <td></td>
216 <td class="paramtype">unsigned *</td> <td class="paramname"><span class="paramname"><em>nr</em></span>, </td>
217 </tr>
218 <tr>
219 <td class="paramkey"></td>
220 <td></td>
221 <td class="paramtype">struct <a class="el" href="a00296.html">hwloc_distances_s</a> **</td> <td class="paramname"><span class="paramname"><em>distances</em></span>, </td>
222 </tr>
223 <tr>
224 <td class="paramkey"></td>
225 <td></td>
226 <td class="paramtype">unsigned long</td> <td class="paramname"><span class="paramname"><em>kind</em></span>, </td>
227 </tr>
228 <tr>
229 <td class="paramkey"></td>
230 <td></td>
231 <td class="paramtype">unsigned long</td> <td class="paramname"><span class="paramname"><em>flags</em></span>&#160;)</td>
232 </tr>
233 </table>
234 </div><div class="memdoc">
235
236 <p>Retrieve distance matrices for object at a specific depth in the topology. </p>
237 <p>Identical to <a class="el" href="#ga613e6b2a5d0f06626ee8d0c12fa46691" title="Retrieve distance matrices.">hwloc_distances_get()</a> with the additional <code class="param">depth</code> filter.</p>
238 <dl class="section return"><dt>Returns</dt><dd>0 on success, -1 on error. </dd></dl>
239
240 </div>
241 </div>
242 <a id="gaa457f35b8745ca41ec17797c0d7b20f0" name="gaa457f35b8745ca41ec17797c0d7b20f0"></a>
243 <h2 class="memtitle"><span class="permalink"><a href="#gaa457f35b8745ca41ec17797c0d7b20f0">&#9670;&#160;</a></span>hwloc_distances_get_by_name()</h2>
244
245 <div class="memitem">
246 <div class="memproto">
247 <table class="memname">
248 <tr>
249 <td class="memname">int hwloc_distances_get_by_name </td>
250 <td>(</td>
251 <td class="paramtype"><a class="el" href="a00169.html#ga9d1e76ee15a7dee158b786c30b6a6e38">hwloc_topology_t</a></td> <td class="paramname"><span class="paramname"><em>topology</em></span>, </td>
252 </tr>
253 <tr>
254 <td class="paramkey"></td>
255 <td></td>
256 <td class="paramtype">const char *</td> <td class="paramname"><span class="paramname"><em>name</em></span>, </td>
257 </tr>
258 <tr>
259 <td class="paramkey"></td>
260 <td></td>
261 <td class="paramtype">unsigned *</td> <td class="paramname"><span class="paramname"><em>nr</em></span>, </td>
262 </tr>
263 <tr>
264 <td class="paramkey"></td>
265 <td></td>
266 <td class="paramtype">struct <a class="el" href="a00296.html">hwloc_distances_s</a> **</td> <td class="paramname"><span class="paramname"><em>distances</em></span>, </td>
267 </tr>
268 <tr>
269 <td class="paramkey"></td>
270 <td></td>
271 <td class="paramtype">unsigned long</td> <td class="paramname"><span class="paramname"><em>flags</em></span>&#160;)</td>
272 </tr>
273 </table>
274 </div><div class="memdoc">
275
276 <p>Retrieve a distance matrix with the given name. </p>
277 <p>Usually only one distances structure may match a given name.</p>
278 <p>The name of the most common structure is "NUMALatency". Others include "XGMIBandwidth", "XGMIHops", "XeLinkBandwidth", and "NVLinkBandwidth".</p>
279 <dl class="section return"><dt>Returns</dt><dd>0 on success, -1 on error. </dd></dl>
280
281 </div>
282 </div>
283 <a id="gaaa6bfbc20072a4f4de132eec859067f6" name="gaaa6bfbc20072a4f4de132eec859067f6"></a>
284 <h2 class="memtitle"><span class="permalink"><a href="#gaaa6bfbc20072a4f4de132eec859067f6">&#9670;&#160;</a></span>hwloc_distances_get_by_type()</h2>
285
286 <div class="memitem">
287 <div class="memproto">
288 <table class="memname">
289 <tr>
290 <td class="memname">int hwloc_distances_get_by_type </td>
291 <td>(</td>
292 <td class="paramtype"><a class="el" href="a00169.html#ga9d1e76ee15a7dee158b786c30b6a6e38">hwloc_topology_t</a></td> <td class="paramname"><span class="paramname"><em>topology</em></span>, </td>
293 </tr>
294 <tr>
295 <td class="paramkey"></td>
296 <td></td>
297 <td class="paramtype"><a class="el" href="a00167.html#gacd37bb612667dc437d66bfb175a8dc55">hwloc_obj_type_t</a></td> <td class="paramname"><span class="paramname"><em>type</em></span>, </td>
298 </tr>
299 <tr>
300 <td class="paramkey"></td>
301 <td></td>
302 <td class="paramtype">unsigned *</td> <td class="paramname"><span class="paramname"><em>nr</em></span>, </td>
303 </tr>
304 <tr>
305 <td class="paramkey"></td>
306 <td></td>
307 <td class="paramtype">struct <a class="el" href="a00296.html">hwloc_distances_s</a> **</td> <td class="paramname"><span class="paramname"><em>distances</em></span>, </td>
308 </tr>
309 <tr>
310 <td class="paramkey"></td>
311 <td></td>
312 <td class="paramtype">unsigned long</td> <td class="paramname"><span class="paramname"><em>kind</em></span>, </td>
313 </tr>
314 <tr>
315 <td class="paramkey"></td>
316 <td></td>
317 <td class="paramtype">unsigned long</td> <td class="paramname"><span class="paramname"><em>flags</em></span>&#160;)</td>
318 </tr>
319 </table>
320 </div><div class="memdoc">
321
322 <p>Retrieve distance matrices for object of a specific type. </p>
323 <p>Identical to <a class="el" href="#ga613e6b2a5d0f06626ee8d0c12fa46691" title="Retrieve distance matrices.">hwloc_distances_get()</a> with the additional <code class="param">type</code> filter.</p>
324 <dl class="section return"><dt>Returns</dt><dd>0 on success, -1 on error. </dd></dl>
325
326 </div>
327 </div>
328 <a id="gaff5366e26178f77d5e8dc3ac8863f2ed" name="gaff5366e26178f77d5e8dc3ac8863f2ed"></a>
329 <h2 class="memtitle"><span class="permalink"><a href="#gaff5366e26178f77d5e8dc3ac8863f2ed">&#9670;&#160;</a></span>hwloc_distances_get_name()</h2>
330
331 <div class="memitem">
332 <div class="memproto">
333 <table class="memname">
334 <tr>
335 <td class="memname">const char * hwloc_distances_get_name </td>
336 <td>(</td>
337 <td class="paramtype"><a class="el" href="a00169.html#ga9d1e76ee15a7dee158b786c30b6a6e38">hwloc_topology_t</a></td> <td class="paramname"><span class="paramname"><em>topology</em></span>, </td>
338 </tr>
339 <tr>
340 <td class="paramkey"></td>
341 <td></td>
342 <td class="paramtype">struct <a class="el" href="a00296.html">hwloc_distances_s</a> *</td> <td class="paramname"><span class="paramname"><em>distances</em></span>&#160;)</td>
343 </tr>
344 </table>
345 </div><div class="memdoc">
346
347 <p>Get a description of what a distances structure contains. </p>
348 <p>For instance "NUMALatency" for hardware-provided NUMA distances (ACPI SLIT), or <code>NULL</code> if unknown.</p>
349 <dl class="section return"><dt>Returns</dt><dd>the constant string with the name of the distance structure.</dd></dl>
350 <dl class="section note"><dt>Note</dt><dd>The returned name should not be freed by the caller, it belongs to the hwloc library. </dd></dl>
351
352 </div>
353 </div>
354 <a id="ga1dd78c1f9acd54f26aba0e284e97e51d" name="ga1dd78c1f9acd54f26aba0e284e97e51d"></a>
355 <h2 class="memtitle"><span class="permalink"><a href="#ga1dd78c1f9acd54f26aba0e284e97e51d">&#9670;&#160;</a></span>hwloc_distances_release()</h2>
356
357 <div class="memitem">
358 <div class="memproto">
359 <table class="memname">
360 <tr>
361 <td class="memname">void hwloc_distances_release </td>
362 <td>(</td>
363 <td class="paramtype"><a class="el" href="a00169.html#ga9d1e76ee15a7dee158b786c30b6a6e38">hwloc_topology_t</a></td> <td class="paramname"><span class="paramname"><em>topology</em></span>, </td>
364 </tr>
365 <tr>
366 <td class="paramkey"></td>
367 <td></td>
368 <td class="paramtype">struct <a class="el" href="a00296.html">hwloc_distances_s</a> *</td> <td class="paramname"><span class="paramname"><em>distances</em></span>&#160;)</td>
369 </tr>
370 </table>
371 </div><div class="memdoc">
372
373 <p>Release a distance matrix structure previously returned by <a class="el" href="#ga613e6b2a5d0f06626ee8d0c12fa46691" title="Retrieve distance matrices.">hwloc_distances_get()</a>. </p>
374 <dl class="section note"><dt>Note</dt><dd>This function is not required if the structure is removed with <a class="el" href="a00194.html#ga80bbf6f0db9af48c61780dd5152664c2" title="Release and remove the given distance matrice from the topology.">hwloc_distances_release_remove()</a>. </dd></dl>
375
376 </div>
377 </div>
378 <a id="gabcadd041f3072999d68f2d94e38670f7" name="gabcadd041f3072999d68f2d94e38670f7"></a>
379 <h2 class="memtitle"><span class="permalink"><a href="#gabcadd041f3072999d68f2d94e38670f7">&#9670;&#160;</a></span>hwloc_distances_transform()</h2>
380
381 <div class="memitem">
382 <div class="memproto">
383 <table class="memname">
384 <tr>
385 <td class="memname">int hwloc_distances_transform </td>
386 <td>(</td>
387 <td class="paramtype"><a class="el" href="a00169.html#ga9d1e76ee15a7dee158b786c30b6a6e38">hwloc_topology_t</a></td> <td class="paramname"><span class="paramname"><em>topology</em></span>, </td>
388 </tr>
389 <tr>
390 <td class="paramkey"></td>
391 <td></td>
392 <td class="paramtype">struct <a class="el" href="a00296.html">hwloc_distances_s</a> *</td> <td class="paramname"><span class="paramname"><em>distances</em></span>, </td>
393 </tr>
394 <tr>
395 <td class="paramkey"></td>
396 <td></td>
397 <td class="paramtype">enum <a class="el" href="#ga42859b651adec5ef0aaacb53ff220b00">hwloc_distances_transform_e</a></td> <td class="paramname"><span class="paramname"><em>transform</em></span>, </td>
398 </tr>
399 <tr>
400 <td class="paramkey"></td>
401 <td></td>
402 <td class="paramtype">void *</td> <td class="paramname"><span class="paramname"><em>transform_attr</em></span>, </td>
403 </tr>
404 <tr>
405 <td class="paramkey"></td>
406 <td></td>
407 <td class="paramtype">unsigned long</td> <td class="paramname"><span class="paramname"><em>flags</em></span>&#160;)</td>
408 </tr>
409 </table>
410 </div><div class="memdoc">
411
412 <p>Apply a transformation to a distances structure. </p>
413 <p>Modify a distances structure that was previously obtained with <a class="el" href="#ga613e6b2a5d0f06626ee8d0c12fa46691" title="Retrieve distance matrices.">hwloc_distances_get()</a> or one of its variants.</p>
414 <p>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 <a class="el" href="#ga613e6b2a5d0f06626ee8d0c12fa46691" title="Retrieve distance matrices.">hwloc_distances_get()</a> or exported to XML). To do so, one should add a new distances structure with same name, kind, objects and values (see <a class="el" href="a00193.html">Add distances between objects</a>) and then remove this old one with <a class="el" href="a00194.html#ga80bbf6f0db9af48c61780dd5152664c2" title="Release and remove the given distance matrice from the topology.">hwloc_distances_release_remove()</a>.</p>
415 <p><code class="param">transform</code> must be one of the transformations listed in <a class="el" href="#ga42859b651adec5ef0aaacb53ff220b00" title="Transformations of distances structures.">hwloc_distances_transform_e</a>.</p>
416 <p>These transformations may modify the contents of the <code class="param">objs</code> or <code class="param">values</code> arrays.</p>
417 <p><code class="param">transform_attr</code> must be <code>NULL</code> for now.</p>
418 <p><code class="param">flags</code> must be <code>0</code> for now.</p>
419 <dl class="section return"><dt>Returns</dt><dd>0 on success, -1 on error for instance if flags are invalid.</dd></dl>
420 <dl class="section note"><dt>Note</dt><dd>Objects in distances array <code class="param">objs</code> may be directly modified in place without using <a class="el" href="#gabcadd041f3072999d68f2d94e38670f7" title="Apply a transformation to a distances structure.">hwloc_distances_transform()</a>. One may use <a class="el" href="a00183.html#gab5df3ad1e8565ea0c2cf06412f6f6233" title="Return an object of a different type with same locality.">hwloc_get_obj_with_same_locality()</a> to easily convert between similar objects of different types. </dd></dl>
421
422 </div>
423 </div>
424 </div><!-- contents -->
425 <!-- start footer part -->
426 <hr class="footer"/><address class="footer"><small>
427 Generated by&#160;<a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.15.0
428 </small></address>
429 </div><!-- doc-content -->
430 </body>
431 </html>