1 | /* |
---|
2 | This is part of the OTF library. Copyright by ZIH, TU Dresden 2005-2008. |
---|
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/callbacls 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 | * Searchs a reader stream and returns it. |
---|
484 | * If the stream does not exist it will be created. |
---|
485 | * |
---|
486 | * @param reader Pointer to an initialized OTF_Reader object. See |
---|
487 | * also OTF_Reader_open(). |
---|
488 | * @param id Identifier of the stream searched. |
---|
489 | * |
---|
490 | * @return Initialised OTF_RStream object. |
---|
491 | * |
---|
492 | * \ingroup reader |
---|
493 | */ |
---|
494 | OTF_RStream* OTF_Reader_getStream( OTF_Reader* reader, uint32_t id ); |
---|
495 | |
---|
496 | /** disable given process. deprecated, use 'OTF_Reader_setProcessStatus()' instead. |
---|
497 | |
---|
498 | This funktion will destroy a pending read operation, i.e. a read operation |
---|
499 | currently interrupted cannot be continued! |
---|
500 | \ingroup reader */ |
---|
501 | int OTF_Reader_disableProcess( OTF_Reader* reader, uint32_t processId ); |
---|
502 | |
---|
503 | /** enable given process. deprecated, use 'OTF_Reader_setProcessStatus()' instead. |
---|
504 | |
---|
505 | This funktion will destroy a pending read operation, i.e. a read operation |
---|
506 | currently interrupted cannot be continued! |
---|
507 | \ingroup reader */ |
---|
508 | int OTF_Reader_enableProcess( OTF_Reader* reader, uint32_t processId ); |
---|
509 | |
---|
510 | |
---|
511 | /** |
---|
512 | * Returns the current process status |
---|
513 | * |
---|
514 | * @param reader Pointer to an initialized OTF_Reader object. See |
---|
515 | * also OTF_Reader_open(). |
---|
516 | * @param processId Identifier of the process to get the status from |
---|
517 | * |
---|
518 | * @return Current process status. '1' for enabled, '0' for disabled |
---|
519 | * or unknown. |
---|
520 | * |
---|
521 | * \ingroup reader |
---|
522 | */ |
---|
523 | uint8_t OTF_Reader_getProcessStatus( OTF_Reader* reader, uint32_t processId ); |
---|
524 | |
---|
525 | |
---|
526 | /** |
---|
527 | * Sets the current status of the process. This function will destroy a pending |
---|
528 | * read operation, i.e. a read operation currently interrupted cannot be |
---|
529 | * continued! |
---|
530 | * |
---|
531 | * @param reader Pointer to an initialized OTF_Reader object. See |
---|
532 | * also OTF_Reader_open(). |
---|
533 | * @param processId Identifier of the process. |
---|
534 | * @param status new status of the process. '1' for enabled, '0' |
---|
535 | * for disabled or unknown. |
---|
536 | * |
---|
537 | * @return 1 on success, 0 if an error occurs. |
---|
538 | * |
---|
539 | * \ingroup reader |
---|
540 | */ |
---|
541 | int OTF_Reader_setProcessStatus( OTF_Reader* reader, uint32_t processId, |
---|
542 | uint8_t status ); |
---|
543 | |
---|
544 | /** |
---|
545 | * Sets the status for all processes with a single call. This function will |
---|
546 | * destroy a pending read operation, i.e. a read operation currently |
---|
547 | * interrupted cannot be continued! |
---|
548 | * |
---|
549 | * @param reader Pointer to an initialized OTF_Reader object. See |
---|
550 | * also OTF_Reader_open(). |
---|
551 | * @param status new status of the process. |
---|
552 | * |
---|
553 | * @return 1 on success, 0 if an error occurs. |
---|
554 | * |
---|
555 | * \ingroup reader |
---|
556 | */ |
---|
557 | int OTF_Reader_setProcessStatusAll( OTF_Reader* reader, uint8_t status ); |
---|
558 | |
---|
559 | |
---|
560 | /** |
---|
561 | * Set the minimum time and the maximum time of the reader. |
---|
562 | * |
---|
563 | * @param reader Pointer to an initialized OTF_Reader object. See |
---|
564 | * also OTF_Reader_open(). |
---|
565 | * @param minTime minimum to read records |
---|
566 | * @param maxTime maximum time to read records |
---|
567 | * |
---|
568 | * \ingroup reader |
---|
569 | */ |
---|
570 | void OTF_Reader_setTimeInterval( OTF_Reader* reader, uint64_t minTime, |
---|
571 | uint64_t maxTime ); |
---|
572 | |
---|
573 | |
---|
574 | /** |
---|
575 | * Returns the begin of current time interval. |
---|
576 | * |
---|
577 | * @param reader Pointer to an initialized OTF_Reader object. See |
---|
578 | * also OTF_Reader_open(). |
---|
579 | * |
---|
580 | * \ingroup reader |
---|
581 | */ |
---|
582 | uint64_t OTF_Reader_getTimeIntervalMin( OTF_Reader* reader ); |
---|
583 | |
---|
584 | |
---|
585 | /** |
---|
586 | * Returns end of current time interval. |
---|
587 | * |
---|
588 | * @param reader Pointer to an initialized OTF_Reader object. See |
---|
589 | * also OTF_Reader_open(). |
---|
590 | * |
---|
591 | * \ingroup reader |
---|
592 | */ |
---|
593 | uint64_t OTF_Reader_getTimeIntervalMax( OTF_Reader* reader ); |
---|
594 | |
---|
595 | |
---|
596 | /** |
---|
597 | * Set the maximum number of records delivered by a single call to |
---|
598 | * OTF_Reader_readXYZ(). Defaults to OTF_READ_MAXRECORDS == \infty. |
---|
599 | * 'OTF_Reader_readXYZ()' returns with the number of records processed. |
---|
600 | * Successive calls to 'OTF_Reader_readXYZ()' will deliver the remaining |
---|
601 | * records. This funktion will NOT destroy a pending read operation, i.e. a |
---|
602 | * read operation currently interrupted CAN be continued! |
---|
603 | * |
---|
604 | * @param reader Pointer to an initialized OTF_Reader object. See |
---|
605 | * also OTF_Reader_open(). |
---|
606 | * @param limit record limit. has to be smaller than or equal to |
---|
607 | * OTF_READ_MAXRECORDS |
---|
608 | * |
---|
609 | * \ingroup reader |
---|
610 | */ |
---|
611 | void OTF_Reader_setRecordLimit( OTF_Reader* reader, uint64_t limit ); |
---|
612 | |
---|
613 | |
---|
614 | /** |
---|
615 | * Returns the current record limit. |
---|
616 | * |
---|
617 | * @param reader Pointer to an initialized OTF_Reader object. See |
---|
618 | * also OTF_Reader_open(). |
---|
619 | * |
---|
620 | * @return Current record limit. |
---|
621 | * |
---|
622 | * \ingroup reader |
---|
623 | */ |
---|
624 | uint64_t OTF_Reader_getRecordLimit( OTF_Reader* reader ); |
---|
625 | |
---|
626 | /** |
---|
627 | * Resets all filters for timelimit, process selection and record count limit. |
---|
628 | * |
---|
629 | * @param reader Pointer to an initialized OTF_Reader object. See |
---|
630 | * also OTF_Reader_open(). |
---|
631 | * |
---|
632 | * \ingroup reader |
---|
633 | */ |
---|
634 | void OTF_Reader_reset( OTF_Reader* reader ); |
---|
635 | |
---|
636 | /** |
---|
637 | * Closes all streams that are open in the reader. |
---|
638 | * |
---|
639 | * @param reader Pointer to an initialized OTF_Reader object. See |
---|
640 | * also OTF_Reader_open(). |
---|
641 | * |
---|
642 | * @return 1 on success, 0 if an error occurs. |
---|
643 | * |
---|
644 | * \ingroup reader |
---|
645 | */ |
---|
646 | int OTF_Reader_closeAllStreams( OTF_Reader* reader ); |
---|
647 | |
---|
648 | |
---|
649 | /** depricated. @see OTF_Reader_eventTimeProgress() */ |
---|
650 | uint8_t OTF_Reader_eventProgress( OTF_Reader* reader, uint64_t* minimum, |
---|
651 | uint64_t* current, uint64_t* maximum ); |
---|
652 | |
---|
653 | /** depricated. @see OTF_Reader_snapshotTimeProgress() */ |
---|
654 | uint8_t OTF_Reader_snapshotProgress( OTF_Reader* reader, |
---|
655 | uint64_t* minimum, uint64_t* current, uint64_t* maximum ); |
---|
656 | |
---|
657 | /** depricated. @see OTF_Reader_statisticTimeProgress() */ |
---|
658 | uint8_t OTF_Reader_statisticProgress( OTF_Reader* reader, |
---|
659 | uint64_t* minimum, uint64_t* current, uint64_t* maximum ); |
---|
660 | |
---|
661 | |
---|
662 | /** |
---|
663 | * Delivers a progress report for reading events. Progress is given in terms |
---|
664 | * of time stamps. A percentage can be computed as |
---|
665 | * ( current - minimum ) / ( maximum - minimum ). |
---|
666 | * This computation takes restricted time intervals into account! This would not |
---|
667 | * be possible when referring to bytes read instead of time stamps. |
---|
668 | * The progress report is only valid after one or several calls to |
---|
669 | * 'readEvents()'.In the latter case the return arguments |
---|
670 | * 'minimum', 'current' and 'maximum' are undefined! If 'minimum' > 'maximum' |
---|
671 | * the values are invalid. |
---|
672 | * |
---|
673 | * @param reader Pointer to an initialized OTF_Reader object. See |
---|
674 | * also OTF_Reader_open(). |
---|
675 | * @param minimum Return value for the minium time. |
---|
676 | * @param current Return value for the current time. |
---|
677 | * @param maximum Return value for the maximum time. |
---|
678 | * |
---|
679 | * @return 1 on success, 0 if an error occurs. |
---|
680 | * |
---|
681 | * \ingroup reader |
---|
682 | */ |
---|
683 | uint8_t OTF_Reader_eventTimeProgress( OTF_Reader* reader, uint64_t* minimum, |
---|
684 | uint64_t* current, uint64_t* maximum ); |
---|
685 | |
---|
686 | |
---|
687 | /** |
---|
688 | * Delivers a progress report for reading snapshots. Progress is given in terms |
---|
689 | * of time stamps. a percentage can be computed as |
---|
690 | * ( current - minimum ) / ( maximum - minimum ). |
---|
691 | * This computation takes restricted time intervals into account! this would |
---|
692 | * not be possible when refering to bytes read instead of time stamps. |
---|
693 | * The progress report is only valid after one or several calls to |
---|
694 | * 'readSnapshots()'. In the latter case the return arguments |
---|
695 | * 'minimum', 'current' and 'maximum' are undefined! If 'minimum' > 'maximum' |
---|
696 | * the values are invalid. |
---|
697 | * |
---|
698 | * @param reader Pointer to an initialized OTF_Reader object. See |
---|
699 | * also OTF_Reader_open(). |
---|
700 | * @param minimum Return value for the minium time. |
---|
701 | * @param current Return value for the current time. |
---|
702 | * @param maximum Return value for the maximum time. |
---|
703 | * |
---|
704 | * @return 1 on success, 0 if an error occurs. |
---|
705 | * |
---|
706 | * \ingroup reader |
---|
707 | */ |
---|
708 | uint8_t OTF_Reader_snapshotTimeProgress( OTF_Reader* reader, |
---|
709 | uint64_t* minimum, uint64_t* current, uint64_t* maximum ); |
---|
710 | |
---|
711 | |
---|
712 | /** |
---|
713 | * Delivers a progress report for reading statistics. Progress is given in terms |
---|
714 | * of time stamps. a percentage can be computed as |
---|
715 | * ( current - minimum ) / ( maximum - minimum ). |
---|
716 | * This computation takes restricted time intervals into account! this would |
---|
717 | * not be possible when refering to bytes read instead of time stamps. |
---|
718 | * The progress report is only valid after one or several calls to |
---|
719 | * 'readStatistics()'. In the latter case the return arguments |
---|
720 | * 'minimum', 'current' and 'maximum' are undefined! If 'minimum' > 'maximum' |
---|
721 | * the values are invalid. |
---|
722 | * |
---|
723 | * @param reader Pointer to an initialized OTF_Reader object. See |
---|
724 | * also OTF_Reader_open(). |
---|
725 | * @param minimum Return value for the minium time. |
---|
726 | * @param current Return value for the current time. |
---|
727 | * @param maximum Return value for the maximum time. |
---|
728 | * |
---|
729 | * @return 1 on success, 0 if an error occurs. |
---|
730 | * |
---|
731 | * \ingroup reader |
---|
732 | */ |
---|
733 | uint8_t OTF_Reader_statisticTimeProgress( OTF_Reader* reader, |
---|
734 | uint64_t* minimum, uint64_t* current, uint64_t* maximum ); |
---|
735 | |
---|
736 | |
---|
737 | /** |
---|
738 | * Delivers a progress report for reading events. Progress is given in terms |
---|
739 | * of time stamps. a percentage can be computed as |
---|
740 | * ( current - minimum ) / ( maximum - minimum ). |
---|
741 | * This computation takes the read bytes of every stream into account. In the |
---|
742 | * latter case the return arguments 'minimum', 'current' and 'maximum' are |
---|
743 | * undefined! If 'minimum' > 'maximum' the values are invalid. |
---|
744 | * |
---|
745 | * @param reader Pointer to an initialized OTF_Reader object. See |
---|
746 | * also OTF_Reader_open(). |
---|
747 | * @param minimum Return value for the minium bytes read ( is 0 everytime ). |
---|
748 | * @param current Return value for the current bytes read. |
---|
749 | * @param maximum Return value for the filesize. |
---|
750 | * |
---|
751 | * @return 1 on success, 0 if an error occurs. |
---|
752 | * |
---|
753 | * \ingroup reader |
---|
754 | */ |
---|
755 | uint8_t OTF_Reader_eventBytesProgress( OTF_Reader* reader, uint64_t* minimum, |
---|
756 | uint64_t* current, uint64_t* maximum ); |
---|
757 | |
---|
758 | |
---|
759 | /** |
---|
760 | * Delivers a progress report for reading snapshots. Progress is given in terms |
---|
761 | * of time stamps. a percentage can be computed as |
---|
762 | * ( current - minimum ) / ( maximum - minimum ). |
---|
763 | * This computation takes the read bytes of every stream into account. In the |
---|
764 | * latter case the return arguments 'minimum', 'current' and 'maximum' are |
---|
765 | * undefined! If 'minimum' > 'maximum' the values are invalid. |
---|
766 | * |
---|
767 | * @param reader Pointer to an initialized OTF_Reader object. See |
---|
768 | * also OTF_Reader_open(). |
---|
769 | * @param minimum Return value for the minium bytes read ( is 0 everytime ). |
---|
770 | * @param current Return value for the current bytes read. |
---|
771 | * @param maximum Return value for the filesize. |
---|
772 | * |
---|
773 | * @return 1 on success, 0 if an error occurs. |
---|
774 | * |
---|
775 | * \ingroup reader |
---|
776 | */ |
---|
777 | uint8_t OTF_Reader_snapshotBytesProgress( OTF_Reader* reader, |
---|
778 | uint64_t* minimum, uint64_t* current, uint64_t* maximum ); |
---|
779 | |
---|
780 | /** |
---|
781 | * Delivers a progress report for reading statistics. Progress is given in terms |
---|
782 | * of time stamps. a percentage can be computed as |
---|
783 | * ( current - minimum ) / ( maximum - minimum ). |
---|
784 | * This computation takes the read bytes of every stream into account. In the |
---|
785 | * latter case the return arguments 'minimum', 'current' and 'maximum' are |
---|
786 | * undefined! If 'minimum' > 'maximum' the values are invalid. |
---|
787 | * |
---|
788 | * @param reader Pointer to an initialized OTF_Reader object. See |
---|
789 | * also OTF_Reader_open(). |
---|
790 | * @param minimum Return value for the minium bytes read ( is 0 everytime ). |
---|
791 | * @param current Return value for the current bytes read. |
---|
792 | * @param maximum Return value for the filesize. |
---|
793 | * |
---|
794 | * @return 1 on success, 0 if an error occurs. |
---|
795 | * |
---|
796 | * \ingroup reader |
---|
797 | */ |
---|
798 | uint8_t OTF_Reader_statisticBytesProgress( OTF_Reader* reader, |
---|
799 | uint64_t* minimum, uint64_t* current, uint64_t* maximum ); |
---|
800 | |
---|
801 | #ifdef __cplusplus |
---|
802 | } |
---|
803 | #endif /* __cplusplus */ |
---|
804 | |
---|
805 | #endif /* OTF_READER_H */ |
---|