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