[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 | /** |
---|
| 7 | * @file OTF_RBuffer.h |
---|
| 8 | * |
---|
| 9 | * @brief Provides read access to trace buffers. |
---|
| 10 | * |
---|
| 11 | * \ingroup internal |
---|
| 12 | */ |
---|
| 13 | |
---|
| 14 | |
---|
| 15 | #ifndef OTF_RBUFFER_H |
---|
| 16 | #define OTF_RBUFFER_H |
---|
| 17 | |
---|
| 18 | |
---|
| 19 | #include <stdlib.h> |
---|
| 20 | #include <stdio.h> |
---|
| 21 | |
---|
| 22 | |
---|
| 23 | #include "OTF_inttypes.h" |
---|
| 24 | |
---|
| 25 | |
---|
| 26 | #include "OTF_File.h" |
---|
| 27 | |
---|
| 28 | |
---|
| 29 | #ifdef __cplusplus |
---|
| 30 | extern "C" { |
---|
| 31 | #endif /* __cplusplus */ |
---|
| 32 | |
---|
| 33 | struct struct_OTF_RBuffer { |
---|
| 34 | |
---|
| 35 | |
---|
| 36 | OTF_File* file; |
---|
| 37 | |
---|
| 38 | |
---|
| 39 | /** actual buffer */ |
---|
| 40 | char* buffer; |
---|
| 41 | |
---|
| 42 | /** Current read position in buffer. |
---|
| 43 | 'end <= pos' indicates an invalid state! */ |
---|
| 44 | uint32_t pos; |
---|
| 45 | |
---|
| 46 | /** Current end of data in buffer in case it is not full. |
---|
| 47 | 'end <= pos' indicates an invalid state! */ |
---|
| 48 | uint32_t end; |
---|
| 49 | |
---|
| 50 | /** Last '\n' in the buffer. */ |
---|
| 51 | uint32_t lastnewline; |
---|
| 52 | |
---|
| 53 | /** Current size of buffer. */ |
---|
| 54 | uint32_t size; |
---|
| 55 | |
---|
| 56 | /** If 'OTF_RBuffer_jump()' is called only 'jumpsize' bytes are |
---|
| 57 | read into buffer. */ |
---|
| 58 | uint32_t jumpsize; |
---|
| 59 | |
---|
| 60 | /** Current time inside this stream, necessary for state machine, |
---|
| 61 | (-1) means unknown. */ |
---|
| 62 | uint64_t time; |
---|
| 63 | |
---|
| 64 | /** Current process inside this stream, necessary for state machine, |
---|
| 65 | (-1) means unknown. */ |
---|
| 66 | uint32_t process; |
---|
| 67 | |
---|
| 68 | /** Total size of the file in bytes. This is used in |
---|
| 69 | searchTime(). A value of (-1) means unknown. |
---|
| 70 | Determined by internal function OTF_RBuffer_getFileProperties(). */ |
---|
| 71 | uint64_t filesize; |
---|
| 72 | |
---|
| 73 | /** The very first timestamp of that stream. This is used in |
---|
| 74 | searchTime(). A value of (-1) means unknown. |
---|
| 75 | Determined by internal function OTF_RBuffer_getFileProperties(). */ |
---|
| 76 | uint64_t firstTime; |
---|
| 77 | |
---|
| 78 | /** The very last timestamp of that stream. This is used in |
---|
| 79 | searchTime(). A value of (-1) means unknown. |
---|
| 80 | Determined by internal function OTF_RBuffer_getFileProperties(). */ |
---|
| 81 | uint64_t lastTime; |
---|
| 82 | |
---|
| 83 | #ifdef HAVE_ZLIB |
---|
| 84 | /** Default size of zbuffers managed by this buffer. */ |
---|
| 85 | uint32_t zbuffersize; |
---|
| 86 | #endif /* HAVE_ZLIB */ |
---|
| 87 | }; |
---|
| 88 | typedef struct struct_OTF_RBuffer OTF_RBuffer; |
---|
| 89 | |
---|
| 90 | |
---|
| 91 | /** constructor - internal use only */ |
---|
| 92 | OTF_RBuffer* OTF_RBuffer_open( const char* filename, OTF_FileManager* manager ); |
---|
| 93 | |
---|
| 94 | /** destructor - internal use only */ |
---|
| 95 | int OTF_RBuffer_close( OTF_RBuffer* rbuffer ); |
---|
| 96 | |
---|
| 97 | /** Set buffer size. Cannot shrink buffer but only extend. */ |
---|
| 98 | int OTF_RBuffer_setSize( OTF_RBuffer* rbuffer, size_t size ); |
---|
| 99 | |
---|
| 100 | /** Set zbuffer size. */ |
---|
| 101 | void OTF_RBuffer_setZBufferSize( OTF_RBuffer* rbuffer, uint32_t size ); |
---|
| 102 | |
---|
| 103 | /** Set 'jumpsize'. Return 0 if 'size' is greater than the |
---|
| 104 | buffer size. */ |
---|
| 105 | int OTF_RBuffer_setJumpSize( OTF_RBuffer* rbuffer, size_t size ); |
---|
| 106 | |
---|
| 107 | /** Make the next record availabe from the buffer. Return the pointer to the |
---|
| 108 | record string which is terminated by '\n' not '\0' ! |
---|
| 109 | This funktion must be called before any record access. It ensures the |
---|
| 110 | record is available completely in the buffer. Furthermore, time and process |
---|
| 111 | information is kept track of. |
---|
| 112 | It is recommended to use the 'OTF_RBuffer_readXXX()' functions below to |
---|
| 113 | read record components instead of parsing manually. In any case, after |
---|
| 114 | reading 'OTF_RBuffer_readNewline()' needs to be called which proceeds to |
---|
| 115 | the next record begin no matter if there are still characters from the |
---|
| 116 | current record present or not. */ |
---|
| 117 | char* OTF_RBuffer_getRecord( OTF_RBuffer* rbuffer ); |
---|
| 118 | |
---|
| 119 | |
---|
| 120 | /** Ask the buffer to guarantee at least one complete record at the current |
---|
| 121 | read position inside the buffer. This means one line, e.g. '\n' character. |
---|
| 122 | If no complete record is found the buffer has to be advanced by reading new |
---|
| 123 | contents from file. Return 1 on success, 0 means the file is exceeded. */ |
---|
| 124 | int OTF_RBuffer_guaranteeRecord( OTF_RBuffer* rbuffer ); |
---|
| 125 | |
---|
| 126 | |
---|
| 127 | /** Print the record at the current buffer position, i.e. until the next |
---|
| 128 | newline character. This is for debugging purposes only and won't modify the |
---|
| 129 | buffer in any way. */ |
---|
| 130 | char *OTF_RBuffer_printRecord( OTF_RBuffer* rbuffer ); |
---|
| 131 | |
---|
| 132 | |
---|
| 133 | /** Jump to the given file position and restore buffer and references as if |
---|
| 134 | the buffer had reached the position by advancing through the file linearly. |
---|
| 135 | In particular, find the next record start, then find next timestamp and |
---|
| 136 | process specification in order to set 'time' and 'process' to true values. |
---|
| 137 | Return error code 1 on success. Otherwise the file is not that large or |
---|
| 138 | there are no appropriate time and process specifications on the tail of |
---|
| 139 | the file. Then the buffer contents is undefined */ |
---|
| 140 | int OTF_RBuffer_jump( OTF_RBuffer* rbuffer, uint64_t filepos ); |
---|
| 141 | |
---|
| 142 | /** Read an 64bit unsigned integer in hex format from buffer and return it. */ |
---|
| 143 | uint64_t OTF_RBuffer_readUint64( OTF_RBuffer* rbuffer ); |
---|
| 144 | |
---|
| 145 | /** Read an unsigned integer in hex format from buffer and return it. */ |
---|
| 146 | uint32_t OTF_RBuffer_readUint32( OTF_RBuffer* rbuffer ); |
---|
| 147 | |
---|
| 148 | /** Read a string from buffer and return it. */ |
---|
| 149 | const char* OTF_RBuffer_readString( OTF_RBuffer* rbuffer ); |
---|
| 150 | |
---|
| 151 | /** Read a array from buffer and return the number of elements. |
---|
| 152 | malloc memory for *array internally, needs to be freed by caller */ |
---|
| 153 | uint32_t OTF_RBuffer_readArray( OTF_RBuffer* rbuffer, uint32_t** array ); |
---|
| 154 | |
---|
| 155 | /** Test if the next character equals the given one (leading spaces are |
---|
| 156 | ignored). If the right character is found return 1, and advance by 1 step. |
---|
| 157 | If the character was not found, keep the buffer position such that the test |
---|
| 158 | can be repeated with another character. */ |
---|
| 159 | int OTF_RBuffer_testChar( OTF_RBuffer* rbuffer, char c ); |
---|
| 160 | |
---|
| 161 | /** Test if the next string equals the given one (leading spaces are |
---|
| 162 | ignored). The next character must not be an uppercase letter as used in |
---|
| 163 | keywords. If the right string is found return 1, and advance the buffer |
---|
| 164 | position. If the string was not found, keep the buffer position such |
---|
| 165 | that the test can be repeated with another string. */ |
---|
| 166 | int OTF_RBuffer_testKeyword( OTF_RBuffer* rbuffer, const char* string ); |
---|
| 167 | |
---|
| 168 | /** Test if the next string equals the given one (leading spaces are |
---|
| 169 | ignored). This version is similar to the above function but does not test |
---|
| 170 | the following character, i.e. it can be used to test for prefixes. |
---|
| 171 | If the right string is found return 1, and advance the buffer |
---|
| 172 | position. If the string was not found, keep the buffer position such |
---|
| 173 | that the test can be repeated with another string. */ |
---|
| 174 | int OTF_RBuffer_testPrefix( OTF_RBuffer* rbuffer, const char* string ); |
---|
| 175 | |
---|
| 176 | /** Read a newline such that the buffer pos is at the next record beginning. |
---|
| 177 | Skip all characters found, assume they are to be ignored. |
---|
| 178 | Return 1 on success, 0 on error. */ |
---|
| 179 | int OTF_RBuffer_readNewline( OTF_RBuffer* rbuffer ); |
---|
| 180 | |
---|
| 181 | /** Advance the buffer position while there are spaces. */ |
---|
| 182 | void OTF_RBuffer_skipSpaces( OTF_RBuffer* rbuffer ); |
---|
| 183 | |
---|
| 184 | /** Advance the buffer position while there are capital letters. */ |
---|
| 185 | void OTF_RBuffer_skipKeyword( OTF_RBuffer* rbuffer ); |
---|
| 186 | |
---|
| 187 | /** Return the current time of the buffer. */ |
---|
| 188 | uint64_t OTF_RBuffer_getCurrentTime( OTF_RBuffer* rbuffer ); |
---|
| 189 | |
---|
| 190 | /** Set the current time of the buffer to the given one. */ |
---|
| 191 | void OTF_RBuffer_setCurrentTime( OTF_RBuffer* rbuffer, uint64_t time ); |
---|
| 192 | |
---|
| 193 | /** Return the current process of the buffer. */ |
---|
| 194 | uint32_t OTF_RBuffer_getCurrentProcess( OTF_RBuffer* rbuffer ); |
---|
| 195 | |
---|
| 196 | /** Set the current process of the buffer to the given one. */ |
---|
| 197 | void OTF_RBuffer_setCurrentProcess( OTF_RBuffer* rbuffer, uint32_t process ); |
---|
| 198 | |
---|
| 199 | /** Search the buffer for the given time and set the buffer position to |
---|
| 200 | the next record after that time. Return 1 on success, 0 on error. */ |
---|
| 201 | int OTF_RBuffer_searchTime( OTF_RBuffer* rbuffer, uint64_t time ); |
---|
| 202 | |
---|
| 203 | /** Determine buffers filesize, firstTime and lastTime if not already set. |
---|
| 204 | Return 1 on success, 0 on error. */ |
---|
| 205 | int OTF_RBuffer_getFileProperties( OTF_RBuffer* rbuffer ); |
---|
| 206 | |
---|
| 207 | /** Returns the filesize of the file attached to this buffer */ |
---|
| 208 | uint64_t OTF_RBuffer_getFileSize( OTF_RBuffer* rbuffer ); |
---|
| 209 | |
---|
| 210 | /** Returns the fileposition of the file attached to this buffer */ |
---|
| 211 | uint64_t OTF_RBuffer_getFilePos( OTF_RBuffer* rbuffer ); |
---|
| 212 | |
---|
| 213 | #ifdef __cplusplus |
---|
| 214 | } |
---|
| 215 | #endif /* __cplusplus */ |
---|
| 216 | |
---|
| 217 | #endif /* OTF_RBUFFER_H */ |
---|
| 218 | |
---|