OpenMPI  0.1.1
OTF_Reader.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_Reader.h
8  *
9  * @brief Transparently reads OTF traces which consist of multiple streams.
10  *
11  * This interface should be used whenever a trace file is to be read as a
12  * whole.
13  *
14  * \ingroup reader
15  */
16 
17 
18 #ifndef OTF_READER_H
19 #define OTF_READER_H
20 
21 
22 #include "OTF_inttypes.h"
23 
24 
25 #include "OTF_MasterControl.h"
26 #include "OTF_FileManager.h"
27 #include "OTF_RStream.h"
28 #include "OTF_HandlerArray.h"
29 
30 
31 #ifdef __cplusplus
32 extern "C" {
33 #endif /* __cplusplus */
34 
35 /** \defgroup reader Reader Interface
36  *
37  * The reader provides high level read access to traces
38  * disregarding the presence of streams.
39  *
40  * \section reader_example1 A simple Example
41  *
42  * \code
43  * #include <stdio.h>
44  * #include <assert.h>
45  * #include "otf.h"
46  * \endcode
47  *
48  * Define handlers/callbacks for the records you want to read.
49  * \code
50  * int handleEnter (void *userData, uint64_t time, uint32_t function, uint32_t process, uint32_t source) {
51  *
52  * printf("we just entered function %u\n", function);
53  *
54  * return OTF_RETURN_OK;
55  * }
56  *
57  * int handleLeave (void *userData, uint64_t time, uint32_t function, uint32_t process, uint32_t source) {
58  *
59  * printf("byebye\n");
60  *
61  * return OTF_RETURN_OK;
62  * }
63  * \endcode
64  *
65  * \code
66  * int main( int argc, char** argv ) {
67  * \endcode
68  *
69  * Declare a file manager, a reader, and a handler array.
70  * \code
71  * OTF_FileManager* manager;
72  * OTF_Reader* reader;
73  * OTF_HandlerArray* handlers;
74  * \endcode
75  *
76  * Initialize the file manager. Do not open more than 100 files.
77  * \code
78  * manager= OTF_FileManager_open( 100 );
79  * assert( manager );
80  * \endcode
81  *
82  * Initialize the handler array.
83  * \code
84  * handlers = OTF_HandlerArray_open();
85  * assert( handlers );
86  * \endcode
87  *
88  * Initialize the reader.
89  * \code
90  * reader = OTF_Reader_open( "mytrace", manager );
91  * assert( reader );
92  * \endcode
93  *
94  * Register your callback functions to the handler array.
95  * \code
96  * OTF_HandlerArray_setHandler( handlers, (OTF_FunctionPointer*) handleEnter, OTF_ENTER_RECORD );
97  * OTF_HandlerArray_setHandler( handlers, (OTF_FunctionPointer*) handleLeave, OTF_LEAVE_RECORD );
98  * \endcode
99  *
100  *
101  * Do the actual reading.
102  * \code
103  * OTF_Reader_readEvents( reader, handlers );
104  * \endcode
105  *
106  *
107  * Clean everything up before exiting the program.
108  * \code
109  * OTF_Reader_close( reader );
110  * OTF_HandlerArray_close( handlers );
111  * OTF_FileManager_close( manager );
112  *
113  * return 0;
114  * }
115  * \endcode
116  *
117  * Compile and link this using $ gcc -o test test.c `otfconfig --libs`.
118  *
119  *
120  * \section reader_example2 A second, more complex Example
121  *
122  * Same as before
123  * \code
124  * #include <stdio.h>
125  * #include <assert.h>
126  * #include "otf.h"
127  * \endcode
128  *
129  * Create a structure, which holds information needed in every handler.
130  * We will register this structure to the handlers, so that the userData pointer
131  * in every handler will point to it.
132  * In this example we just want to count the occurences.
133  * \code
134  * typedef struct {
135  * uint64_t count;
136  * } HandlerArgument;
137  * \endcode
138  *
139  * Define four handlers.
140  * In every handler we will increase HandlerArgument::count.
141  * \code
142  * int handleDefProcess (void *userData, uint32_t stream, uint32_t process, const char *name, uint32_t parent) {
143  * ((HandlerArgument*)userData)->count++;
144  * return OTF_RETURN_OK;
145  * }
146  * int handleDefFunction (void *userData, uint32_t stream, uint32_t func, const char *name, uint32_t funcGroup, uint32_t source) {
147  * ((HandlerArgument*)userData)->count++;
148  * return OTF_RETURN_OK;
149  * }
150  * int handleEnter (void *userData, uint64_t time, uint32_t function, uint32_t process, uint32_t source) {
151  * ((HandlerArgument*)userData)->count++;
152  * return OTF_RETURN_OK;
153  * }
154  * int handleLeave (void *userData, uint64_t time, uint32_t function, uint32_t process, uint32_t source) {
155  * ((HandlerArgument*)userData)->count++;
156  * return OTF_RETURN_OK;
157  * }
158  * \endcode
159  *
160  *
161  * Same as before
162  * \code
163  * int main( int argc, char** argv ) {
164  *
165  * OTF_FileManager* manager;
166  * OTF_Reader* reader;
167  * OTF_HandlerArray* handlers;
168  * \endcode
169  *
170  * We need some additional variables for the read progress
171  * \code
172  * uint64_t minbytes;
173  * uint64_t curbytes;
174  * uint64_t maxbytes;
175  * \endcode
176  *
177  * \code
178  * uint64_t ret;
179  * HandlerArgument ha;
180  * ha.count = 0;
181  *
182  * manager= OTF_FileManager_open( 100 );
183  * assert( manager );
184  *
185  * handlers = OTF_HandlerArray_open();
186  * assert( handlers );
187  *
188  * reader = OTF_Reader_open( "mytrace", manager );
189  * assert( reader );
190  * \endcode
191  *
192  * Register handlers for define process records,
193  * define function records, enter records and leave records
194  *
195  * \code
196  * OTF_HandlerArray_setHandler( handlers, (OTF_FunctionPointer*) handleDefProcess, OTF_DEFPROCESS_RECORD );
197  * \endcode
198  * Register the first handler argument ha to the handler where it should be passed into.
199  * \code
200  * OTF_HandlerArray_setFirstHandlerArg( handlers, &ha, OTF_DEFPROCESS_RECORD );
201  * \endcode
202  *
203  * \code
204  * OTF_HandlerArray_setHandler( handlers, (OTF_FunctionPointer*) handleDefFunction, OTF_DEFFUNCTION_RECORD );
205  * OTF_HandlerArray_setFirstHandlerArg( handlers, &ha, OTF_DEFFUNCTION_RECORD );
206  *
207  * OTF_HandlerArray_setHandler( handlers, (OTF_FunctionPointer*) handleEnter, OTF_ENTER_RECORD );
208  * OTF_HandlerArray_setFirstHandlerArg( handlers, &ha, OTF_ENTER_RECORD );
209  *
210  * OTF_HandlerArray_setHandler( handlers, (OTF_FunctionPointer*) handleLeave, OTF_LEAVE_RECORD );
211  * OTF_HandlerArray_setFirstHandlerArg( handlers, &ha, OTF_LEAVE_RECORD );
212  * \endcode
213  *
214  * Read definitions ( .def files).
215  * Inside this function the defProcess and defFunction handler will be called.
216  * \code
217  * OTF_Reader_readDefinitions( reader, handlers );
218  * \endcode
219  *
220  * Set the record limit to zero and read the events once.
221  * This initializes internal datastructures needed for getting the reading progress.
222  * \code
223  * OTF_Reader_setRecordLimit( reader, 0 );
224  * OTF_Reader_readEvents( reader, handlers );
225  * \endcode
226  *
227  * To leave OTF_Reader_readEvents() once in a while, in order to update the progress,
228  * set the record limit to an appropriate number. 100000 in this case.
229  *
230  * \code
231  * OTF_Reader_setRecordLimit( reader, 100000 );
232  * \endcode
233  *
234  * Read the trace until no records are left.
235  * \code
236  * while ( 0 != ( ret= OTF_Reader_readEvents( reader, handlers ) ) ) {
237  * \endcode
238  *
239  * If an error occurs, leave the program.
240  * \code
241  * if( OTF_READ_ERROR == ret ) {
242  * fprintf( stderr, "Error while reading events. Aborting\n" );
243  *
244  * OTF_Reader_close( reader );
245  * OTF_HandlerArray_close( handlers );
246  * OTF_FileManager_close( manager );
247  *
248  * exit(1);
249  * }
250  *
251  * \endcode
252  * Update the progress.
253  * \code
254  * OTF_Reader_eventBytesProgress( reader, &minbytes, &curbytes, &maxbytes );
255  * printf( "%llub / %llub\n", (long long unsigned)(curbytes - minbytes), (long long unsigned)(maxbytes-minbytes) );
256  * \endcode
257  *
258  * \code
259  * }
260  * \endcode
261  * Print out the gathered count of occurences of the four record types.
262  * \code
263  * printf( "count: %llu\n", (long long unsigned) ha.count );
264  * \endcode
265  *
266  * Finish everything
267  * \code
268  * OTF_Reader_close( reader );
269  * OTF_HandlerArray_close( handlers );
270  * OTF_FileManager_close( manager );
271  *
272  * return 0;
273  * }
274  * \endcode
275  * Compile and link this using $ gcc -o test test.c `otfconfig --libs`.
276  *
277  * When executing this test the output will be something like this:
278  * \verbatim
279  * 4194304b / 73530754b
280  * [..]
281  * 73530754b / 73530754b
282  * count: 4582694 \endverbatim
283  *
284  */
285 
286 /** reader object \ingroup reader */
288 
289 
290 /**
291  * Open a MasterControl file and return a OTF_Reader.
292  *
293  * @param namestub File name prefix which is going to be used by
294  * all sub-files which belong to the trace.
295  * @param fileManager File handle manager.
296  *
297  * @return Initialized OTF_Reader instance or 0 if a failure
298  * occurred.
299  *
300  * \ingroup reader
301  */
303 
304 /**
305  * Set the default buffer size for all buffers managed by this Reader.
306  * This is only effective for future buffers and will not change already
307  * allocated buffers. Those can be changed with the buffers directly.
308  *
309  * @param reader Pointer to an initialized OTF_Reader object. See
310  * also OTF_Reader_open().
311  * @param size Intended buffer size.
312  *
313  * @return 1 on success, 0 if an error occurs.
314  *
315  * \ingroup reader
316  */
317 int OTF_Reader_setBufferSizes( OTF_Reader* reader, uint32_t size );
318 
319 /**
320  * Get the default buffer size.
321  *
322  * @param reader Pointer to an initialized OTF_Reader object. See
323  * also OTF_Reader_open().
324  *
325  * @return Default buffer size.
326  *
327  * \ingroup reader
328  */
329 uint32_t OTF_Reader_getBufferSizes( OTF_Reader* reader );
330 
331 /**
332  * Set the default zbuffer size for all buffers managed by this Reader.
333  * This is only effective for future files and will not change already
334  * allocated zbuffers. Those can be changed with the files directly.
335  *
336  * @param reader Pointer to an initialized OTF_Reader object. See
337  * also OTF_Reader_open().
338  *
339  * @param size Intended zbuffer size.
340  *
341  * \ingroup reader
342  */
343 void OTF_Reader_setZBufferSizes( OTF_Reader* reader, uint32_t size );
344 
345 /**
346  * Get the default zbuffer size.
347  *
348  * @param reader Pointer to an initialized OTF_Reader object. See
349  * also OTF_Reader_open().
350  *
351  * @return zbuffer size.
352  *
353  * \ingroup reader
354  */
355 uint32_t OTF_Reader_getZBufferSizes( OTF_Reader* reader );
356 
357 /**
358  * Get a pointer to the mastercontrol of the reader
359  *
360  * @param reader Pointer to an initialized OTF_Reader object. See
361  * also OTF_Reader_open().
362  *
363  * @return Pointer to the mastercontrol.
364  *
365  * \ingroup reader
366  */
368 
369 /**
370  * Close an OTF_Reader instance and all its related files.
371  *
372  * @param reader Pointer to an initialized OTF_Reader object. See
373  * also OTF_Reader_open().
374  *
375  * @return 1 if instance was closed successfully and 0 otherwise.
376  *
377  * \ingroup reader
378  */
379 int OTF_Reader_close( OTF_Reader* reader );
380 
381 /**
382  * This function reads all definitions from trace.
383  *
384  * @param reader Pointer to an initialized OTF_Reader object. See
385  * also OTF_Reader_open().
386  * @param handlers Pointer to the handler array.
387  *
388  * @return number of records successfully read or OTF_READ_ERROR
389  *
390  * \ingroup reader
391  */
392 uint64_t OTF_Reader_readDefinitions( OTF_Reader* reader, OTF_HandlerArray* handlers );
393 
394 /**
395  * This function reads all events from trace and calls the appropriate
396  * handler sorted by time
397  *
398  * @param reader Pointer to an initialized OTF_Reader object. See
399  * also OTF_Reader_open().
400  * @param handlers Pointer to the handler array.
401  *
402  * @return number of records successfully read or OTF_READ_ERROR
403  *
404  * \ingroup reader
405  */
406 uint64_t OTF_Reader_readEvents( OTF_Reader* reader, OTF_HandlerArray* handlers );
407 
408 /**
409  * This function reads all events from trace and calls the appropriate handler
410  * NOT sorted by time.
411  * It calls every handler in ONE stream sorted by time.
412  * And walks through the streams one by one.
413  * ( So the handlers of one process will be called, sorted by time, too )
414  *
415  * This function is faster than OTF_Reader_readEvents(), especially for
416  * a bigger number of streams
417  *
418  * @see OTF_Reader_readEvents()
419  *
420  * \ingroup reader
421  */
422 uint64_t OTF_Reader_readEventsUnsorted( OTF_Reader* reader, OTF_HandlerArray* handlers );
423 
424 /**
425  * This function reads all snapshots from trace
426  *
427  * @param reader Pointer to an initialized OTF_Reader object. See
428  * also OTF_Reader_open().
429  * @param handlers Pointer to the handler array.
430  *
431  * @return number of records successfully read or OTF_READ_ERROR
432  *
433  * \ingroup reader
434  */
435 uint64_t OTF_Reader_readSnapshots( OTF_Reader* reader, OTF_HandlerArray* handlers );
436 
437 /**
438  * This function reads all snapshots from trace and calls the appropriate handler
439  * NOT sorted by time.
440  * It calls every handler in ONE stream sorted by time.
441  * And it walks through the streams one by one.
442  * ( So the handlers of one process will be called, sorted by time, too )
443  *
444  * This function is faster than OTF_Reader_readSnapshots(), especially for
445  * a bigger number of streams
446  *
447  * @see OTF_Reader_readSnapshots()
448  *
449  * \ingroup reader
450  */
451 uint64_t OTF_Reader_readSnapshotsUnsorted( OTF_Reader* reader, OTF_HandlerArray* handlers );
452 
453 /**
454  * This function reads all statistic records from trace
455  *
456  * @param reader Pointer to an initialized OTF_Reader object. See
457  * also OTF_Reader_open().
458  * @param handlers Pointer to the handler array.
459  *
460  * @return number of records successfully read or OTF_READ_ERROR
461  *
462  * \ingroup reader
463  */
464 uint64_t OTF_Reader_readStatistics( OTF_Reader* reader, OTF_HandlerArray* handlers );
465 
466 /**
467  * This function reads all statistics from trace and calls the appropriate handler
468  * NOT sorted by time.
469  * It calls every handler in ONE stream sorted by time.
470  * And it walks through the streams one by one.
471  * ( So the handlers of one process will be called, sorted by time, too )
472  *
473  * This function is faster than OTF_Reader_readStatistics(), especially for
474  * a bigger number of streams
475  *
476  * @see OTF_Reader_readStatistics()
477  *
478  * \ingroup reader
479  */
480 uint64_t OTF_Reader_readStatisticsUnsorted( OTF_Reader* reader, OTF_HandlerArray* handlers );
481 
482 /**
483  * This function reads all markers from trace.
484  *
485  * @param reader Pointer to an initialized OTF_Reader object. See
486  * also OTF_Reader_open().
487  * @param handlers Pointer to the handler array.
488  *
489  * @return number of records successfully read or OTF_READ_ERROR
490  *
491  * \ingroup reader
492  */
493 uint64_t OTF_Reader_readMarkers( OTF_Reader* reader, OTF_HandlerArray* handlers );
494 
495 /**
496  * Searchs a reader stream and returns it.
497  * If the stream does not exist it will be created.
498  *
499  * @param reader Pointer to an initialized OTF_Reader object. See
500  * also OTF_Reader_open().
501  * @param id Identifier of the stream searched.
502  *
503  * @return Initialised OTF_RStream object.
504  *
505  * \ingroup reader
506  */
507 OTF_RStream* OTF_Reader_getStream( OTF_Reader* reader, uint32_t id );
508 
509 /** disable given process. deprecated, use 'OTF_Reader_setProcessStatus()' instead.
510 
511 This funktion will destroy a pending read operation, i.e. a read operation
512 currently interrupted cannot be continued!
513 \ingroup reader */
514 int OTF_Reader_disableProcess( OTF_Reader* reader, uint32_t processId );
515 
516 /** enable given process. deprecated, use 'OTF_Reader_setProcessStatus()' instead.
517 
518 This funktion will destroy a pending read operation, i.e. a read operation
519 currently interrupted cannot be continued!
520 \ingroup reader */
521 int OTF_Reader_enableProcess( OTF_Reader* reader, uint32_t processId );
522 
523 
524 /**
525  * Returns the current process status
526  *
527  * @param reader Pointer to an initialized OTF_Reader object. See
528  * also OTF_Reader_open().
529  * @param processId Identifier of the process to get the status from
530  *
531  * @return Current process status. '1' for enabled, '0' for disabled
532  * or unknown.
533  *
534  * \ingroup reader
535  */
536 uint8_t OTF_Reader_getProcessStatus( OTF_Reader* reader, uint32_t processId );
537 
538 
539 /**
540  * Sets the current status of the process. This function will destroy a pending
541  * read operation, i.e. a read operation currently interrupted cannot be
542  * continued!
543  *
544  * @param reader Pointer to an initialized OTF_Reader object. See
545  * also OTF_Reader_open().
546  * @param processId Identifier of the process.
547  * @param status new status of the process. '1' for enabled, '0'
548  * for disabled or unknown.
549  *
550  * @return 1 on success, 0 if an error occurs.
551  *
552  * \ingroup reader
553  */
554 int OTF_Reader_setProcessStatus( OTF_Reader* reader, uint32_t processId,
555  uint8_t status );
556 
557 /**
558  * Sets the status for all processes with a single call. This function will
559  * destroy a pending read operation, i.e. a read operation currently
560  * interrupted cannot be continued!
561  *
562  * @param reader Pointer to an initialized OTF_Reader object. See
563  * also OTF_Reader_open().
564  * @param status new status of the process.
565  *
566  * @return 1 on success, 0 if an error occurs.
567  *
568  * \ingroup reader
569  */
570 int OTF_Reader_setProcessStatusAll( OTF_Reader* reader, uint8_t status );
571 
572 
573 /**
574  * Set the minimum time and the maximum time of the reader.
575  *
576  * \par For example:
577  * minTime = 100000;
578  * \n maxTime = 100003;
579  * \n Times to read: 100000, 100001, 100002
580  *
581  * @param reader Pointer to an initialized OTF_Reader object. See
582  * also OTF_Reader_open().
583  * @param minTime time where reading starts (including this timestamp)
584  * @param maxTime time where reading ends (excluding this timestamp)
585  *
586  * \ingroup reader
587  */
588 void OTF_Reader_setTimeInterval( OTF_Reader* reader, uint64_t minTime,
589  uint64_t maxTime );
590 
591 
592 /**
593  * Returns the begin of current time interval.
594  *
595  * @param reader Pointer to an initialized OTF_Reader object. See
596  * also OTF_Reader_open().
597  *
598  * \ingroup reader
599  */
600 uint64_t OTF_Reader_getTimeIntervalMin( OTF_Reader* reader );
601 
602 
603 /**
604  * Returns end of current time interval.
605  *
606  * @param reader Pointer to an initialized OTF_Reader object. See
607  * also OTF_Reader_open().
608  *
609  * \ingroup reader
610  */
611 uint64_t OTF_Reader_getTimeIntervalMax( OTF_Reader* reader );
612 
613 
614 /**
615  * Set the maximum number of records delivered by a single call to
616  * OTF_Reader_readXYZ(). Defaults to OTF_READ_MAXRECORDS == \infty.
617  * 'OTF_Reader_readXYZ()' returns with the number of records processed.
618  * Successive calls to 'OTF_Reader_readXYZ()' will deliver the remaining
619  * records. This funktion will NOT destroy a pending read operation, i.e. a
620  * read operation currently interrupted CAN be continued!
621  *
622  * @param reader Pointer to an initialized OTF_Reader object. See
623  * also OTF_Reader_open().
624  * @param limit record limit. has to be smaller than or equal to
625  * OTF_READ_MAXRECORDS
626  *
627  * \ingroup reader
628  */
629 void OTF_Reader_setRecordLimit( OTF_Reader* reader, uint64_t limit );
630 
631 
632 /**
633  * Returns the current record limit.
634  *
635  * @param reader Pointer to an initialized OTF_Reader object. See
636  * also OTF_Reader_open().
637  *
638  * @return Current record limit.
639  *
640  * \ingroup reader
641  */
642 uint64_t OTF_Reader_getRecordLimit( OTF_Reader* reader );
643 
644 /**
645  * Resets all filters for timelimit, process selection and record count limit.
646  *
647  * @param reader Pointer to an initialized OTF_Reader object. See
648  * also OTF_Reader_open().
649  *
650  * \ingroup reader
651  */
652 void OTF_Reader_reset( OTF_Reader* reader );
653 
654 /**
655  * Closes all streams that are open in the reader.
656  *
657  * @param reader Pointer to an initialized OTF_Reader object. See
658  * also OTF_Reader_open().
659  *
660  * @return 1 on success, 0 if an error occurs.
661  *
662  * \ingroup reader
663  */
665 
666 
667 /** depricated. @see OTF_Reader_eventTimeProgress() */
668 uint8_t OTF_Reader_eventProgress( OTF_Reader* reader, uint64_t* minimum,
669  uint64_t* current, uint64_t* maximum );
670 
671 /** depricated. @see OTF_Reader_snapshotTimeProgress() */
672 uint8_t OTF_Reader_snapshotProgress( OTF_Reader* reader,
673  uint64_t* minimum, uint64_t* current, uint64_t* maximum );
674 
675 /** depricated. @see OTF_Reader_statisticTimeProgress() */
677  uint64_t* minimum, uint64_t* current, uint64_t* maximum );
678 
679 
680 /**
681  * Delivers a progress report for reading events. It is given in terms
682  * of time stamps. A percentage can be computed as
683  * ( current - minimum ) / ( maximum - minimum ).
684  * This computation takes restricted time intervals into account which is not
685  * possible with OTF_Reader_eventBytesProgress().
686  *
687  * The progress report is only valid after one or several calls to
688  * OTF_Reader_readEvents(). Otherwise the return arguments 'minimum', 'current'
689  * and 'maximum' are undefined!
690  * If 'minimum' > 'maximum' the values are invalid.
691  *
692  * @param reader Pointer to an initialized OTF_Reader object. See
693  * also OTF_Reader_open().
694  * @param minimum Return value for the minium time.
695  * @param current Return value for the current time.
696  * @param maximum Return value for the maximum time.
697  *
698  * @return 1 on success, 0 if an error occurs.
699  *
700  * \ingroup reader
701  */
702 uint8_t OTF_Reader_eventTimeProgress( OTF_Reader* reader, uint64_t* minimum,
703  uint64_t* current, uint64_t* maximum );
704 
705 
706 /**
707  * Delivers a progress report for reading snapshots. It is given in terms
708  * of time stamps. A percentage can be computed as
709  * ( current - minimum ) / ( maximum - minimum ).
710  * This computation takes restricted time intervals into account which is not
711  * possible with OTF_Reader_snapshotBytesProgress().
712  *
713  * The progress report is only valid after one or several calls to
714  * OTF_Reader_readSnapshots(). Otherwise the return arguments 'minimum', 'current'
715  * and 'maximum' are undefined!
716  * If 'minimum' > 'maximum' the values are invalid.
717  *
718  * @param reader Pointer to an initialized OTF_Reader object. See
719  * also OTF_Reader_open().
720  * @param minimum Return value for the minium time.
721  * @param current Return value for the current time.
722  * @param maximum Return value for the maximum time.
723  *
724  * @return 1 on success, 0 if an error occurs.
725  *
726  * \ingroup reader
727  */
729  uint64_t* minimum, uint64_t* current, uint64_t* maximum );
730 
731 
732 /**
733  * Delivers a progress report for reading statistics. It is given in terms
734  * of time stamps. A percentage can be computed as
735  * ( current - minimum ) / ( maximum - minimum ).
736  * This computation takes restricted time intervals into account which is not
737  * possible with OTF_Reader_statisticBytesProgress().
738  *
739  * The progress report is only valid after one or several calls to
740  * OTF_Reader_readStatistics(). Otherwise the return arguments 'minimum', 'current'
741  * and 'maximum' are undefined!
742  * If 'minimum' > 'maximum' the values are invalid.
743  *
744  * @param reader Pointer to an initialized OTF_Reader object. See
745  * also OTF_Reader_open().
746  * @param minimum Return value for the minium time.
747  * @param current Return value for the current time.
748  * @param maximum Return value for the maximum time.
749  *
750  * @return 1 on success, 0 if an error occurs.
751  *
752  * \ingroup reader
753  */
755  uint64_t* minimum, uint64_t* current, uint64_t* maximum );
756 
757 
758 /**
759  * Delivers a progress report for reading events. Progress is given in terms
760  * of bytes. The percentage can be computed as ( current - minimum ) / ( maximum - minimum ).
761  *
762  * ATTENTION: This is only a rough estimate of the progress, because it is
763  * computed based on the block I/O from files but not based on the actual bytes
764  * processed. This may result in constant values for small traces.
765  * See also OTF_Reader_eventTimeProgress():
766  *
767  * This computation takes the read bytes of every active stream into account.
768  * The progress report is only valid after one or several calls to
769  * OTF_Reader_readEvents(). Otherwise the return arguments 'minimum', 'current' and 'maximum' are
770  * undefined! If 'minimum' > 'maximum' the values are invalid.
771  *
772  * @param reader Pointer to an initialized OTF_Reader object. See
773  * also OTF_Reader_open().
774  * @param minimum Return value for the minium bytes read ( is 0 everytime ).
775  * @param current Return value for the current bytes read.
776  * @param maximum Return value for the filesize.
777  *
778  * @return 1 on success, 0 if an error occurs.
779  *
780  * \ingroup reader
781  */
782 uint8_t OTF_Reader_eventBytesProgress( OTF_Reader* reader, uint64_t* minimum,
783  uint64_t* current, uint64_t* maximum );
784 
785 
786 /**
787  * Delivers a progress report for reading snapshots. Progress is given in terms
788  * of bytes. The percentage can be computed as ( current - minimum ) / ( maximum - minimum ).
789  *
790  * ATTENTION: This is only a rough estimate of the progress, because it is
791  * computed based on the block I/O from files but not based on the actual bytes
792  * processed. This may result in constant values for small traces.
793  * See also OTF_Reader_snapshotTimeProgress():
794  *
795  * This computation takes the read bytes of every active stream into account.
796  * The progress report is only valid after one or several calls to
797  * OTF_Reader_readSnapshots(). Otherwise the return arguments 'minimum', 'current' and 'maximum' are
798  * undefined! If 'minimum' > 'maximum' the values are invalid.
799  *
800  * @param reader Pointer to an initialized OTF_Reader object. See
801  * also OTF_Reader_open().
802  * @param minimum Return value for the minium bytes read ( is 0 everytime ).
803  * @param current Return value for the current bytes read.
804  * @param maximum Return value for the filesize.
805  *
806  * @return 1 on success, 0 if an error occurs.
807  *
808  * \ingroup reader
809  */
811  uint64_t* minimum, uint64_t* current, uint64_t* maximum );
812 
813 /**
814  * Delivers a progress report for reading statistics. Progress is given in terms
815  * of bytes. The percentage can be computed as ( current - minimum ) / ( maximum - minimum ).
816  *
817  * ATTENTION: This is only a rough estimate of the progress, because it is
818  * computed based on the block I/O from files but not based on the actual bytes
819  * processed. This may result in constant values for small traces.
820  * See also OTF_Reader_statisticTimeProgress():
821  *
822  * This computation takes the read bytes of every active stream into account.
823  * The progress report is only valid after one or several calls to
824  * OTF_Reader_readStatistics(). Otherwise the return arguments 'minimum', 'current' and 'maximum' are
825  * undefined! If 'minimum' > 'maximum' the values are invalid.
826  *
827  * @param reader Pointer to an initialized OTF_Reader object. See
828  * also OTF_Reader_open().
829  * @param minimum Return value for the minium bytes read ( is 0 everytime ).
830  * @param current Return value for the current bytes read.
831  * @param maximum Return value for the filesize.
832  *
833  * @return 1 on success, 0 if an error occurs.
834  *
835  * \ingroup reader
836  */
838  uint64_t* minimum, uint64_t* current, uint64_t* maximum );
839 
840 #ifdef __cplusplus
841 }
842 #endif /* __cplusplus */
843 
844 #endif /* OTF_READER_H */
uint64_t maxTime
Contain the maximum time stamp where to stop reading.
Definition: OTF_Reader.c:143
uint64_t OTF_Reader_readDefinitions(OTF_Reader *reader, OTF_HandlerArray *handlers)
This function reads all definitions from trace.
Definition: OTF_Reader.c:1472
Provides access to process-stream-mapping, which are located in .otf files.
uint64_t OTF_Reader_readMarkers(OTF_Reader *reader, OTF_HandlerArray *handlers)
This function reads all markers from trace.
Definition: OTF_Reader.c:3557
uint64_t OTF_Reader_getRecordLimit(OTF_Reader *reader)
Returns the current record limit.
Definition: OTF_Reader.c:3746
uint64_t OTF_Reader_readEventsUnsorted(OTF_Reader *reader, OTF_HandlerArray *handlers)
This function reads all events from trace and calls the appropriate handler NOT sorted by time...
Definition: OTF_Reader.c:1961
uint64_t OTF_Reader_readSnapshots(OTF_Reader *reader, OTF_HandlerArray *handlers)
This function reads all snapshots from trace.
Definition: OTF_Reader.c:2267
int OTF_Reader_setProcessStatus(OTF_Reader *reader, uint32_t processId, uint8_t status)
Sets the current status of the process.
Definition: OTF_Reader.c:1454
Data structure that collects the information about which stream contains which parts of a multi-file ...
Definition: OTF_MasterControl.h:166
void OTF_Reader_reset(OTF_Reader *reader)
Resets all filters for timelimit, process selection and record count limit.
Definition: OTF_Reader.c:1348
uint8_t OTF_Reader_snapshotBytesProgress(OTF_Reader *reader, uint64_t *minimum, uint64_t *current, uint64_t *maximum)
Delivers a progress report for reading snapshots.
Definition: OTF_Reader.c:3877
uint32_t OTF_Reader_getBufferSizes(OTF_Reader *reader)
Get the default buffer size.
Definition: OTF_Reader.c:1298
uint8_t OTF_Reader_eventProgress(OTF_Reader *reader, uint64_t *minimum, uint64_t *current, uint64_t *maximum)
depricated.
Definition: OTF_Reader.c:3770
uint64_t OTF_Reader_readStatisticsUnsorted(OTF_Reader *reader, OTF_HandlerArray *handlers)
This function reads all statistics from trace and calls the appropriate handler NOT sorted by time...
Definition: OTF_Reader.c:3250
void OTF_Reader_setTimeInterval(OTF_Reader *reader, uint64_t minTime, uint64_t maxTime)
Set the minimum time and the maximum time of the reader.
Definition: OTF_Reader.c:3704
uint8_t OTF_Reader_statisticBytesProgress(OTF_Reader *reader, uint64_t *minimum, uint64_t *current, uint64_t *maximum)
Delivers a progress report for reading statistics.
Definition: OTF_Reader.c:3902
uint64_t OTF_Reader_readSnapshotsUnsorted(OTF_Reader *reader, OTF_HandlerArray *handlers)
This function reads all snapshots from trace and calls the appropriate handler NOT sorted by time...
Definition: OTF_Reader.c:2605
int OTF_Reader_close(OTF_Reader *reader)
Close an OTF_Reader instance and all its related files.
Definition: OTF_Reader.c:1246
OTF_RStream * OTF_Reader_getStream(OTF_Reader *reader, uint32_t id)
Searchs a reader stream and returns it.
Definition: OTF_Reader.c:1364
uint8_t OTF_Reader_eventTimeProgress(OTF_Reader *reader, uint64_t *minimum, uint64_t *current, uint64_t *maximum)
Delivers a progress report for reading events.
Definition: OTF_Reader.c:3794
void OTF_Reader_setRecordLimit(OTF_Reader *reader, uint64_t limit)
Set the maximum number of records delivered by a single call to OTF_Reader_readXYZ().
Definition: OTF_Reader.c:3729
Object structure which holds OTF record handlers.
Definition: OTF_HandlerArray.h:52
uint64_t OTF_Reader_readStatistics(OTF_Reader *reader, OTF_HandlerArray *handlers)
This function reads all statistic records from trace.
Definition: OTF_Reader.c:2909
uint64_t OTF_Reader_readEvents(OTF_Reader *reader, OTF_HandlerArray *handlers)
This function reads all events from trace and calls the appropriate handler sorted by time...
Definition: OTF_Reader.c:1628
Manages file handles.
OTF_MasterControl * OTF_Reader_getMasterControl(OTF_Reader *reader)
Get a pointer to the mastercontrol of the reader.
Definition: OTF_Reader.c:1621
int OTF_Reader_disableProcess(OTF_Reader *reader, uint32_t processId)
disable given process.
Definition: OTF_Reader.c:1431
OTF_Reader * OTF_Reader_open(const char *namestub, OTF_FileManager *manager)
Open a MasterControl file and return a OTF_Reader.
Definition: OTF_Reader.c:1149
uint8_t OTF_Reader_getProcessStatus(OTF_Reader *reader, uint32_t processId)
Returns the current process status.
Definition: OTF_Reader.c:1446
void OTF_Reader_setZBufferSizes(OTF_Reader *reader, uint32_t size)
Set the default zbuffer size for all buffers managed by this Reader.
Definition: OTF_Reader.c:1305
uint8_t OTF_Reader_snapshotProgress(OTF_Reader *reader, uint64_t *minimum, uint64_t *current, uint64_t *maximum)
depricated.
Definition: OTF_Reader.c:3778
uint64_t OTF_Reader_getTimeIntervalMax(OTF_Reader *reader)
Returns end of current time interval.
Definition: OTF_Reader.c:3722
int OTF_Reader_setProcessStatusAll(OTF_Reader *reader, uint8_t status)
Sets the status for all processes with a single call.
Definition: OTF_Reader.c:1463
char * namestub
name stub: all files will begin with this name
Definition: OTF_Reader.c:119
uint32_t OTF_Reader_getZBufferSizes(OTF_Reader *reader)
Get the default zbuffer size.
Definition: OTF_Reader.c:1337
uint64_t minTime
Contain the minimum time stamp where to start reading.
Definition: OTF_Reader.c:140
uint8_t OTF_Reader_eventBytesProgress(OTF_Reader *reader, uint64_t *minimum, uint64_t *current, uint64_t *maximum)
Delivers a progress report for reading events.
Definition: OTF_Reader.c:3852
Definition: OTF_RStream.h:133
OTF_FileManager * manager
file handle manager
Definition: OTF_Reader.c:158
uint8_t OTF_Reader_snapshotTimeProgress(OTF_Reader *reader, uint64_t *minimum, uint64_t *current, uint64_t *maximum)
Delivers a progress report for reading snapshots.
Definition: OTF_Reader.c:3814
Definition: OTF_Reader.c:116
Provides read access to trace streams, which consist of multiple buffers.
uint64_t OTF_Reader_getTimeIntervalMin(OTF_Reader *reader)
Returns the begin of current time interval.
Definition: OTF_Reader.c:3715
int OTF_Reader_enableProcess(OTF_Reader *reader, uint32_t processId)
enable given process.
Definition: OTF_Reader.c:1438
uint8_t OTF_Reader_statisticProgress(OTF_Reader *reader, uint64_t *minimum, uint64_t *current, uint64_t *maximum)
depricated.
Definition: OTF_Reader.c:3786
int OTF_Reader_setBufferSizes(OTF_Reader *reader, uint32_t size)
Set the default buffer size for all buffers managed by this Reader.
Definition: OTF_Reader.c:1267
uint8_t OTF_Reader_statisticTimeProgress(OTF_Reader *reader, uint64_t *minimum, uint64_t *current, uint64_t *maximum)
Delivers a progress report for reading statistics.
Definition: OTF_Reader.c:3833
file handles management structure
Definition: OTF_FileManager.c:32
Provides read access to OTF traces which consist of multiple streams.
int OTF_Reader_closeAllStreams(OTF_Reader *reader)
Closes all streams that are open in the reader.
Definition: OTF_Reader.c:3753
Deals with all data type related issues.