1#ifndef WEBRTC_AUDIO_DEVICE_PA_RINGBUFFER_H
2#define WEBRTC_AUDIO_DEVICE_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>
72typedef int32_t PaRingBufferSize;
73#elif defined( __GNUC__ )
74typedef long PaRingBufferSize;
75#elif (_MSC_VER >= 1400)
76typedef long PaRingBufferSize;
77#elif defined(_MSC_VER) || defined(__BORLANDC__)
78typedef long PaRingBufferSize;
79#else
80typedef long PaRingBufferSize;
81#endif
82
83
84
85#ifdef __cplusplus
86extern "C"
87{
88#endif /* __cplusplus */
89
90typedef struct PaUtilRingBuffer
91{
92    PaRingBufferSize  bufferSize; /**< Number of elements in FIFO. Power of 2. Set by PaUtil_InitRingBuffer. */
93    PaRingBufferSize  writeIndex; /**< Index of next writable element. Set by PaUtil_AdvanceRingBufferWriteIndex. */
94    PaRingBufferSize  readIndex;  /**< Index of next readable element. Set by PaUtil_AdvanceRingBufferReadIndex. */
95    PaRingBufferSize  bigMask;    /**< Used for wrapping indices with extra bit to 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*/
114PaRingBufferSize PaUtil_InitializeRingBuffer( PaUtilRingBuffer *rbuf, PaRingBufferSize elementSizeBytes, PaRingBufferSize elementCount, void *dataPtr );
115
116/** Clear buffer. Should only be called when buffer is NOT being read.
117
118 @param rbuf The ring buffer.
119*/
120void PaUtil_FlushRingBuffer( PaUtilRingBuffer *rbuf );
121
122/** Retrieve the number of elements available in the ring buffer for writing.
123
124 @param rbuf The ring buffer.
125
126 @return The number of elements available for writing.
127*/
128PaRingBufferSize PaUtil_GetRingBufferWriteAvailable( PaUtilRingBuffer *rbuf );
129
130/** Retrieve the number of elements available in the ring buffer for reading.
131
132 @param rbuf The ring buffer.
133
134 @return The number of elements available for reading.
135*/
136PaRingBufferSize PaUtil_GetRingBufferReadAvailable( PaUtilRingBuffer *rbuf );
137
138/** Write data to the ring buffer.
139
140 @param rbuf The ring buffer.
141
142 @param data The address of new data to write to the buffer.
143
144 @param elementCount The number of elements to be written.
145
146 @return The number of elements written.
147*/
148PaRingBufferSize PaUtil_WriteRingBuffer( PaUtilRingBuffer *rbuf, const void *data, PaRingBufferSize elementCount );
149
150/** Read data from the ring buffer.
151
152 @param rbuf The ring buffer.
153
154 @param data The address where the data should be stored.
155
156 @param elementCount The number of elements to be read.
157
158 @return The number of elements read.
159*/
160PaRingBufferSize PaUtil_ReadRingBuffer( PaUtilRingBuffer *rbuf, void *data, PaRingBufferSize elementCount );
161
162/** Get address of region(s) to which we can write data.
163
164 @param rbuf The ring buffer.
165
166 @param elementCount The number of elements desired.
167
168 @param dataPtr1 The address where the first (or only) region pointer will be
169 stored.
170
171 @param sizePtr1 The address where the first (or only) region length will be
172 stored.
173
174 @param dataPtr2 The address where the second region pointer will be stored if
175 the first region is too small to satisfy elementCount.
176
177 @param sizePtr2 The address where the second region length will be stored if
178 the first region is too small to satisfy elementCount.
179
180 @return The room available to be written or elementCount, whichever is smaller.
181*/
182PaRingBufferSize PaUtil_GetRingBufferWriteRegions( PaUtilRingBuffer *rbuf, PaRingBufferSize elementCount,
183                                       void **dataPtr1, PaRingBufferSize *sizePtr1,
184                                       void **dataPtr2, PaRingBufferSize *sizePtr2 );
185
186/** Advance the write index to the next location to be written.
187
188 @param rbuf The ring buffer.
189
190 @param elementCount The number of elements to advance.
191
192 @return The new position.
193*/
194PaRingBufferSize PaUtil_AdvanceRingBufferWriteIndex( PaUtilRingBuffer *rbuf, PaRingBufferSize elementCount );
195
196/** Get address of region(s) from which we can write data.
197
198 @param rbuf The ring buffer.
199
200 @param elementCount The number of elements desired.
201
202 @param dataPtr1 The address where the first (or only) region pointer will be
203 stored.
204
205 @param sizePtr1 The address where the first (or only) region length will be
206 stored.
207
208 @param dataPtr2 The address where the second region pointer will be stored if
209 the first region is too small to satisfy elementCount.
210
211 @param sizePtr2 The address where the second region length will be stored if
212 the first region is too small to satisfy elementCount.
213
214 @return The number of elements available for reading.
215*/
216PaRingBufferSize PaUtil_GetRingBufferReadRegions( PaUtilRingBuffer *rbuf, PaRingBufferSize elementCount,
217                                      void **dataPtr1, PaRingBufferSize *sizePtr1,
218                                      void **dataPtr2, PaRingBufferSize *sizePtr2 );
219
220/** Advance the read index to the next location to be read.
221
222 @param rbuf The ring buffer.
223
224 @param elementCount The number of elements to advance.
225
226 @return The new position.
227*/
228PaRingBufferSize PaUtil_AdvanceRingBufferReadIndex( PaUtilRingBuffer *rbuf, PaRingBufferSize elementCount );
229
230#ifdef __cplusplus
231}
232#endif /* __cplusplus */
233#endif /* MODULES_AUDIO_DEVICE_MAIN_SOURCE_MAC_PORTAUDIO_PA_RINGBUFFER_H_ */
234