]>
Commit | Line | Data |
---|---|---|
88c5f205 DB |
1 | /* |
2 | * QEMU generic buffers | |
3 | * | |
4 | * Copyright (c) 2015 Red Hat, Inc. | |
5 | * | |
6 | * This library is free software; you can redistribute it and/or | |
7 | * modify it under the terms of the GNU Lesser General Public | |
8 | * License as published by the Free Software Foundation; either | |
61f3c91a | 9 | * version 2.1 of the License, or (at your option) any later version. |
88c5f205 DB |
10 | * |
11 | * This library is distributed in the hope that it will be useful, | |
12 | * but WITHOUT ANY WARRANTY; without even the implied warranty of | |
13 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | |
14 | * Lesser General Public License for more details. | |
15 | * | |
16 | * You should have received a copy of the GNU Lesser General Public | |
17 | * License along with this library; if not, see <http://www.gnu.org/licenses/>. | |
18 | * | |
19 | */ | |
20 | ||
2a6a4076 MA |
21 | #ifndef QEMU_BUFFER_H |
22 | #define QEMU_BUFFER_H | |
88c5f205 | 23 | |
88c5f205 DB |
24 | |
25 | typedef struct Buffer Buffer; | |
26 | ||
27 | /** | |
28 | * Buffer: | |
29 | * | |
30 | * The Buffer object provides a simple dynamically resizing | |
31 | * array, with separate tracking of capacity and usage. This | |
32 | * is typically useful when buffering I/O or processing data. | |
33 | */ | |
34 | ||
35 | struct Buffer { | |
810082d1 | 36 | char *name; |
88c5f205 DB |
37 | size_t capacity; |
38 | size_t offset; | |
f14c3d85 | 39 | uint64_t avg_size; |
88c5f205 DB |
40 | uint8_t *buffer; |
41 | }; | |
42 | ||
810082d1 GH |
43 | /** |
44 | * buffer_init: | |
45 | * @buffer: the buffer object | |
46 | * @name: buffer name | |
47 | * | |
48 | * Optionally attach a name to the buffer, to make it easier | |
49 | * to identify in debug traces. | |
50 | */ | |
51 | void buffer_init(Buffer *buffer, const char *name, ...) | |
9edc6313 | 52 | G_GNUC_PRINTF(2, 3); |
810082d1 | 53 | |
1ff36b5d GH |
54 | /** |
55 | * buffer_shrink: | |
56 | * @buffer: the buffer object | |
57 | * | |
58 | * Try to shrink the buffer. Checks current buffer capacity and size | |
59 | * and reduces capacity in case only a fraction of the buffer is | |
60 | * actually used. | |
61 | */ | |
62 | void buffer_shrink(Buffer *buffer); | |
63 | ||
88c5f205 DB |
64 | /** |
65 | * buffer_reserve: | |
66 | * @buffer: the buffer object | |
67 | * @len: the minimum required free space | |
68 | * | |
69 | * Ensure that the buffer has space allocated for at least | |
70 | * @len bytes. If the current buffer is too small, it will | |
71 | * be reallocated, possibly to a larger size than requested. | |
72 | */ | |
73 | void buffer_reserve(Buffer *buffer, size_t len); | |
74 | ||
75 | /** | |
76 | * buffer_reset: | |
77 | * @buffer: the buffer object | |
78 | * | |
79 | * Reset the length of the stored data to zero, but do | |
80 | * not free / reallocate the memory buffer | |
81 | */ | |
82 | void buffer_reset(Buffer *buffer); | |
83 | ||
84 | /** | |
85 | * buffer_free: | |
86 | * @buffer: the buffer object | |
87 | * | |
88 | * Reset the length of the stored data to zero and also | |
89 | * free the internal memory buffer | |
90 | */ | |
91 | void buffer_free(Buffer *buffer); | |
92 | ||
93 | /** | |
94 | * buffer_append: | |
95 | * @buffer: the buffer object | |
96 | * @data: the data block to append | |
97 | * @len: the length of @data in bytes | |
98 | * | |
99 | * Append the contents of @data to the end of the buffer. | |
100 | * The caller must ensure that the buffer has sufficient | |
101 | * free space for @len bytes, typically by calling the | |
102 | * buffer_reserve() method prior to appending. | |
103 | */ | |
104 | void buffer_append(Buffer *buffer, const void *data, size_t len); | |
105 | ||
106 | /** | |
107 | * buffer_advance: | |
108 | * @buffer: the buffer object | |
109 | * @len: the number of bytes to skip | |
110 | * | |
111 | * Remove @len bytes of data from the head of the buffer. | |
112 | * The internal buffer will not be reallocated, so will | |
113 | * have at least @len bytes of free space after this | |
114 | * call completes | |
115 | */ | |
116 | void buffer_advance(Buffer *buffer, size_t len); | |
117 | ||
118 | /** | |
119 | * buffer_end: | |
120 | * @buffer: the buffer object | |
121 | * | |
122 | * Get a pointer to the tail end of the internal buffer | |
123 | * The returned pointer is only valid until the next | |
124 | * call to buffer_reserve(). | |
125 | * | |
126 | * Returns: the tail of the buffer | |
127 | */ | |
128 | uint8_t *buffer_end(Buffer *buffer); | |
129 | ||
130 | /** | |
131 | * buffer_empty: | |
132 | * @buffer: the buffer object | |
133 | * | |
134 | * Determine if the buffer contains any current data | |
135 | * | |
136 | * Returns: true if the buffer holds data, false otherwise | |
137 | */ | |
138 | gboolean buffer_empty(Buffer *buffer); | |
139 | ||
4d1eb5fd GH |
140 | /** |
141 | * buffer_move_empty: | |
142 | * @to: destination buffer object | |
143 | * @from: source buffer object | |
144 | * | |
145 | * Moves buffer, without copying data. 'to' buffer must be empty. | |
146 | * 'from' buffer is empty and zero-sized on return. | |
147 | */ | |
148 | void buffer_move_empty(Buffer *to, Buffer *from); | |
149 | ||
830a9583 GH |
150 | /** |
151 | * buffer_move: | |
152 | * @to: destination buffer object | |
153 | * @from: source buffer object | |
154 | * | |
155 | * Moves buffer, copying data (unless 'to' buffer happens to be empty). | |
156 | * 'from' buffer is empty and zero-sized on return. | |
157 | */ | |
158 | void buffer_move(Buffer *to, Buffer *from); | |
159 | ||
2a6a4076 | 160 | #endif /* QEMU_BUFFER_H */ |