Debian Codegraph @

doc/doxygen-doc/html/a00193.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): Add 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="#typedef-members">Typedefs</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">Add 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-typedef-members" class="groupheader"><a id="typedef-members" name="typedef-members"></a>
54 Typedefs</h2></td></tr>
55 <tr class="memitem:ga554a4c1e315265f961830e2b616e4989" id="r_ga554a4c1e315265f961830e2b616e4989"><td class="memItemLeft" align="right" valign="top">typedef void *&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="#ga554a4c1e315265f961830e2b616e4989">hwloc_distances_add_handle_t</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:ga22428b6bab271411e3834e6b4ca22e37" id="r_ga22428b6bab271411e3834e6b4ca22e37"><td class="memItemLeft" align="right" valign="top">enum &#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="#ga22428b6bab271411e3834e6b4ca22e37">hwloc_distances_add_flag_e</a> { <a class="el" href="#gga22428b6bab271411e3834e6b4ca22e37a7f6baba797d70538d03c9d13052c62ab">HWLOC_DISTANCES_ADD_FLAG_GROUP</a>
60 , <a class="el" href="#gga22428b6bab271411e3834e6b4ca22e37a5233ccf631c3bc53dd5c3e7a5d5c9b77">HWLOC_DISTANCES_ADD_FLAG_GROUP_INACCURATE</a>
61 }</td></tr>
62 </table><table class="memberdecls">
63 <tr class="heading"><td colspan="2"><h2 id="header-func-members" class="groupheader"><a id="func-members" name="func-members"></a>
64 Functions</h2></td></tr>
65 <tr class="memitem:ga823d38fa8d21dc338497fb0f79c96704" id="r_ga823d38fa8d21dc338497fb0f79c96704"><td class="memItemLeft" align="right" valign="top"><a class="el" href="#ga554a4c1e315265f961830e2b616e4989">hwloc_distances_add_handle_t</a>&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="#ga823d38fa8d21dc338497fb0f79c96704">hwloc_distances_add_create</a> (<a class="el" href="a00169.html#ga9d1e76ee15a7dee158b786c30b6a6e38">hwloc_topology_t</a> topology, const char *name, unsigned long kind, unsigned long flags)</td></tr>
66 <tr class="memitem:ga8c9715481b0bce344c8a33c6e6a56469" id="r_ga8c9715481b0bce344c8a33c6e6a56469"><td class="memItemLeft" align="right" valign="top">int&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="#ga8c9715481b0bce344c8a33c6e6a56469">hwloc_distances_add_values</a> (<a class="el" href="a00169.html#ga9d1e76ee15a7dee158b786c30b6a6e38">hwloc_topology_t</a> topology, <a class="el" href="#ga554a4c1e315265f961830e2b616e4989">hwloc_distances_add_handle_t</a> handle, unsigned nbobjs, <a class="el" href="a00168.html#ga79b8ab56877ef99ac59b833203391c7d">hwloc_obj_t</a> *objs, hwloc_uint64_t *values, unsigned long flags)</td></tr>
67 <tr class="memitem:ga1f5a29760ebb8f9af831e645315f553c" id="r_ga1f5a29760ebb8f9af831e645315f553c"><td class="memItemLeft" align="right" valign="top">int&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="#ga1f5a29760ebb8f9af831e645315f553c">hwloc_distances_add_commit</a> (<a class="el" href="a00169.html#ga9d1e76ee15a7dee158b786c30b6a6e38">hwloc_topology_t</a> topology, <a class="el" href="#ga554a4c1e315265f961830e2b616e4989">hwloc_distances_add_handle_t</a> handle, unsigned long flags)</td></tr>
68 </table>
69 <a name="details" id="details"></a><h2 id="header-details" class="groupheader">Detailed Description</h2>
70 <p>The usual way to add distances is: </p><div class="fragment"><div class="line"><a class="code hl_typedef" href="#ga554a4c1e315265f961830e2b616e4989">hwloc_distances_add_handle_t</a> handle;</div>
71 <div class="line"><span class="keywordtype">int</span> err = -1;</div>
72 <div class="line">handle = <a class="code hl_function" href="#ga823d38fa8d21dc338497fb0f79c96704">hwloc_distances_add_create</a>(topology, <span class="stringliteral">&quot;name&quot;</span>, kind, 0);</div>
73 <div class="line"><span class="keywordflow">if</span> (handle) {</div>
74 <div class="line"> err = <a class="code hl_function" href="#ga8c9715481b0bce344c8a33c6e6a56469">hwloc_distances_add_values</a>(topology, handle, nbobjs, objs, values, 0);</div>
75 <div class="line"> <span class="keywordflow">if</span> (!err)</div>
76 <div class="line"> err = <a class="code hl_function" href="#ga1f5a29760ebb8f9af831e645315f553c">hwloc_distances_add_commit</a>(topology, handle, flags);</div>
77 <div class="line">}</div>
78 <div class="ttc" id="aa00193_html_ga1f5a29760ebb8f9af831e645315f553c"><div class="ttname"><a href="#ga1f5a29760ebb8f9af831e645315f553c">hwloc_distances_add_commit</a></div><div class="ttdeci">int hwloc_distances_add_commit(hwloc_topology_t topology, hwloc_distances_add_handle_t handle, unsigned long flags)</div><div class="ttdoc">Commit a new distances structure.</div></div>
79 <div class="ttc" id="aa00193_html_ga554a4c1e315265f961830e2b616e4989"><div class="ttname"><a href="#ga554a4c1e315265f961830e2b616e4989">hwloc_distances_add_handle_t</a></div><div class="ttdeci">void * hwloc_distances_add_handle_t</div><div class="ttdoc">Handle to a new distances structure during its addition to the topology.</div><div class="ttdef"><b>Definition</b> distances.h:355</div></div>
80 <div class="ttc" id="aa00193_html_ga823d38fa8d21dc338497fb0f79c96704"><div class="ttname"><a href="#ga823d38fa8d21dc338497fb0f79c96704">hwloc_distances_add_create</a></div><div class="ttdeci">hwloc_distances_add_handle_t hwloc_distances_add_create(hwloc_topology_t topology, const char *name, unsigned long kind, unsigned long flags)</div><div class="ttdoc">Create a new empty distances structure.</div></div>
81 <div class="ttc" id="aa00193_html_ga8c9715481b0bce344c8a33c6e6a56469"><div class="ttname"><a href="#ga8c9715481b0bce344c8a33c6e6a56469">hwloc_distances_add_values</a></div><div class="ttdeci">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)</div><div class="ttdoc">Specify the objects and values in a new empty distances structure.</div></div>
82 </div><!-- fragment --><p> If <code class="param">err</code> is <code>0</code> at the end, then addition was successful. </p>
83 <a name="doc-typedef-members" id="doc-typedef-members"></a><h2 id="header-doc-typedef-members" class="groupheader">Typedef Documentation</h2>
84 <a id="ga554a4c1e315265f961830e2b616e4989" name="ga554a4c1e315265f961830e2b616e4989"></a>
85 <h2 class="memtitle"><span class="permalink"><a href="#ga554a4c1e315265f961830e2b616e4989">&#9670;&#160;</a></span>hwloc_distances_add_handle_t</h2>
86
87 <div class="memitem">
88 <div class="memproto">
89 <table class="memname">
90 <tr>
91 <td class="memname">typedef void* <a class="el" href="#ga554a4c1e315265f961830e2b616e4989">hwloc_distances_add_handle_t</a></td>
92 </tr>
93 </table>
94 </div><div class="memdoc">
95
96 <p>Handle to a new distances structure during its addition to the topology. </p>
97
98 </div>
99 </div>
100 <a name="doc-enum-members" id="doc-enum-members"></a><h2 id="header-doc-enum-members" class="groupheader">Enumeration Type Documentation</h2>
101 <a id="ga22428b6bab271411e3834e6b4ca22e37" name="ga22428b6bab271411e3834e6b4ca22e37"></a>
102 <h2 class="memtitle"><span class="permalink"><a href="#ga22428b6bab271411e3834e6b4ca22e37">&#9670;&#160;</a></span>hwloc_distances_add_flag_e</h2>
103
104 <div class="memitem">
105 <div class="memproto">
106 <table class="memname">
107 <tr>
108 <td class="memname">enum <a class="el" href="#ga22428b6bab271411e3834e6b4ca22e37">hwloc_distances_add_flag_e</a></td>
109 </tr>
110 </table>
111 </div><div class="memdoc">
112
113 <p>Flags for adding a new distances to a topology. </p>
114 <table class="fieldtable">
115 <tr><th colspan="2">Enumerator</th></tr><tr><td class="fieldname"><a id="gga22428b6bab271411e3834e6b4ca22e37a7f6baba797d70538d03c9d13052c62ab" name="gga22428b6bab271411e3834e6b4ca22e37a7f6baba797d70538d03c9d13052c62ab"></a>HWLOC_DISTANCES_ADD_FLAG_GROUP&#160;</td><td class="fielddoc"><p>Try to group objects based on the newly provided distance information. Grouping is only performed when the distances structure contains latencies, and when all objects are of the same type. </p>
116 </td></tr>
117 <tr><td class="fieldname"><a id="gga22428b6bab271411e3834e6b4ca22e37a5233ccf631c3bc53dd5c3e7a5d5c9b77" name="gga22428b6bab271411e3834e6b4ca22e37a5233ccf631c3bc53dd5c3e7a5d5c9b77"></a>HWLOC_DISTANCES_ADD_FLAG_GROUP_INACCURATE&#160;</td><td class="fielddoc"><p>If grouping, consider the distance values as inaccurate and relax the comparisons during the grouping algorithms. The actual accuracy may be modified through the HWLOC_GROUPING_ACCURACY environment variable (see <a class="el" href="a00373.html#envvar_heuristics">Environment variables for tweaking hwloc heuristics</a>). </p>
118 </td></tr>
119 </table>
120
121 </div>
122 </div>
123 <a name="doc-func-members" id="doc-func-members"></a><h2 id="header-doc-func-members" class="groupheader">Function Documentation</h2>
124 <a id="ga1f5a29760ebb8f9af831e645315f553c" name="ga1f5a29760ebb8f9af831e645315f553c"></a>
125 <h2 class="memtitle"><span class="permalink"><a href="#ga1f5a29760ebb8f9af831e645315f553c">&#9670;&#160;</a></span>hwloc_distances_add_commit()</h2>
126
127 <div class="memitem">
128 <div class="memproto">
129 <table class="memname">
130 <tr>
131 <td class="memname">int hwloc_distances_add_commit </td>
132 <td>(</td>
133 <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>
134 </tr>
135 <tr>
136 <td class="paramkey"></td>
137 <td></td>
138 <td class="paramtype"><a class="el" href="#ga554a4c1e315265f961830e2b616e4989">hwloc_distances_add_handle_t</a></td> <td class="paramname"><span class="paramname"><em>handle</em></span>, </td>
139 </tr>
140 <tr>
141 <td class="paramkey"></td>
142 <td></td>
143 <td class="paramtype">unsigned long</td> <td class="paramname"><span class="paramname"><em>flags</em></span>&#160;)</td>
144 </tr>
145 </table>
146 </div><div class="memdoc">
147
148 <p>Commit a new distances structure. </p>
149 <p>This function finalizes the distances structure and inserts in it the topology.</p>
150 <p>Parameter <code class="param">handle</code> was previously returned by <a class="el" href="#ga823d38fa8d21dc338497fb0f79c96704" title="Create a new empty distances structure.">hwloc_distances_add_create()</a>. Then objects and values were specified with <a class="el" href="#ga8c9715481b0bce344c8a33c6e6a56469" title="Specify the objects and values in a new empty distances structure.">hwloc_distances_add_values()</a>.</p>
151 <p><code class="param">flags</code> configures the behavior of the function using an optional OR'ed set of <a class="el" href="#ga22428b6bab271411e3834e6b4ca22e37" title="Flags for adding a new distances to a topology.">hwloc_distances_add_flag_e</a>. It may be used to request the grouping of existing objects based on distances.</p>
152 <p>On error, the temporary distances structure and its content are destroyed.</p>
153 <dl class="section return"><dt>Returns</dt><dd>0 on success. </dd>
154 <dd>
155 -1 on error. </dd></dl>
156
157 </div>
158 </div>
159 <a id="ga823d38fa8d21dc338497fb0f79c96704" name="ga823d38fa8d21dc338497fb0f79c96704"></a>
160 <h2 class="memtitle"><span class="permalink"><a href="#ga823d38fa8d21dc338497fb0f79c96704">&#9670;&#160;</a></span>hwloc_distances_add_create()</h2>
161
162 <div class="memitem">
163 <div class="memproto">
164 <table class="memname">
165 <tr>
166 <td class="memname"><a class="el" href="#ga554a4c1e315265f961830e2b616e4989">hwloc_distances_add_handle_t</a> hwloc_distances_add_create </td>
167 <td>(</td>
168 <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>
169 </tr>
170 <tr>
171 <td class="paramkey"></td>
172 <td></td>
173 <td class="paramtype">const char *</td> <td class="paramname"><span class="paramname"><em>name</em></span>, </td>
174 </tr>
175 <tr>
176 <td class="paramkey"></td>
177 <td></td>
178 <td class="paramtype">unsigned long</td> <td class="paramname"><span class="paramname"><em>kind</em></span>, </td>
179 </tr>
180 <tr>
181 <td class="paramkey"></td>
182 <td></td>
183 <td class="paramtype">unsigned long</td> <td class="paramname"><span class="paramname"><em>flags</em></span>&#160;)</td>
184 </tr>
185 </table>
186 </div><div class="memdoc">
187
188 <p>Create a new empty distances structure. </p>
189 <p>Create an empty distances structure to be filled with <a class="el" href="#ga8c9715481b0bce344c8a33c6e6a56469" title="Specify the objects and values in a new empty distances structure.">hwloc_distances_add_values()</a> and then committed with <a class="el" href="#ga1f5a29760ebb8f9af831e645315f553c" title="Commit a new distances structure.">hwloc_distances_add_commit()</a>.</p>
190 <p>Parameter <code class="param">name</code> is optional, it may be <code>NULL</code>. Otherwise, it will be copied internally and may later be freed by the caller.</p>
191 <p><code class="param">kind</code> specifies the kind of distance as a OR'ed set of <a class="el" href="a00191.html#gab1bb10d3adb85b52cdc6fe5a7f74f108" title="Kinds of distance matrices.">hwloc_distances_kind_e</a>. Only one kind of meaning and one kind of provenance may be given if appropriate (e.g. <a class="el" href="a00191.html#ggab1bb10d3adb85b52cdc6fe5a7f74f108a41b19f141a3c0ffe85f9affaca4b0293" title="Distance values are similar to bandwidths between objects. Values are higher for closer objects,...">HWLOC_DISTANCES_KIND_MEANS_BANDWIDTH</a> and <a class="el" href="a00191.html#ggab1bb10d3adb85b52cdc6fe5a7f74f108a0148d7f9be833a04f5a55455437c227b" title="These distances were provided by the user.">HWLOC_DISTANCES_KIND_FROM_USER</a>). Kind <a class="el" href="a00191.html#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> will be automatically set according to objects having different types in <a class="el" href="#ga8c9715481b0bce344c8a33c6e6a56469" title="Specify the objects and values in a new empty distances structure.">hwloc_distances_add_values()</a>.</p>
192 <p><code class="param">flags</code> must be <code>0</code> for now.</p>
193 <dl class="section return"><dt>Returns</dt><dd>A <a class="el" href="#ga554a4c1e315265f961830e2b616e4989" title="Handle to a new distances structure during its addition to the topology.">hwloc_distances_add_handle_t</a> that should then be passed to <a class="el" href="#ga8c9715481b0bce344c8a33c6e6a56469" title="Specify the objects and values in a new empty distances structure.">hwloc_distances_add_values()</a> and <a class="el" href="#ga1f5a29760ebb8f9af831e645315f553c" title="Commit a new distances structure.">hwloc_distances_add_commit()</a>.</dd>
194 <dd>
195 <code>NULL</code> on error. </dd></dl>
196
197 </div>
198 </div>
199 <a id="ga8c9715481b0bce344c8a33c6e6a56469" name="ga8c9715481b0bce344c8a33c6e6a56469"></a>
200 <h2 class="memtitle"><span class="permalink"><a href="#ga8c9715481b0bce344c8a33c6e6a56469">&#9670;&#160;</a></span>hwloc_distances_add_values()</h2>
201
202 <div class="memitem">
203 <div class="memproto">
204 <table class="memname">
205 <tr>
206 <td class="memname">int hwloc_distances_add_values </td>
207 <td>(</td>
208 <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>
209 </tr>
210 <tr>
211 <td class="paramkey"></td>
212 <td></td>
213 <td class="paramtype"><a class="el" href="#ga554a4c1e315265f961830e2b616e4989">hwloc_distances_add_handle_t</a></td> <td class="paramname"><span class="paramname"><em>handle</em></span>, </td>
214 </tr>
215 <tr>
216 <td class="paramkey"></td>
217 <td></td>
218 <td class="paramtype">unsigned</td> <td class="paramname"><span class="paramname"><em>nbobjs</em></span>, </td>
219 </tr>
220 <tr>
221 <td class="paramkey"></td>
222 <td></td>
223 <td class="paramtype"><a class="el" href="a00168.html#ga79b8ab56877ef99ac59b833203391c7d">hwloc_obj_t</a> *</td> <td class="paramname"><span class="paramname"><em>objs</em></span>, </td>
224 </tr>
225 <tr>
226 <td class="paramkey"></td>
227 <td></td>
228 <td class="paramtype">hwloc_uint64_t *</td> <td class="paramname"><span class="paramname"><em>values</em></span>, </td>
229 </tr>
230 <tr>
231 <td class="paramkey"></td>
232 <td></td>
233 <td class="paramtype">unsigned long</td> <td class="paramname"><span class="paramname"><em>flags</em></span>&#160;)</td>
234 </tr>
235 </table>
236 </div><div class="memdoc">
237
238 <p>Specify the objects and values in a new empty distances structure. </p>
239 <p>Specify the objects and values for a new distances structure that was returned as a handle by <a class="el" href="#ga823d38fa8d21dc338497fb0f79c96704" title="Create a new empty distances structure.">hwloc_distances_add_create()</a>. The structure must then be committed with <a class="el" href="#ga1f5a29760ebb8f9af831e645315f553c" title="Commit a new distances structure.">hwloc_distances_add_commit()</a>.</p>
240 <p>The number of objects is <code class="param">nbobjs</code> and the array of objects is <code class="param">objs</code>. Distance values are stored as a one-dimension array in <code class="param">values</code>. The distance from object i to object j is in slot i*nbobjs+j.</p>
241 <p><code class="param">nbobjs</code> must be at least 2.</p>
242 <p>Arrays <code class="param">objs</code> and <code class="param">values</code> will be copied internally, they may later be freed by the caller.</p>
243 <p>On error, the temporary distances structure and its content are destroyed.</p>
244 <p><code class="param">flags</code> must be <code>0</code> for now.</p>
245 <dl class="section return"><dt>Returns</dt><dd>0 on success. </dd>
246 <dd>
247 -1 on error. </dd></dl>
248
249 </div>
250 </div>
251 </div><!-- contents -->
252 <!-- start footer part -->
253 <hr class="footer"/><address class="footer"><small>
254 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
255 </small></address>
256 </div><!-- doc-content -->
257 </body>
258 </html>