LXR qemu/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
  26typedef 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
  36struct 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 */
  52void 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 */
  63void 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 */
  74void 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 */
  83void 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 */
  92void 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 */
 105void 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 */
 117void 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 */
 129uint8_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 */
 139gboolean 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 */
 149void 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 */
 159void buffer_move(Buffer *to, Buffer *from);
 160
 161#endif /* QEMU_BUFFER_H */
 162