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 |
9 | * version 2 of the License, or (at your option) any later version. |
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 | |
21 | #ifndef QEMU_BUFFER_H |
22 | #define QEMU_BUFFER_H |
23 | |
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 { |
36 | char *name; |
37 | size_t capacity; |
38 | size_t offset; |
39 | uint64_t avg_size; |
40 | uint8_t *buffer; |
41 | }; |
42 | |
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, ...) |
52 | GCC_FMT_ATTR(2, 3); |
53 | |
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 | |
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 | |
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 | |
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 | |
160 | #endif /* QEMU_BUFFER_H */ |
161 | |