arduino-audio-tools
Loading...
Searching...
No Matches
Public Member Functions | List of all members
RingBufferSPSC< T > Class Template Referenceabstract
Arduino Audio Tools » Tools » Buffers

Lock-free Single-Producer Single-Consumer ring buffer. More...

#include <RingBufferSPSC.h>

Inheritance diagram for RingBufferSPSC< T >:
BaseBuffer< uint8_t >

Public Member Functions

 RingBufferSPSC ()=default
 RingBufferSPSC (const RingBufferSPSC &)=delete
 RingBufferSPSC (size_t capacity)
 ~RingBufferSPSC () override=default
T * address () override
 returns the address of the start of the physical read buffer
int available () override
 provides the number of entries that are available to read
int availableForWrite () override
 provides the number of entries that are available to write
virtual int bufferCountEmpty ()
 Provides the number of entries that are available to write: -1 does not apply.
virtual int bufferCountFilled ()
 Provides the number of entries that are available to read: -1 does not apply.
void clear ()
 same as reset
virtual int clearArray (int len)
 Removes the next len entries.
virtual void flush ()
virtual float freePercent ()
 Returns the free space of the buffer in %.
bool isEmpty ()
virtual bool isFull ()
 checks if the buffer is full
virtual float levelPercent ()
 Returns the level of the buffer in %.
RingBufferSPSC & operator= (const RingBufferSPSC &)=delete
virtual bool peek (uint8_t &result)=0
 peeks the actual entry from the buffer
bool peek (T &result) override
virtual bool read (uint8_t &result)=0
 reads a single value
bool read (T &result) override
virtual int readArray (uint8_t data[], int len)
 reads multiple values
int readArray (T data[], int len) override
void reset () override
 clears the buffer
bool resize (size_t capacity) override
 Resizes the buffer if supported: returns false if not supported.
void setUsePSRAM (bool flag)
size_t size () override
virtual bool write (uint8_t data)=0
 write add an entry to the buffer
bool write (T data) override
virtual int writeArray (const uint8_t data[], int len)
 Fills the buffer data.
int writeArray (const T data[], int len) override
virtual int writeArrayOverwrite (const uint8_t data[], int len)
 Fills the buffer data and overwrites the oldest data if the buffer is full.

Detailed Description

template<typename T = uint8_t>
class audio_tools::RingBufferSPSC< T >

Lock-free Single-Producer Single-Consumer ring buffer.

Safe to use from two cores / contexts simultaneously only when there is exactly one writer and exactly one reader — e.g. an ISR or a second core filling the buffer while the main loop drains it (USB audio RX path on RP2040 with core-1 tud_task).

