OpenMPI 0.1.1

- Main Page
- Related Pages
- Modules
- Data Structures
- Files

- File List
- Globals

OTF_MasterControl.h
Go to the documentation of this file.
1 /*
2 This is part of the OTF library. Copyright by ZIH, TU Dresden 2005-2012.
3 Authors: Andreas Knuepfer, Holger Brunst, Ronny Brendel, Thomas Kriebitzsch
4 */
5
6 /**
7 * @file OTF_MasterControl.h
8 *
9 * @brief Provides access to process-stream-mapping, which are located in
10 * .otf files.
11 *
12 * \ingroup mc
13 */
14
15 /** \defgroup mc Master Control Interface
16 *
17 * This interface is dedicated to managing master control files ( *.otf )
18 * A master control file contains a mapping from process streams
19 * to processes and vice versa.
20 *
21 * \section mc_example A simple Example
22 *
23 * This is example will create a simple mapping and read it again to
24 * show how reading and writing works with the master control file.
25 *
26 * The need for creating your own master control file arises when you are not
27 * using the highlevel reader/writer, but the stream reader/writer.
28 *
29 *
30 * \code
31 * #include <stdio.h>
32 * #include <assert.h>
33 * #include "otf.h"
34 *
35 * int main( int argc, char** argv ) {
36 * \endcode
37 *
38 * Declare a couple of variables.
39 * \code
40 * uint32_t streamcount;
41 * uint32_t a;
42 * uint32_t i;
43 * OTF_MapEntry* entry;
44 * OTF_FileManager* manager;
45 * OTF_MasterControl* mc;
46 * \endcode
47 *
48 * Initialize the file manager and the mastercontrol.
49 * \code
50 * manager= OTF_FileManager_open( 100 );
51 * assert( manager );
52 *
53 * mc = OTF_MasterControl_new( manager );
54 * \endcode
55 *
56 * Add four processes (100,101,102,103) to two streams (1,2)
57 * \code
58 * OTF_MasterControl_append( mc, 1, 100 );
59 * OTF_MasterControl_append( mc, 1, 101 );
60 * OTF_MasterControl_append( mc, 2, 102 );
61 * OTF_MasterControl_append( mc, 2, 103 );
62 * \endcode
63 *
64 * Write everything to the file "mytrace.otf"
65 * and close the master control.
66 * \code
67 * OTF_MasterControl_write( mc, "mytrace" );
68 * OTF_MasterControl_close( mc );
69 * \endcode
70 *
71 * Now initialize the master control structure and read the
72 * newly written master control file.
73 * \code
74 * mc = OTF_MasterControl_new( manager );
75 * OTF_MasterControl_read( mc, "mytrace" );
76 * \endcode
77 *
78 * Visit all stream-process pairs and print them out
79 * \code
80 * streamcount = OTF_MasterControl_getCount( mc );
81 *
82 * for( i = 0; i < streamcount; ++i ) {
83 * entry = OTF_MasterControl_getEntryByIndex( mc, i );
84 * for( a = 0; a < entry->n; ++a ) {
85 * printf( " stream %u contains process %u\n", entry->argument,
86 * entry->values[a] );
87 * }
88 * }
89 * \endcode
90 *
91 * Clean everything up before exiting the program
92 * \code
93 * OTF_MasterControl_close( mc );
94 *
95 *
96 * return 0;
97 * }
98 * \endcode
99 *
100 * Compile this using $ gcc -o test test.c `otfconfig --libs`.
101 *
102 * The program will show this output:
103 * \verbatim
104 * stream 1 contains process 100
105 * stream 1 contains process 101
106 * stream 2 contains process 102
107 * stream 2 contains process 103 \endverbatim
108 *
109 * */
110
111 #ifndef OTF_MASTERCONTROL_H
112 #define OTF_MASTERCONTROL_H
113
114
115 #include <stdlib.h>
116 #include <stdio.h>
117 #include <string.h>
118
119
120 #include "OTF_inttypes.h"
121
122
123 #include "OTF_File.h"
124 #include "OTF_Filenames.h"
125 #include "OTF_WBuffer.h"
126 #include "OTF_RBuffer.h"
127
128
129 #ifdef __cplusplus
130 extern "C" {
131 #endif /* __cplusplus */
132
133 /** entry for 1:n mapping */
134 struct struct_OTF_MapEntry {
135
136 /** Unique argument ids. (stream ids) */
137 uint32_t argument;
138
139 /** Current number of entries in 'values'. */
140 uint32_t n;
141
142 /** Current size of array 'values'. */
143 uint32_t s;
144
145 /** List of size 's' containing 'n' sorted entries of unique value ids
146 (process ids). */
147 uint32_t* values;
148 };
149 /** entry for 1:n mapping \ingroup mc */
150 typedef struct struct_OTF_MapEntry OTF_MapEntry;
151
152
153 /** entry for 1:1 mapping */
154 struct struct_OTF_Pair {
155
156 uint32_t argument;
157 uint32_t value;
158 };
159 /** entry for 1:1 mapping \ingroup mc */
160 typedef struct struct_OTF_Pair OTF_Pair;
161
162
163 /** Data structure that collects the information about which stream contains
164 which parts of a multi-file trace. This is supposed to be an 1:1 copy of
165 the information in the master control file. */
166 struct struct_OTF_MasterControl {
167
168
169 /** Current number of entries in 'map'. */
170 uint32_t n;
171
172 /** Current size of array 'map'. */
173 uint32_t s;
174
175 /** Mapping from stream ids (argument) to process ids (values).
176 1:n mapping since a stream can contain multiple processes.
177 This mapping is the authoritative source as listed in the master
178 control file. */
179 OTF_MapEntry* map;
180
181
182 /** Current number of entries in 'rmap'. */
183 uint32_t rn;
184
185 /** Current size of array 'rmap'. */
186 uint32_t rs;
187
188 /** Reverse mapping to 'map'. this is an 1:1 mapping since every
189 process belongs to exactly one stream.
190 This recursive mapping is to be derived from the authoritative source
191 in 'map'. */
192 OTF_Pair* rmap;
193
194 /** file handle manager */
195 OTF_FileManager* manager;
196 };
197 /** master control object. This object contains all information of the master
198 * control file. \ingroup mc */
199 typedef struct struct_OTF_MasterControl OTF_MasterControl;
200
201
202 /**
203 * Creates an empty OTF_MasterControl object.
204 * The returned object must be freed by OTF_MasterControl_close().
205 *
206 * @param manager File handle manager.
207 *
208 * @return newly created master control object
209 *
210 * \ingroup mc
211 */
212 OTF_MasterControl* OTF_MasterControl_new( OTF_FileManager* manager );
213
214
215 /**
216 * INTERFACE CHANGED!
217 * Read a master control file according to namestub, reset the _existing_
218 * OTF_MasterControl structure and fill it according to the file.
219 *
220 * @param mc Pointer to an initialized OTF_Mastercontrol object. See also
221 * OTF_MasterControl_new().
222 *
223 * @return 1 on success, 0 if an error occurs
224 *
225 * \ingroup mc
226 */
227 int OTF_MasterControl_read(OTF_MasterControl* mc, const char* namestub );
228
229
230 /** Destructor, delete OTF_MasterControl object. DEPRECATED \ingroup mc*/
231 void OTF_MasterControl_finish( OTF_MasterControl* mc );
232
233 /**
234 * Deletes a OTF_MasterControl object.
235 *
236 * @param mc Pointer to an initialized OTF_Mastercontrol object. See also
237 * OTF_MasterControl_new().
238 *
239 * \ingroup mc
240 */
241 void OTF_MasterControl_close( OTF_MasterControl* mc );
242
243 /**
244 * Append the mapping argument -> value to the master control structure,
245 *
246 * @param mc Pointer to an initialized OTF_Mastercontrol object. See also
247 * OTF_MasterControl_new().
248 * @param argument Represents the stream identifier.
249 * @param value Represents the process identifier.
250 *
251 * @return 1 on sucess, 0 if an error occurs (e.g. the new pair
252 * conflicts with the current mapping).
253 *
254 * \ingroup mc
255 */
256 int OTF_MasterControl_append( OTF_MasterControl* mc,
257 uint32_t argument, uint32_t value );
258
259
260 /**
261 * Append the mapping argument -> ( list of l values ) to the master control
262 * structure. This is equal to calling 'OTF_MasterControl_append()' with every
263 * value in list separately.
264 *
265 * @param mc Pointer to an initialized OTF_Mastercontrol object. See also
266 * OTF_MasterControl_new().
267 * @param argument Represents the stream identifier.
268 * @param l Number of elements in the value array.
269 * @param values Array of process identifiers belonging to the stream.
270 *
271 * @return 1 on success, 0 if an error occurs (e.g. the new entries
272 * conflict with the current mapping).
273 *
274 *
275 *
276 * \ingroup mc
277 */
278 int OTF_MasterControl_appendList( OTF_MasterControl* mc, uint32_t argument,
279 uint32_t l, uint32_t* values );
280
281
282 /**
283 * Returns the argument to the given value. If no mapping was defined
284 * make up a new one.
285 *
286 * @param mc Pointer to an initialized OTF_Mastercontrol object. See also
287 * OTF_MasterControl_new().
288 * @param value Represents the process identifier.
289 *
290 * @return Argument to which the value belongs to.
291 *
292 * \ingroup mc
293 */
294 uint32_t OTF_MasterControl_mapReverse( OTF_MasterControl* mc, uint32_t value );
295
296
297 /**
298 * Writes a master control file with the current contents of the given
299 * object.
300 *
301 * @param mc Pointer to an initialized OTF_Mastercontrol object. See also
302 * OTF_MasterControl_new().
303 * @param namestub File name prefix which.
304 *
305 * @return 1 on success, 0 if an error occurs.
306 *
307 * \ingroup mc
308 */
309 int OTF_MasterControl_write( OTF_MasterControl* mc, const char* namestub );
310
311
312 /**
313 * Checks if the current mapping is consistent in itself.
314 *
315 * @param mc Pointer to an initialized OTF_Mastercontrol object. See also
316 * OTF_MasterControl_new().
317 *
318 * @return 1 on success, 0 if the mapping is not consistent in itself.
319 *
320 * \ingroup mc
321 */
322 int OTF_MasterControl_check( OTF_MasterControl* mc );
323
324
325 /**
326 * Prints the mapping to stderr.
327 *
328 * @param mc Pointer to an initialized OTF_Mastercontrol object. See also
329 * OTF_MasterControl_new().
330 *
331 * \ingroup mc
332 */
333 void OTF_MasterControl_print( OTF_MasterControl* mc );
334
335
336 /**
337 * Returns the entry for the given argument.
338 *
339 * @param mc Pointer to an initialized OTF_Mastercontrol object. See also
340 * OTF_MasterControl_new().
341 * @param argument Represents the stream identifier.
342 *
343 * @return The map entry belonging to the argument, or NULL if an error
344 * occurs.
345 *
346 * \ingroup mc
347 */
348 OTF_MapEntry* OTF_MasterControl_getEntry( OTF_MasterControl* mc,
349 uint32_t argument );
350
351
352 /**
353 * Returns the entry for the given index.
354 *
355 * @param mc Pointer to an initialized OTF_Mastercontrol object. See also
356 * OTF_MasterControl_new().
357 * @param index Index of the entry to return.
358 *
359 * @return The map entry belonging to the index, or NULL if the index
360 * exceeds the mapping.
361 *
362 * \ingroup mc
363 */
364 OTF_MapEntry* OTF_MasterControl_getEntryByIndex( OTF_MasterControl* mc,
365 uint32_t index );
366
367
368 /**
369 * Returns a pair of value and argument for the given index.
370 *
371 * @param mc Pointer to an initialized OTF_Mastercontrol object. See also
372 * OTF_MasterControl_new().
373 * @param index Index of the pair in the reverse mapping.
374 *
375 * @return Pair of value and argument belonging
376 * to the index, or NULL if the index exceeds the reverse
377 * mapping.
378 *
379 * \ingroup mc
380 */
381 OTF_Pair* OTF_MasterControl_getREntryByIndex( OTF_MasterControl* mc,
382 uint32_t index );
383
384
385 /**
386 * Returns the number of arguments in the current list.
387 *
388 * @param mc Pointer to an initialized OTF_Mastercontrol object. See also
389 * OTF_MasterControl_new().
390 *
391 * @return Number of entrys in the current list.
392 * (equals the number of streams)
393 *
394 * \ingroup mc
395 */
396 uint32_t OTF_MasterControl_getCount( OTF_MasterControl* mc );
397
398 /**
399 * Returns the number of arguments in current reverse list.
400 *
401 * @param mc Pointer to an initialized OTF_Mastercontrol object. See also
402 * OTF_MasterControl_new().
403 *
404 * @return Number of entrys in the current reverse list.
405 * (equals the number of processes)
406 *
407 * \ingroup mc
408 */
409 uint32_t OTF_MasterControl_getrCount( OTF_MasterControl* mc );
410
411 /**
412 * Returns the number of values for the given argument.
413 *
414 * @param mc Pointer to an initialized OTF_Mastercontrol object. See also
415 * OTF_MasterControl_new().
416 * @param argument Represents the stream identifier.
417 *
418 * @return Number of values for the given argument, or
419 * 0 if the argument is unknown.
420 *
421 * \ingroup mc
422 */
423 uint32_t OTF_MasterControl_getValueCount( OTF_MasterControl* mc,
424 uint32_t argument );
425
426
427 /**
428 * Returns a pointer to the value array for 'argument'. Get size of list with
429 * 'OTF_MasterControl_getValueCount()'.
430 *
431 * @param mc Pointer to an initialized OTF_Mastercontrol object. See also
432 * OTF_MasterControl_new().
433 * @param argument Represents the stream identifier.
434 *
435 * @return Pointer to the value array for 'argument', or NULL if an
436 * error occurs.
437 *
438 * \ingroup mc
439 */
440 uint32_t* OTF_MasterControl_getValues( OTF_MasterControl* mc,
441 uint32_t argument );
442
443
444 /**
445 * Returns a previously unused argument. Of course, one cannot avoid
446 * collisions with arguments explicitly defined later on.
447 *
448 * @param mc Pointer to an initialized OTF_Mastercontrol object. See also
449 * OTF_MasterControl_new().
450 *
451 * @return Unused argument.
452 *
453 * \ingroup mc
454 */
455 uint32_t OTF_MasterControl_getNewStreamId( OTF_MasterControl* mc );
456
457
458 #ifdef __cplusplus
459 }
460 #endif /* __cplusplus */
461
462 #endif /* OTF_MASTERCONTROL_H */
463
struct_OTF_MapEntry::s
uint32_t s
Current size of array 'values'.
Definition: OTF_MasterControl.h:143
OTF_MasterControl_close
void OTF_MasterControl_close(OTF_MasterControl *mc)
Deletes a OTF_MasterControl object.
Definition: OTF_MasterControl.c:121
OTF_MasterControl_getEntryByIndex
OTF_MapEntry * OTF_MasterControl_getEntryByIndex(OTF_MasterControl *mc, uint32_t index)
Returns the entry for the given index.
Definition: OTF_MasterControl.c:846
struct_OTF_Pair
entry for 1:1 mapping
Definition: OTF_MasterControl.h:154
struct_OTF_MasterControl::map
OTF_MapEntry * map
Mapping from stream ids (argument) to process ids (values).
Definition: OTF_MasterControl.h:179
OTF_MasterControl_write
int OTF_MasterControl_write(OTF_MasterControl *mc, const char *namestub)
Writes a master control file with the current contents of the given object.
Definition: OTF_MasterControl.c:645
OTF_MasterControl_print
void OTF_MasterControl_print(OTF_MasterControl *mc)
Prints the mapping to stderr.
Definition: OTF_MasterControl.c:772
OTF_MasterControl_getrCount
uint32_t OTF_MasterControl_getrCount(OTF_MasterControl *mc)
Returns the number of arguments in current reverse list.
Definition: OTF_MasterControl.c:879
OTF_MasterControl_appendList
int OTF_MasterControl_appendList(OTF_MasterControl *mc, uint32_t argument, uint32_t l, uint32_t *values)
Append the mapping argument -> ( list of l values ) to the master control structure.
Definition: OTF_MasterControl.c:573
struct_OTF_MapEntry
entry for 1:n mapping
Definition: OTF_MasterControl.h:134
OTF_MasterControl_append
int OTF_MasterControl_append(OTF_MasterControl *mc, uint32_t argument, uint32_t value)
Append the mapping argument -> value to the master control structure,.
Definition: OTF_MasterControl.c:528
struct_OTF_MasterControl
Data structure that collects the information about which stream contains which parts of a multi-file ...
Definition: OTF_MasterControl.h:166
OTF_MasterControl_read
int OTF_MasterControl_read(OTF_MasterControl *mc, const char *namestub)
INTERFACE CHANGED! Read a master control file according to namestub, reset the existing OTF_MasterCon...
Definition: OTF_MasterControl.c:131
struct_OTF_MasterControl::rmap
OTF_Pair * rmap
Reverse mapping to 'map'.
Definition: OTF_MasterControl.h:192
OTF_MasterControl_mapReverse
uint32_t OTF_MasterControl_mapReverse(OTF_MasterControl *mc, uint32_t value)
Returns the argument to the given value.
Definition: OTF_MasterControl.c:590
OTF_MasterControl_new
OTF_MasterControl * OTF_MasterControl_new(OTF_FileManager *manager)
Creates an empty OTF_MasterControl object.
Definition: OTF_MasterControl.c:234
OTF_File.h
Provides a low-level API for accessing files.
OTF_MasterControl_finish
void OTF_MasterControl_finish(OTF_MasterControl *mc)
Destructor, delete OTF_MasterControl object.
Definition: OTF_MasterControl.c:109
struct_OTF_MapEntry::n
uint32_t n
Current number of entries in 'values'.
Definition: OTF_MasterControl.h:140
OTF_MasterControl_check
int OTF_MasterControl_check(OTF_MasterControl *mc)
Checks if the current mapping is consistent in itself.
Definition: OTF_MasterControl.c:713
struct_OTF_MapEntry::values
uint32_t * values
List of size 's' containing 'n' sorted entries of unique value ids (process ids). ...
Definition: OTF_MasterControl.h:147
OTF_MasterControl_getREntryByIndex
OTF_Pair * OTF_MasterControl_getREntryByIndex(OTF_MasterControl *mc, uint32_t index)
Returns a pair of value and argument for the given index.
Definition: OTF_MasterControl.c:860
struct_OTF_MasterControl::s
uint32_t s
Current size of array 'map'.
Definition: OTF_MasterControl.h:173
OTF_MasterControl_getEntry
OTF_MapEntry * OTF_MasterControl_getEntry(OTF_MasterControl *mc, uint32_t argument)
Returns the entry for the given argument.
Definition: OTF_MasterControl.c:804
OTF_WBuffer.h
Provides write access to trace buffers.
OTF_MasterControl_getNewStreamId
uint32_t OTF_MasterControl_getNewStreamId(OTF_MasterControl *mc)
Returns a previously unused argument.
Definition: OTF_MasterControl.c:942
struct_OTF_MasterControl::manager
OTF_FileManager * manager
file handle manager
Definition: OTF_MasterControl.h:195
OTF_MasterControl_getValueCount
uint32_t OTF_MasterControl_getValueCount(OTF_MasterControl *mc, uint32_t argument)
Returns the number of values for the given argument.
Definition: OTF_MasterControl.c:886
struct_OTF_MasterControl::n
uint32_t n
Current number of entries in 'map'.
Definition: OTF_MasterControl.h:170
OTF_MasterControl_getCount
uint32_t OTF_MasterControl_getCount(OTF_MasterControl *mc)
Returns the number of arguments in the current list.
Definition: OTF_MasterControl.c:873
struct_OTF_MapEntry::argument
uint32_t argument
Unique argument ids.
Definition: OTF_MasterControl.h:137
struct_OTF_FileManager
file handles management structure
Definition: OTF_FileManager.c:32
struct_OTF_MasterControl::rs
uint32_t rs
Current size of array 'rmap'.
Definition: OTF_MasterControl.h:186
OTF_Filenames.h
Handles file naming issues.
OTF_MasterControl_getValues
uint32_t * OTF_MasterControl_getValues(OTF_MasterControl *mc, uint32_t argument)
Returns a pointer to the value array for 'argument'.
Definition: OTF_MasterControl.c:901
OTF_inttypes.h
Deals with all data type related issues.
struct_OTF_MasterControl::rn
uint32_t rn
Current number of entries in 'rmap'.
Definition: OTF_MasterControl.h:183
OTF_RBuffer.h
Provides read access to trace buffers.