OpenMPI  0.1.1
OTF_WBuffer.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_WBuffer.h
8  *
9  * @brief Provides write access to trace buffers.
10  *
11  * \ingroup internal
12  */
13 
14 
15 #ifndef OTF_WBUFFER_H
16 #define OTF_WBUFFER_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 #include "OTF_Filenames.h"
28 
29 #include "OTF_KeyValue.h"
30 
31 
32 #ifdef __cplusplus
33 extern "C" {
34 #endif /* __cplusplus */
35 
37 
38 
39  OTF_File* file;
40 
41 
42  /** Begin of the actual buffer. */
43  char* buffer;
44 
45  /** Current size of buffer. */
46  uint32_t size;
47 
48  /** Next write position in buffer. */
49  uint32_t pos;
50 
51  /** Current process inside this file buffer, necessary for state
52  machine. This must not be part of OTF_WStream because there are
53  multiple buffers per stream that might be written in parallel. */
54  uint32_t process;
55 
56  /** Current time inside this file buffer, necessary for state machine.
57  This must not be part of OTF_WStream because there are multiple
58  buffers per stream that might be written in parallel. */
59  uint64_t time;
60 
61 #ifdef HAVE_ZLIB
62  /** Default size of zbuffers managed by this buffer. */
63  uint32_t zbuffersize;
64 #endif /* HAVE_ZLIB */
65 };
66 typedef struct struct_OTF_WBuffer OTF_WBuffer;
67 
68 
69 /** Constructor - internal use only */
70 OTF_WBuffer* OTF_WBuffer_open( const char* filename, OTF_FileManager* manager );
71 
72 /** Destructor - internal use only */
73 int OTF_WBuffer_close( OTF_WBuffer* wbuffer );
74 
75 /** Set the size of the buffer. Cannot shrink buffer but only extend. */
76 int OTF_WBuffer_setSize( OTF_WBuffer* wbuffer, size_t size );
77 
78 /** Set the size of the zbuffer. */
79 void OTF_WBuffer_setZBufferSize( OTF_WBuffer* wbuffer, uint32_t size );
80 
81 /** Writes the buffer contents to 'file' and marks the buffer empty again. */
82 int OTF_WBuffer_flush( OTF_WBuffer* wbuffer );
83 
84 /** Ask the buffer to guarantee at least 'space' bytes at current writing
85  position before the next flush is necessary. Return 1 on success. */
86 int OTF_WBuffer_guarantee( OTF_WBuffer* wbuffer, size_t space );
87 
88 
89 /** Set process state machine to 'p' and time stamp state machine to 't'.
90  If 'p' is the current process and 't' is the current time stamp nothing
91  is done. If the process has changed a process record will be written.
92  If the time has changed the new time stamp and the current process will
93  be written. If 't' is lower than the current time stamp
94  it is regarded as an error. Return != 1 on success and 0 on error. */
96  uint64_t t, uint32_t p );
97 
98 /* *** basic write operations *** */
99 
100 /** Append a key word to the write buffer. A key word is a string without
101  quotes. Buffer flush is done if necessary. Return the number of bytes
102  written. */
103 uint32_t OTF_WBuffer_writeKeyword( OTF_WBuffer* wbuffer, const char* keyword );
104 
105 /** Append a string to the write buffer. A string is surrounded by quotes.
106  Buffer flush is done if necessary. Return the number of bytes written. */
107 uint32_t OTF_WBuffer_writeString( OTF_WBuffer* wbuffer, const char* string );
108 
109 /** Append a char to the write buffer. Buffer flush is done if necessary.
110  Return the number of bytes written (=1). */
111 uint32_t OTF_WBuffer_writeChar( OTF_WBuffer* wbuffer, const char character );
112 
113 /** This function append an 8bit unsigned integer 'value' in hex format to
114  the write buffer. Buffer flush is done if necessary. The return value
115  is the number of written characters. */
116 uint32_t OTF_WBuffer_writeUint8( OTF_WBuffer* wbuffer, uint8_t value );
117 
118 /** This function append an 16bit unsigned integer 'value' in hex format to
119  the write buffer. Buffer flush is done if necessary. The return value
120  is the number of written characters. */
121 uint32_t OTF_WBuffer_writeUint16( OTF_WBuffer* wbuffer, uint16_t value );
122 
123 /** This function append an unsigned integer 'value' in hex format to
124  the write buffer. Buffer flush is done if necessary. The return value
125  is the number of written characters. */
126 uint32_t OTF_WBuffer_writeUint32( OTF_WBuffer* wbuffer, uint32_t value );
127 
128 /** This function append an 64bit unsigned integer 'value' in hex format to
129  the write buffer. Buffer flush is done if necessary. The return value
130  is the number of written characters. */
131 uint32_t OTF_WBuffer_writeUint64( OTF_WBuffer* wbuffer, uint64_t value );
132 
133 /** Append a newline character to the buffer. Buffer flush is done if
134  necessary. Return the number of bytes written. */
135 uint32_t OTF_WBuffer_writeNewline( OTF_WBuffer* wbuffer );
136 
137 /** This function append an byte array in hex format to
138  the write buffer. Buffer flush is done if necessary. The return value
139  is the number of written characters. */
140 uint32_t OTF_WBuffer_writeBytes( OTF_WBuffer* wbuffer, const uint8_t *value, uint32_t len);
141 
142 /** Append a KeyValuePair to the buffer (short format). Return the number of bytes written. */
144 
145 /** Append a KeyValuePair to the buffer (long format). Return the number of bytes written. */
147 
148 /** Append a KeyValueList to the buffer (short format). Return the number of bytes written. */
150 
151 /** Append a KeyValueList to the buffer (long format). Return the number of bytes written. */
153 
154 /** internal use */
155 OTF_WBuffer* OTF_WBuffer_open_zlevel( const char* filename,
156  OTF_FileManager* manager, OTF_FileCompression compression );
157 
158 #ifdef __cplusplus
159 }
160 #endif /* __cplusplus */
161 
162 #endif /* OTF_WBUFFER_H */
163 
uint32_t OTF_WBuffer_writeKeyValuePair_long(OTF_WBuffer *buffer, OTF_KeyValuePair *pair)
Append a KeyValuePair to the buffer (long format).
Definition: OTF_WBuffer.c:731
Definition: OTF_File.c:78
OTF_WBuffer * OTF_WBuffer_open(const char *filename, OTF_FileManager *manager)
Constructor - internal use only.
Definition: OTF_WBuffer.c:72
uint32_t OTF_WBuffer_writeKeyValueList_short(OTF_WBuffer *buffer, OTF_KeyValueList *list)
Append a KeyValueList to the buffer (short format).
Definition: OTF_WBuffer.c:809
uint32_t OTF_WBuffer_writeKeyValuePair_short(OTF_WBuffer *buffer, OTF_KeyValuePair *pair)
Append a KeyValuePair to the buffer (short format).
Definition: OTF_WBuffer.c:654
uint32_t pos
Next write position in buffer.
Definition: OTF_WBuffer.h:49
int OTF_WBuffer_setSize(OTF_WBuffer *wbuffer, size_t size)
Set the size of the buffer.
Definition: OTF_WBuffer.c:128
OTF_WBuffer * OTF_WBuffer_open_zlevel(const char *filename, OTF_FileManager *manager, OTF_FileCompression compression)
internal use
Definition: OTF_WBuffer.c:862
uint32_t OTF_WBuffer_writeBytes(OTF_WBuffer *wbuffer, const uint8_t *value, uint32_t len)
This function append an byte array in hex format to the write buffer.
Definition: OTF_WBuffer.c:616
uint32_t OTF_WBuffer_writeUint8(OTF_WBuffer *wbuffer, uint8_t value)
This function append an 8bit unsigned integer 'value' in hex format to the write buffer.
Definition: OTF_WBuffer.c:407
struct OTF_KeyValuePair_struct OTF_KeyValuePair
Object type which holds a key-value pair.
Definition: OTF_KeyValue.h:245
uint32_t OTF_WBuffer_writeUint64(OTF_WBuffer *wbuffer, uint64_t value)
This function append an 64bit unsigned integer 'value' in hex format to the write buffer...
Definition: OTF_WBuffer.c:550
uint32_t OTF_WBuffer_writeKeyValueList_long(OTF_WBuffer *buffer, OTF_KeyValueList *list)
Append a KeyValueList to the buffer (long format).
Definition: OTF_WBuffer.c:836
Provides a low-level API for accessing files.
uint32_t process
Current process inside this file buffer, necessary for state machine.
Definition: OTF_WBuffer.h:54
uint32_t OTF_WBuffer_writeKeyword(OTF_WBuffer *wbuffer, const char *keyword)
Append a key word to the write buffer.
Definition: OTF_WBuffer.c:313
uint32_t OTF_WBuffer_writeString(OTF_WBuffer *wbuffer, const char *string)
Append a string to the write buffer.
Definition: OTF_WBuffer.c:343
uint64_t time
Current time inside this file buffer, necessary for state machine.
Definition: OTF_WBuffer.h:59
uint32_t OTF_WBuffer_writeUint16(OTF_WBuffer *wbuffer, uint16_t value)
This function append an 16bit unsigned integer 'value' in hex format to the write buffer...
Definition: OTF_WBuffer.c:455
int OTF_WBuffer_guarantee(OTF_WBuffer *wbuffer, size_t space)
Ask the buffer to guarantee at least 'space' bytes at current writing position before the next flush ...
Definition: OTF_WBuffer.c:216
int OTF_WBuffer_flush(OTF_WBuffer *wbuffer)
Writes the buffer contents to 'file' and marks the buffer empty again.
Definition: OTF_WBuffer.c:194
int OTF_WBuffer_close(OTF_WBuffer *wbuffer)
Destructor - internal use only.
Definition: OTF_WBuffer.c:80
int OTF_WBuffer_setTimeAndProcess(OTF_WBuffer *wbuffer, uint64_t t, uint32_t p)
Set process state machine to 'p' and time stamp state machine to 't'.
Definition: OTF_WBuffer.c:249
Definition: OTF_WBuffer.h:36
Provides an additional list of key value pairs that can be added to records.
struct OTF_KeyValueList_struct OTF_KeyValueList
Object type which holds a key-value list.
Definition: OTF_KeyValue.h:242
uint32_t OTF_WBuffer_writeNewline(OTF_WBuffer *wbuffer)
Append a newline character to the buffer.
Definition: OTF_WBuffer.c:597
uint32_t OTF_WBuffer_writeUint32(OTF_WBuffer *wbuffer, uint32_t value)
This function append an unsigned integer 'value' in hex format to the write buffer.
Definition: OTF_WBuffer.c:503
file handles management structure
Definition: OTF_FileManager.c:32
Handles file naming issues.
Deals with all data type related issues.
uint32_t OTF_WBuffer_writeChar(OTF_WBuffer *wbuffer, const char character)
Append a char to the write buffer.
Definition: OTF_WBuffer.c:386
void OTF_WBuffer_setZBufferSize(OTF_WBuffer *wbuffer, uint32_t size)
Set the size of the zbuffer.
Definition: OTF_WBuffer.c:158
uint32_t size
Current size of buffer.
Definition: OTF_WBuffer.h:46
char * buffer
Begin of the actual buffer.
Definition: OTF_WBuffer.h:43