| 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.1 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 | G_GNUC_PRINTF(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 */ |