PortAudio  2.0
Data Structures | Typedefs | Functions
pa_ringbuffer.h File Reference

Single-reader single-writer lock-free ring buffer. More...

Go to the source code of this file.

Data Structures

struct  PaUtilRingBuffer
 

Typedefs

typedef long ring_buffer_size_t
 
typedef struct PaUtilRingBuffer PaUtilRingBuffer
 

Functions

ring_buffer_size_t PaUtil_InitializeRingBuffer (PaUtilRingBuffer *rbuf, ring_buffer_size_t elementSizeBytes, ring_buffer_size_t elementCount, void *dataPtr)
 
void PaUtil_FlushRingBuffer (PaUtilRingBuffer *rbuf)
 
ring_buffer_size_t PaUtil_GetRingBufferWriteAvailable (const PaUtilRingBuffer *rbuf)
 
ring_buffer_size_t PaUtil_GetRingBufferReadAvailable (const PaUtilRingBuffer *rbuf)
 
ring_buffer_size_t PaUtil_WriteRingBuffer (PaUtilRingBuffer *rbuf, const void *data, ring_buffer_size_t elementCount)
 
ring_buffer_size_t PaUtil_ReadRingBuffer (PaUtilRingBuffer *rbuf, void *data, ring_buffer_size_t elementCount)
 
ring_buffer_size_t PaUtil_GetRingBufferWriteRegions (PaUtilRingBuffer *rbuf, ring_buffer_size_t elementCount, void **dataPtr1, ring_buffer_size_t *sizePtr1, void **dataPtr2, ring_buffer_size_t *sizePtr2)
 
ring_buffer_size_t PaUtil_AdvanceRingBufferWriteIndex (PaUtilRingBuffer *rbuf, ring_buffer_size_t elementCount)
 
ring_buffer_size_t PaUtil_GetRingBufferReadRegions (PaUtilRingBuffer *rbuf, ring_buffer_size_t elementCount, void **dataPtr1, ring_buffer_size_t *sizePtr1, void **dataPtr2, ring_buffer_size_t *sizePtr2)
 
ring_buffer_size_t PaUtil_AdvanceRingBufferReadIndex (PaUtilRingBuffer *rbuf, ring_buffer_size_t elementCount)
 

Detailed Description

Single-reader single-writer lock-free ring buffer.

PaUtilRingBuffer is a ring buffer used to transport samples between different execution contexts (threads, OS callbacks, interrupt handlers) without requiring the use of any locks. This only works when there is a single reader and a single writer (ie. one thread or callback writes to the ring buffer, another thread or callback reads from it).

The PaUtilRingBuffer structure manages a ring buffer containing N elements, where N must be a power of two. An element may be any size (specified in bytes).

The memory area used to store the buffer elements must be allocated by the client prior to calling PaUtil_InitializeRingBuffer() and must outlive the use of the ring buffer.

Note
The ring buffer functions are not normally exposed in the PortAudio libraries. If you want to call them then you will need to add pa_ringbuffer.c to your application source code.

Typedef Documentation

typedef long ring_buffer_size_t

Function Documentation

ring_buffer_size_t PaUtil_AdvanceRingBufferReadIndex ( PaUtilRingBuffer rbuf,
ring_buffer_size_t  elementCount 
)

Advance the read index to the next location to be read.

Parameters
rbufThe ring buffer.
elementCountThe number of elements to advance.
Returns
The new position.

References PaUtilRingBuffer::bigMask, and PaUtilRingBuffer::readIndex.

Referenced by PaUtil_ReadRingBuffer().

ring_buffer_size_t PaUtil_AdvanceRingBufferWriteIndex ( PaUtilRingBuffer rbuf,
ring_buffer_size_t  elementCount 
)

Advance the write index to the next location to be written.

Parameters
rbufThe ring buffer.
elementCountThe number of elements to advance.
Returns
The new position.

References PaUtilRingBuffer::bigMask, and PaUtilRingBuffer::writeIndex.

Referenced by PaUtil_WriteRingBuffer(), and resetBlioRingBuffers().

void PaUtil_FlushRingBuffer ( PaUtilRingBuffer rbuf)

Reset buffer to empty. Should only be called when buffer is NOT being read or written.

Parameters
rbufThe ring buffer.

References PaUtilRingBuffer::readIndex, and PaUtilRingBuffer::writeIndex.

Referenced by PaUtil_InitializeRingBuffer(), and resetBlioRingBuffers().

ring_buffer_size_t PaUtil_GetRingBufferReadAvailable ( const PaUtilRingBuffer rbuf)

Retrieve the number of elements available in the ring buffer for reading.

Parameters
rbufThe ring buffer.
Returns
The number of elements available for reading.

References PaUtilRingBuffer::bigMask, PaUtilRingBuffer::readIndex, and PaUtilRingBuffer::writeIndex.

Referenced by BlioCallback(), GetStreamReadAvailable(), PaUtil_GetRingBufferReadRegions(), PaUtil_GetRingBufferWriteAvailable(), ReadStream(), and waitUntilBlioWriteBufferIsEmpty().

