Debian Codegraph @

doc/doxygen-doc/html/a00213.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): Sharing topologies between processes</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="#func-members">Functions</a> </div>
47 <div class="headertitle"><div class="title">Sharing topologies between processes </div></div>
48 </div><!--header-->
49 <div class="contents">
50 <table class="memberdecls">
51 <tr class="heading"><td colspan="2"><h2 id="header-func-members" class="groupheader"><a id="func-members" name="func-members"></a>
52 Functions</h2></td></tr>
53 <tr class="memitem:ga772ab52750cdd0eec85128df24888001" id="r_ga772ab52750cdd0eec85128df24888001"><td class="memItemLeft" align="right" valign="top">int&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="#ga772ab52750cdd0eec85128df24888001">hwloc_shmem_topology_get_length</a> (<a class="el" href="a00169.html#ga9d1e76ee15a7dee158b786c30b6a6e38">hwloc_topology_t</a> topology, size_t *lengthp, unsigned long flags)</td></tr>
54 <tr class="memitem:ga61b20e346fc76f76420e3a88cc80a671" id="r_ga61b20e346fc76f76420e3a88cc80a671"><td class="memItemLeft" align="right" valign="top">int&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="#ga61b20e346fc76f76420e3a88cc80a671">hwloc_shmem_topology_write</a> (<a class="el" href="a00169.html#ga9d1e76ee15a7dee158b786c30b6a6e38">hwloc_topology_t</a> topology, int fd, hwloc_uint64_t fileoffset, void *mmap_address, size_t length, unsigned long flags)</td></tr>
55 <tr class="memitem:ga21545bd0f09d9b554c8e60a630e0e629" id="r_ga21545bd0f09d9b554c8e60a630e0e629"><td class="memItemLeft" align="right" valign="top">int&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="#ga21545bd0f09d9b554c8e60a630e0e629">hwloc_shmem_topology_adopt</a> (<a class="el" href="a00169.html#ga9d1e76ee15a7dee158b786c30b6a6e38">hwloc_topology_t</a> *topologyp, int fd, hwloc_uint64_t fileoffset, void *mmap_address, size_t length, unsigned long flags)</td></tr>
56 </table>
57 <a name="details" id="details"></a><h2 id="header-details" class="groupheader">Detailed Description</h2>
58 <p>These functions are used to share a topology between processes by duplicating it into a file-backed shared-memory buffer.</p>
59 <p>The master process must first get the required shared-memory size for storing this topology with <a class="el" href="#ga772ab52750cdd0eec85128df24888001" title="Get the required shared memory length for storing a topology.">hwloc_shmem_topology_get_length()</a>.</p>
60 <p>Then it must find a virtual memory area of that size that is available in all processes (identical virtual addresses in all processes). On Linux, this can be done by comparing holes found in /proc/&lt;pid&gt;/maps for each process.</p>
61 <p>Once found, it must open a destination file for storing the buffer, and pass it to <a class="el" href="#ga61b20e346fc76f76420e3a88cc80a671" title="Duplicate a topology to a shared memory file.">hwloc_shmem_topology_write()</a> together with virtual memory address and length obtained above.</p>
62 <p>Other processes may then adopt this shared topology by opening the same file and passing it to <a class="el" href="#ga21545bd0f09d9b554c8e60a630e0e629" title="Adopt a shared memory topology stored in a file.">hwloc_shmem_topology_adopt()</a> with the exact same virtual memory address and length. </p>
63 <a name="doc-func-members" id="doc-func-members"></a><h2 id="header-doc-func-members" class="groupheader">Function Documentation</h2>
64 <a id="ga21545bd0f09d9b554c8e60a630e0e629" name="ga21545bd0f09d9b554c8e60a630e0e629"></a>
65 <h2 class="memtitle"><span class="permalink"><a href="#ga21545bd0f09d9b554c8e60a630e0e629">&#9670;&#160;</a></span>hwloc_shmem_topology_adopt()</h2>
66
67 <div class="memitem">
68 <div class="memproto">
69 <table class="memname">
70 <tr>
71 <td class="memname">int hwloc_shmem_topology_adopt </td>
72 <td>(</td>
73 <td class="paramtype"><a class="el" href="a00169.html#ga9d1e76ee15a7dee158b786c30b6a6e38">hwloc_topology_t</a> *</td> <td class="paramname"><span class="paramname"><em>topologyp</em></span>, </td>
74 </tr>
75 <tr>
76 <td class="paramkey"></td>
77 <td></td>
78 <td class="paramtype">int</td> <td class="paramname"><span class="paramname"><em>fd</em></span>, </td>
79 </tr>
80 <tr>
81 <td class="paramkey"></td>
82 <td></td>
83 <td class="paramtype">hwloc_uint64_t</td> <td class="paramname"><span class="paramname"><em>fileoffset</em></span>, </td>
84 </tr>
85 <tr>
86 <td class="paramkey"></td>
87 <td></td>
88 <td class="paramtype">void *</td> <td class="paramname"><span class="paramname"><em>mmap_address</em></span>, </td>
89 </tr>
90 <tr>
91 <td class="paramkey"></td>
92 <td></td>
93 <td class="paramtype">size_t</td> <td class="paramname"><span class="paramname"><em>length</em></span>, </td>
94 </tr>
95 <tr>
96 <td class="paramkey"></td>
97 <td></td>
98 <td class="paramtype">unsigned long</td> <td class="paramname"><span class="paramname"><em>flags</em></span>&#160;)</td>
99 </tr>
100 </table>
101 </div><div class="memdoc">
102
103 <p>Adopt a shared memory topology stored in a file. </p>
104 <p>Map a file in virtual memory and adopt the topology that was previously stored there with <a class="el" href="#ga61b20e346fc76f76420e3a88cc80a671" title="Duplicate a topology to a shared memory file.">hwloc_shmem_topology_write()</a>.</p>
105 <p>The returned adopted topology in <code class="param">topologyp</code> can be used just like any topology. And it must be destroyed with <a class="el" href="a00169.html#ga9f34a640b6fd28d23699d4d084667b15" title="Terminate and free a topology context.">hwloc_topology_destroy()</a> as usual.</p>
106 <p>However the topology is read-only. For instance, it cannot be modified with <a class="el" href="a00177.html#ga6db81ed13ac0a9d70cc80372ab537815" title="Restrict the topology to the given CPU set or nodeset.">hwloc_topology_restrict()</a> and object userdata pointers cannot be changed.</p>
107 <p>The segment of the file pointed by descriptor <code class="param">fd</code>, starting at offset <code class="param">fileoffset</code>, and of length <code class="param">length</code> (in bytes), will be mapped at virtual address <code class="param">mmap_address</code>.</p>
108 <p>The file pointed by descriptor <code class="param">fd</code>, the offset <code class="param">fileoffset</code>, the requested mapping virtual address <code class="param">mmap_address</code> and the length <code class="param">length</code> must be identical to what was given to <a class="el" href="#ga61b20e346fc76f76420e3a88cc80a671" title="Duplicate a topology to a shared memory file.">hwloc_shmem_topology_write()</a> earlier.</p>
109 <dl class="section note"><dt>Note</dt><dd>Flags <code class="param">flags</code> are currently unused, must be 0.</dd>
110 <dd>
111 The object userdata pointer should not be used unless the process that created the shared topology also placed userdata-pointed buffers in shared memory.</dd>
112 <dd>
113 This function takes care of calling <a class="el" href="a00169.html#ga0647ae66458fe68172eb5a320042f870" title="Verify that the topology is compatible with the current hwloc library.">hwloc_topology_abi_check()</a>.</dd></dl>
114 <dl class="section return"><dt>Returns</dt><dd>0 on success.</dd>
115 <dd>
116 -1 with errno set to <code>EBUSY</code> if the virtual memory mapping defined by <code class="param">mmap_address</code> and <code class="param">length</code> isn't available in the process.</dd>
117 <dd>
118 -1 with errno set to <code>EINVAL</code> if <code class="param">fileoffset</code>, <code class="param">mmap_address</code> or <code class="param">length</code> aren't page-aligned, or do not match what was given to <a class="el" href="#ga61b20e346fc76f76420e3a88cc80a671" title="Duplicate a topology to a shared memory file.">hwloc_shmem_topology_write()</a> earlier.</dd>
119 <dd>
120 -1 with errno set to <code>EINVAL</code> if the layout of the topology structure is different between the writer process and the adopter process. </dd></dl>
121
122 </div>
123 </div>
124 <a id="ga772ab52750cdd0eec85128df24888001" name="ga772ab52750cdd0eec85128df24888001"></a>
125 <h2 class="memtitle"><span class="permalink"><a href="#ga772ab52750cdd0eec85128df24888001">&#9670;&#160;</a></span>hwloc_shmem_topology_get_length()</h2>
126
127 <div class="memitem">
128 <div class="memproto">
129 <table class="memname">
130 <tr>
131 <td class="memname">int hwloc_shmem_topology_get_length </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">size_t *</td> <td class="paramname"><span class="paramname"><em>lengthp</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>Get the required shared memory length for storing a topology. </p>
149 <p>This length (in bytes) must be used in <a class="el" href="#ga61b20e346fc76f76420e3a88cc80a671" title="Duplicate a topology to a shared memory file.">hwloc_shmem_topology_write()</a> and <a class="el" href="#ga21545bd0f09d9b554c8e60a630e0e629" title="Adopt a shared memory topology stored in a file.">hwloc_shmem_topology_adopt()</a> later.</p>
150 <dl class="section return"><dt>Returns</dt><dd>the length, or -1 on error, for instance if flags are invalid.</dd></dl>
151 <dl class="section note"><dt>Note</dt><dd>Flags <code class="param">flags</code> are currently unused, must be 0. </dd></dl>
152
153 </div>
154 </div>
155 <a id="ga61b20e346fc76f76420e3a88cc80a671" name="ga61b20e346fc76f76420e3a88cc80a671"></a>
156 <h2 class="memtitle"><span class="permalink"><a href="#ga61b20e346fc76f76420e3a88cc80a671">&#9670;&#160;</a></span>hwloc_shmem_topology_write()</h2>
157
158 <div class="memitem">
159 <div class="memproto">
160 <table class="memname">
161 <tr>
162 <td class="memname">int hwloc_shmem_topology_write </td>
163 <td>(</td>
164 <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>
165 </tr>
166 <tr>
167 <td class="paramkey"></td>
168 <td></td>
169 <td class="paramtype">int</td> <td class="paramname"><span class="paramname"><em>fd</em></span>, </td>
170 </tr>
171 <tr>
172 <td class="paramkey"></td>
173 <td></td>
174 <td class="paramtype">hwloc_uint64_t</td> <td class="paramname"><span class="paramname"><em>fileoffset</em></span>, </td>
175 </tr>
176 <tr>
177 <td class="paramkey"></td>
178 <td></td>
179 <td class="paramtype">void *</td> <td class="paramname"><span class="paramname"><em>mmap_address</em></span>, </td>
180 </tr>
181 <tr>
182 <td class="paramkey"></td>
183 <td></td>
184 <td class="paramtype">size_t</td> <td class="paramname"><span class="paramname"><em>length</em></span>, </td>
185 </tr>
186 <tr>
187 <td class="paramkey"></td>
188 <td></td>
189 <td class="paramtype">unsigned long</td> <td class="paramname"><span class="paramname"><em>flags</em></span>&#160;)</td>
190 </tr>
191 </table>
192 </div><div class="memdoc">
193
194 <p>Duplicate a topology to a shared memory file. </p>
195 <p>Temporarily map a file in virtual memory and duplicate the topology <code class="param">topology</code> by allocating duplicates in there.</p>
196 <p>The segment of the file pointed by descriptor <code class="param">fd</code>, starting at offset <code class="param">fileoffset</code>, and of length <code class="param">length</code> (in bytes), will be temporarily mapped at virtual address <code class="param">mmap_address</code> during the duplication.</p>
197 <p>The mapping length <code class="param">length</code> must have been previously obtained with <a class="el" href="#ga772ab52750cdd0eec85128df24888001" title="Get the required shared memory length for storing a topology.">hwloc_shmem_topology_get_length()</a> and the topology must not have been modified in the meantime.</p>
198 <dl class="section note"><dt>Note</dt><dd>Flags <code class="param">flags</code> are currently unused, must be 0.</dd>
199 <dd>
200 The object userdata pointer is duplicated but the pointed buffer is not. However the caller may also allocate it manually in shared memory to share it as well.</dd></dl>
201 <dl class="section return"><dt>Returns</dt><dd>0 on success. </dd>
202 <dd>
203 -1 with errno set to <code>EBUSY</code> if the virtual memory mapping defined by <code class="param">mmap_address</code> and <code class="param">length</code> isn't available in the process. </dd>
204 <dd>
205 -1 with errno set to <code>EINVAL</code> if <code class="param">fileoffset</code>, <code class="param">mmap_address</code> or <code class="param">length</code> aren't page-aligned. </dd></dl>
206
207 </div>
208 </div>
209 </div><!-- contents -->
210 <!-- start footer part -->
211 <hr class="footer"/><address class="footer"><small>
212 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
213 </small></address>
214 </div><!-- doc-content -->
215 </body>
216 </html>