Debian Codegraph @

doc/doxygen-doc/man/man3/hwlocality_diff.3

raw
1 .TH "hwlocality_diff" 3 "Version 2.14.0" "Hardware Locality (hwloc)" \" -*- nroff -*-
2 .ad l
3 .nh
4 .SH NAME
5 hwlocality_diff \- Topology differences
6 .SH SYNOPSIS
7 .br
8 .PP
9 .SS "Data Structures"
10
11 .in +1c
12 .ti -1c
13 .RI "union \fBhwloc_topology_diff_obj_attr_u\fP"
14 .br
15 .ti -1c
16 .RI "union \fBhwloc_topology_diff_u\fP"
17 .br
18 .in -1c
19 .SS "Typedefs"
20
21 .in +1c
22 .ti -1c
23 .RI "typedef enum \fBhwloc_topology_diff_obj_attr_type_e\fP \fBhwloc_topology_diff_obj_attr_type_t\fP"
24 .br
25 .ti -1c
26 .RI "typedef enum \fBhwloc_topology_diff_type_e\fP \fBhwloc_topology_diff_type_t\fP"
27 .br
28 .ti -1c
29 .RI "typedef union \fBhwloc_topology_diff_u\fP * \fBhwloc_topology_diff_t\fP"
30 .br
31 .in -1c
32 .SS "Enumerations"
33
34 .in +1c
35 .ti -1c
36 .RI "enum \fBhwloc_topology_diff_obj_attr_type_e\fP { \fBHWLOC_TOPOLOGY_DIFF_OBJ_ATTR_SIZE\fP, \fBHWLOC_TOPOLOGY_DIFF_OBJ_ATTR_NAME\fP, \fBHWLOC_TOPOLOGY_DIFF_OBJ_ATTR_INFO\fP }"
37 .br
38 .ti -1c
39 .RI "enum \fBhwloc_topology_diff_type_e\fP { \fBHWLOC_TOPOLOGY_DIFF_OBJ_ATTR\fP, \fBHWLOC_TOPOLOGY_DIFF_TOO_COMPLEX\fP }"
40 .br
41 .ti -1c
42 .RI "enum \fBhwloc_topology_diff_apply_flags_e\fP { \fBHWLOC_TOPOLOGY_DIFF_APPLY_REVERSE\fP }"
43 .br
44 .in -1c
45 .SS "Functions"
46
47 .in +1c
48 .ti -1c
49 .RI "int \fBhwloc_topology_diff_build\fP (\fBhwloc_topology_t\fP topology, \fBhwloc_topology_t\fP newtopology, unsigned long flags, \fBhwloc_topology_diff_t\fP *diff)"
50 .br
51 .ti -1c
52 .RI "int \fBhwloc_topology_diff_apply\fP (\fBhwloc_topology_t\fP topology, \fBhwloc_topology_diff_t\fP diff, unsigned long flags)"
53 .br
54 .ti -1c
55 .RI "int \fBhwloc_topology_diff_destroy\fP (\fBhwloc_topology_diff_t\fP diff)"
56 .br
57 .ti -1c
58 .RI "int \fBhwloc_topology_diff_load_xml\fP (const char *xmlpath, \fBhwloc_topology_diff_t\fP *diff, char **refname)"
59 .br
60 .ti -1c
61 .RI "int \fBhwloc_topology_diff_export_xml\fP (\fBhwloc_topology_diff_t\fP diff, const char *refname, const char *xmlpath)"
62 .br
63 .ti -1c
64 .RI "int \fBhwloc_topology_diff_load_xmlbuffer\fP (const char *xmlbuffer, int buflen, \fBhwloc_topology_diff_t\fP *diff, char **refname)"
65 .br
66 .ti -1c
67 .RI "int \fBhwloc_topology_diff_export_xmlbuffer\fP (\fBhwloc_topology_diff_t\fP diff, const char *refname, char **xmlbuffer, int *buflen)"
68 .br
69 .in -1c
70 .SH "Detailed Description"
71 .PP
72 Applications that manipulate many similar topologies, for instance one for each node of a homogeneous cluster, may want to compress topologies to reduce the memory footprint\&.
73
74 .PP
75 This file offers a way to manipulate the difference between topologies and export/import it to/from XML\&. Compression may therefore be achieved by storing one topology entirely while the others are only described by their differences with the former\&. The actual topology can be reconstructed when actually needed by applying the precomputed difference to the reference topology\&.
76
77 .PP
78 This interface targets very similar nodes\&. Only very simple differences between topologies are actually supported, for instance a change in the memory size, the name of the object, or some info attribute\&. More complex differences such as adding or removing objects cannot be represented in the difference structures and therefore return errors\&. Differences between object sets or topology-wide allowed sets, cannot be represented either\&.
79
80 .PP
81 It means that there is no need to apply the difference when looking at the tree organization (how many levels, how many objects per level, what kind of objects, CPU and node sets, etc) and when binding to objects\&. However the difference must be applied when looking at object attributes such as the name, the memory size or info attributes\&.
82 .SH "Typedef Documentation"
83 .PP
84 .SS "typedef enum \fBhwloc_topology_diff_obj_attr_type_e\fP \fBhwloc_topology_diff_obj_attr_type_t\fP"
85
86 .PP
87 Type of one object attribute difference\&.
88 .SS "typedef union \fBhwloc_topology_diff_u\fP * \fBhwloc_topology_diff_t\fP"
89
90 .PP
91 One element of a difference list between two topologies\&.
92 .SS "typedef enum \fBhwloc_topology_diff_type_e\fP \fBhwloc_topology_diff_type_t\fP"
93
94 .PP
95 Type of one element of a difference list\&.
96 .SH "Enumeration Type Documentation"
97 .PP
98 .SS "enum \fBhwloc_topology_diff_apply_flags_e\fP"
99
100 .PP
101 Flags to be given to \fBhwloc_topology_diff_apply()\fP\&.
102 .PP
103 \fBEnumerator\fP
104 .in +1c
105 .TP
106 \f(BIHWLOC_TOPOLOGY_DIFF_APPLY_REVERSE \fP
107 Apply topology diff in reverse direction\&.
108 .SS "enum \fBhwloc_topology_diff_obj_attr_type_e\fP"
109
110 .PP
111 Type of one object attribute difference\&.
112 .PP
113 \fBEnumerator\fP
114 .in +1c
115 .TP
116 \f(BIHWLOC_TOPOLOGY_DIFF_OBJ_ATTR_SIZE \fP
117 The object local memory is modified\&. The union is a \fBhwloc_topology_diff_obj_attr_u::hwloc_topology_diff_obj_attr_uint64_s\fP (and the index field is ignored)\&.
118 .TP
119 \f(BIHWLOC_TOPOLOGY_DIFF_OBJ_ATTR_NAME \fP
120 The object name is modified\&. The union is a \fBhwloc_topology_diff_obj_attr_u::hwloc_topology_diff_obj_attr_string_s\fP (and the name field is ignored)\&.
121 .TP
122 \f(BIHWLOC_TOPOLOGY_DIFF_OBJ_ATTR_INFO \fP
123 the value of an info attribute is modified\&. The union is a \fBhwloc_topology_diff_obj_attr_u::hwloc_topology_diff_obj_attr_string_s\fP\&.
124 .SS "enum \fBhwloc_topology_diff_type_e\fP"
125
126 .PP
127 Type of one element of a difference list\&.
128 .PP
129 \fBEnumerator\fP
130 .in +1c
131 .TP
132 \f(BIHWLOC_TOPOLOGY_DIFF_OBJ_ATTR \fP
133 An object attribute was changed\&. The union is a \fBhwloc_topology_diff_u::hwloc_topology_diff_obj_attr_s\fP\&.
134 .TP
135 \f(BIHWLOC_TOPOLOGY_DIFF_TOO_COMPLEX \fP
136 The difference is too complex, it cannot be represented\&. The difference below this object has not been checked\&. \fBhwloc_topology_diff_build()\fP will return 1\&. The union is a \fBhwloc_topology_diff_u::hwloc_topology_diff_too_complex_s\fP\&.
137 .SH "Function Documentation"
138 .PP
139 .SS "int hwloc_topology_diff_apply (\fBhwloc_topology_t\fP topology, \fBhwloc_topology_diff_t\fP diff, unsigned long flags)"
140
141 .PP
142 Apply a topology diff to an existing topology\&. \fRflags\fP is an OR'ed set of \fBhwloc_topology_diff_apply_flags_e\fP\&.
143
144 .PP
145 The new topology is modified in place\&. \fBhwloc_topology_dup()\fP may be used to duplicate it before patching\&.
146
147 .PP
148 If the difference cannot be applied entirely, all previous applied elements are unapplied before returning\&.
149
150 .PP
151 \fBReturns\fP
152 .RS 4
153 0 on success\&.
154
155 .PP
156 -N if applying the difference failed while trying to apply the N-th part of the difference\&. For instance -1 is returned if the very first difference element could not be applied\&.
157 .RE
158 .PP
159
160 .SS "int hwloc_topology_diff_build (\fBhwloc_topology_t\fP topology, \fBhwloc_topology_t\fP newtopology, unsigned long flags, \fBhwloc_topology_diff_t\fP * diff)"
161
162 .PP
163 Compute the difference between 2 topologies\&. The difference is stored as a list of \fBhwloc_topology_diff_t\fP entries starting at \fRdiff\fP\&. It is computed by doing a depth-first traversal of both topology trees simultaneously\&.
164
165 .PP
166 If the difference between 2 objects is too complex to be represented (for instance if some objects have different types, or different numbers of children), a special diff entry of type \fBHWLOC_TOPOLOGY_DIFF_TOO_COMPLEX\fP is queued\&. The computation of the diff does not continue below these objects\&. So each such diff entry means that the difference between two subtrees could not be computed\&.
167
168 .PP
169 \fBReturns\fP
170 .RS 4
171 0 if the difference can be represented properly\&.
172
173 .PP
174 0 with \fRdiff\fP pointing to NULL if there is no difference between the topologies\&.
175
176 .PP
177 1 if the difference is too complex (see above)\&. Some entries in the list will be of type \fBHWLOC_TOPOLOGY_DIFF_TOO_COMPLEX\fP\&.
178
179 .PP
180 -1 on any other error\&.
181 .RE
182 .PP
183 \fBNote\fP
184 .RS 4
185 \fRflags\fP is currently not used\&. It should be 0\&.
186
187 .PP
188 The output diff has to be freed with \fBhwloc_topology_diff_destroy()\fP\&.
189
190 .PP
191 The output diff can only be exported to XML or passed to \fBhwloc_topology_diff_apply()\fP if 0 was returned, i\&.e\&. if no entry of type \fBHWLOC_TOPOLOGY_DIFF_TOO_COMPLEX\fP is listed\&.
192
193 .PP
194 The output diff may be modified by removing some entries from the list\&. The removed entries should be freed by passing them to to \fBhwloc_topology_diff_destroy()\fP (possible as another list)\&.
195 .RE
196 .PP
197
198 .SS "int hwloc_topology_diff_destroy (\fBhwloc_topology_diff_t\fP diff)"
199
200 .PP
201 Destroy a list of topology differences\&.
202 .PP
203 \fBReturns\fP
204 .RS 4
205 0\&.
206 .RE
207 .PP
208
209 .SS "int hwloc_topology_diff_export_xml (\fBhwloc_topology_diff_t\fP diff, const char * refname, const char * xmlpath)"
210
211 .PP
212 Export a list of topology differences to a XML file\&. If not \fRNULL\fP, \fRrefname\fP defines an identifier string for the reference topology which was used as a base when computing this difference\&. This identifier is usually the name of the other XML file that contains the reference topology\&. This attribute is given back when reading the diff from XML\&.
213
214 .PP
215 \fBReturns\fP
216 .RS 4
217 0 on success, -1 on error\&.
218 .RE
219 .PP
220
221 .SS "int hwloc_topology_diff_export_xmlbuffer (\fBhwloc_topology_diff_t\fP diff, const char * refname, char ** xmlbuffer, int * buflen)"
222
223 .PP
224 Export a list of topology differences to a XML buffer\&. If not \fRNULL\fP, \fRrefname\fP defines an identifier string for the reference topology which was used as a base when computing this difference\&. This identifier is usually the name of the other XML file that contains the reference topology\&. This attribute is given back when reading the diff from XML\&.
225
226 .PP
227 The returned buffer ends with a \fR\\0\fP that is included in the returned length\&.
228
229 .PP
230 \fBReturns\fP
231 .RS 4
232 0 on success, -1 on error\&.
233 .RE
234 .PP
235 \fBNote\fP
236 .RS 4
237 The XML buffer should later be freed with \fBhwloc_free_xmlbuffer()\fP\&.
238 .RE
239 .PP
240
241 .SS "int hwloc_topology_diff_load_xml (const char * xmlpath, \fBhwloc_topology_diff_t\fP * diff, char ** refname)"
242
243 .PP
244 Load a list of topology differences from a XML file\&. If not \fRNULL\fP, \fRrefname\fP will be filled with the identifier string of the reference topology for the difference file, if any was specified in the XML file\&. This identifier is usually the name of the other XML file that contains the reference topology\&.
245
246 .PP
247 \fBReturns\fP
248 .RS 4
249 0 on success, -1 on error\&.
250 .RE
251 .PP
252 \fBNote\fP
253 .RS 4
254 the pointer returned in refname should later be freed by the caller\&.
255 .RE
256 .PP
257
258 .SS "int hwloc_topology_diff_load_xmlbuffer (const char * xmlbuffer, int buflen, \fBhwloc_topology_diff_t\fP * diff, char ** refname)"
259
260 .PP
261 Load a list of topology differences from a XML buffer\&. Build a list of differences from the XML memory buffer given at \fRxmlbuffer\fP and of length \fRbuflen\fP (including an ending \fR\\0\fP)\&. This buffer may have been filled earlier with \fBhwloc_topology_diff_export_xmlbuffer()\fP\&.
262
263 .PP
264 If not \fRNULL\fP, \fRrefname\fP will be filled with the identifier string of the reference topology for the difference file, if any was specified in the XML file\&. This identifier is usually the name of the other XML file that contains the reference topology\&.
265
266 .PP
267 \fBReturns\fP
268 .RS 4
269 0 on success, -1 on error\&.
270 .RE
271 .PP
272 \fBNote\fP
273 .RS 4
274 the pointer returned in refname should later be freed by the caller\&.
275 .RE
276 .PP
277
278 .SH "Author"
279 .PP
280 Generated automatically by Doxygen for Hardware Locality (hwloc) from the source code\&.