1 #ifndef MODULES_THIRD_PARTY_PORTAUDIO_PA_RINGBUFFER_H_ 2 #define MODULES_THIRD_PARTY_PORTAUDIO_PA_RINGBUFFER_H_ 3 /* 4 * $Id$ 5 * Portable Audio I/O Library 6 * Ring Buffer utility. 7 * 8 * Author: Phil Burk, http://www.softsynth.com 9 * modified for SMP safety on OS X by Bjorn Roche. 10 * also allowed for const where possible. 11 * modified for multiple-byte-sized data elements by Sven Fischer 12 * 13 * Note that this is safe only for a single-thread reader 14 * and a single-thread writer. 15 * 16 * This program is distributed with the PortAudio Portable Audio Library. 17 * For more information see: http://www.portaudio.com 18 * Copyright (c) 1999-2000 Ross Bencina and Phil Burk 19 * 20 * Permission is hereby granted, free of charge, to any person obtaining 21 * a copy of this software and associated documentation files 22 * (the "Software"), to deal in the Software without restriction, 23 * including without limitation the rights to use, copy, modify, merge, 24 * publish, distribute, sublicense, and/or sell copies of the Software, 25 * and to permit persons to whom the Software is furnished to do so, 26 * subject to the following conditions: 27 * 28 * The above copyright notice and this permission notice shall be 29 * included in all copies or substantial portions of the Software. 30 * 31 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, 32 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 33 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. 34 * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR 35 * ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF 36 * CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION 37 * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. 38 */ 39 40 /* 41 * The text above constitutes the entire PortAudio license; however, 42 * the PortAudio community also makes the following non-binding requests: 43 * 44 * Any person wishing to distribute modifications to the Software is 45 * requested to send the modifications to the original developer so that 46 * they can be incorporated into the canonical version. It is also 47 * requested that these non-binding requests be included along with the 48 * license above. 49 */ 50 51 /** @file 52 @ingroup common_src 53 @brief Single-reader single-writer lock-free ring buffer 54 55 PaUtilRingBuffer is a ring buffer used to transport samples between 56 different execution contexts (threads, OS callbacks, interrupt handlers) 57 without requiring the use of any locks. This only works when there is 58 a single reader and a single writer (ie. one thread or callback writes 59 to the ring buffer, another thread or callback reads from it). 60 61 The PaUtilRingBuffer structure manages a ring buffer containing N 62 elements, where N must be a power of two. An element may be any size 63 (specified in bytes). 64 65 The memory area used to store the buffer elements must be allocated by 66 the client prior to calling PaUtil_InitializeRingBuffer() and must outlive 67 the use of the ring buffer. 68 69 @note The ring buffer functions are not normally exposed in the PortAudio 70 libraries. If you want to call them then you will need to add pa_ringbuffer.c 71 to your application source code. 72 */ 73 74 #if defined(__APPLE__) 75 #include <sys/types.h> 76 typedef int32_t ring_buffer_size_t; 77 #elif defined(__GNUC__) 78 typedef long ring_buffer_size_t; 79 #elif (_MSC_VER >= 1400) 80 typedef long ring_buffer_size_t; 81 #elif defined(_MSC_VER) || defined(__BORLANDC__) 82 typedef long ring_buffer_size_t; 83 #else 84 typedef long ring_buffer_size_t; 85 #endif 86 87 #ifdef __cplusplus 88 extern "C" { 89 #endif /* __cplusplus */ 90 91 typedef struct PaUtilRingBuffer { 92 ring_buffer_size_t bufferSize; /**< Number of elements in FIFO. Power of 2. 93 Set by PaUtil_InitRingBuffer. */ 94 volatile ring_buffer_size_t 95 writeIndex; /**< Index of next writable element. Set by 96 PaUtil_AdvanceRingBufferWriteIndex. */ 97 volatile ring_buffer_size_t 98 readIndex; /**< Index of next readable element. Set by 99 PaUtil_AdvanceRingBufferReadIndex. */ 100 ring_buffer_size_t bigMask; /**< Used for wrapping indices with extra bit to 101 distinguish full/empty. */ 102 ring_buffer_size_t smallMask; /**< Used for fitting indices to buffer. */ 103 ring_buffer_size_t elementSizeBytes; /**< Number of bytes per element. */ 104 char* buffer; /**< Pointer to the buffer containing the actual data. */ 105 } PaUtilRingBuffer; 106 107 /** Initialize Ring Buffer to empty state ready to have elements written to it. 108 109 @param rbuf The ring buffer. 110 111 @param elementSizeBytes The size of a single data element in bytes. 112 113 @param elementCount The number of elements in the buffer (must be a power of 114 2). 115 116 @param dataPtr A pointer to a previously allocated area where the data 117 will be maintained. It must be elementCount*elementSizeBytes long. 118 119 @return -1 if elementCount is not a power of 2, otherwise 0. 120 */ 121 ring_buffer_size_t PaUtil_InitializeRingBuffer( 122 PaUtilRingBuffer* rbuf, 123 ring_buffer_size_t elementSizeBytes, 124 ring_buffer_size_t elementCount, 125 void* dataPtr); 126 127 /** Reset buffer to empty. Should only be called when buffer is NOT being read 128 or written. 129 130 @param rbuf The ring buffer. 131 */ 132 void PaUtil_FlushRingBuffer(PaUtilRingBuffer* rbuf); 133 134 /** Retrieve the number of elements available in the ring buffer for writing. 135 136 @param rbuf The ring buffer. 137 138 @return The number of elements available for writing. 139 */ 140 ring_buffer_size_t PaUtil_GetRingBufferWriteAvailable( 141 const PaUtilRingBuffer* rbuf); 142 143 /** Retrieve the number of elements available in the ring buffer for reading. 144 145 @param rbuf The ring buffer. 146 147 @return The number of elements available for reading. 148 */ 149 ring_buffer_size_t PaUtil_GetRingBufferReadAvailable( 150 const PaUtilRingBuffer* rbuf); 151 152 /** Write data to the ring buffer. 153 154 @param rbuf The ring buffer. 155 156 @param data The address of new data to write to the buffer. 157 158 @param elementCount The number of elements to be written. 159 160 @return The number of elements written. 161 */ 162 ring_buffer_size_t PaUtil_WriteRingBuffer(PaUtilRingBuffer* rbuf, 163 const void* data, 164 ring_buffer_size_t elementCount); 165 166 /** Read data from the ring buffer. 167 168 @param rbuf The ring buffer. 169 170 @param data The address where the data should be stored. 171 172 @param elementCount The number of elements to be read. 173 174 @return The number of elements read. 175 */ 176 ring_buffer_size_t PaUtil_ReadRingBuffer(PaUtilRingBuffer* rbuf, 177 void* data, 178 ring_buffer_size_t elementCount); 179 180 /** Get address of region(s) to which we can write data. 181 182 @param rbuf The ring buffer. 183 184 @param elementCount The number of elements desired. 185 186 @param dataPtr1 The address where the first (or only) region pointer will be 187 stored. 188 189 @param sizePtr1 The address where the first (or only) region length will be 190 stored. 191 192 @param dataPtr2 The address where the second region pointer will be stored if 193 the first region is too small to satisfy elementCount. 194 195 @param sizePtr2 The address where the second region length will be stored if 196 the first region is too small to satisfy elementCount. 197 198 @return The room available to be written or elementCount, whichever is smaller. 199 */ 200 ring_buffer_size_t PaUtil_GetRingBufferWriteRegions( 201 PaUtilRingBuffer* rbuf, 202 ring_buffer_size_t elementCount, 203 void** dataPtr1, 204 ring_buffer_size_t* sizePtr1, 205 void** dataPtr2, 206 ring_buffer_size_t* sizePtr2); 207 208 /** Advance the write index to the next location to be written. 209 210 @param rbuf The ring buffer. 211 212 @param elementCount The number of elements to advance. 213 214 @return The new position. 215 */ 216 ring_buffer_size_t PaUtil_AdvanceRingBufferWriteIndex( 217 PaUtilRingBuffer* rbuf, 218 ring_buffer_size_t elementCount); 219 220 /** Get address of region(s) from which we can read data. 221 222 @param rbuf The ring buffer. 223 224 @param elementCount The number of elements desired. 225 226 @param dataPtr1 The address where the first (or only) region pointer will be 227 stored. 228 229 @param sizePtr1 The address where the first (or only) region length will be 230 stored. 231 232 @param dataPtr2 The address where the second region pointer will be stored if 233 the first region is too small to satisfy elementCount. 234 235 @param sizePtr2 The address where the second region length will be stored if 236 the first region is too small to satisfy elementCount. 237 238 @return The number of elements available for reading. 239 */ 240 ring_buffer_size_t PaUtil_GetRingBufferReadRegions( 241 PaUtilRingBuffer* rbuf, 242 ring_buffer_size_t elementCount, 243 void** dataPtr1, 244 ring_buffer_size_t* sizePtr1, 245 void** dataPtr2, 246 ring_buffer_size_t* sizePtr2); 247 248 /** Advance the read index to the next location to be read. 249 250 @param rbuf The ring buffer. 251 252 @param elementCount The number of elements to advance. 253 254 @return The new position. 255 */ 256 ring_buffer_size_t PaUtil_AdvanceRingBufferReadIndex( 257 PaUtilRingBuffer* rbuf, 258 ring_buffer_size_t elementCount); 259 260 #ifdef __cplusplus 261 } 262 #endif /* __cplusplus */ 263 #endif /* MODULES_THIRD_PARTY_PORTAUDIO_PA_RINGBUFFER_H_ */ 264