1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.9.1"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>Hardware Locality (hwloc): Sharing topologies between processes</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr style="height: 56px;">
<td id="projectalign" style="padding-left: 0.5em;">
<div id="projectname">Hardware Locality (hwloc)
 <span id="projectnumber">2.4.1</span>
</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.9.1 -->
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&dn=gpl-2.0.txt GPL-v2 */
$(function() {
initMenu('',false,false,'search.php','Search');
});
/* @license-end */</script>
<div id="main-nav"></div>
</div><!-- top -->
<div class="header">
<div class="summary">
<a href="#func-members">Functions</a> </div>
<div class="headertitle">
<div class="title">Sharing topologies between processes</div> </div>
</div><!--header-->
<div class="contents">
<table class="memberdecls">
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a name="func-members"></a>
Functions</h2></td></tr>
<tr class="memitem:ga772ab52750cdd0eec85128df24888001"><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="a00232.html#ga772ab52750cdd0eec85128df24888001">hwloc_shmem_topology_get_length</a> (<a class="el" href="a00192.html#ga9d1e76ee15a7dee158b786c30b6a6e38">hwloc_topology_t</a> topology, size_t *lengthp, unsigned long flags)</td></tr>
<tr class="separator:ga772ab52750cdd0eec85128df24888001"><td class="memSeparator" colspan="2"> </td></tr>
<tr class="memitem:ga61b20e346fc76f76420e3a88cc80a671"><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="a00232.html#ga61b20e346fc76f76420e3a88cc80a671">hwloc_shmem_topology_write</a> (<a class="el" href="a00192.html#ga9d1e76ee15a7dee158b786c30b6a6e38">hwloc_topology_t</a> topology, int fd, hwloc_uint64_t fileoffset, void *mmap_address, size_t length, unsigned long flags)</td></tr>
<tr class="separator:ga61b20e346fc76f76420e3a88cc80a671"><td class="memSeparator" colspan="2"> </td></tr>
<tr class="memitem:ga21545bd0f09d9b554c8e60a630e0e629"><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="a00232.html#ga21545bd0f09d9b554c8e60a630e0e629">hwloc_shmem_topology_adopt</a> (<a class="el" href="a00192.html#ga9d1e76ee15a7dee158b786c30b6a6e38">hwloc_topology_t</a> *topologyp, int fd, hwloc_uint64_t fileoffset, void *mmap_address, size_t length, unsigned long flags)</td></tr>
<tr class="separator:ga21545bd0f09d9b554c8e60a630e0e629"><td class="memSeparator" colspan="2"> </td></tr>
</table>
<a name="details" id="details"></a><h2 class="groupheader">Detailed Description</h2>
<p>These functions are used to share a topology between processes by duplicating it into a file-backed shared-memory buffer.</p>
<p>The master process must first get the required shared-memory size for storing this topology with <a class="el" href="a00232.html#ga772ab52750cdd0eec85128df24888001" title="Get the required shared memory length for storing a topology.">hwloc_shmem_topology_get_length()</a>.</p>
<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/<pid>/maps for each process.</p>
<p>Once found, it must open a destination file for storing the buffer, and pass it to <a class="el" href="a00232.html#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>
<p>Other processes may then adopt this shared topology by opening the same file and passing it to <a class="el" href="a00232.html#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>
<h2 class="groupheader">Function Documentation</h2>
<a id="ga21545bd0f09d9b554c8e60a630e0e629"></a>
<h2 class="memtitle"><span class="permalink"><a href="#ga21545bd0f09d9b554c8e60a630e0e629">◆ </a></span>hwloc_shmem_topology_adopt()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int hwloc_shmem_topology_adopt </td>
<td>(</td>
<td class="paramtype"><a class="el" href="a00192.html#ga9d1e76ee15a7dee158b786c30b6a6e38">hwloc_topology_t</a> * </td>
<td class="paramname"><em>topologyp</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int </td>
<td class="paramname"><em>fd</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">hwloc_uint64_t </td>
<td class="paramname"><em>fileoffset</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">void * </td>
<td class="paramname"><em>mmap_address</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">size_t </td>
<td class="paramname"><em>length</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">unsigned long </td>
<td class="paramname"><em>flags</em> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Adopt a shared memory topology stored in a file. </p>
<p>Map a file in virtual memory and adopt the topology that was previously stored there with <a class="el" href="a00232.html#ga61b20e346fc76f76420e3a88cc80a671" title="Duplicate a topology to a shared memory file.">hwloc_shmem_topology_write()</a>.</p>
<p>The returned adopted topology in <code>topologyp</code> can be used just like any topology. And it must be destroyed with <a class="el" href="a00192.html#ga9f34a640b6fd28d23699d4d084667b15" title="Terminate and free a topology context.">hwloc_topology_destroy()</a> as usual.</p>
<p>However the topology is read-only. For instance, it cannot be modified with <a class="el" href="a00200.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>
<p>The segment of the file pointed by descriptor <code>fd</code>, starting at offset <code>fileoffset</code>, and of length <code>length</code> (in bytes), will be mapped at virtual address <code>mmap_address</code>.</p>
<p>The file pointed by descriptor <code>fd</code>, the offset <code>fileoffset</code>, the requested mapping virtual address <code>mmap_address</code> and the length <code>length</code> must be identical to what was given to <a class="el" href="a00232.html#ga61b20e346fc76f76420e3a88cc80a671" title="Duplicate a topology to a shared memory file.">hwloc_shmem_topology_write()</a> earlier.</p>
<dl class="section note"><dt>Note</dt><dd>Flags <code>flags</code> are currently unused, must be 0.</dd>
<dd>
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>
<dd>
This function takes care of calling <a class="el" href="a00192.html#ga0647ae66458fe68172eb5a320042f870" title="Verify that the topology is compatible with the current hwloc library.">hwloc_topology_abi_check()</a>.</dd></dl>
<dl class="section return"><dt>Returns</dt><dd>-1 with errno set to EBUSY if the virtual memory mapping defined by <code>mmap_address</code> and <code>length</code> isn't available in the process.</dd>
<dd>
-1 with errno set to EINVAL if <code>fileoffset</code>, <code>mmap_address</code> or <code>length</code> aren't page-aligned, or do not match what was given to <a class="el" href="a00232.html#ga61b20e346fc76f76420e3a88cc80a671" title="Duplicate a topology to a shared memory file.">hwloc_shmem_topology_write()</a> earlier.</dd>
<dd>
-1 with errno set to EINVAL if the layout of the topology structure is different between the writer process and the adopter process. </dd></dl>
</div>
</div>
<a id="ga772ab52750cdd0eec85128df24888001"></a>
<h2 class="memtitle"><span class="permalink"><a href="#ga772ab52750cdd0eec85128df24888001">◆ </a></span>hwloc_shmem_topology_get_length()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int hwloc_shmem_topology_get_length </td>
<td>(</td>
<td class="paramtype"><a class="el" href="a00192.html#ga9d1e76ee15a7dee158b786c30b6a6e38">hwloc_topology_t</a> </td>
<td class="paramname"><em>topology</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">size_t * </td>
<td class="paramname"><em>lengthp</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">unsigned long </td>
<td class="paramname"><em>flags</em> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Get the required shared memory length for storing a topology. </p>
<p>This length (in bytes) must be used in <a class="el" href="a00232.html#ga61b20e346fc76f76420e3a88cc80a671" title="Duplicate a topology to a shared memory file.">hwloc_shmem_topology_write()</a> and <a class="el" href="a00232.html#ga21545bd0f09d9b554c8e60a630e0e629" title="Adopt a shared memory topology stored in a file.">hwloc_shmem_topology_adopt()</a> later.</p>
<dl class="section note"><dt>Note</dt><dd>Flags <code>flags</code> are currently unused, must be 0. </dd></dl>
</div>
</div>
<a id="ga61b20e346fc76f76420e3a88cc80a671"></a>
<h2 class="memtitle"><span class="permalink"><a href="#ga61b20e346fc76f76420e3a88cc80a671">◆ </a></span>hwloc_shmem_topology_write()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int hwloc_shmem_topology_write </td>
<td>(</td>
<td class="paramtype"><a class="el" href="a00192.html#ga9d1e76ee15a7dee158b786c30b6a6e38">hwloc_topology_t</a> </td>
<td class="paramname"><em>topology</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int </td>
<td class="paramname"><em>fd</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">hwloc_uint64_t </td>
<td class="paramname"><em>fileoffset</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">void * </td>
<td class="paramname"><em>mmap_address</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">size_t </td>
<td class="paramname"><em>length</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">unsigned long </td>
<td class="paramname"><em>flags</em> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Duplicate a topology to a shared memory file. </p>
<p>Temporarily map a file in virtual memory and duplicate the topology <code>topology</code> by allocating duplicates in there.</p>
<p>The segment of the file pointed by descriptor <code>fd</code>, starting at offset <code>fileoffset</code>, and of length <code>length</code> (in bytes), will be temporarily mapped at virtual address <code>mmap_address</code> during the duplication.</p>
<p>The mapping length <code>length</code> must have been previously obtained with <a class="el" href="a00232.html#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>
<dl class="section note"><dt>Note</dt><dd>Flags <code>flags</code> are currently unused, must be 0.</dd>
<dd>
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>
<dl class="section return"><dt>Returns</dt><dd>-1 with errno set to EBUSY if the virtual memory mapping defined by <code>mmap_address</code> and <code>length</code> isn't available in the process. </dd>
<dd>
-1 with errno set to EINVAL if <code>fileoffset</code>, <code>mmap_address</code> or <code>length</code> aren't page-aligned. </dd></dl>
</div>
</div>
</div><!-- contents -->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated by <a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.9.1
</small></address>
</body>
</html>
|
