jDttSP/ringb.h

   1 /*
   2   Memory-mapped ringbuffer
   3   Derived from jack/ringbuffer.h
   4
   5     This program is free software; you can redistribute it and/or modify
   6     it under the terms of the GNU Lesser General Public License as published by
   7     the Free Software Foundation; either version 2.1 of the License, or
   8     (at your option) any later version.
   9
  10     This program is distributed in the hope that it will be useful,
  11     but WITHOUT ANY WARRANTY; without even the implied warranty of
  12     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13     GNU Lesser General Public License for more details.
  14
  15     You should have received a copy of the GNU Lesser General Public License
  16     along with this program; if not, write to the Free Software
  17     Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
  18
  19     Original
  20     Copyright (C) 2000 Paul Davis
  21     Copyright (C) 2003 Rohan Drape
  22
  23     Derived
  24     Copyright (C) 2004 by Frank Brickle, AB2KT and Bob McGwier, N4HY
  25 */
  26
  27 #ifndef _ringb_h
  28 #define _ringb_h
  29
  30 #include <sys/types.h>
  31
  32 typedef struct {
  33   char *buf;
  34   size_t len;
  35 } ringb_data_t;
  36
  37 typedef struct {
  38   char *buf;
  39   size_t wptr,
  40          rptr,
  41          size,
  42          mask;
  43 } ringb_t;
  44
  45 /* Sets up a ringbuffer data structure of a specified size
  46  * in pre-allocated memory.
  47  * sz is requested ringbuffer size in bytes,
  48  * MUST be a power of 2.
  49  * pre-allocated memory must be large enough to
  50  * accommodate (ringb header + stipulated memory size).
  51  * return a pointer to a new ringb_t, if successful,
  52  * 0 otherwise. */
  53
  54 extern ringb_t *ringb_create(char *usemem, size_t sz2);
  55
  56 /*
  57  * There is no corresponding 'free' function
  58  * since memory is all pre-allocated
  59  */
  60
  61 //void ringb_free(ringb_t *rb);
  62
  63 /* Fill a data structure with a description of the current readable
  64  * data held in the ringbuffer.  This description is returned in a two
  65  * element array of ringb_data_t.  Two elements are needed
  66  * because the data to be read may be split across the end of the
  67  * ringbuffer.
  68  *
  69  * The first element will always contain a valid len field, which
  70  * may be zero or greater.  If the len field is non-zero, then data
  71  * can be read in a contiguous fashion using the address given in the
  72  * corresponding @a buf field.
  73  *
  74  * If the second element has a non-zero len field, then a second
  75  * contiguous stretch of data can be read from the address given in
  76  * its corresponding buf field.
  77  *
  78  * rb a pointer to the ringbuffer structure.
  79  * vec a pointer to a 2 element array of ringb_data_t. */
  80
  81 extern void ringb_get_read_vector(const ringb_t *rb, ringb_data_t *vec);
  82
  83 /* Fill a data structure with a description of the current writable
  84  * space in the ringbuffer.  The description is returned in a two
  85  * element array of ringb_data_t.  Two elements are needed
  86  * because the space available for writing may be split across the end
  87  * of the ringbuffer.
  88  * The first element will always contain a valid len field, which
  89  * may be zero or greater.  If the @a len field is non-zero, then data
  90  * can be written in a contiguous fashion using the address given in
  91  * the corresponding buf field.
  92  * If the second element has a non-zero len field, then a second
  93  * contiguous stretch of data can be written to the address given in
  94  * the corresponding buf field.
  95  * rb a pointer to the ringbuffer structure.
  96  * vec a pointer to a 2 element array of ringb_data_t. */
  97
  98 extern void ringb_get_write_vector(const ringb_t *rb, ringb_data_t *vec);
  99
 100 /*
 101  * Read data from the ringbuffer.
 102  * rb a pointer to the ringbuffer structure.
 103  * dest a pointer to a buffer where data read from the
 104  * ringbuffer will go.
 105  * cnt the number of bytes to read.
 106  *
 107  * return the number of bytes read, which may range from 0 to cnt. */
 108
 109 extern size_t ringb_read(ringb_t *rb, char *dest, size_t cnt);
 110
 111 /* Read data from the ringbuffer. Opposed to ringb_read()
 112  * this function does not move the read pointer. Thus it's
 113  * a convenient way to inspect data in the ringbuffer in a
 114  * continous fashion. The price is that the data is copied
 115  * into a user provided buffer. For "raw" non-copy inspection
 116  * of the data in the ringbuffer use ringb_get_read_vector().
 117  * rb a pointer to the ringbuffer structure.
 118  * dest a pointer to a buffer where data read from the
 119  *   ringbuffer will go.
 120  * cnt the number of bytes to read.
 121  * return the number of bytes read, which may range from 0 to cnt.
 122  */
 123
 124 extern size_t ringb_peek(ringb_t *rb, char *dest, size_t cnt);
 125
 126 /* Advance the read pointer.
 127  * After data have been read from the ringbuffer using the pointers
 128  * returned by ringb_get_read_vector(), use this function to
 129  * advance the buffer pointers, making that space available for future
 130  * write operations.
 131  *
 132  * rb a pointer to the ringbuffer structure.
 133  * cnt the number of bytes read. */
 134
 135 extern void ringb_read_advance(ringb_t *rb, size_t cnt);
 136
 137 /* Return the number of bytes available for reading.
 138  * rb a pointer to the ringbuffer structure.
 139  * return the number of bytes available to read. */
 140
 141 extern size_t ringb_read_space(const ringb_t *rb);
 142
 143 /* Reset the read and write pointers, making an empty buffer.
 144  * This is not thread safe. */
 145
 146 extern void ringb_reset(ringb_t *rb);
 147
 148 /* Write data into the ringbuffer.
 149  * rb a pointer to the ringbuffer structure.
 150  * src a pointer to the data to be written to the ringbuffer.
 151  * cnt the number of bytes to write.
 152  * return the number of bytes write, which may range from 0 to cnt */
 153
 154 extern size_t ringb_write(ringb_t *rb, const char *src, size_t cnt);
 155
 156 /* Advance the write pointer.
 157  * After data have been written the ringbuffer using the pointers
 158  * returned by ringb_get_write_vector(), use this function
 159  * to advance the buffer pointer, making the data available for future
 160  * read operations.
 161  * rb a pointer to the ringbuffer structure.
 162  * cnt the number of bytes written. */
 163
 164 extern void ringb_write_advance(ringb_t *rb, size_t cnt);
 165
 166 /* Return the number of bytes available for writing.
 167  * rb a pointer to the ringbuffer structure.
 168  * return the amount of free space (in bytes) available for writing. */
 169
 170 extern size_t ringb_write_space(const ringb_t *rb);
 171
 172 #endif