Design ──────

  • head_ is the element-count of everything ever written; only the producer writes it (release store) and the consumer reads it (acquire load).
  • tail_ is the element-count of everything ever read; only the consumer writes it (release store) and the producer reads it (acquire load).
  • No shared mutable counter between the two sides — the shared mutable state of RingBuffer<T>::_numElems is the classic data race on M0+.
  • Capacity is rounded up to the next power of two so that index masking replaces modulo and wrap-around is handled by a single bit-AND.
  • readArray / writeArray use memcpy for bulk transfers and split them at the wrap-around point, giving at most two memcpy calls per operation (T=uint8_t makes this a byte copy; for other T it's an element copy).

Not suitable for MPMC (multiple producers or consumers); use QueueLockFree for that.

Backing storage is a Vector<T>, using Vector's own default allocator (plain heap - unaffected, existing callers like the I2S/USB audio TX/RX buffers see no change at all). setUsePSRAM(true), called before the first resize(), switches it to an allocator that prefers PSRAM and falls back to the plain heap silently where PSRAM isn't available - useful for a buffer sized to soak up bursty backlogs (see e.g. PacedVideoOutput) where a few hundred KB would be far too much to ask of internal RAM but is a rounding error against multiple MB of PSRAM.

Template Parameters
TElement type. Works for any trivially-copyable T; the bulk-copy optimisation is most effective for T=uint8_t (audio streams).
Author
Phil Schatzmann
Copyright
GPLv3

Constructor & Destructor Documentation

◆ RingBufferSPSC() [1/3]

template<typename T = uint8_t>
RingBufferSPSC ( )
default

◆ RingBufferSPSC() [2/3]

template<typename T = uint8_t>
RingBufferSPSC ( size_t capacity)
inlineexplicit

◆ ~RingBufferSPSC()

template<typename T = uint8_t>
~RingBufferSPSC ( )
overridedefault

◆ RingBufferSPSC() [3/3]

template<typename T = uint8_t>
RingBufferSPSC ( const RingBufferSPSC< T > & )
delete

Member Function Documentation

◆ address()

template<typename T = uint8_t>
T * address ( )
inlineoverridevirtual

returns the address of the start of the physical read buffer

Implements BaseBuffer< uint8_t >.

◆ available()

template<typename T = uint8_t>
int available ( )
inlineoverridevirtual

provides the number of entries that are available to read

Implements BaseBuffer< uint8_t >.

◆ availableForWrite()

template<typename T = uint8_t>
int availableForWrite ( )
inlineoverridevirtual

provides the number of entries that are available to write

Implements BaseBuffer< uint8_t >.

◆ bufferCountEmpty()

virtual int bufferCountEmpty ( )
inlinevirtualinherited

Provides the number of entries that are available to write: -1 does not apply.

Reimplemented in NBuffer< T >, NBuffer< T >, NBuffer< uint8_t >, NBuffer< T >, SynchronizedNBufferRTOST< uint8_t >, and SynchronizedNBufferZephyrT< uint8_t >.

◆ bufferCountFilled()

virtual int bufferCountFilled ( )
inlinevirtualinherited

Provides the number of entries that are available to read: -1 does not apply.

Reimplemented in NBuffer< T >, NBuffer< T >, NBuffer< uint8_t >, NBuffer< T >, SynchronizedNBufferRTOST< uint8_t >, and SynchronizedNBufferZephyrT< uint8_t >.

◆ clear()

void clear ( )
inlineinherited

same as reset

◆ clearArray()

virtual int clearArray ( int len)
inlinevirtualinherited

Removes the next len entries.

Reimplemented in SingleBuffer< T >, SingleBuffer< T >, SingleBuffer< uint8_t >, and SingleBuffer< T >.

◆ flush()

virtual void flush ( )
inlinevirtualinherited

Submit any partially-filled write buffer so the reader can access it. Only meaningful for NBuffer-style block pools; no-op for ring buffers.

Reimplemented in NBuffer< T >, NBuffer< T >, NBuffer< uint8_t >, and NBuffer< T >.

◆ freePercent()

virtual float freePercent ( )
inlinevirtualinherited

Returns the free space of the buffer in %.

◆ isEmpty()

bool isEmpty ( )
inlineinherited

◆ isFull()

virtual bool isFull ( )
inlinevirtualinherited

checks if the buffer is full

Reimplemented in NBuffer< T >, NBuffer< T >, NBuffer< uint8_t >, RingBuffer< T >, RingBuffer< T >, RingBuffer< uint8_t >, SingleBuffer< T >, SingleBuffer< T >, SingleBuffer< uint8_t >, BufferRP2040T< uint8_t >, BufferRTOS< uint8_t >, NBuffer< T >, RingBuffer< T >, and SingleBuffer< T >.

◆ levelPercent()

virtual float levelPercent ( )
inlinevirtualinherited

Returns the level of the buffer in %.

Reimplemented in AdaptiveResamplingBuffer.

◆ operator=()

template<typename T = uint8_t>
RingBufferSPSC & operator= ( const RingBufferSPSC< T > & )
delete

◆ peek() [1/2]

virtual bool peek ( uint8_t & result)
pure virtualinherited

peeks the actual entry from the buffer

Implemented in AdaptiveResamplingBuffer, NBuffer< uint8_t >, RingBuffer< uint8_t >, RingBufferSPSC< uint8_t >, SingleBuffer< uint8_t >, BufferRP2040T< uint8_t >, and BufferRTOS< uint8_t >.

◆ peek() [2/2]

template<typename T = uint8_t>
bool peek ( T & result)
inlineoverride

◆ read() [1/2]

virtual bool read ( uint8_t & result)
pure virtualinherited

reads a single value

Implemented in AdaptiveResamplingBuffer, NBuffer< uint8_t >, RingBuffer< uint8_t >, RingBufferSPSC< uint8_t >, SingleBuffer< uint8_t >, BufferRP2040T< uint8_t >, and BufferRTOS< uint8_t >.

◆ read() [2/2]

template<typename T = uint8_t>
bool read ( T & result)
inlineoverride

◆ readArray() [1/2]

virtual int readArray ( uint8_t data[],
int len )
inlinevirtualinherited

reads multiple values

Reimplemented in AdaptiveResamplingBuffer, NBuffer< uint8_t >, RingBuffer< uint8_t >, RingBufferSPSC< uint8_t >, BufferRP2040T< uint8_t >, and BufferRTOS< uint8_t >.

◆ readArray() [2/2]

template<typename T = uint8_t>
int readArray ( T data[],
int len )
inlineoverride

◆ reset()

template<typename T = uint8_t>
void reset ( )
inlineoverridevirtual

clears the buffer

Implements BaseBuffer< uint8_t >.

◆ resize()

template<typename T = uint8_t>
bool resize ( size_t bytes)
inlineoverridevirtual

Resizes the buffer if supported: returns false if not supported.

Reimplemented from BaseBuffer< uint8_t >.

◆ setUsePSRAM()

template<typename T = uint8_t>
void setUsePSRAM ( bool flag)
inline

◆ size()

template<typename T = uint8_t>
size_t size ( )
inlineoverridevirtual

Implements BaseBuffer< uint8_t >.

◆ write() [1/2]

virtual bool write ( uint8_t data)
pure virtualinherited

write add an entry to the buffer

Implemented in AdaptiveResamplingBuffer, NBuffer< uint8_t >, RingBuffer< uint8_t >, RingBufferSPSC< uint8_t >, SingleBuffer< uint8_t >, BufferRP2040T< uint8_t >, and BufferRTOS< uint8_t >.

◆ write() [2/2]

template<typename T = uint8_t>
bool write ( T data)
inlineoverride

◆ writeArray() [1/2]

virtual int writeArray ( const uint8_t data[],
int len )
inlinevirtualinherited

Fills the buffer data.

Reimplemented in AdaptiveResamplingBuffer, RingBuffer< uint8_t >, RingBufferSPSC< uint8_t >, SingleBuffer< uint8_t >, BufferRP2040T< uint8_t >, and BufferRTOS< uint8_t >.

◆ writeArray() [2/2]

template<typename T = uint8_t>
int writeArray ( const T data[],
int len )
inlineoverride

◆ writeArrayOverwrite()

virtual int writeArrayOverwrite ( const uint8_t data[],
int len )
inlinevirtualinherited

Fills the buffer data and overwrites the oldest data if the buffer is full.

The documentation for this class was generated from the following file:
Generated by doxygen 1.15.0