OpenMPI 0.1.1

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

- File List
- Globals

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 */
287 typedef struct struct_OTF_Reader OTF_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 */
302 OTF_Reader* OTF_Reader_open( const char* namestub, OTF_FileManager* manager );
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 */
367 OTF_MasterControl* OTF_Reader_getMasterControl( OTF_Reader* reader );
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 */
664 int OTF_Reader_closeAllStreams( OTF_Reader* reader );
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() */
676 uint8_t OTF_Reader_statisticProgress( OTF_Reader* reader,
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 */
728 uint8_t OTF_Reader_snapshotTimeProgress( OTF_Reader* reader,
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 */
754 uint8_t OTF_Reader_statisticTimeProgress( OTF_Reader* reader,
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 */
810 uint8_t OTF_Reader_snapshotBytesProgress( OTF_Reader* reader,
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 */
837 uint8_t OTF_Reader_statisticBytesProgress( OTF_Reader* reader,
838 uint64_t* minimum, uint64_t* current, uint64_t* maximum );
839
840 #ifdef __cplusplus
841 }
842 #endif /* __cplusplus */
843
844 #endif /* OTF_READER_H */
struct_OTF_Reader::maxTime
uint64_t maxTime
Contain the maximum time stamp where to stop reading.
Definition: OTF_Reader.c:143
OTF_Reader_readDefinitions
uint64_t OTF_Reader_readDefinitions(OTF_Reader *reader, OTF_HandlerArray *handlers)
This function reads all definitions from trace.
Definition: OTF_Reader.c:1472
OTF_MasterControl.h
Provides access to process-stream-mapping, which are located in .otf files.
OTF_Reader_readMarkers
uint64_t OTF_Reader_readMarkers(OTF_Reader *reader, OTF_HandlerArray *handlers)
This function reads all markers from trace.
Definition: OTF_Reader.c:3557
OTF_Reader_getRecordLimit
uint64_t OTF_Reader_getRecordLimit(OTF_Reader *reader)
Returns the current record limit.
Definition: OTF_Reader.c:3746
OTF_Reader_readEventsUnsorted
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
OTF_Reader_readSnapshots
uint64_t OTF_Reader_readSnapshots(OTF_Reader *reader, OTF_HandlerArray *handlers)
This function reads all snapshots from trace.
Definition: OTF_Reader.c:2267
OTF_Reader_setProcessStatus
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
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_Reader_reset
void OTF_Reader_reset(OTF_Reader *reader)
Resets all filters for timelimit, process selection and record count limit.
Definition: OTF_Reader.c:1348
OTF_Reader_snapshotBytesProgress
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
OTF_Reader_getBufferSizes
uint32_t OTF_Reader_getBufferSizes(OTF_Reader *reader)
Get the default buffer size.
Definition: OTF_Reader.c:1298
OTF_Reader_eventProgress
uint8_t OTF_Reader_eventProgress(OTF_Reader *reader, uint64_t *minimum, uint64_t *current, uint64_t *maximum)
depricated.
Definition: OTF_Reader.c:3770
OTF_Reader_readStatisticsUnsorted
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
OTF_Reader_setTimeInterval
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
OTF_Reader_statisticBytesProgress
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
OTF_Reader_readSnapshotsUnsorted
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
OTF_Reader_close
int OTF_Reader_close(OTF_Reader *reader)
Close an OTF_Reader instance and all its related files.
Definition: OTF_Reader.c:1246
OTF_Reader_getStream
OTF_RStream * OTF_Reader_getStream(OTF_Reader *reader, uint32_t id)
Searchs a reader stream and returns it.
Definition: OTF_Reader.c:1364
OTF_Reader_eventTimeProgress
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
OTF_Reader_setRecordLimit
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
struct_OTF_HandlerArray
Object structure which holds OTF record handlers.
Definition: OTF_HandlerArray.h:52
OTF_Reader_readStatistics
uint64_t OTF_Reader_readStatistics(OTF_Reader *reader, OTF_HandlerArray *handlers)
This function reads all statistic records from trace.
Definition: OTF_Reader.c:2909
OTF_Reader_readEvents
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
OTF_FileManager.h
Manages file handles.
OTF_Reader_getMasterControl
OTF_MasterControl * OTF_Reader_getMasterControl(OTF_Reader *reader)
Get a pointer to the mastercontrol of the reader.
Definition: OTF_Reader.c:1621
OTF_Reader_disableProcess
int OTF_Reader_disableProcess(OTF_Reader *reader, uint32_t processId)
disable given process.
Definition: OTF_Reader.c:1431
OTF_Reader_open
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
OTF_Reader_getProcessStatus
uint8_t OTF_Reader_getProcessStatus(OTF_Reader *reader, uint32_t processId)
Returns the current process status.
Definition: OTF_Reader.c:1446
OTF_Reader_setZBufferSizes
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
OTF_Reader_snapshotProgress
uint8_t OTF_Reader_snapshotProgress(OTF_Reader *reader, uint64_t *minimum, uint64_t *current, uint64_t *maximum)
depricated.
Definition: OTF_Reader.c:3778
OTF_Reader_getTimeIntervalMax
uint64_t OTF_Reader_getTimeIntervalMax(OTF_Reader *reader)
Returns end of current time interval.
Definition: OTF_Reader.c:3722
OTF_Reader_setProcessStatusAll
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
struct_OTF_Reader::namestub
char * namestub
name stub: all files will begin with this name
Definition: OTF_Reader.c:119
OTF_Reader_getZBufferSizes
uint32_t OTF_Reader_getZBufferSizes(OTF_Reader *reader)
Get the default zbuffer size.
Definition: OTF_Reader.c:1337
struct_OTF_Reader::minTime
uint64_t minTime
Contain the minimum time stamp where to start reading.
Definition: OTF_Reader.c:140
OTF_Reader_eventBytesProgress
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
struct_OTF_RStream
Definition: OTF_RStream.h:133
struct_OTF_Reader::manager
OTF_FileManager * manager
file handle manager
Definition: OTF_Reader.c:158
OTF_Reader_snapshotTimeProgress
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
struct_OTF_Reader
Definition: OTF_Reader.c:116
OTF_RStream.h
Provides read access to trace streams, which consist of multiple buffers.
OTF_Reader_getTimeIntervalMin
uint64_t OTF_Reader_getTimeIntervalMin(OTF_Reader *reader)
Returns the begin of current time interval.
Definition: OTF_Reader.c:3715
OTF_Reader_enableProcess
int OTF_Reader_enableProcess(OTF_Reader *reader, uint32_t processId)
enable given process.
Definition: OTF_Reader.c:1438
OTF_Reader_statisticProgress
uint8_t OTF_Reader_statisticProgress(OTF_Reader *reader, uint64_t *minimum, uint64_t *current, uint64_t *maximum)
depricated.
Definition: OTF_Reader.c:3786
OTF_Reader_setBufferSizes
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
OTF_Reader_statisticTimeProgress
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
struct_OTF_FileManager
file handles management structure
Definition: OTF_FileManager.c:32
OTF_HandlerArray.h
Provides read access to OTF traces which consist of multiple streams.
OTF_Reader_closeAllStreams
int OTF_Reader_closeAllStreams(OTF_Reader *reader)
Closes all streams that are open in the reader.
Definition: OTF_Reader.c:3753
OTF_inttypes.h
Deals with all data type related issues.