1 #ifndef MODULES_THIRD_PARTY_PORTAUDIO_PA_RINGBUFFER_H_ 2 #define MODULES_THIRD_PARTY_PORTAUDIO_PA_RINGBUFFER_H_ 3 /* 4 * $Id: pa_ringbuffer.h 1421 2009-11-18 16:09:05Z bjornroche $ 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 70 #if defined(__APPLE__) 71 #include <sys/types.h> 72 typedef int32_t PaRingBufferSize; 73 #elif defined(__GNUC__) 74 typedef long PaRingBufferSize; 75 #elif (_MSC_VER >= 1400) 76 typedef long PaRingBufferSize; 77 #elif defined(_MSC_VER) || defined(__BORLANDC__) 78 typedef long PaRingBufferSize; 79 #else 80 typedef long PaRingBufferSize; 81 #endif 82 83 #ifdef __cplusplus 84 extern "C" { 85 #endif /* __cplusplus */ 86 87 typedef struct PaUtilRingBuffer { 88 PaRingBufferSize bufferSize; /**< Number of elements in FIFO. Power of 2. Set 89 by PaUtil_InitRingBuffer. */ 90 PaRingBufferSize writeIndex; /**< Index of next writable element. Set by 91 PaUtil_AdvanceRingBufferWriteIndex. */ 92 PaRingBufferSize readIndex; /**< Index of next readable element. Set by 93 PaUtil_AdvanceRingBufferReadIndex. */ 94 PaRingBufferSize bigMask; /**< Used for wrapping indices with extra bit to 95 distinguish full/empty. */ 96 PaRingBufferSize smallMask; /**< Used for fitting indices to buffer. */ 97 PaRingBufferSize elementSizeBytes; /**< Number of bytes per element. */ 98 char* buffer; /**< Pointer to the buffer containing the actual data. */ 99 } PaUtilRingBuffer; 100 101 /** Initialize Ring Buffer. 102 103 @param rbuf The ring buffer. 104 105 @param elementSizeBytes The size of a single data element in bytes. 106 107 @param elementCount The number of elements in the buffer (must be power of 2). 108 109 @param dataPtr A pointer to a previously allocated area where the data 110 will be maintained. It must be elementCount*elementSizeBytes long. 111 112 @return -1 if elementCount is not a power of 2, otherwise 0. 113 */ 114 PaRingBufferSize PaUtil_InitializeRingBuffer(PaUtilRingBuffer* rbuf, 115 PaRingBufferSize elementSizeBytes, 116 PaRingBufferSize elementCount, 117 void* dataPtr); 118 119 /** Clear buffer. Should only be called when buffer is NOT being read. 120 121 @param rbuf The ring buffer. 122 */ 123 void PaUtil_FlushRingBuffer(PaUtilRingBuffer* rbuf); 124 125 /** Retrieve the number of elements available in the ring buffer for writing. 126 127 @param rbuf The ring buffer. 128 129 @return The number of elements available for writing. 130 */ 131 PaRingBufferSize PaUtil_GetRingBufferWriteAvailable(PaUtilRingBuffer* rbuf); 132 133 /** Retrieve the number of elements available in the ring buffer for reading. 134 135 @param rbuf The ring buffer. 136 137 @return The number of elements available for reading. 138 */ 139 PaRingBufferSize PaUtil_GetRingBufferReadAvailable(PaUtilRingBuffer* rbuf); 140 141 /** Write data to the ring buffer. 142 143 @param rbuf The ring buffer. 144 145 @param data The address of new data to write to the buffer. 146 147 @param elementCount The number of elements to be written. 148 149 @return The number of elements written. 150 */ 151 PaRingBufferSize PaUtil_WriteRingBuffer(PaUtilRingBuffer* rbuf, 152 const void* data, 153 PaRingBufferSize elementCount); 154 155 /** Read data from the ring buffer. 156 157 @param rbuf The ring buffer. 158 159 @param data The address where the data should be stored. 160 161 @param elementCount The number of elements to be read. 162 163 @return The number of elements read. 164 */ 165 PaRingBufferSize PaUtil_ReadRingBuffer(PaUtilRingBuffer* rbuf, 166 void* data, 167 PaRingBufferSize elementCount); 168 169 /** Get address of region(s) to which we can write data. 170 171 @param rbuf The ring buffer. 172 173 @param elementCount The number of elements desired. 174 175 @param dataPtr1 The address where the first (or only) region pointer will be 176 stored. 177 178 @param sizePtr1 The address where the first (or only) region length will be 179 stored. 180 181 @param dataPtr2 The address where the second region pointer will be stored if 182 the first region is too small to satisfy elementCount. 183 184 @param sizePtr2 The address where the second region length will be stored if 185 the first region is too small to satisfy elementCount. 186 187 @return The room available to be written or elementCount, whichever is smaller. 188 */ 189 PaRingBufferSize PaUtil_GetRingBufferWriteRegions(PaUtilRingBuffer* rbuf, 190 PaRingBufferSize elementCount, 191 void** dataPtr1, 192 PaRingBufferSize* sizePtr1, 193 void** dataPtr2, 194 PaRingBufferSize* sizePtr2); 195 196 /** Advance the write index to the next location to be written. 197 198 @param rbuf The ring buffer. 199 200 @param elementCount The number of elements to advance. 201 202 @return The new position. 203 */ 204 PaRingBufferSize PaUtil_AdvanceRingBufferWriteIndex( 205 PaUtilRingBuffer* rbuf, 206 PaRingBufferSize elementCount); 207 208 /** Get address of region(s) from which we can write data. 209 210 @param rbuf The ring buffer. 211 212 @param elementCount The number of elements desired. 213 214 @param dataPtr1 The address where the first (or only) region pointer will be 215 stored. 216 217 @param sizePtr1 The address where the first (or only) region length will be 218 stored. 219 220 @param dataPtr2 The address where the second region pointer will be stored if 221 the first region is too small to satisfy elementCount. 222 223 @param sizePtr2 The address where the second region length will be stored if 224 the first region is too small to satisfy elementCount. 225 226 @return The number of elements available for reading. 227 */ 228 PaRingBufferSize PaUtil_GetRingBufferReadRegions(PaUtilRingBuffer* rbuf, 229 PaRingBufferSize elementCount, 230 void** dataPtr1, 231 PaRingBufferSize* sizePtr1, 232 void** dataPtr2, 233 PaRingBufferSize* sizePtr2); 234 235 /** Advance the read index to the next location to be read. 236 237 @param rbuf The ring buffer. 238 239 @param elementCount The number of elements to advance. 240 241 @return The new position. 242 */ 243 PaRingBufferSize PaUtil_AdvanceRingBufferReadIndex( 244 PaUtilRingBuffer* rbuf, 245 PaRingBufferSize elementCount); 246 247 #ifdef __cplusplus 248 } 249 #endif /* __cplusplus */ 250 #endif /* MODULES_THIRD_PARTY_PORTAUDIO_PA_RINGBUFFER_H_ */ 251