[97] | 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 | /* NOTE |
---|
| 7 | the OTF_RStream interface is not able to perform jumps to random timestamps, |
---|
| 8 | and cannot quit at a certain maximum time stamp. |
---|
| 9 | Maybe in future versions we add this. |
---|
| 10 | It is not in, because the OTF_Reader interface uses the buffer-methodes directly |
---|
| 11 | to set the timestamps, so saving it in the stream too will be worthless in this |
---|
| 12 | case. */ |
---|
| 13 | |
---|
| 14 | /** |
---|
| 15 | * @file OTF_RStream.h |
---|
| 16 | * |
---|
| 17 | * @brief Provides read access to trace streams, which consist of multiple |
---|
| 18 | * buffers. |
---|
| 19 | * |
---|
| 20 | * \ingroup rstream |
---|
| 21 | */ |
---|
| 22 | |
---|
| 23 | /** \defgroup rstream Stream Reader Interface |
---|
| 24 | * |
---|
| 25 | * rstream provides an interface for dealing with a single stream of a trace. |
---|
| 26 | * A stream consists of up to four different buffers (event buffer, |
---|
| 27 | * definition buffer, snapshots buffer, statistics buffer). |
---|
| 28 | * |
---|
| 29 | * rstream is structured similarly to the reader, but it is not |
---|
| 30 | * able to perform jumps to random timestamps, and cannot quit at a certain |
---|
| 31 | * maximum time stamp. |
---|
| 32 | * |
---|
| 33 | * \section rstream_example A simple Example |
---|
| 34 | * |
---|
| 35 | * Common includes |
---|
| 36 | * \code |
---|
| 37 | * #include <stdio.h> |
---|
| 38 | * #include <assert.h> |
---|
| 39 | * #include "otf.h" |
---|
| 40 | * \endcode |
---|
| 41 | * |
---|
| 42 | * |
---|
| 43 | * Define the Handler(s). |
---|
| 44 | * We just want to process the def process event and print out all appearing processes. |
---|
| 45 | * \code |
---|
| 46 | * int handleDefProcess (void *userData, uint32_t stream, uint32_t process, const char *name, uint32_t parent) { |
---|
| 47 | * |
---|
| 48 | * printf( "process %u is named \"%s\"\n", process, name ); |
---|
| 49 | * |
---|
| 50 | * return OTF_RETURN_OK; |
---|
| 51 | * } |
---|
| 52 | * \endcode |
---|
| 53 | * |
---|
| 54 | * \code |
---|
| 55 | * int main( int argc, char** argv ) { |
---|
| 56 | * \endcode |
---|
| 57 | * |
---|
| 58 | * Declare a file manager, a reader, and a handler array |
---|
| 59 | * \code |
---|
| 60 | * OTF_RStream* rstream; |
---|
| 61 | * OTF_FileManager* manager; |
---|
| 62 | * OTF_HandlerArray* handlers; |
---|
| 63 | * \endcode |
---|
| 64 | * |
---|
| 65 | * Initialize the file manager. Do not open more than 100 files. |
---|
| 66 | * \code |
---|
| 67 | * manager= OTF_FileManager_open( 100 ); |
---|
| 68 | * assert( manager ); |
---|
| 69 | * \endcode |
---|
| 70 | * |
---|
| 71 | * Initialize the handler array. |
---|
| 72 | * \code |
---|
| 73 | * handlers = OTF_HandlerArray_open(); |
---|
| 74 | * assert( handlers ); |
---|
| 75 | * \endcode |
---|
| 76 | * |
---|
| 77 | * Initialize the rstream object. |
---|
| 78 | * \code |
---|
| 79 | |
---|
| 80 | * rstream = OTF_RStream_open( "mytrace", 0, manager ); |
---|
| 81 | * assert( rstream ); |
---|
| 82 | * \endcode |
---|
| 83 | * |
---|
| 84 | * Register your callback functions to the handler array. |
---|
| 85 | * \code |
---|
| 86 | * OTF_HandlerArray_setHandler( handlers, (OTF_FunctionPointer*) handleDefProcess, OTF_DEFPROCESS_RECORD ); |
---|
| 87 | * \endcode |
---|
| 88 | * |
---|
| 89 | * |
---|
| 90 | * Do the actual reading. |
---|
| 91 | * \code |
---|
| 92 | * OTF_RStream_readDefinitions( rstream, handlers ); |
---|
| 93 | * \endcode |
---|
| 94 | * |
---|
| 95 | * |
---|
| 96 | * Clean everything up before exiting the program. |
---|
| 97 | * \code |
---|
| 98 | * OTF_RStream_close( rstream ); |
---|
| 99 | * OTF_HandlerArray_close( handlers ); |
---|
| 100 | * OTF_FileManager_close( manager ); |
---|
| 101 | * |
---|
| 102 | * return 0; |
---|
| 103 | * } |
---|
| 104 | * \endcode |
---|
| 105 | * |
---|
| 106 | * Compile and link this using $ gcc -o test test.c `otfconfig --libs`. |
---|
| 107 | * |
---|
| 108 | */ |
---|
| 109 | |
---|
| 110 | |
---|
| 111 | #ifndef OTF_RSTREAM_H |
---|
| 112 | #define OTF_RSTREAM_H |
---|
| 113 | |
---|
| 114 | |
---|
| 115 | #include <stdlib.h> |
---|
| 116 | #include <string.h> |
---|
| 117 | #include <stdio.h> |
---|
| 118 | |
---|
| 119 | |
---|
| 120 | #include "OTF_inttypes.h" |
---|
| 121 | |
---|
| 122 | |
---|
| 123 | #include "OTF_FileManager.h" |
---|
| 124 | #include "OTF_RBuffer.h" |
---|
| 125 | #include "OTF_Filenames.h" |
---|
| 126 | #include "OTF_HandlerArray.h" |
---|
| 127 | |
---|
| 128 | |
---|
| 129 | #ifdef __cplusplus |
---|
| 130 | extern "C" { |
---|
| 131 | #endif /* __cplusplus */ |
---|
| 132 | |
---|
| 133 | struct struct_OTF_RStream { |
---|
| 134 | |
---|
| 135 | |
---|
| 136 | /** name stub: all files will begin with this name */ |
---|
| 137 | char* namestub; |
---|
| 138 | |
---|
| 139 | /** Unique id for the current stream */ |
---|
| 140 | uint32_t id; |
---|
| 141 | |
---|
| 142 | /** Definitions buffer. Definitions buffer carries definition |
---|
| 143 | records */ |
---|
| 144 | OTF_RBuffer* defBuffer; |
---|
| 145 | |
---|
| 146 | /** Event buffer. The event buffer carries records for actual |
---|
| 147 | events, i.e. records with a time stamp */ |
---|
| 148 | OTF_RBuffer* eventBuffer; |
---|
| 149 | |
---|
| 150 | /** Snaps (snapshots) buffer. The snapshots buffer carries |
---|
| 151 | snapshots of the whole state at a point in time - as oppossed to |
---|
| 152 | events which only show changes in the state. This can be used to |
---|
| 153 | start from such a snapshot instead of from the very begining. */ |
---|
| 154 | OTF_RBuffer* snapsBuffer; |
---|
| 155 | |
---|
| 156 | /** Statistics buffer. Statistics buffer carries statistical |
---|
| 157 | information about a certain time interval resp. data at |
---|
| 158 | points of time that allow to derive statistics without |
---|
| 159 | reading through all events of that interval. */ |
---|
| 160 | OTF_RBuffer* statsBuffer; |
---|
| 161 | |
---|
| 162 | /** Default size of buffers managed by this RStream. */ |
---|
| 163 | uint32_t buffersizes; |
---|
| 164 | |
---|
| 165 | #ifdef HAVE_ZLIB |
---|
| 166 | /** Default size of zbuffers managed by this RStream. */ |
---|
| 167 | uint32_t zbuffersizes; |
---|
| 168 | #endif /* HAVE_ZLIB */ |
---|
| 169 | |
---|
| 170 | /** file handle manager */ |
---|
| 171 | OTF_FileManager* manager; |
---|
| 172 | |
---|
| 173 | /** maximum number of records delivered by a single call to OTF_Reader_readXYZ() |
---|
| 174 | defaults to OTF_READ_MAXRECORDS == \infty */ |
---|
| 175 | uint64_t recordLimit; |
---|
| 176 | }; |
---|
| 177 | /** rstream object \ingroup rstream */ |
---|
| 178 | typedef struct struct_OTF_RStream OTF_RStream; |
---|
| 179 | |
---|
| 180 | |
---|
| 181 | /** |
---|
| 182 | * Create a new OTF_RStream instance. |
---|
| 183 | * |
---|
| 184 | * @param nameStub File name prefix which is going to be used by |
---|
| 185 | * all sub-files which belong to the reader stream. |
---|
| 186 | * @param id Abitrary but unique identifier of the reader stream. |
---|
| 187 | * Cannot be '0'. |
---|
| 188 | * @param manager File handle manager. |
---|
| 189 | * |
---|
| 190 | * @return Initialized OTF_RStream instance or 0 if an error |
---|
| 191 | * occurred. |
---|
| 192 | * |
---|
| 193 | * \ingroup rstream |
---|
| 194 | */ |
---|
| 195 | OTF_RStream* OTF_RStream_open( const char* nameStub, uint32_t id, OTF_FileManager* manager ); |
---|
| 196 | |
---|
| 197 | |
---|
| 198 | /** |
---|
| 199 | * Close an OTF_RStream instance and all its related files. |
---|
| 200 | * |
---|
| 201 | * @param rstream Pointer to an initialized OTF_RStream object. See |
---|
| 202 | * also OTF_RStream_open(). |
---|
| 203 | * |
---|
| 204 | * @return 1 if instance was closed successfully and 0 otherwise. |
---|
| 205 | * |
---|
| 206 | * \ingroup rstream |
---|
| 207 | */ |
---|
| 208 | int OTF_RStream_close( OTF_RStream* rstream ); |
---|
| 209 | |
---|
| 210 | |
---|
| 211 | /** |
---|
| 212 | * Returns the definition buffer of the according reader stream. |
---|
| 213 | * |
---|
| 214 | * @param rstream Pointer to an initialized OTF_RStream object. See |
---|
| 215 | * also OTF_RStream_open(). |
---|
| 216 | * |
---|
| 217 | * @return Initialized OTF_RBuffer instance or 0 if an error occured. |
---|
| 218 | * |
---|
| 219 | * \ingroup rstream |
---|
| 220 | */ |
---|
| 221 | OTF_RBuffer* OTF_RStream_getDefBuffer( OTF_RStream* rstream ); |
---|
| 222 | |
---|
| 223 | |
---|
| 224 | /** |
---|
| 225 | * Closes the stream defefinition buffer. |
---|
| 226 | * |
---|
| 227 | * @param rstream Pointer to an initialized OTF_RStream object. See |
---|
| 228 | * also OTF_RStream_open(). |
---|
| 229 | * |
---|
| 230 | * @return 1 on success, 0 if an error occurs |
---|
| 231 | * |
---|
| 232 | * \ingroup rstream |
---|
| 233 | */ |
---|
| 234 | int OTF_RStream_closeDefBuffer( OTF_RStream* rstream ); |
---|
| 235 | |
---|
| 236 | |
---|
| 237 | /** |
---|
| 238 | * Returns the event buffer of the according reader stream. |
---|
| 239 | * |
---|
| 240 | * @param rstream Pointer to an initialized OTF_RStream object. See |
---|
| 241 | * also OTF_RStream_open(). |
---|
| 242 | * |
---|
| 243 | * @return Initialized OTF_RBuffer instance or 0 if an error occured. |
---|
| 244 | * |
---|
| 245 | * \ingroup rstream |
---|
| 246 | */ |
---|
| 247 | OTF_RBuffer* OTF_RStream_getEventBuffer( OTF_RStream* rstream ); |
---|
| 248 | |
---|
| 249 | |
---|
| 250 | /** |
---|
| 251 | * Closes the stream event buffer. |
---|
| 252 | * |
---|
| 253 | * @param rstream Pointer to an initialized OTF_RStream object. See |
---|
| 254 | * also OTF_RStream_open(). |
---|
| 255 | * |
---|
| 256 | * @return 1 on success, 0 if an error occurs |
---|
| 257 | * |
---|
| 258 | * \ingroup rstream |
---|
| 259 | */ |
---|
| 260 | int OTF_RStream_closeEventBuffer( OTF_RStream* rstream ); |
---|
| 261 | |
---|
| 262 | |
---|
| 263 | /** |
---|
| 264 | * Returns the snapshots buffer of the according reader stream. |
---|
| 265 | * |
---|
| 266 | * @param rstream Pointer to an initialized OTF_RStream object. See |
---|
| 267 | * also OTF_RStream_open(). |
---|
| 268 | * |
---|
| 269 | * @return Initialized OTF_RBuffer instance or 0 if an error occured. |
---|
| 270 | * |
---|
| 271 | * \ingroup rstream |
---|
| 272 | */ |
---|
| 273 | OTF_RBuffer* OTF_RStream_getSnapsBuffer( OTF_RStream* rstream ); |
---|
| 274 | |
---|
| 275 | |
---|
| 276 | /** |
---|
| 277 | * Closes the stream snapshots buffer. |
---|
| 278 | * |
---|
| 279 | * @param rstream Pointer to an initialized OTF_RStream object. See |
---|
| 280 | * also OTF_RStream_open(). |
---|
| 281 | * |
---|
| 282 | * @return 1 on success, 0 if an error occurs |
---|
| 283 | * |
---|
| 284 | * \ingroup rstream |
---|
| 285 | */ |
---|
| 286 | int OTF_RStream_closeSnapsBuffer( OTF_RStream* rstream ); |
---|
| 287 | |
---|
| 288 | |
---|
| 289 | /** |
---|
| 290 | * Returns the statistics buffer of the according reader stream. |
---|
| 291 | * |
---|
| 292 | * @param rstream Pointer to an initialized OTF_RStream object. See |
---|
| 293 | * also OTF_RStream_open(). |
---|
| 294 | * |
---|
| 295 | * @return Initialized OTF_RBuffer instance or 0 if an error occured. |
---|
| 296 | * |
---|
| 297 | * \ingroup rstream |
---|
| 298 | */ |
---|
| 299 | OTF_RBuffer* OTF_RStream_getStatsBuffer( OTF_RStream* rstream ); |
---|
| 300 | |
---|
| 301 | /** |
---|
| 302 | * Closes the stream statistics buffer. |
---|
| 303 | * |
---|
| 304 | * @param rstream Pointer to an initialized OTF_RStream object. See |
---|
| 305 | * also OTF_RStream_open(). |
---|
| 306 | * |
---|
| 307 | * @return 1 on success, 0 if an error occurs |
---|
| 308 | * |
---|
| 309 | * \ingroup rstream |
---|
| 310 | */ |
---|
| 311 | int OTF_RStream_closeStatsBuffer( OTF_RStream* rstream ); |
---|
| 312 | |
---|
| 313 | |
---|
| 314 | /** |
---|
| 315 | * Set the default buffer size for all buffers managed by this reader stream. |
---|
| 316 | * This is only effective for future buffers and will not change already |
---|
| 317 | * allocated buffers. Those can be changed with the buffers directly. |
---|
| 318 | * |
---|
| 319 | * @param rstream Pointer to an initialized OTF_RStream object. See |
---|
| 320 | * also OTF_RStream_open(). |
---|
| 321 | * |
---|
| 322 | * @param size Intended buffer size. |
---|
| 323 | * |
---|
| 324 | * \ingroup rstream |
---|
| 325 | */ |
---|
| 326 | void OTF_RStream_setBufferSizes( OTF_RStream* rstream, uint32_t size ); |
---|
| 327 | |
---|
| 328 | |
---|
| 329 | /** |
---|
| 330 | * Get the default buffer size for all buffers managed by this reader stream. |
---|
| 331 | * |
---|
| 332 | * @param rstream Pointer to an initialized OTF_RStream object. See |
---|
| 333 | * also OTF_RStream_open(). |
---|
| 334 | * |
---|
| 335 | * @return Default buffer size for all buffers managed by this reader |
---|
| 336 | * stream. |
---|
| 337 | * |
---|
| 338 | * \ingroup rstream |
---|
| 339 | */ |
---|
| 340 | uint32_t OTF_RStream_getBufferSizes( OTF_RStream* rstream ); |
---|
| 341 | |
---|
| 342 | |
---|
| 343 | /** |
---|
| 344 | * Set the default zbuffer size for all files managed by this reader stream. |
---|
| 345 | * This is only effective for future files and will not change already |
---|
| 346 | * allocated buffers. Those can be changed with the files directly. |
---|
| 347 | * |
---|
| 348 | * @param rstream Pointer to an initialized OTF_RStream object. See |
---|
| 349 | * also OTF_RStream_open(). |
---|
| 350 | * |
---|
| 351 | * @param size Intended buffer size. |
---|
| 352 | * |
---|
| 353 | * \ingroup rstream |
---|
| 354 | */ |
---|
| 355 | void OTF_RStream_setZBufferSizes( OTF_RStream* rstream, uint32_t size ); |
---|
| 356 | |
---|
| 357 | |
---|
| 358 | /** |
---|
| 359 | * Get the default zbuffer size for all files managed by this reader stream. |
---|
| 360 | * |
---|
| 361 | * @param rstream Pointer to an initialized OTF_RStream object. See |
---|
| 362 | * also OTF_RStream_open(). |
---|
| 363 | * |
---|
| 364 | * @return Default buffer size for all buffers managed by this reader |
---|
| 365 | * stream. |
---|
| 366 | * |
---|
| 367 | * \ingroup rstream |
---|
| 368 | */ |
---|
| 369 | uint32_t OTF_RStream_getZBufferSizes( OTF_RStream* rstream ); |
---|
| 370 | |
---|
| 371 | |
---|
| 372 | /** |
---|
| 373 | * Sets the maximum number of records delivered by a single call to |
---|
| 374 | * OTF_RStream_readXYZ(). Defaults to OTF_READ_MAXRECORDS == \infty. |
---|
| 375 | * 'OTF_Reader_readXYZ()' returns with the number of records processed. |
---|
| 376 | * Successive calls to 'OTF_Reader_readXYZ()' will deliver the remaining |
---|
| 377 | * records. |
---|
| 378 | * |
---|
| 379 | * This function will NOT destroy a pending read operation, i.e. a read |
---|
| 380 | * operation currently interrupted CAN be continued! |
---|
| 381 | * |
---|
| 382 | * @param rstream Pointer to an initialized OTF_RStream object. See |
---|
| 383 | * also OTF_RStream_open(). |
---|
| 384 | * @param limit new record limit. has to be smaller than or equal to |
---|
| 385 | * OTF_READ_MAXRECORDS |
---|
| 386 | * |
---|
| 387 | * \ingroup rstream |
---|
| 388 | */ |
---|
| 389 | void OTF_RStream_setRecordLimit( OTF_RStream* rstream, uint64_t limit ); |
---|
| 390 | |
---|
| 391 | |
---|
| 392 | /** |
---|
| 393 | * Returns the current record limit. |
---|
| 394 | * |
---|
| 395 | * @param rstream Pointer to an initialized OTF_RStream object. See |
---|
| 396 | * also OTF_RStream_open(). |
---|
| 397 | * |
---|
| 398 | * @return Current record limit. |
---|
| 399 | * |
---|
| 400 | * \ingroup rstream |
---|
| 401 | */ |
---|
| 402 | uint64_t OTF_RStream_getRecordLimit( OTF_RStream* rstream ); |
---|
| 403 | |
---|
| 404 | |
---|
| 405 | |
---|
| 406 | /** |
---|
| 407 | * Reads all definitions from the stream. |
---|
| 408 | * |
---|
| 409 | * @param rstream Pointer to an initialized OTF_RStream object. See |
---|
| 410 | * also OTF_RStream_open(). |
---|
| 411 | * @param handlers Pointer to the handler array. |
---|
| 412 | * |
---|
| 413 | * @return Number of records read or OTF_READ_MAXRECORDS |
---|
| 414 | * |
---|
| 415 | * \ingroup rstream |
---|
| 416 | */ |
---|
| 417 | uint64_t OTF_RStream_readDefinitions( OTF_RStream* rstream, |
---|
| 418 | OTF_HandlerArray* handlers ); |
---|
| 419 | |
---|
| 420 | |
---|
| 421 | /** |
---|
| 422 | * Reads all events from the stream and calls the appropriated handler sorted |
---|
| 423 | * by time. |
---|
| 424 | * |
---|
| 425 | * @param rstream Pointer to an initialized OTF_RStream object. See |
---|
| 426 | * also OTF_RStream_open(). |
---|
| 427 | * @param handlers Pointer to the handler array. |
---|
| 428 | * |
---|
| 429 | * @return Number of records read or OTF_READ_MAXRECORDS |
---|
| 430 | * |
---|
| 431 | * \ingroup rstream |
---|
| 432 | */ |
---|
| 433 | uint64_t OTF_RStream_readEvents( OTF_RStream* rstream, OTF_HandlerArray* handlers ); |
---|
| 434 | |
---|
| 435 | |
---|
| 436 | /** |
---|
| 437 | * Reads all snapshots from the stream. |
---|
| 438 | * |
---|
| 439 | * @param rstream Pointer to an initialized OTF_RStream object. See |
---|
| 440 | * also OTF_RStream_open(). |
---|
| 441 | * @param handlers Pointer to the handler array. |
---|
| 442 | * |
---|
| 443 | * @return Number of records read or OTF_READ_MAXRECORDS |
---|
| 444 | * |
---|
| 445 | * \ingroup rstream |
---|
| 446 | */ |
---|
| 447 | uint64_t OTF_RStream_readSnapshots( OTF_RStream* rstream, OTF_HandlerArray* handlers ); |
---|
| 448 | |
---|
| 449 | |
---|
| 450 | /** |
---|
| 451 | * Reads all statistics from the stream. |
---|
| 452 | * |
---|
| 453 | * @param rstream Pointer to an initialized OTF_RStream object. See |
---|
| 454 | * also OTF_RStream_open(). |
---|
| 455 | * @param handlers Pointer to the handler array. |
---|
| 456 | * |
---|
| 457 | * @return Number of records read or OTF_READ_MAXRECORDS |
---|
| 458 | * |
---|
| 459 | * \ingroup rstream |
---|
| 460 | */ |
---|
| 461 | uint64_t OTF_RStream_readStatistics( OTF_RStream* rstream, OTF_HandlerArray* handlers ); |
---|
| 462 | |
---|
| 463 | |
---|
| 464 | |
---|
| 465 | /** depricated. @see OTF_RStream_eventTimeProgress() \ingroup rstream */ |
---|
| 466 | uint8_t OTF_RStream_eventProgress( OTF_RStream* rstream, uint64_t* minimum, |
---|
| 467 | uint64_t* current, uint64_t* maximum ); |
---|
| 468 | |
---|
| 469 | /** depricated. @see OTF_RStream_snapshotTimeProgress() \ingroup rstream */ |
---|
| 470 | uint8_t OTF_RStream_snapshotProgress( OTF_RStream* rstream, |
---|
| 471 | uint64_t* minimum, uint64_t* current, uint64_t* maximum ); |
---|
| 472 | |
---|
| 473 | /** depricated. @see OTF_RStream_statisticTimeProgress() \ingroup rstream */ |
---|
| 474 | uint8_t OTF_RStream_statisticProgress( OTF_RStream* rstream, |
---|
| 475 | uint64_t* minimum, uint64_t* current, uint64_t* maximum ); |
---|
| 476 | |
---|
| 477 | |
---|
| 478 | /** |
---|
| 479 | * Delivers a progress report for reading events. Progress is given in terms |
---|
| 480 | * of time stamps. A percentage can be computed as |
---|
| 481 | * ( current - minimum ) / ( maximum - minimum ). |
---|
| 482 | * This computation takes restricted time intervals into account! This would not |
---|
| 483 | * be possible when referring to bytes read instead of time stamps. |
---|
| 484 | * The progress report is only valid after one or several calls to |
---|
| 485 | * 'readEvents()'.In the latter case the return arguments |
---|
| 486 | * 'minimum', 'current' and 'maximum' are undefined! If 'minimum' > 'maximum' |
---|
| 487 | * the values are invalid. |
---|
| 488 | * |
---|
| 489 | * @param rstream Pointer to an initialized OTF_RStream object. See |
---|
| 490 | * also OTF_RStream_open(). |
---|
| 491 | * @param minimum Return value for the minium time. |
---|
| 492 | * @param current Return value for the current time. |
---|
| 493 | * @param maximum Return value for the maximum time. |
---|
| 494 | * |
---|
| 495 | * @return 1 on success, 0 if an error occurs. |
---|
| 496 | * |
---|
| 497 | * \ingroup rstream |
---|
| 498 | */ |
---|
| 499 | uint8_t OTF_RStream_eventTimeProgress( OTF_RStream* rstream, uint64_t* minimum, |
---|
| 500 | uint64_t* current, uint64_t* maximum ); |
---|
| 501 | |
---|
| 502 | |
---|
| 503 | /** |
---|
| 504 | * Delivers a progress report for reading snapshots. Progress is given in terms |
---|
| 505 | * of time stamps. a percentage can be computed as |
---|
| 506 | * ( current - minimum ) / ( maximum - minimum ). |
---|
| 507 | * This computation takes restricted time intervals into account! this would |
---|
| 508 | * not be possible when refering to bytes read instead of time stamps. |
---|
| 509 | * The progress report is only valid after one or several calls to |
---|
| 510 | * 'readSnapshots()'. In the latter case the return arguments |
---|
| 511 | * 'minimum', 'current' and 'maximum' are undefined! If 'minimum' > 'maximum' |
---|
| 512 | * the values are invalid. |
---|
| 513 | * |
---|
| 514 | * @param rstream Pointer to an initialized OTF_RStream object. See |
---|
| 515 | * also OTF_RStream_open(). |
---|
| 516 | * @param minimum Return value for the minium time. |
---|
| 517 | * @param current Return value for the current time. |
---|
| 518 | * @param maximum Return value for the maximum time. |
---|
| 519 | * |
---|
| 520 | * @return 1 on success, 0 if an error occurs. |
---|
| 521 | * |
---|
| 522 | * \ingroup rstream |
---|
| 523 | */ |
---|
| 524 | uint8_t OTF_RStream_snapshotTimeProgress( OTF_RStream* rstream, |
---|
| 525 | uint64_t* minimum, uint64_t* current, uint64_t* maximum ); |
---|
| 526 | |
---|
| 527 | |
---|
| 528 | /** |
---|
| 529 | * Delivers a progress report for reading statistics. Progress is given in terms |
---|
| 530 | * of time stamps. a percentage can be computed as |
---|
| 531 | * ( current - minimum ) / ( maximum - minimum ). |
---|
| 532 | * This computation takes restricted time intervals into account! this would |
---|
| 533 | * not be possible when refering to bytes read instead of time stamps. |
---|
| 534 | * The progress report is only valid after one or several calls to |
---|
| 535 | * 'readStatistics()'. In the latter case the return arguments |
---|
| 536 | * 'minimum', 'current' and 'maximum' are undefined! If 'minimum' > 'maximum' |
---|
| 537 | * the values are invalid. |
---|
| 538 | * |
---|
| 539 | * @param rstream Pointer to an initialized OTF_RStream object. See |
---|
| 540 | * also OTF_RStream_open(). |
---|
| 541 | * @param minimum Return value for the minium time. |
---|
| 542 | * @param current Return value for the current time. |
---|
| 543 | * @param maximum Return value for the maximum time. |
---|
| 544 | * |
---|
| 545 | * @return 1 on success, 0 if an error occurs. |
---|
| 546 | * |
---|
| 547 | * \ingroup rstream |
---|
| 548 | */ |
---|
| 549 | uint8_t OTF_RStream_statisticTimeProgress( OTF_RStream* rstream, |
---|
| 550 | uint64_t* minimum, uint64_t* current, uint64_t* maximum ); |
---|
| 551 | |
---|
| 552 | |
---|
| 553 | /** |
---|
| 554 | * Delivers a progress report for reading events. Progress is given in terms |
---|
| 555 | * of time stamps. a percentage can be computed as |
---|
| 556 | * ( current - minimum ) / ( maximum - minimum ). |
---|
| 557 | * This computation takes the read bytes of every stream into account. In the |
---|
| 558 | * latter case the return arguments 'minimum', 'current' and 'maximum' are |
---|
| 559 | * undefined! If 'minimum' > 'maximum' the values are invalid. |
---|
| 560 | * |
---|
| 561 | * @param rstream Pointer to an initialized OTF_RStream object. See |
---|
| 562 | * also OTF_RStream_open(). |
---|
| 563 | * @param minimum Return value for the minium bytes read ( is 0 everytime ). |
---|
| 564 | * @param current Return value for the current bytes read. |
---|
| 565 | * @param maximum Return value for the filesize. |
---|
| 566 | * |
---|
| 567 | * @return 1 on success, 0 if an error occurs. |
---|
| 568 | * |
---|
| 569 | * \ingroup rstream |
---|
| 570 | */ |
---|
| 571 | uint8_t OTF_RStream_eventBytesProgress( OTF_RStream* rstream, uint64_t* minimum, |
---|
| 572 | uint64_t* current, uint64_t* maximum ); |
---|
| 573 | |
---|
| 574 | |
---|
| 575 | /** |
---|
| 576 | * Delivers a progress report for reading snapshots. Progress is given in terms |
---|
| 577 | * of time stamps. a percentage can be computed as |
---|
| 578 | * ( current - minimum ) / ( maximum - minimum ). |
---|
| 579 | * This computation takes the read bytes of every stream into account. In the |
---|
| 580 | * latter case the return arguments 'minimum', 'current' and 'maximum' are |
---|
| 581 | * undefined! If 'minimum' > 'maximum' the values are invalid. |
---|
| 582 | * |
---|
| 583 | * @param rstream Pointer to an initialized OTF_RStream object. See |
---|
| 584 | * also OTF_RStream_open(). |
---|
| 585 | * @param minimum Return value for the minium bytes read ( is 0 everytime ). |
---|
| 586 | * @param current Return value for the current bytes read. |
---|
| 587 | * @param maximum Return value for the filesize. |
---|
| 588 | * |
---|
| 589 | * @return 1 on success, 0 if an error occurs. |
---|
| 590 | * |
---|
| 591 | * \ingroup rstream |
---|
| 592 | */ |
---|
| 593 | uint8_t OTF_RStream_snapshotBytesProgress( OTF_RStream* rstream, |
---|
| 594 | uint64_t* minimum, uint64_t* current, uint64_t* maximum ); |
---|
| 595 | |
---|
| 596 | /** |
---|
| 597 | * Delivers a progress report for reading statistics. Progress is given in terms |
---|
| 598 | * of time stamps. a percentage can be computed as |
---|
| 599 | * ( current - minimum ) / ( maximum - minimum ). |
---|
| 600 | * This computation takes the read bytes of every stream into account. In the |
---|
| 601 | * latter case the return arguments 'minimum', 'current' and 'maximum' are |
---|
| 602 | * undefined! If 'minimum' > 'maximum' the values are invalid. |
---|
| 603 | * |
---|
| 604 | * @param rstream Pointer to an initialized OTF_RStream object. See |
---|
| 605 | * also OTF_RStream_open(). |
---|
| 606 | * @param minimum Return value for the minium bytes read ( is 0 everytime ). |
---|
| 607 | * @param current Return value for the current bytes read. |
---|
| 608 | * @param maximum Return value for the filesize. |
---|
| 609 | * |
---|
| 610 | * @return 1 on success, 0 if an error occurs. |
---|
| 611 | * |
---|
| 612 | * \ingroup rstream |
---|
| 613 | */ |
---|
| 614 | uint8_t OTF_RStream_statisticBytesProgress( OTF_RStream* rstream, |
---|
| 615 | uint64_t* minimum, uint64_t* current, uint64_t* maximum ); |
---|
| 616 | |
---|
| 617 | #ifdef __cplusplus |
---|
| 618 | } |
---|
| 619 | #endif /* __cplusplus */ |
---|
| 620 | |
---|
| 621 | #endif /* OTF_RSTREAM_H */ |
---|