/* This is part of the OTF library. Copyright by ZIH, TU Dresden 2005-2008. Authors: Andreas Knuepfer, Holger Brunst, Ronny Brendel, Thomas Kriebitzsch */ /* NOTE the OTF_RStream interface is not able to perform jumps to random timestamps, and cannot quit at a certain maximum time stamp. Maybe in future versions we add this. It is not in, because the OTF_Reader interface uses the buffer-methodes directly to set the timestamps, so saving it in the stream too will be worthless in this case. */ /** * @file OTF_RStream.h * * @brief Provides read access to trace streams, which consist of multiple * buffers. * * \ingroup rstream */ /** \defgroup rstream Stream Reader Interface * * rstream provides an interface for dealing with a single stream of a trace. * A stream consists of up to four different buffers (event buffer, * definition buffer, snapshots buffer, statistics buffer). * * rstream is structured similarly to the reader, but it is not * able to perform jumps to random timestamps, and cannot quit at a certain * maximum time stamp. * * \section rstream_example A simple Example * * Common includes * \code * #include * #include * #include "otf.h" * \endcode * * * Define the Handler(s). * We just want to process the def process event and print out all appearing processes. * \code * int handleDefProcess (void *userData, uint32_t stream, uint32_t process, const char *name, uint32_t parent) { * * printf( "process %u is named \"%s\"\n", process, name ); * * return OTF_RETURN_OK; * } * \endcode * * \code * int main( int argc, char** argv ) { * \endcode * * Declare a file manager, a reader, and a handler array * \code * OTF_RStream* rstream; * OTF_FileManager* manager; * OTF_HandlerArray* handlers; * \endcode * * Initialize the file manager. Do not open more than 100 files. * \code * manager= OTF_FileManager_open( 100 ); * assert( manager ); * \endcode * * Initialize the handler array. * \code * handlers = OTF_HandlerArray_open(); * assert( handlers ); * \endcode * * Initialize the rstream object. * \code * rstream = OTF_RStream_open( "mytrace", 0, manager ); * assert( rstream ); * \endcode * * Register your callback functions to the handler array. * \code * OTF_HandlerArray_setHandler( handlers, (OTF_FunctionPointer*) handleDefProcess, OTF_DEFPROCESS_RECORD ); * \endcode * * * Do the actual reading. * \code * OTF_RStream_readDefinitions( rstream, handlers ); * \endcode * * * Clean everything up before exiting the program. * \code * OTF_RStream_close( rstream ); * OTF_HandlerArray_close( handlers ); * OTF_FileManager_close( manager ); * * return 0; * } * \endcode * * Compile and link this using $ gcc -o test test.c `otfconfig --libs`. * */ #ifndef OTF_RSTREAM_H #define OTF_RSTREAM_H #include #include #include #include "OTF_inttypes.h" #include "OTF_FileManager.h" #include "OTF_RBuffer.h" #include "OTF_Filenames.h" #include "OTF_HandlerArray.h" #ifdef __cplusplus extern "C" { #endif /* __cplusplus */ struct struct_OTF_RStream { /** name stub: all files will begin with this name */ char* namestub; /** Unique id for the current stream */ uint32_t id; /** Definitions buffer. Definitions buffer carries definition records */ OTF_RBuffer* defBuffer; /** Event buffer. The event buffer carries records for actual events, i.e. records with a time stamp */ OTF_RBuffer* eventBuffer; /** Snaps (snapshots) buffer. The snapshots buffer carries snapshots of the whole state at a point in time - as oppossed to events which only show changes in the state. This can be used to start from such a snapshot instead of from the very begining. */ OTF_RBuffer* snapsBuffer; /** Statistics buffer. Statistics buffer carries statistical information about a certain time interval resp. data at points of time that allow to derive statistics without reading through all events of that interval. */ OTF_RBuffer* statsBuffer; /** Default size of buffers managed by this RStream. */ uint32_t buffersizes; #ifdef HAVE_ZLIB /** Default size of zbuffers managed by this RStream. */ uint32_t zbuffersizes; #endif /* HAVE_ZLIB */ /** file handle manager */ OTF_FileManager* manager; /** maximum number of records delivered by a single call to OTF_Reader_readXYZ() defaults to OTF_READ_MAXRECORDS == \infty */ uint64_t recordLimit; }; /** rstream object \ingroup rstream */ typedef struct struct_OTF_RStream OTF_RStream; /** * Create a new OTF_RStream instance. * * @param nameStub File name prefix which is going to be used by * all sub-files which belong to the reader stream. * @param id Abitrary but unique identifier of the reader stream. * Cannot be '0'. * @param manager File handle manager. * * @return Initialized OTF_RStream instance or 0 if an error * occurred. * * \ingroup rstream */ OTF_RStream* OTF_RStream_open( const char* nameStub, uint32_t id, OTF_FileManager* manager ); /** * Close an OTF_RStream instance and all its related files. * * @param rstream Pointer to an initialized OTF_RStream object. See * also OTF_RStream_open(). * * @return 1 if instance was closed successfully and 0 otherwise. * * \ingroup rstream */ int OTF_RStream_close( OTF_RStream* rstream ); /** * Returns the definition buffer of the according reader stream. * * @param rstream Pointer to an initialized OTF_RStream object. See * also OTF_RStream_open(). * * @return Initialized OTF_RBuffer instance or 0 if an error occured. * * \ingroup rstream */ OTF_RBuffer* OTF_RStream_getDefBuffer( OTF_RStream* rstream ); /** * Closes the stream defefinition buffer. * * @param rstream Pointer to an initialized OTF_RStream object. See * also OTF_RStream_open(). * * @return 1 on success, 0 if an error occurs * * \ingroup rstream */ int OTF_RStream_closeDefBuffer( OTF_RStream* rstream ); /** * Returns the event buffer of the according reader stream. * * @param rstream Pointer to an initialized OTF_RStream object. See * also OTF_RStream_open(). * * @return Initialized OTF_RBuffer instance or 0 if an error occured. * * \ingroup rstream */ OTF_RBuffer* OTF_RStream_getEventBuffer( OTF_RStream* rstream ); /** * Closes the stream event buffer. * * @param rstream Pointer to an initialized OTF_RStream object. See * also OTF_RStream_open(). * * @return 1 on success, 0 if an error occurs * * \ingroup rstream */ int OTF_RStream_closeEventBuffer( OTF_RStream* rstream ); /** * Returns the snapshots buffer of the according reader stream. * * @param rstream Pointer to an initialized OTF_RStream object. See * also OTF_RStream_open(). * * @return Initialized OTF_RBuffer instance or 0 if an error occured. * * \ingroup rstream */ OTF_RBuffer* OTF_RStream_getSnapsBuffer( OTF_RStream* rstream ); /** * Closes the stream snapshots buffer. * * @param rstream Pointer to an initialized OTF_RStream object. See * also OTF_RStream_open(). * * @return 1 on success, 0 if an error occurs * * \ingroup rstream */ int OTF_RStream_closeSnapsBuffer( OTF_RStream* rstream ); /** * Returns the statistics buffer of the according reader stream. * * @param rstream Pointer to an initialized OTF_RStream object. See * also OTF_RStream_open(). * * @return Initialized OTF_RBuffer instance or 0 if an error occured. * * \ingroup rstream */ OTF_RBuffer* OTF_RStream_getStatsBuffer( OTF_RStream* rstream ); /** * Closes the stream statistics buffer. * * @param rstream Pointer to an initialized OTF_RStream object. See * also OTF_RStream_open(). * * @return 1 on success, 0 if an error occurs * * \ingroup rstream */ int OTF_RStream_closeStatsBuffer( OTF_RStream* rstream ); /** * Set the default buffer size for all buffers managed by this reader stream. * This is only effective for future buffers and will not change already * allocated buffers. Those can be changed with the buffers directly. * * @param rstream Pointer to an initialized OTF_RStream object. See * also OTF_RStream_open(). * * @param size Intended buffer size. * * \ingroup rstream */ void OTF_RStream_setBufferSizes( OTF_RStream* rstream, uint32_t size ); /** * Get the default buffer size for all buffers managed by this reader stream. * * @param rstream Pointer to an initialized OTF_RStream object. See * also OTF_RStream_open(). * * @return Default buffer size for all buffers managed by this reader * stream. * * \ingroup rstream */ uint32_t OTF_RStream_getBufferSizes( OTF_RStream* rstream ); /** * Set the default zbuffer size for all files managed by this reader stream. * This is only effective for future files and will not change already * allocated buffers. Those can be changed with the files directly. * * @param rstream Pointer to an initialized OTF_RStream object. See * also OTF_RStream_open(). * * @param size Intended buffer size. * * \ingroup rstream */ void OTF_RStream_setZBufferSizes( OTF_RStream* rstream, uint32_t size ); /** * Get the default zbuffer size for all files managed by this reader stream. * * @param rstream Pointer to an initialized OTF_RStream object. See * also OTF_RStream_open(). * * @return Default buffer size for all buffers managed by this reader * stream. * * \ingroup rstream */ uint32_t OTF_RStream_getZBufferSizes( OTF_RStream* rstream ); /** * Sets the maximum number of records delivered by a single call to * OTF_RStream_readXYZ(). Defaults to OTF_READ_MAXRECORDS == \infty. * 'OTF_Reader_readXYZ()' returns with the number of records processed. * Successive calls to 'OTF_Reader_readXYZ()' will deliver the remaining * records. * * This function will NOT destroy a pending read operation, i.e. a read * operation currently interrupted CAN be continued! * * @param rstream Pointer to an initialized OTF_RStream object. See * also OTF_RStream_open(). * @param limit new record limit. has to be smaller than or equal to * OTF_READ_MAXRECORDS * * \ingroup rstream */ void OTF_RStream_setRecordLimit( OTF_RStream* rstream, uint64_t limit ); /** * Returns the current record limit. * * @param rstream Pointer to an initialized OTF_RStream object. See * also OTF_RStream_open(). * * @return Current record limit. * * \ingroup rstream */ uint64_t OTF_RStream_getRecordLimit( OTF_RStream* rstream ); /** * Reads all definitions from the stream. * * @param rstream Pointer to an initialized OTF_RStream object. See * also OTF_RStream_open(). * @param handlers Pointer to the handler array. * * @return Number of records read or OTF_READ_MAXRECORDS * * \ingroup rstream */ uint64_t OTF_RStream_readDefinitions( OTF_RStream* rstream, OTF_HandlerArray* handlers ); /** * Reads all events from the stream and calls the appropriated handler sorted * by time. * * @param rstream Pointer to an initialized OTF_RStream object. See * also OTF_RStream_open(). * @param handlers Pointer to the handler array. * * @return Number of records read or OTF_READ_MAXRECORDS * * \ingroup rstream */ uint64_t OTF_RStream_readEvents( OTF_RStream* rstream, OTF_HandlerArray* handlers ); /** * Reads all snapshots from the stream. * * @param rstream Pointer to an initialized OTF_RStream object. See * also OTF_RStream_open(). * @param handlers Pointer to the handler array. * * @return Number of records read or OTF_READ_MAXRECORDS * * \ingroup rstream */ uint64_t OTF_RStream_readSnapshots( OTF_RStream* rstream, OTF_HandlerArray* handlers ); /** * Reads all statistics from the stream. * * @param rstream Pointer to an initialized OTF_RStream object. See * also OTF_RStream_open(). * @param handlers Pointer to the handler array. * * @return Number of records read or OTF_READ_MAXRECORDS * * \ingroup rstream */ uint64_t OTF_RStream_readStatistics( OTF_RStream* rstream, OTF_HandlerArray* handlers ); /** depricated. @see OTF_RStream_eventTimeProgress() \ingroup rstream */ uint8_t OTF_RStream_eventProgress( OTF_RStream* rstream, uint64_t* minimum, uint64_t* current, uint64_t* maximum ); /** depricated. @see OTF_RStream_snapshotTimeProgress() \ingroup rstream */ uint8_t OTF_RStream_snapshotProgress( OTF_RStream* rstream, uint64_t* minimum, uint64_t* current, uint64_t* maximum ); /** depricated. @see OTF_RStream_statisticTimeProgress() \ingroup rstream */ uint8_t OTF_RStream_statisticProgress( OTF_RStream* rstream, uint64_t* minimum, uint64_t* current, uint64_t* maximum ); /** * Delivers a progress report for reading events. Progress is given in terms * of time stamps. A percentage can be computed as * ( current - minimum ) / ( maximum - minimum ). * This computation takes restricted time intervals into account! This would not * be possible when referring to bytes read instead of time stamps. * The progress report is only valid after one or several calls to * 'readEvents()'.In the latter case the return arguments * 'minimum', 'current' and 'maximum' are undefined! If 'minimum' > 'maximum' * the values are invalid. * * @param rstream Pointer to an initialized OTF_RStream object. See * also OTF_RStream_open(). * @param minimum Return value for the minium time. * @param current Return value for the current time. * @param maximum Return value for the maximum time. * * @return 1 on success, 0 if an error occurs. * * \ingroup rstream */ uint8_t OTF_RStream_eventTimeProgress( OTF_RStream* rstream, uint64_t* minimum, uint64_t* current, uint64_t* maximum ); /** * Delivers a progress report for reading snapshots. Progress is given in terms * of time stamps. a percentage can be computed as * ( current - minimum ) / ( maximum - minimum ). * This computation takes restricted time intervals into account! this would * not be possible when refering to bytes read instead of time stamps. * The progress report is only valid after one or several calls to * 'readSnapshots()'. In the latter case the return arguments * 'minimum', 'current' and 'maximum' are undefined! If 'minimum' > 'maximum' * the values are invalid. * * @param rstream Pointer to an initialized OTF_RStream object. See * also OTF_RStream_open(). * @param minimum Return value for the minium time. * @param current Return value for the current time. * @param maximum Return value for the maximum time. * * @return 1 on success, 0 if an error occurs. * * \ingroup rstream */ uint8_t OTF_RStream_snapshotTimeProgress( OTF_RStream* rstream, uint64_t* minimum, uint64_t* current, uint64_t* maximum ); /** * Delivers a progress report for reading statistics. Progress is given in terms * of time stamps. a percentage can be computed as * ( current - minimum ) / ( maximum - minimum ). * This computation takes restricted time intervals into account! this would * not be possible when refering to bytes read instead of time stamps. * The progress report is only valid after one or several calls to * 'readStatistics()'. In the latter case the return arguments * 'minimum', 'current' and 'maximum' are undefined! If 'minimum' > 'maximum' * the values are invalid. * * @param rstream Pointer to an initialized OTF_RStream object. See * also OTF_RStream_open(). * @param minimum Return value for the minium time. * @param current Return value for the current time. * @param maximum Return value for the maximum time. * * @return 1 on success, 0 if an error occurs. * * \ingroup rstream */ uint8_t OTF_RStream_statisticTimeProgress( OTF_RStream* rstream, uint64_t* minimum, uint64_t* current, uint64_t* maximum ); /** * Delivers a progress report for reading events. Progress is given in terms * of time stamps. a percentage can be computed as * ( current - minimum ) / ( maximum - minimum ). * This computation takes the read bytes of every stream into account. In the * latter case the return arguments 'minimum', 'current' and 'maximum' are * undefined! If 'minimum' > 'maximum' the values are invalid. * * @param rstream Pointer to an initialized OTF_RStream object. See * also OTF_RStream_open(). * @param minimum Return value for the minium bytes read ( is 0 everytime ). * @param current Return value for the current bytes read. * @param maximum Return value for the filesize. * * @return 1 on success, 0 if an error occurs. * * \ingroup rstream */ uint8_t OTF_RStream_eventBytesProgress( OTF_RStream* rstream, uint64_t* minimum, uint64_t* current, uint64_t* maximum ); /** * Delivers a progress report for reading snapshots. Progress is given in terms * of time stamps. a percentage can be computed as * ( current - minimum ) / ( maximum - minimum ). * This computation takes the read bytes of every stream into account. In the * latter case the return arguments 'minimum', 'current' and 'maximum' are * undefined! If 'minimum' > 'maximum' the values are invalid. * * @param rstream Pointer to an initialized OTF_RStream object. See * also OTF_RStream_open(). * @param minimum Return value for the minium bytes read ( is 0 everytime ). * @param current Return value for the current bytes read. * @param maximum Return value for the filesize. * * @return 1 on success, 0 if an error occurs. * * \ingroup rstream */ uint8_t OTF_RStream_snapshotBytesProgress( OTF_RStream* rstream, uint64_t* minimum, uint64_t* current, uint64_t* maximum ); /** * Delivers a progress report for reading statistics. Progress is given in terms * of time stamps. a percentage can be computed as * ( current - minimum ) / ( maximum - minimum ). * This computation takes the read bytes of every stream into account. In the * latter case the return arguments 'minimum', 'current' and 'maximum' are * undefined! If 'minimum' > 'maximum' the values are invalid. * * @param rstream Pointer to an initialized OTF_RStream object. See * also OTF_RStream_open(). * @param minimum Return value for the minium bytes read ( is 0 everytime ). * @param current Return value for the current bytes read. * @param maximum Return value for the filesize. * * @return 1 on success, 0 if an error occurs. * * \ingroup rstream */ uint8_t OTF_RStream_statisticBytesProgress( OTF_RStream* rstream, uint64_t* minimum, uint64_t* current, uint64_t* maximum ); #ifdef __cplusplus } #endif /* __cplusplus */ #endif /* OTF_RSTREAM_H */