ring_buffer_size_t PaUtil_GetRingBufferReadRegions ( PaUtilRingBuffer rbuf,
ring_buffer_size_t  elementCount,
void **  dataPtr1,
ring_buffer_size_t sizePtr1,
void **  dataPtr2,
ring_buffer_size_t sizePtr2 
)

Get address of region(s) from which we can read data.

Parameters
rbufThe ring buffer.
elementCountThe number of elements desired.
dataPtr1The address where the first (or only) region pointer will be stored.
sizePtr1The address where the first (or only) region length will be stored.
dataPtr2The address where the second region pointer will be stored if the first region is too small to satisfy elementCount.
sizePtr2The address where the second region length will be stored if the first region is too small to satisfy elementCount.
Returns
The number of elements available for reading.

References PaUtilRingBuffer::buffer, PaUtilRingBuffer::bufferSize, PaUtilRingBuffer::elementSizeBytes, PaUtil_GetRingBufferReadAvailable(), PaUtilRingBuffer::readIndex, and PaUtilRingBuffer::smallMask.

Referenced by PaUtil_ReadRingBuffer().

ring_buffer_size_t PaUtil_GetRingBufferWriteAvailable ( const PaUtilRingBuffer rbuf)

Retrieve the number of elements available in the ring buffer for writing.

Parameters
rbufThe ring buffer.
Returns
The number of elements available for writing.

References PaUtilRingBuffer::bufferSize, and PaUtil_GetRingBufferReadAvailable().

Referenced by BlioCallback(), GetStreamWriteAvailable(), PaUtil_GetRingBufferWriteRegions(), ProcessingThread(), and WriteStream().

ring_buffer_size_t PaUtil_GetRingBufferWriteRegions ( PaUtilRingBuffer rbuf,
ring_buffer_size_t  elementCount,
void **  dataPtr1,
ring_buffer_size_t sizePtr1,
void **  dataPtr2,
ring_buffer_size_t sizePtr2 
)

Get address of region(s) to which we can write data.

Parameters
rbufThe ring buffer.
elementCountThe number of elements desired.
dataPtr1The address where the first (or only) region pointer will be stored.
sizePtr1The address where the first (or only) region length will be stored.
dataPtr2The address where the second region pointer will be stored if the first region is too small to satisfy elementCount.
sizePtr2The address where the second region length will be stored if the first region is too small to satisfy elementCount.
Returns
The room available to be written or elementCount, whichever is smaller.

References PaUtilRingBuffer::buffer, PaUtilRingBuffer::bufferSize, PaUtilRingBuffer::elementSizeBytes, PaUtil_GetRingBufferWriteAvailable(), PaUtilRingBuffer::smallMask, and PaUtilRingBuffer::writeIndex.

Referenced by PaUtil_WriteRingBuffer().

ring_buffer_size_t PaUtil_InitializeRingBuffer ( PaUtilRingBuffer rbuf,
ring_buffer_size_t  elementSizeBytes,
ring_buffer_size_t  elementCount,
void *  dataPtr 
)

Initialize Ring Buffer to empty state ready to have elements written to it.

Parameters
rbufThe ring buffer.
elementSizeBytesThe size of a single data element in bytes.
elementCountThe number of elements in the buffer (must be a power of 2).
dataPtrA pointer to a previously allocated area where the data will be maintained. It must be elementCount*elementSizeBytes long.
Returns
-1 if elementCount is not a power of 2, otherwise 0.

References PaUtilRingBuffer::bigMask, PaUtilRingBuffer::buffer, PaUtilRingBuffer::bufferSize, PaUtilRingBuffer::elementSizeBytes, PaUtil_FlushRingBuffer(), and PaUtilRingBuffer::smallMask.

Referenced by initializeBlioRingBuffers().

ring_buffer_size_t PaUtil_ReadRingBuffer ( PaUtilRingBuffer rbuf,
void *  data,
ring_buffer_size_t  elementCount 
)

Read data from the ring buffer.

Parameters
rbufThe ring buffer.
dataThe address where the data should be stored.
elementCountThe number of elements to be read.
Returns
The number of elements read.

References PaUtilRingBuffer::elementSizeBytes, PaUtil_AdvanceRingBufferReadIndex(), and PaUtil_GetRingBufferReadRegions().

Referenced by BlioCallback(), and ReadStream().

ring_buffer_size_t PaUtil_WriteRingBuffer ( PaUtilRingBuffer rbuf,
const void *  data,
ring_buffer_size_t  elementCount 
)

Write data to the ring buffer.

Parameters
rbufThe ring buffer.
dataThe address of new data to write to the buffer.
elementCountThe number of elements to be written.
Returns
The number of elements written.

References PaUtilRingBuffer::elementSizeBytes, PaUtil_AdvanceRingBufferWriteIndex(), and PaUtil_GetRingBufferWriteRegions().

Referenced by BlioCallback(), and WriteStream().