OpenMPI 0.1.1

- Main Page
- Related Pages
- Modules
- Data Structures
- Files

- File List
- Globals

OTF_RBuffer.h
Go to the documentation of this file.
1 /*
2 This is part of the OTF library. Copyright by ZIH, TU Dresden 2005-2012.
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 #include "OTF_KeyValue.h"
29
30 /* *** some macros *** ****************************************** */
31 #define PARSE_ERROR( buffer ) \
32 OTF_Error( "Parse error in function %s, file: %s, line: %i:\n %s\n", \
33 __FUNCTION__, __FILE__, __LINE__, OTF_RBuffer_printRecord( buffer ) );
34
35
36 #ifdef __cplusplus
37 extern "C" {
38 #endif /* __cplusplus */
39
40 struct struct_OTF_RBuffer {
41
42
43 OTF_File* file;
44
45
46 /** actual buffer */
47 char* buffer;
48
49 /** Current read position in buffer.
50 'end <= pos' indicates an invalid state! */
51 uint32_t pos;
52
53 /** Current end of data in buffer in case it is not full.
54 'end <= pos' indicates an invalid state! */
55 uint32_t end;
56
57 /** Last '\n' in the buffer. */
58 uint32_t lastnewline;
59
60 /** Current size of buffer. */
61 uint32_t size;
62
63 /** If 'OTF_RBuffer_jump()' is called only 'jumpsize' bytes are
64 read into buffer. */
65 uint32_t jumpsize;
66
67 /** Array which hold the members of a DEFPROCESSGROUP record
68 or the list of attributes of a DEFATTRLIST record. */
69 uint32_t* array;
70
71 /** Current size of array. */
72 uint32_t arraysize;
73
74 /** Current time inside this stream, necessary for state machine,
75 (-1) means unknown. */
76 uint64_t time;
77
78 /** Current process inside this stream, necessary for state machine,
79 (-1) means unknown. */
80 uint32_t process;
81
82 /** Total size of the file in bytes. This is used in
83 searchTime(). A value of (-1) means unknown.
84 Determined by internal function OTF_RBuffer_getFileProperties(). */
85 uint64_t filesize;
86
87 /** The very first timestamp of that stream. This is used in
88 searchTime(). A value of (-1) means unknown.
89 Determined by internal function OTF_RBuffer_getFileProperties(). */
90 uint64_t firstTime;
91
92 /** The very last timestamp of that stream. This is used in
93 searchTime(). A value of (-1) means unknown.
94 Determined by internal function OTF_RBuffer_getFileProperties(). */
95 uint64_t lastTime;
96
97 OTF_KeyValueList* list;
98
99 #ifdef HAVE_ZLIB
100 /** Default size of zbuffers managed by this buffer. */
101 uint32_t zbuffersize;
102 #endif /* HAVE_ZLIB */
103 };
104 typedef struct struct_OTF_RBuffer OTF_RBuffer;
105
106
107 /** constructor - internal use only */
108 OTF_RBuffer* OTF_RBuffer_open( const char* filename, OTF_FileManager* manager );
109
110 /** constructor - internal use only -- special version with a memory buffer to read from
111 instead of an input file, either compressed or uncompressed */
112 OTF_RBuffer* OTF_RBuffer_open_with_external_buffer( uint32_t len, const char* buffer, uint8_t is_compressed );
113
114 /** destructor - internal use only */
115 int OTF_RBuffer_close( OTF_RBuffer* rbuffer );
116
117
118 /** Set buffer size. Cannot shrink buffer but only extend. */
119 int OTF_RBuffer_setSize( OTF_RBuffer* rbuffer, size_t size );
120
121 /** Set zbuffer size. */
122 void OTF_RBuffer_setZBufferSize( OTF_RBuffer* rbuffer, uint32_t size );
123
124 /** Set 'jumpsize'. Return 0 if 'size' is greater than the
125 buffer size. */
126 int OTF_RBuffer_setJumpSize( OTF_RBuffer* rbuffer, size_t size );
127
128 /** Make the next record availabe from the buffer. Return the pointer to the
129 record string which is terminated by '\n' not '\0' !
130 This funktion must be called before any record access. It ensures the
131 record is available completely in the buffer. Furthermore, time and process
132 information is kept track of.
133 It is recommended to use the 'OTF_RBuffer_readXXX()' functions below to
134 read record components instead of parsing manually. In any case, after
135 reading 'OTF_RBuffer_readNewline()' needs to be called which proceeds to
136 the next record begin no matter if there are still characters from the
137 current record present or not. */
138 char* OTF_RBuffer_getRecord( OTF_RBuffer* rbuffer );
139
140
141 /** Ask the buffer to guarantee at least one complete record at the current
142 read position inside the buffer. This means one line, e.g. '\n' character.
143 If no complete record is found the buffer has to be advanced by reading new
144 contents from file. Return 1 on success, 0 means the file is exceeded. */
145 int OTF_RBuffer_guaranteeRecord( OTF_RBuffer* rbuffer );
146
147
148 /** Print the record at the current buffer position, i.e. until the next
149 newline character. This is for debugging purposes only and won't modify the
150 buffer in any way. */
151 char *OTF_RBuffer_printRecord( OTF_RBuffer* rbuffer );
152
153
154 /** Jump to the given file position and restore buffer and references as if
155 the buffer had reached the position by advancing through the file linearly.
156 In particular, find the next record start, then find next timestamp and
157 process specification in order to set 'time' and 'process' to true values.
158 Return error code 1 on success. Otherwise the file is not that large or
159 there are no appropriate time and process specifications on the tail of
160 the file. Then the buffer contents is undefined */
161 int OTF_RBuffer_jump( OTF_RBuffer* rbuffer, uint64_t filepos );
162
163 /** Read an 64bit unsigned integer in hex format from buffer and return it. */
164 uint64_t OTF_RBuffer_readUint64( OTF_RBuffer* rbuffer );
165
166 /** Read an unsigned integer in hex format from buffer and return it. */
167 uint32_t OTF_RBuffer_readUint32( OTF_RBuffer* rbuffer );
168
169 /** Read a string from buffer and return it. */
170 const char* OTF_RBuffer_readString( OTF_RBuffer* rbuffer );
171
172 /** Read an array from buffer and return the number of elements.
173 (re)malloc memory for *array internally, needs to be freed by caller */
174 uint32_t OTF_RBuffer_readArray( OTF_RBuffer* rbuffer, uint32_t** array, uint32_t* size );
175
176 /** Test if the next character equals the given one (leading spaces are
177 ignored). If the right character is found return 1, and advance by 1 step.
178 If the character was not found, keep the buffer position such that the test
179 can be repeated with another character. */
180 int OTF_RBuffer_testChar( OTF_RBuffer* rbuffer, char c );
181
182 /** Test if the next string equals the given one (leading spaces are
183 ignored). The next character must not be an uppercase letter as used in
184 keywords. If the right string is found return 1, and advance the buffer
185 position. If the string was not found, keep the buffer position such
186 that the test can be repeated with another string. */
187 int OTF_RBuffer_testKeyword( OTF_RBuffer* rbuffer, const char* string );
188
189 /** Test if the next string equals the given one (leading spaces are
190 ignored). This version is similar to the above function but does not test
191 the following character, i.e. it can be used to test for prefixes.
192 If the right string is found return 1, and advance the buffer
193 position. If the string was not found, keep the buffer position such
194 that the test can be repeated with another string. */
195 int OTF_RBuffer_testPrefix( OTF_RBuffer* rbuffer, const char* string );
196
197 /** Read a newline such that the buffer pos is at the next record beginning.
198 Skip all characters found, assume they are to be ignored.
199 Return 1 on success, 0 on error. */
200 int OTF_RBuffer_readNewline( OTF_RBuffer* rbuffer );
201
202 /** Advance the buffer position while there are spaces. */
203 void OTF_RBuffer_skipSpaces( OTF_RBuffer* rbuffer );
204
205 /** Advance the buffer position while there are capital letters. */
206 void OTF_RBuffer_skipKeyword( OTF_RBuffer* rbuffer );
207
208 /** Return the current time of the buffer. */
209 uint64_t OTF_RBuffer_getCurrentTime( OTF_RBuffer* rbuffer );
210
211 /** Set the current time of the buffer to the given one. */
212 void OTF_RBuffer_setCurrentTime( OTF_RBuffer* rbuffer, uint64_t time );
213
214 /** Return the current process of the buffer. */
215 uint32_t OTF_RBuffer_getCurrentProcess( OTF_RBuffer* rbuffer );
216
217 /** Set the current process of the buffer to the given one. */
218 void OTF_RBuffer_setCurrentProcess( OTF_RBuffer* rbuffer, uint32_t process );
219
220 /** Search the buffer for the given time and set the buffer position to
221 the next record after that time. Return 1 on success, 0 on error. */
222 int OTF_RBuffer_searchTime( OTF_RBuffer* rbuffer, uint64_t time );
223
224 /** Determine buffers filesize, firstTime and lastTime if not already set.
225 Return 1 on success, 0 on error. */
226 int OTF_RBuffer_getFileProperties( OTF_RBuffer* rbuffer );
227
228 /** Returns the filesize of the file attached to this buffer */
229 uint64_t OTF_RBuffer_getFileSize( OTF_RBuffer* rbuffer );
230
231 /** Returns the fileposition of the file attached to this buffer */
232 uint64_t OTF_RBuffer_getFilePos( OTF_RBuffer* rbuffer );
233
234 /** Read a byte array in hex format from buffer and return the number of
235 bytes read (=lenght of array).
236 If the return value is greater than max_len, there is more to read
237 (this indicates an error in some cases!). */
238 uint32_t OTF_RBuffer_readBytes( OTF_RBuffer* rbuffer, uint8_t *array, uint32_t max_len );
239
240 /** Read a KeyValueList from the buffer. Return 1 on success, 0 on error */
241 uint32_t OTF_RBuffer_readKeyValueList(OTF_RBuffer* buffer );
242
243 #ifdef __cplusplus
244 }
245 #endif /* __cplusplus */
246
247 #endif /* OTF_RBUFFER_H */
248
struct_OTF_File
Definition: OTF_File.c:78
struct_OTF_RBuffer::time
uint64_t time
Current time inside this stream, necessary for state machine, (-1) means unknown. ...
Definition: OTF_RBuffer.h:76
OTF_RBuffer_setZBufferSize
void OTF_RBuffer_setZBufferSize(OTF_RBuffer *rbuffer, uint32_t size)
Set zbuffer size.
Definition: OTF_RBuffer.c:372
struct_OTF_RBuffer::lastnewline
uint32_t lastnewline
Last ' ' in the buffer.
Definition: OTF_RBuffer.h:58
struct_OTF_RBuffer::arraysize
uint32_t arraysize
Current size of array.
Definition: OTF_RBuffer.h:72
OTF_RBuffer_setCurrentTime
void OTF_RBuffer_setCurrentTime(OTF_RBuffer *rbuffer, uint64_t time)
Set the current time of the buffer to the given one.
Definition: OTF_RBuffer.c:827
OTF_RBuffer_skipKeyword
void OTF_RBuffer_skipKeyword(OTF_RBuffer *rbuffer)
Advance the buffer position while there are capital letters.
Definition: OTF_RBuffer.c:1293
struct_OTF_RBuffer::lastTime
uint64_t lastTime
The very last timestamp of that stream.
Definition: OTF_RBuffer.h:95
OTF_RBuffer_setJumpSize
int OTF_RBuffer_setJumpSize(OTF_RBuffer *rbuffer, size_t size)
Set 'jumpsize'.
Definition: OTF_RBuffer.c:408
struct_OTF_RBuffer::firstTime
uint64_t firstTime
The very first timestamp of that stream.
Definition: OTF_RBuffer.h:90
OTF_RBuffer_readString
const char * OTF_RBuffer_readString(OTF_RBuffer *rbuffer)
Read a string from buffer and return it.
Definition: OTF_RBuffer.c:1205
OTF_RBuffer_open_with_external_buffer
OTF_RBuffer * OTF_RBuffer_open_with_external_buffer(uint32_t len, const char *buffer, uint8_t is_compressed)
constructor - internal use only – special version with a memory buffer to read from instead of an in...
Definition: OTF_RBuffer.c:254
struct_OTF_RBuffer::process
uint32_t process
Current process inside this stream, necessary for state machine, (-1) means unknown.
Definition: OTF_RBuffer.h:80
OTF_RBuffer_getFileProperties
int OTF_RBuffer_getFileProperties(OTF_RBuffer *rbuffer)
Determine buffers filesize, firstTime and lastTime if not already set.
Definition: OTF_RBuffer.c:993
OTF_RBuffer_open
OTF_RBuffer * OTF_RBuffer_open(const char *filename, OTF_FileManager *manager)
constructor - internal use only
Definition: OTF_RBuffer.c:191
struct_OTF_RBuffer::array
uint32_t * array
Array which hold the members of a DEFPROCESSGROUP record or the list of attributes of a DEFATTRLIST r...
Definition: OTF_RBuffer.h:69
OTF_RBuffer_readUint32
uint32_t OTF_RBuffer_readUint32(OTF_RBuffer *rbuffer)
Read an unsigned integer in hex format from buffer and return it.
Definition: OTF_RBuffer.c:879
OTF_File.h
Provides a low-level API for accessing files.
struct_OTF_RBuffer::end
uint32_t end
Current end of data in buffer in case it is not full.
Definition: OTF_RBuffer.h:55
struct_OTF_RBuffer
Definition: OTF_RBuffer.h:40
struct_OTF_RBuffer::buffer
char * buffer
actual buffer
Definition: OTF_RBuffer.h:47
struct_OTF_RBuffer::size
uint32_t size
Current size of buffer.
Definition: OTF_RBuffer.h:61
OTF_RBuffer_getCurrentProcess
uint32_t OTF_RBuffer_getCurrentProcess(OTF_RBuffer *rbuffer)
Return the current process of the buffer.
Definition: OTF_RBuffer.c:834
OTF_RBuffer_guaranteeRecord
int OTF_RBuffer_guaranteeRecord(OTF_RBuffer *rbuffer)
Ask the buffer to guarantee at least one complete record at the current read position inside the buff...
Definition: OTF_RBuffer.c:473
struct_OTF_RBuffer::filesize
uint64_t filesize
Total size of the file in bytes.
Definition: OTF_RBuffer.h:85
OTF_RBuffer_readArray
uint32_t OTF_RBuffer_readArray(OTF_RBuffer *rbuffer, uint32_t **array, uint32_t *size)
Read an array from buffer and return the number of elements.
Definition: OTF_RBuffer.c:1239
OTF_RBuffer_readBytes
uint32_t OTF_RBuffer_readBytes(OTF_RBuffer *rbuffer, uint8_t *array, uint32_t max_len)
Read a byte array in hex format from buffer and return the number of bytes read (=lenght of array)...
Definition: OTF_RBuffer.c:1319
OTF_RBuffer_testKeyword
int OTF_RBuffer_testKeyword(OTF_RBuffer *rbuffer, const char *string)
Test if the next string equals the given one (leading spaces are ignored).
Definition: OTF_RBuffer.c:927
OTF_RBuffer_close
int OTF_RBuffer_close(OTF_RBuffer *rbuffer)
destructor - internal use only
Definition: OTF_RBuffer.c:308
OTF_RBuffer_testChar
int OTF_RBuffer_testChar(OTF_RBuffer *rbuffer, char c)
Test if the next character equals the given one (leading spaces are ignored).
Definition: OTF_RBuffer.c:910
OTF_RBuffer_readUint64
uint64_t OTF_RBuffer_readUint64(OTF_RBuffer *rbuffer)
Read an 64bit unsigned integer in hex format from buffer and return it.
Definition: OTF_RBuffer.c:848
OTF_RBuffer_getRecord
char * OTF_RBuffer_getRecord(OTF_RBuffer *rbuffer)
Make the next record availabe from the buffer.
Definition: OTF_RBuffer.c:445
OTF_RBuffer_jump
int OTF_RBuffer_jump(OTF_RBuffer *rbuffer, uint64_t filepos)
Jump to the given file position and restore buffer and references as if the buffer had reached the po...
Definition: OTF_RBuffer.c:650
OTF_RBuffer_skipSpaces
void OTF_RBuffer_skipSpaces(OTF_RBuffer *rbuffer)
Advance the buffer position while there are spaces.
Definition: OTF_RBuffer.c:801
OTF_RBuffer_testPrefix
int OTF_RBuffer_testPrefix(OTF_RBuffer *rbuffer, const char *string)
Test if the next string equals the given one (leading spaces are ignored).
Definition: OTF_RBuffer.c:962
OTF_KeyValue.h
Provides an additional list of key value pairs that can be added to records.
OTF_RBuffer_getFilePos
uint64_t OTF_RBuffer_getFilePos(OTF_RBuffer *rbuffer)
Returns the fileposition of the file attached to this buffer.
Definition: OTF_RBuffer.c:1313
OTF_RBuffer_searchTime
int OTF_RBuffer_searchTime(OTF_RBuffer *rbuffer, uint64_t time)
Search the buffer for the given time and set the buffer position to the next record after that time...
Definition: OTF_RBuffer.c:1077
OTF_RBuffer_setCurrentProcess
void OTF_RBuffer_setCurrentProcess(OTF_RBuffer *rbuffer, uint32_t process)
Set the current process of the buffer to the given one.
Definition: OTF_RBuffer.c:841
OTF_RBuffer_setSize
int OTF_RBuffer_setSize(OTF_RBuffer *rbuffer, size_t size)
Set buffer size.
Definition: OTF_RBuffer.c:329
OTF_KeyValueList
struct OTF_KeyValueList_struct OTF_KeyValueList
Object type which holds a key-value list.
Definition: OTF_KeyValue.h:242
OTF_RBuffer_printRecord
char * OTF_RBuffer_printRecord(OTF_RBuffer *rbuffer)
Print the record at the current buffer position, i.e.
Definition: OTF_RBuffer.c:550
struct_OTF_FileManager
file handles management structure
Definition: OTF_FileManager.c:32
struct_OTF_RBuffer::jumpsize
uint32_t jumpsize
If 'OTF_RBuffer_jump()' is called only 'jumpsize' bytes are read into buffer.
Definition: OTF_RBuffer.h:65
OTF_RBuffer_readKeyValueList
uint32_t OTF_RBuffer_readKeyValueList(OTF_RBuffer *buffer)
Read a KeyValueList from the buffer.
Definition: OTF_RBuffer.c:1361
struct_OTF_RBuffer::pos
uint32_t pos
Current read position in buffer.
Definition: OTF_RBuffer.h:51
OTF_RBuffer_readNewline
int OTF_RBuffer_readNewline(OTF_RBuffer *rbuffer)
Read a newline such that the buffer pos is at the next record beginning.
Definition: OTF_RBuffer.c:777
OTF_inttypes.h
Deals with all data type related issues.
OTF_RBuffer_getFileSize
uint64_t OTF_RBuffer_getFileSize(OTF_RBuffer *rbuffer)
Returns the filesize of the file attached to this buffer.
Definition: OTF_RBuffer.c:1306
OTF_RBuffer_getCurrentTime
uint64_t OTF_RBuffer_getCurrentTime(OTF_RBuffer *rbuffer)
Return the current time of the buffer.
Definition: OTF_RBuffer.c:813