OpenMPI  0.1.1
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 
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. */
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. */
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 */
242 
243 #ifdef __cplusplus
244 }
245 #endif /* __cplusplus */
246 
247 #endif /* OTF_RBUFFER_H */
248 
Definition: OTF_File.c:78
uint64_t time
Current time inside this stream, necessary for state machine, (-1) means unknown. ...
Definition: OTF_RBuffer.h:76
void OTF_RBuffer_setZBufferSize(OTF_RBuffer *rbuffer, uint32_t size)
Set zbuffer size.
Definition: OTF_RBuffer.c:372
uint32_t lastnewline
Last ' ' in the buffer.
Definition: OTF_RBuffer.h:58
uint32_t arraysize
Current size of array.
Definition: OTF_RBuffer.h:72
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
void OTF_RBuffer_skipKeyword(OTF_RBuffer *rbuffer)
Advance the buffer position while there are capital letters.
Definition: OTF_RBuffer.c:1293
uint64_t lastTime
The very last timestamp of that stream.
Definition: OTF_RBuffer.h:95
int OTF_RBuffer_setJumpSize(OTF_RBuffer *rbuffer, size_t size)
Set 'jumpsize'.
Definition: OTF_RBuffer.c:408
uint64_t firstTime
The very first timestamp of that stream.
Definition: OTF_RBuffer.h:90
const char * OTF_RBuffer_readString(OTF_RBuffer *rbuffer)
Read a string from buffer and return it.
Definition: OTF_RBuffer.c:1205
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
uint32_t process
Current process inside this stream, necessary for state machine, (-1) means unknown.
Definition: OTF_RBuffer.h:80
int OTF_RBuffer_getFileProperties(OTF_RBuffer *rbuffer)
Determine buffers filesize, firstTime and lastTime if not already set.
Definition: OTF_RBuffer.c:993
OTF_RBuffer * OTF_RBuffer_open(const char *filename, OTF_FileManager *manager)
constructor - internal use only
Definition: OTF_RBuffer.c:191
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
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
Provides a low-level API for accessing files.
uint32_t end
Current end of data in buffer in case it is not full.
Definition: OTF_RBuffer.h:55
Definition: OTF_RBuffer.h:40
char * buffer
actual buffer
Definition: OTF_RBuffer.h:47
uint32_t size
Current size of buffer.
Definition: OTF_RBuffer.h:61
uint32_t OTF_RBuffer_getCurrentProcess(OTF_RBuffer *rbuffer)
Return the current process of the buffer.
Definition: OTF_RBuffer.c:834
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
uint64_t filesize
Total size of the file in bytes.
Definition: OTF_RBuffer.h:85
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
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
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
int OTF_RBuffer_close(OTF_RBuffer *rbuffer)
destructor - internal use only
Definition: OTF_RBuffer.c:308
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
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
char * OTF_RBuffer_getRecord(OTF_RBuffer *rbuffer)
Make the next record availabe from the buffer.
Definition: OTF_RBuffer.c:445
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
void OTF_RBuffer_skipSpaces(OTF_RBuffer *rbuffer)
Advance the buffer position while there are spaces.
Definition: OTF_RBuffer.c:801
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
Provides an additional list of key value pairs that can be added to records.
uint64_t OTF_RBuffer_getFilePos(OTF_RBuffer *rbuffer)
Returns the fileposition of the file attached to this buffer.
Definition: OTF_RBuffer.c:1313
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
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
int OTF_RBuffer_setSize(OTF_RBuffer *rbuffer, size_t size)
Set buffer size.
Definition: OTF_RBuffer.c:329
struct OTF_KeyValueList_struct OTF_KeyValueList
Object type which holds a key-value list.
Definition: OTF_KeyValue.h:242
char * OTF_RBuffer_printRecord(OTF_RBuffer *rbuffer)
Print the record at the current buffer position, i.e.
Definition: OTF_RBuffer.c:550
file handles management structure
Definition: OTF_FileManager.c:32
uint32_t jumpsize
If 'OTF_RBuffer_jump()' is called only 'jumpsize' bytes are read into buffer.
Definition: OTF_RBuffer.h:65
uint32_t OTF_RBuffer_readKeyValueList(OTF_RBuffer *buffer)
Read a KeyValueList from the buffer.
Definition: OTF_RBuffer.c:1361
uint32_t pos
Current read position in buffer.
Definition: OTF_RBuffer.h:51
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
Deals with all data type related issues.
uint64_t OTF_RBuffer_getFileSize(OTF_RBuffer *rbuffer)
Returns the filesize of the file attached to this buffer.
Definition: OTF_RBuffer.c:1306
uint64_t OTF_RBuffer_getCurrentTime(OTF_RBuffer *rbuffer)
Return the current time of the buffer.
Definition: OTF_RBuffer.c:813