include/qemu/buffer.h

   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__ */