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