OpenMPI  0.1.1
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 */
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 */
151 
152 
153 /** entry for 1:1 mapping */
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. */
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. */
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'. */
193 
194  /** file handle manager */
196 };
197 /** master control object. This object contains all information of the master
198  * control file. \ingroup mc */
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  */
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*/
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
456 
457 
458 #ifdef __cplusplus
459 }
460 #endif /* __cplusplus */
461 
462 #endif /* OTF_MASTERCONTROL_H */
463 
uint32_t s
Current size of array 'values'.
Definition: OTF_MasterControl.h:143
void OTF_MasterControl_close(OTF_MasterControl *mc)
Deletes a OTF_MasterControl object.
Definition: OTF_MasterControl.c:121
OTF_MapEntry * OTF_MasterControl_getEntryByIndex(OTF_MasterControl *mc, uint32_t index)
Returns the entry for the given index.
Definition: OTF_MasterControl.c:846
entry for 1:1 mapping
Definition: OTF_MasterControl.h:154
OTF_MapEntry * map
Mapping from stream ids (argument) to process ids (values).
Definition: OTF_MasterControl.h:179
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
void OTF_MasterControl_print(OTF_MasterControl *mc)
Prints the mapping to stderr.
Definition: OTF_MasterControl.c:772
uint32_t OTF_MasterControl_getrCount(OTF_MasterControl *mc)
Returns the number of arguments in current reverse list.
Definition: OTF_MasterControl.c:879
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
entry for 1:n mapping
Definition: OTF_MasterControl.h:134
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
Data structure that collects the information about which stream contains which parts of a multi-file ...
Definition: OTF_MasterControl.h:166
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
OTF_Pair * rmap
Reverse mapping to 'map'.
Definition: OTF_MasterControl.h:192
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 * OTF_MasterControl_new(OTF_FileManager *manager)
Creates an empty OTF_MasterControl object.
Definition: OTF_MasterControl.c:234
Provides a low-level API for accessing files.
void OTF_MasterControl_finish(OTF_MasterControl *mc)
Destructor, delete OTF_MasterControl object.
Definition: OTF_MasterControl.c:109
uint32_t n
Current number of entries in 'values'.
Definition: OTF_MasterControl.h:140
int OTF_MasterControl_check(OTF_MasterControl *mc)
Checks if the current mapping is consistent in itself.
Definition: OTF_MasterControl.c:713
uint32_t * values
List of size 's' containing 'n' sorted entries of unique value ids (process ids). ...
Definition: OTF_MasterControl.h:147
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
uint32_t s
Current size of array 'map'.
Definition: OTF_MasterControl.h:173
OTF_MapEntry * OTF_MasterControl_getEntry(OTF_MasterControl *mc, uint32_t argument)
Returns the entry for the given argument.
Definition: OTF_MasterControl.c:804
Provides write access to trace buffers.
uint32_t OTF_MasterControl_getNewStreamId(OTF_MasterControl *mc)
Returns a previously unused argument.
Definition: OTF_MasterControl.c:942
OTF_FileManager * manager
file handle manager
Definition: OTF_MasterControl.h:195
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
uint32_t n
Current number of entries in 'map'.
Definition: OTF_MasterControl.h:170
uint32_t OTF_MasterControl_getCount(OTF_MasterControl *mc)
Returns the number of arguments in the current list.
Definition: OTF_MasterControl.c:873
uint32_t argument
Unique argument ids.
Definition: OTF_MasterControl.h:137
file handles management structure
Definition: OTF_FileManager.c:32
uint32_t rs
Current size of array 'rmap'.
Definition: OTF_MasterControl.h:186
Handles file naming issues.
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
Deals with all data type related issues.
uint32_t rn
Current number of entries in 'rmap'.
Definition: OTF_MasterControl.h:183
Provides read access to trace buffers.