Debian Codegraph @

doc/doxygen-doc/html/a00175.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): Changing the Source of Topology Discovery</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="#enum-members">Enumerations</a> &#124;
47 <a href="#func-members">Functions</a> </div>
48 <div class="headertitle"><div class="title">Changing the Source of Topology Discovery </div></div>
49 </div><!--header-->
50 <div class="contents">
51 <table class="memberdecls">
52 <tr class="heading"><td colspan="2"><h2 id="header-enum-members" class="groupheader"><a id="enum-members" name="enum-members"></a>
53 Enumerations</h2></td></tr>
54 <tr class="memitem:ga949f656c779208a36790feba24048b7e" id="r_ga949f656c779208a36790feba24048b7e"><td class="memItemLeft" align="right" valign="top">enum &#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="#ga949f656c779208a36790feba24048b7e">hwloc_topology_components_flag_e</a> { <a class="el" href="#gga949f656c779208a36790feba24048b7ea33eec25d29253a2aba21dd3c731b416e">HWLOC_TOPOLOGY_COMPONENTS_FLAG_BLACKLIST</a>
55 }</td></tr>
56 </table><table class="memberdecls">
57 <tr class="heading"><td colspan="2"><h2 id="header-func-members" class="groupheader"><a id="func-members" name="func-members"></a>
58 Functions</h2></td></tr>
59 <tr class="memitem:ga341fc17b5867a4715570baab131f68cd" id="r_ga341fc17b5867a4715570baab131f68cd"><td class="memItemLeft" align="right" valign="top">int&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="#ga341fc17b5867a4715570baab131f68cd">hwloc_topology_set_pid</a> (<a class="el" href="a00169.html#ga9d1e76ee15a7dee158b786c30b6a6e38">hwloc_topology_t</a> restrict topology, hwloc_pid_t pid)</td></tr>
60 <tr class="memitem:ga4fab186bb6181a00bcf585825fddd38d" id="r_ga4fab186bb6181a00bcf585825fddd38d"><td class="memItemLeft" align="right" valign="top">int&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="#ga4fab186bb6181a00bcf585825fddd38d">hwloc_topology_set_synthetic</a> (<a class="el" href="a00169.html#ga9d1e76ee15a7dee158b786c30b6a6e38">hwloc_topology_t</a> restrict topology, const char *restrict description)</td></tr>
61 <tr class="memitem:ga879439b7ee99407ee911b3ac64e9a25e" id="r_ga879439b7ee99407ee911b3ac64e9a25e"><td class="memItemLeft" align="right" valign="top">int&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="#ga879439b7ee99407ee911b3ac64e9a25e">hwloc_topology_set_xml</a> (<a class="el" href="a00169.html#ga9d1e76ee15a7dee158b786c30b6a6e38">hwloc_topology_t</a> restrict topology, const char *restrict xmlpath)</td></tr>
62 <tr class="memitem:ga2745616b65595e1c1e579ecc7e461fa8" id="r_ga2745616b65595e1c1e579ecc7e461fa8"><td class="memItemLeft" align="right" valign="top">int&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="#ga2745616b65595e1c1e579ecc7e461fa8">hwloc_topology_set_xmlbuffer</a> (<a class="el" href="a00169.html#ga9d1e76ee15a7dee158b786c30b6a6e38">hwloc_topology_t</a> restrict topology, const char *restrict buffer, int size)</td></tr>
63 <tr class="memitem:ga9ad41adf418cee1c0ee32ba9bd4a3d36" id="r_ga9ad41adf418cee1c0ee32ba9bd4a3d36"><td class="memItemLeft" align="right" valign="top">int&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="#ga9ad41adf418cee1c0ee32ba9bd4a3d36">hwloc_topology_set_components</a> (<a class="el" href="a00169.html#ga9d1e76ee15a7dee158b786c30b6a6e38">hwloc_topology_t</a> restrict topology, unsigned long flags, const char *restrict name)</td></tr>
64 </table>
65 <a name="details" id="details"></a><h2 id="header-details" class="groupheader">Detailed Description</h2>
66 <p>These functions must be called between <a class="el" href="a00169.html#ga03fd4a16d8b9ee1ffc32b25fd2f6bdfa" title="Allocate a topology context.">hwloc_topology_init()</a> and <a class="el" href="a00169.html#gabdf58d87ad77f6615fccdfe0535ff826" title="Build the actual topology.">hwloc_topology_load()</a>. Otherwise, they will return -1 with errno set to <code>EBUSY</code>.</p>
67 <p>If none of the functions below is called, the default is to detect all the objects of the machine that the caller is allowed to access.</p>
68 <p>This default behavior may also be modified through environment variables if the application did not modify it already. Setting HWLOC_XMLFILE in the environment enforces the discovery from a XML file as if <a class="el" href="#ga879439b7ee99407ee911b3ac64e9a25e" title="Enable XML-file based topology.">hwloc_topology_set_xml()</a> had been called. Setting HWLOC_SYNTHETIC enforces a synthetic topology as if <a class="el" href="#ga4fab186bb6181a00bcf585825fddd38d" title="Enable synthetic topology.">hwloc_topology_set_synthetic()</a> had been called.</p>
69 <p>Finally, HWLOC_THISSYSTEM enforces the return value of <a class="el" href="a00176.html#ga68ffdcfd9175cdf40709801092f18017" title="Does the topology context come from this system?">hwloc_topology_is_thissystem()</a>. </p>
70 <a name="doc-enum-members" id="doc-enum-members"></a><h2 id="header-doc-enum-members" class="groupheader">Enumeration Type Documentation</h2>
71 <a id="ga949f656c779208a36790feba24048b7e" name="ga949f656c779208a36790feba24048b7e"></a>
72 <h2 class="memtitle"><span class="permalink"><a href="#ga949f656c779208a36790feba24048b7e">&#9670;&#160;</a></span>hwloc_topology_components_flag_e</h2>
73
74 <div class="memitem">
75 <div class="memproto">
76 <table class="memname">
77 <tr>
78 <td class="memname">enum <a class="el" href="#ga949f656c779208a36790feba24048b7e">hwloc_topology_components_flag_e</a></td>
79 </tr>
80 </table>
81 </div><div class="memdoc">
82
83 <p>Flags to be passed to <a class="el" href="#ga9ad41adf418cee1c0ee32ba9bd4a3d36" title="Prevent a discovery component from being used for a topology.">hwloc_topology_set_components()</a>. </p>
84 <table class="fieldtable">
85 <tr><th colspan="2">Enumerator</th></tr><tr><td class="fieldname"><a id="gga949f656c779208a36790feba24048b7ea33eec25d29253a2aba21dd3c731b416e" name="gga949f656c779208a36790feba24048b7ea33eec25d29253a2aba21dd3c731b416e"></a>HWLOC_TOPOLOGY_COMPONENTS_FLAG_BLACKLIST&#160;</td><td class="fielddoc"><p>Blacklist the target component from being used. </p>
86 </td></tr>
87 </table>
88
89 </div>
90 </div>
91 <a name="doc-func-members" id="doc-func-members"></a><h2 id="header-doc-func-members" class="groupheader">Function Documentation</h2>
92 <a id="ga9ad41adf418cee1c0ee32ba9bd4a3d36" name="ga9ad41adf418cee1c0ee32ba9bd4a3d36"></a>
93 <h2 class="memtitle"><span class="permalink"><a href="#ga9ad41adf418cee1c0ee32ba9bd4a3d36">&#9670;&#160;</a></span>hwloc_topology_set_components()</h2>
94
95 <div class="memitem">
96 <div class="memproto">
97 <table class="memname">
98 <tr>
99 <td class="memname">int hwloc_topology_set_components </td>
100 <td>(</td>
101 <td class="paramtype"><a class="el" href="a00169.html#ga9d1e76ee15a7dee158b786c30b6a6e38">hwloc_topology_t</a> restrict</td> <td class="paramname"><span class="paramname"><em>topology</em></span>, </td>
102 </tr>
103 <tr>
104 <td class="paramkey"></td>
105 <td></td>
106 <td class="paramtype">unsigned long</td> <td class="paramname"><span class="paramname"><em>flags</em></span>, </td>
107 </tr>
108 <tr>
109 <td class="paramkey"></td>
110 <td></td>
111 <td class="paramtype">const char *restrict</td> <td class="paramname"><span class="paramname"><em>name</em></span>&#160;)</td>
112 </tr>
113 </table>
114 </div><div class="memdoc">
115
116 <p>Prevent a discovery component from being used for a topology. </p>
117 <p><code class="param">name</code> is the name of the discovery component that should not be used when loading topology <code class="param">topology</code>. The name is a string such as "cuda".</p>
118 <p>For components with multiple phases, it may also be suffixed with the name of a phase, for instance "linux:io".</p>
119 <p><code class="param">flags</code> should be <a class="el" href="#gga949f656c779208a36790feba24048b7ea33eec25d29253a2aba21dd3c731b416e" title="Blacklist the target component from being used.">HWLOC_TOPOLOGY_COMPONENTS_FLAG_BLACKLIST</a>.</p>
120 <p>This may be used to avoid expensive parts of the discovery process. For instance, CUDA-specific discovery may be expensive and unneeded while generic I/O discovery could still be useful.</p>
121 <dl class="section return"><dt>Returns</dt><dd>0 on success. </dd>
122 <dd>
123 -1 on error, for instance if flags are invalid. </dd></dl>
124
125 </div>
126 </div>
127 <a id="ga341fc17b5867a4715570baab131f68cd" name="ga341fc17b5867a4715570baab131f68cd"></a>
128 <h2 class="memtitle"><span class="permalink"><a href="#ga341fc17b5867a4715570baab131f68cd">&#9670;&#160;</a></span>hwloc_topology_set_pid()</h2>
129
130 <div class="memitem">
131 <div class="memproto">
132 <table class="memname">
133 <tr>
134 <td class="memname">int hwloc_topology_set_pid </td>
135 <td>(</td>
136 <td class="paramtype"><a class="el" href="a00169.html#ga9d1e76ee15a7dee158b786c30b6a6e38">hwloc_topology_t</a> restrict</td> <td class="paramname"><span class="paramname"><em>topology</em></span>, </td>
137 </tr>
138 <tr>
139 <td class="paramkey"></td>
140 <td></td>
141 <td class="paramtype">hwloc_pid_t</td> <td class="paramname"><span class="paramname"><em>pid</em></span>&#160;)</td>
142 </tr>
143 </table>
144 </div><div class="memdoc">
145
146 <p>Change which process the topology is viewed from. </p>
147 <p>On some systems, processes may have different views of the machine, for instance the set of allowed CPUs. By default, hwloc exposes the view from the current process. Calling <a class="el" href="#ga341fc17b5867a4715570baab131f68cd" title="Change which process the topology is viewed from.">hwloc_topology_set_pid()</a> permits to make it expose the topology of the machine from the point of view of another process.</p>
148 <dl class="section note"><dt>Note</dt><dd><code class="param">hwloc_pid_t</code> is <code class="param">pid_t</code> on Unix platforms, and <code class="param">HANDLE</code> on native Windows platforms.</dd>
149 <dd>
150 -1 is returned and errno is set to <code>ENOSYS</code> on platforms that do not support this feature.</dd>
151 <dd>
152 The PID will not actually be used until <a class="el" href="a00169.html#gabdf58d87ad77f6615fccdfe0535ff826" title="Build the actual topology.">hwloc_topology_load()</a>. If the corresponding process exits in the meantime, hwloc will ignore the PID. If another process reuses the PID, the view of that process will be used.</dd></dl>
153 <dl class="section return"><dt>Returns</dt><dd>0 on success, -1 on error. </dd></dl>
154
155 </div>
156 </div>
157 <a id="ga4fab186bb6181a00bcf585825fddd38d" name="ga4fab186bb6181a00bcf585825fddd38d"></a>
158 <h2 class="memtitle"><span class="permalink"><a href="#ga4fab186bb6181a00bcf585825fddd38d">&#9670;&#160;</a></span>hwloc_topology_set_synthetic()</h2>
159
160 <div class="memitem">
161 <div class="memproto">
162 <table class="memname">
163 <tr>
164 <td class="memname">int hwloc_topology_set_synthetic </td>
165 <td>(</td>
166 <td class="paramtype"><a class="el" href="a00169.html#ga9d1e76ee15a7dee158b786c30b6a6e38">hwloc_topology_t</a> restrict</td> <td class="paramname"><span class="paramname"><em>topology</em></span>, </td>
167 </tr>
168 <tr>
169 <td class="paramkey"></td>
170 <td></td>
171 <td class="paramtype">const char *restrict</td> <td class="paramname"><span class="paramname"><em>description</em></span>&#160;)</td>
172 </tr>
173 </table>
174 </div><div class="memdoc">
175
176 <p>Enable synthetic topology. </p>
177 <p>Gather topology information from the given <code class="param">description</code>, a space-separated string of &lt;type:number&gt; describing the object type and arity at each level. All types may be omitted (space-separated string of numbers) so that hwloc chooses all types according to usual topologies. See also the <a class="el" href="a00381.html">Synthetic topologies</a>.</p>
178 <p>Setting the environment variable HWLOC_SYNTHETIC may also result in this behavior.</p>
179 <p>If <code class="param">description</code> was properly parsed and describes a valid topology configuration, this function returns 0. Otherwise -1 is returned and errno is set to <code>EINVAL</code>.</p>
180 <p>Note that this function does not actually load topology information; it just tells hwloc where to load it from. You'll still need to invoke <a class="el" href="a00169.html#gabdf58d87ad77f6615fccdfe0535ff826" title="Build the actual topology.">hwloc_topology_load()</a> to actually load the topology information.</p>
181 <dl class="section return"><dt>Returns</dt><dd>0 on success. </dd>
182 <dd>
183 -1 with errno set to <code>EINVAL</code> if the description was invalid.</dd></dl>
184 <dl class="section note"><dt>Note</dt><dd>For convenience, this backend provides empty binding hooks which just return success.</dd>
185 <dd>
186 On success, the synthetic component replaces the previously enabled component (if any), but the topology is not actually modified until <a class="el" href="a00169.html#gabdf58d87ad77f6615fccdfe0535ff826" title="Build the actual topology.">hwloc_topology_load()</a>. </dd></dl>
187
188 </div>
189 </div>
190 <a id="ga879439b7ee99407ee911b3ac64e9a25e" name="ga879439b7ee99407ee911b3ac64e9a25e"></a>
191 <h2 class="memtitle"><span class="permalink"><a href="#ga879439b7ee99407ee911b3ac64e9a25e">&#9670;&#160;</a></span>hwloc_topology_set_xml()</h2>
192
193 <div class="memitem">
194 <div class="memproto">
195 <table class="memname">
196 <tr>
197 <td class="memname">int hwloc_topology_set_xml </td>
198 <td>(</td>
199 <td class="paramtype"><a class="el" href="a00169.html#ga9d1e76ee15a7dee158b786c30b6a6e38">hwloc_topology_t</a> restrict</td> <td class="paramname"><span class="paramname"><em>topology</em></span>, </td>
200 </tr>
201 <tr>
202 <td class="paramkey"></td>
203 <td></td>
204 <td class="paramtype">const char *restrict</td> <td class="paramname"><span class="paramname"><em>xmlpath</em></span>&#160;)</td>
205 </tr>
206 </table>
207 </div><div class="memdoc">
208
209 <p>Enable XML-file based topology. </p>
210 <p>Gather topology information from the XML file given at <code class="param">xmlpath</code>. Setting the environment variable HWLOC_XMLFILE may also result in this behavior. This file may have been generated earlier with <a class="el" href="a00189.html#ga333f79975b4eeb28a3d8fad3373583ce" title="Export the topology into an XML file.">hwloc_topology_export_xml()</a> in <a class="el" href="a00104_source.html">hwloc/export.h</a>, or lstopo file.xml.</p>
211 <p>Note that this function does not actually load topology information; it just tells hwloc where to load it from. You'll still need to invoke <a class="el" href="a00169.html#gabdf58d87ad77f6615fccdfe0535ff826" title="Build the actual topology.">hwloc_topology_load()</a> to actually load the topology information.</p>
212 <dl class="section return"><dt>Returns</dt><dd>0 on success. </dd>
213 <dd>
214 -1 with errno set to <code>EINVAL</code> on failure to read the XML file.</dd></dl>
215 <dl class="section note"><dt>Note</dt><dd>See also <a class="el" href="a00189.html#ga5ac6917ea7289955fb1ffda4353af9b0" title="Set the application-specific callback for importing userdata.">hwloc_topology_set_userdata_import_callback()</a> for importing application-specific object userdata.</dd>
216 <dd>
217 For convenience, this backend provides empty binding hooks which just return success. To have hwloc still actually call OS-specific hooks, the <a class="el" href="a00176.html#ggada025d3ec20b4b420f8038d23d6e7bdea6ecb6abc6a0bb75e81564f8bca85783b" title="Assume that the selected backend provides the topology for the system on which we are running.">HWLOC_TOPOLOGY_FLAG_IS_THISSYSTEM</a> has to be set to assert that the loaded file is really the underlying system.</dd>
218 <dd>
219 On success, the XML component replaces the previously enabled component (if any), but the topology is not actually modified until <a class="el" href="a00169.html#gabdf58d87ad77f6615fccdfe0535ff826" title="Build the actual topology.">hwloc_topology_load()</a>.</dd>
220 <dd>
221 If an invalid XML input file is given, the error may be reported either here or later by <a class="el" href="a00169.html#gabdf58d87ad77f6615fccdfe0535ff826" title="Build the actual topology.">hwloc_topology_load()</a> depending on the XML library used by hwloc. </dd></dl>
222
223 </div>
224 </div>
225 <a id="ga2745616b65595e1c1e579ecc7e461fa8" name="ga2745616b65595e1c1e579ecc7e461fa8"></a>
226 <h2 class="memtitle"><span class="permalink"><a href="#ga2745616b65595e1c1e579ecc7e461fa8">&#9670;&#160;</a></span>hwloc_topology_set_xmlbuffer()</h2>
227
228 <div class="memitem">
229 <div class="memproto">
230 <table class="memname">
231 <tr>
232 <td class="memname">int hwloc_topology_set_xmlbuffer </td>
233 <td>(</td>
234 <td class="paramtype"><a class="el" href="a00169.html#ga9d1e76ee15a7dee158b786c30b6a6e38">hwloc_topology_t</a> restrict</td> <td class="paramname"><span class="paramname"><em>topology</em></span>, </td>
235 </tr>
236 <tr>
237 <td class="paramkey"></td>
238 <td></td>
239 <td class="paramtype">const char *restrict</td> <td class="paramname"><span class="paramname"><em>buffer</em></span>, </td>
240 </tr>
241 <tr>
242 <td class="paramkey"></td>
243 <td></td>
244 <td class="paramtype">int</td> <td class="paramname"><span class="paramname"><em>size</em></span>&#160;)</td>
245 </tr>
246 </table>
247 </div><div class="memdoc">
248
249 <p>Enable XML based topology using a memory buffer (instead of a file, as with <a class="el" href="#ga879439b7ee99407ee911b3ac64e9a25e" title="Enable XML-file based topology.">hwloc_topology_set_xml()</a>). </p>
250 <p>Gather topology information from the XML memory buffer given at <code class="param">buffer</code> and of length <code class="param">size</code> (including an ending <code>\0</code>). This buffer may have been filled earlier with <a class="el" href="a00189.html#gad33b7f7c11db10459505a3b1634fd3f1" title="Export the topology into a newly-allocated XML memory buffer.">hwloc_topology_export_xmlbuffer()</a> in <a class="el" href="a00104_source.html">hwloc/export.h</a>.</p>
251 <p>Note that this function does not actually load topology information; it just tells hwloc where to load it from. You'll still need to invoke <a class="el" href="a00169.html#gabdf58d87ad77f6615fccdfe0535ff826" title="Build the actual topology.">hwloc_topology_load()</a> to actually load the topology information.</p>
252 <dl class="section return"><dt>Returns</dt><dd>0 on success. </dd>
253 <dd>
254 -1 with errno set to <code>EINVAL</code> on failure to read the XML buffer.</dd></dl>
255 <dl class="section note"><dt>Note</dt><dd>See also <a class="el" href="a00189.html#ga5ac6917ea7289955fb1ffda4353af9b0" title="Set the application-specific callback for importing userdata.">hwloc_topology_set_userdata_import_callback()</a> for importing application-specific object userdata.</dd>
256 <dd>
257 For convenience, this backend provides empty binding hooks which just return success. To have hwloc still actually call OS-specific hooks, the <a class="el" href="a00176.html#ggada025d3ec20b4b420f8038d23d6e7bdea6ecb6abc6a0bb75e81564f8bca85783b" title="Assume that the selected backend provides the topology for the system on which we are running.">HWLOC_TOPOLOGY_FLAG_IS_THISSYSTEM</a> has to be set to assert that the loaded file is really the underlying system.</dd>
258 <dd>
259 On success, the XML component replaces the previously enabled component (if any), but the topology is not actually modified until <a class="el" href="a00169.html#gabdf58d87ad77f6615fccdfe0535ff826" title="Build the actual topology.">hwloc_topology_load()</a>.</dd>
260 <dd>
261 If an invalid XML input file is given, the error may be reported either here or later by <a class="el" href="a00169.html#gabdf58d87ad77f6615fccdfe0535ff826" title="Build the actual topology.">hwloc_topology_load()</a> depending on the XML library used by hwloc. </dd></dl>
262
263 </div>
264 </div>
265 </div><!-- contents -->
266 <!-- start footer part -->
267 <hr class="footer"/><address class="footer"><small>
268 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
269 </small></address>
270 </div><!-- doc-content -->
271 </body>
272 </html>