jack/ringbuffer.h

   1 /*
   2     Copyright (C) 2000 Paul Davis
   3     Copyright (C) 2003 Rohan Drape
   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 */
  20
  21 #ifndef _RINGBUFFER_H
  22 #define _RINGBUFFER_H
  23
  24 #ifdef __cplusplus
  25 extern "C" {
  26 #endif
  27
  28 #include <sys/types.h>
  29
  30 /** @file ringbuffer.h
  31  *
  32  * A set of library functions to make lock-free ringbuffers available
  33  * to JACK clients.  The `capture_client.c' (in the example_clients
  34  * directory) is a fully functioning user of this API.
  35  *
  36  * The key attribute of a ringbuffer is that it can be safely accessed
  37  * by two threads simultaneously -- one reading from the buffer and
  38  * the other writing to it -- without using any synchronization or
  39  * mutual exclusion primitives.  For this to work correctly, there can
  40  * only be a single reader and a single writer thread.  Their
  41  * identities cannot be interchanged.
  42  */
  43
  44 typedef struct
  45 {
  46   char  *buf;
  47   size_t len;
  48 }
  49 jack_ringbuffer_data_t ;
  50
  51 typedef struct
  52 {
  53   char           *buf;
  54   volatile size_t write_ptr;
  55   volatile size_t read_ptr;
  56   size_t          size;
  57   size_t          size_mask;
  58   int             mlocked;
  59 }
  60 jack_ringbuffer_t ;
  61
  62 /**
  63  * Allocates a ringbuffer data structure of a specified size. The
  64  * caller must arrange for a call to jack_ringbuffer_free() to release
  65  * the memory associated with the ringbuffer.
  66  *
  67  * @param sz the ringbuffer size in bytes.
  68  *
  69  * @return a pointer to a new jack_ringbuffer_t, if successful; NULL
  70  * otherwise.
  71  */
  72 jack_ringbuffer_t *jack_ringbuffer_create(size_t sz);
  73
  74 /**
  75  * Frees the ringbuffer data structure allocated by an earlier call to
  76  * jack_ringbuffer_create().
  77  *
  78  * @param rb a pointer to the ringbuffer structure.
  79  */
  80 void jack_ringbuffer_free(jack_ringbuffer_t *rb);
  81
  82 /**
  83  * Fill a data structure with a description of the current readable
  84  * data held in the ringbuffer.  This description is returned in a two
  85  * element array of jack_ringbuffer_data_t.  Two elements are needed
  86  * because the data to be read may be split across the end of the
  87  * ringbuffer.
  88  *
  89  * The first element will always contain a valid @a len field, which
  90  * may be zero or greater.  If the @a len field is non-zero, then data
  91  * can be read in a contiguous fashion using the address given in the
  92  * corresponding @a buf field.
  93  *
  94  * If the second element has a non-zero @a len field, then a second
  95  * contiguous stretch of data can be read from the address given in
  96  * its corresponding @a buf field.
  97  *
  98  * @param rb a pointer to the ringbuffer structure.
  99  * @param vec a pointer to a 2 element array of jack_ringbuffer_data_t.
 100  *
 101  */
 102 void jack_ringbuffer_get_read_vector(const jack_ringbuffer_t *rb,
 103                                      jack_ringbuffer_data_t *vec);
 104
 105 /**
 106  * Fill a data structure with a description of the current writable
 107  * space in the ringbuffer.  The description is returned in a two
 108  * element array of jack_ringbuffer_data_t.  Two elements are needed
 109  * because the space available for writing may be split across the end
 110  * of the ringbuffer.
 111  *
 112  * The first element will always contain a valid @a len field, which
 113  * may be zero or greater.  If the @a len field is non-zero, then data
 114  * can be written in a contiguous fashion using the address given in
 115  * the corresponding @a buf field.
 116  *
 117  * If the second element has a non-zero @a len field, then a second
 118  * contiguous stretch of data can be written to the address given in
 119  * the corresponding @a buf field.
 120  *
 121  * @param rb a pointer to the ringbuffer structure.
 122  * @param vec a pointer to a 2 element array of jack_ringbuffer_data_t.
 123  */
 124 void jack_ringbuffer_get_write_vector(const jack_ringbuffer_t *rb,
 125                                       jack_ringbuffer_data_t *vec);
 126
 127 /**
 128  * Read data from the ringbuffer.
 129  *
 130  * @param rb a pointer to the ringbuffer structure.
 131  * @param dest a pointer to a buffer where data read from the
 132  * ringbuffer will go.
 133  * @param cnt the number of bytes to read.
 134  *
 135  * @return the number of bytes read, which may range from 0 to cnt.
 136  */
 137 size_t jack_ringbuffer_read(jack_ringbuffer_t *rb, char *dest, size_t cnt);
 138
 139 /**
 140  * Read data from the ringbuffer. Opposed to jack_ringbuffer_read()
 141  * this function does not move the read pointer. Thus it's
 142  * a convenient way to inspect data in the ringbuffer in a
 143  * continous fashion. The price is that the data is copied
 144  * into a user provided buffer. For "raw" non-copy inspection
 145  * of the data in the ringbuffer use jack_ringbuffer_get_read_vector().
 146  *
 147  * @param rb a pointer to the ringbuffer structure.
 148  * @param dest a pointer to a buffer where data read from the
 149  * ringbuffer will go.
 150  * @param cnt the number of bytes to read.
 151  *
 152  * @return the number of bytes read, which may range from 0 to cnt.
 153  */
 154 size_t jack_ringbuffer_peek(jack_ringbuffer_t *rb, char *dest, size_t cnt);
 155
 156 /**
 157  * Advance the read pointer.
 158  *
 159  * After data have been read from the ringbuffer using the pointers
 160  * returned by jack_ringbuffer_get_read_vector(), use this function to
 161  * advance the buffer pointers, making that space available for future
 162  * write operations.
 163  *
 164  * @param rb a pointer to the ringbuffer structure.
 165  * @param cnt the number of bytes read.
 166  */
 167 void jack_ringbuffer_read_advance(jack_ringbuffer_t *rb, size_t cnt);
 168
 169 /**
 170  * Return the number of bytes available for reading.
 171  *
 172  * @param rb a pointer to the ringbuffer structure.
 173  *
 174  * @return the number of bytes available to read.
 175  */
 176 size_t jack_ringbuffer_read_space(const jack_ringbuffer_t *rb);
 177
 178 /**
 179  * Lock a ringbuffer data block into memory.
 180  *
 181  * Uses the mlock() system call.  This is not a realtime operation.
 182  *
 183  * @param rb a pointer to the ringbuffer structure.
 184  */
 185 int jack_ringbuffer_mlock(jack_ringbuffer_t *rb);
 186
 187 /**
 188  * Reset the read and write pointers, making an empty buffer.
 189  *
 190  * This is not thread safe.
 191  *
 192  * @param rb a pointer to the ringbuffer structure.
 193  */
 194 void jack_ringbuffer_reset(jack_ringbuffer_t *rb);
 195
 196 /**
 197  * Write data into the ringbuffer.
 198  *
 199  * @param rb a pointer to the ringbuffer structure.
 200  * @param src a pointer to the data to be written to the ringbuffer.
 201  * @param cnt the number of bytes to write.
 202  *
 203  * @return the number of bytes write, which may range from 0 to cnt
 204  */
 205 size_t jack_ringbuffer_write(jack_ringbuffer_t *rb, const char *src,
 206                              size_t cnt);
 207
 208 /**
 209  * Advance the write pointer.
 210  *
 211  * After data have been written the ringbuffer using the pointers
 212  * returned by jack_ringbuffer_get_write_vector(), use this function
 213  * to advance the buffer pointer, making the data available for future
 214  * read operations.
 215  *
 216  * @param rb a pointer to the ringbuffer structure.
 217  * @param cnt the number of bytes written.
 218  */
 219 void jack_ringbuffer_write_advance(jack_ringbuffer_t *rb, size_t cnt);
 220
 221 /**
 222  * Return the number of bytes available for writing.
 223  *
 224  * @param rb a pointer to the ringbuffer structure.
 225  *
 226  * @return the amount of free space (in bytes) available for writing.
 227  */
 228 size_t jack_ringbuffer_write_space(const jack_ringbuffer_t *rb);
 229
 230
 231 #ifdef __cplusplus
 232 }
 233 #endif
 234
 235 #endif