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 #include "qemu-common.h" 25 26 typedef struct Buffer Buffer; 27 28 /** 29 * Buffer: 30 * 31 * The Buffer object provides a simple dynamically resizing 32 * array, with separate tracking of capacity and usage. This 33 * is typically useful when buffering I/O or processing data. 34 */ 35 36 struct Buffer { 37 char *name; 38 size_t capacity; 39 size_t offset; 40 uint64_t avg_size; 41 uint8_t *buffer; 42 }; 43 44 /** 45 * buffer_init: 46 * @buffer: the buffer object 47 * @name: buffer name 48 * 49 * Optionally attach a name to the buffer, to make it easier 50 * to identify in debug traces. 51 */ 52 void buffer_init(Buffer *buffer, const char *name, ...) 53 GCC_FMT_ATTR(2, 3); 54 55 /** 56 * buffer_shrink: 57 * @buffer: the buffer object 58 * 59 * Try to shrink the buffer. Checks current buffer capacity and size 60 * and reduces capacity in case only a fraction of the buffer is 61 * actually used. 62 */ 63 void buffer_shrink(Buffer *buffer); 64 65 /** 66 * buffer_reserve: 67 * @buffer: the buffer object 68 * @len: the minimum required free space 69 * 70 * Ensure that the buffer has space allocated for at least 71 * @len bytes. If the current buffer is too small, it will 72 * be reallocated, possibly to a larger size than requested. 73 */ 74 void buffer_reserve(Buffer *buffer, size_t len); 75 76 /** 77 * buffer_reset: 78 * @buffer: the buffer object 79 * 80 * Reset the length of the stored data to zero, but do 81 * not free / reallocate the memory buffer 82 */ 83 void buffer_reset(Buffer *buffer); 84 85 /** 86 * buffer_free: 87 * @buffer: the buffer object 88 * 89 * Reset the length of the stored data to zero and also 90 * free the internal memory buffer 91 */ 92 void buffer_free(Buffer *buffer); 93 94 /** 95 * buffer_append: 96 * @buffer: the buffer object 97 * @data: the data block to append 98 * @len: the length of @data in bytes 99 * 100 * Append the contents of @data to the end of the buffer. 101 * The caller must ensure that the buffer has sufficient 102 * free space for @len bytes, typically by calling the 103 * buffer_reserve() method prior to appending. 104 */ 105 void buffer_append(Buffer *buffer, const void *data, size_t len); 106 107 /** 108 * buffer_advance: 109 * @buffer: the buffer object 110 * @len: the number of bytes to skip 111 * 112 * Remove @len bytes of data from the head of the buffer. 113 * The internal buffer will not be reallocated, so will 114 * have at least @len bytes of free space after this 115 * call completes 116 */ 117 void buffer_advance(Buffer *buffer, size_t len); 118 119 /** 120 * buffer_end: 121 * @buffer: the buffer object 122 * 123 * Get a pointer to the tail end of the internal buffer 124 * The returned pointer is only valid until the next 125 * call to buffer_reserve(). 126 * 127 * Returns: the tail of the buffer 128 */ 129 uint8_t *buffer_end(Buffer *buffer); 130 131 /** 132 * buffer_empty: 133 * @buffer: the buffer object 134 * 135 * Determine if the buffer contains any current data 136 * 137 * Returns: true if the buffer holds data, false otherwise 138 */ 139 gboolean buffer_empty(Buffer *buffer); 140 141 /** 142 * buffer_move_empty: 143 * @to: destination buffer object 144 * @from: source buffer object 145 * 146 * Moves buffer, without copying data. 'to' buffer must be empty. 147 * 'from' buffer is empty and zero-sized on return. 148 */ 149 void buffer_move_empty(Buffer *to, Buffer *from); 150 151 /** 152 * buffer_move: 153 * @to: destination buffer object 154 * @from: source buffer object 155 * 156 * Moves buffer, copying data (unless 'to' buffer happens to be empty). 157 * 'from' buffer is empty and zero-sized on return. 158 */ 159 void buffer_move(Buffer *to, Buffer *from); 160 161 #endif /* QEMU_BUFFER_H__ */ 162