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 | |
---|