RingBuffer Class Reference

Holds streamed audio samples. More...

#include <RingBuffer.h>

Inheritance diagram for RingBuffer:

Collaboration diagram for RingBuffer:

Public Member Functions
	RingBuffer (sampleFormat format, size_t size)
	~RingBuffer ()
size_t	AvailForPut () const
size_t	WrittenForGet () const
	Reader may concurrently cause a decrease of what this returns. More...
size_t	Put (constSamplePtr buffer, sampleFormat format, size_t samples, size_t padding=0)
	Does not apply dithering. More...
size_t	Unput (size_t size)
	Remove an initial segment of data that has been Put but not Flushed yet. More...
size_t	Clear (sampleFormat format, size_t samples)
std::pair< samplePtr, size_t >	GetUnflushed (unsigned iBlock)
void	Flush ()
	Flush after a sequence of Put (and/or Clear) calls to let consumer see. More...
size_t	AvailForGet () const
size_t	Get (samplePtr buffer, sampleFormat format, size_t samples)
	Does not apply dithering. More...
size_t	Discard (size_t samples)

Private Member Functions
size_t	Filled (size_t start, size_t end) const
size_t	Free (size_t start, size_t end) const

Private Attributes
size_t	mWritten {0}
size_t	mLastPadding {0}
NonInterfering< std::atomic< size_t > >	mStart { 0 }
NonInterfering< std::atomic< size_t > >	mEnd { 0 }
const size_t	mBufferSize
const sampleFormat	mFormat
const SampleBuffer	mBuffer

Detailed Description

Holds streamed audio samples.

Assuming that there is only one thread writing, and one thread reading, this class implements a lock-free thread-safe bounded queue of samples with atomic variables that contain the first filled and free positions.

If two threads both need to read, or both need to write, they need to lock this class from outside using their own mutex.

AvailForPut and AvailForGet may underestimate but will never overestimate.

Definition at line 17 of file RingBuffer.h.

Constructor & Destructor Documentation

RingBuffer()

RingBuffer::RingBuffer	(	sampleFormat	format,
		size_t	size
	)

Definition at line 32 of file RingBuffer.cpp.

   : mBufferSize{ std::max<size_t>(size, 64) }
   , mFormat{ format }
   , mBuffer{ mBufferSize, mFormat }
{
}

~RingBuffer()

RingBuffer::~RingBuffer

(

)

Definition at line 39 of file RingBuffer.cpp.

{
}

Member Function Documentation

AvailForGet()

size_t RingBuffer::AvailForGet

(

)

const

Definition at line 226 of file RingBuffer.cpp.

{
   auto end = mEnd.load( std::memory_order_relaxed ); // get away with it here
   auto start = mStart.load( std::memory_order_relaxed );
   return Filled( start, end );
 
   // Writer might increase the available samples after return, but will
   // never decrease them, so reader can safely assume this much at least
}

References details::end(), Filled(), mEnd, and mStart.

Referenced by AudioIO::GetCommonlyAvailCapture(), and AudioIoCallback::GetCommonlyReadyPlayback().

Here is the call graph for this function:

Here is the caller graph for this function:

AvailForPut()

size_t RingBuffer::AvailForPut

(

)

const

Definition at line 64 of file RingBuffer.cpp.

{
   auto start = mStart.load( std::memory_order_relaxed );
   return Free( start, mWritten );
 
   // Reader might increase the available free space after return, but will
   // never decrease it, so writer can safely assume this much at least
}

References Free(), mStart, and mWritten.

Referenced by AudioIO::GetCommonlyFreePlayback().

Here is the call graph for this function:

Here is the caller graph for this function:

Clear()

size_t RingBuffer::Clear	(	sampleFormat	format,
		size_t	samples
	)

Definition at line 164 of file RingBuffer.cpp.

{
   auto start = mStart.load( std::memory_order_acquire );
   auto end = mWritten;
   samplesToClear = std::min( samplesToClear, Free( start, end ) );
   size_t cleared = 0;
   auto pos = end;
 
   while(samplesToClear) {
      auto block = std::min( samplesToClear, mBufferSize - pos );
 
      ClearSamples(mBuffer.ptr(), format, pos, block);
 
      pos = (pos + block) % mBufferSize;
      samplesToClear -= block;
      cleared += block;
   }
 
   mWritten = pos;
 
   return cleared;
}

References ClearSamples(), details::end(), anonymous_namespace{ExportPCM.cpp}::format, Free(), mBuffer, mBufferSize, min(), mStart, mWritten, and SampleBuffer::ptr().

Here is the call graph for this function:

Discard()

size_t RingBuffer::Discard

(

size_t

samples

)

Definition at line 267 of file RingBuffer.cpp.

{
   auto end = mEnd.load( std::memory_order_relaxed ); // get away with it here
   auto start = mStart.load( std::memory_order_relaxed );
   samplesToDiscard = std::min( samplesToDiscard, Filled( start, end ) );
 
   // Communicate to writer that we have skipped some data, and that's all
   mStart.store((start + samplesToDiscard) % mBufferSize,
                std::memory_order_relaxed);
 
   return samplesToDiscard;
}

References details::end(), Filled(), mBufferSize, mEnd, min(), and mStart.

Here is the call graph for this function:

Filled()

size_t RingBuffer::Filled ( size_t  start, size_t  end  ) const

private

Definition at line 46 of file RingBuffer.cpp.

{
   return (end + mBufferSize - start) % mBufferSize;
}

References details::end(), and mBufferSize.

Referenced by AvailForGet(), Discard(), Free(), Get(), GetUnflushed(), Unput(), and WrittenForGet().

Here is the call graph for this function:

Here is the caller graph for this function:

Flush()

void RingBuffer::Flush

(

)

Flush after a sequence of Put (and/or Clear) calls to let consumer see.

Definition at line 210 of file RingBuffer.cpp.

{
   // Atomically update the end pointer with release, so the nonatomic writes
   // just done to the buffer don't get reordered after
   mEnd.store(mWritten, std::memory_order_release);
   mLastPadding = 0;
}

References mEnd, mLastPadding, and mWritten.

Free()

size_t RingBuffer::Free ( size_t  start, size_t  end  ) const

private

Definition at line 51 of file RingBuffer.cpp.

{
   return std::max<size_t>(mBufferSize - Filled( start, end ), 4) - 4;
}

References details::end(), Filled(), and mBufferSize.

Referenced by AvailForPut(), Clear(), and Put().

Here is the call graph for this function:

Here is the caller graph for this function:

Get()

size_t RingBuffer::Get	(	samplePtr	buffer,
		sampleFormat	format,
		size_t	samples
	)

Does not apply dithering.

Definition at line 236 of file RingBuffer.cpp.

{
   // Must match the writer's release with acquire for well defined reads of
   // the buffer
   auto end = mEnd.load( std::memory_order_acquire );
   auto start = mStart.load( std::memory_order_relaxed );
   samplesToCopy = std::min( samplesToCopy, Filled( start, end ) );
   auto dest = buffer;
   size_t copied = 0;
 
   while(samplesToCopy) {
      auto block = std::min( samplesToCopy, mBufferSize - start );
 
      CopySamples(mBuffer.ptr() + start * SAMPLE_SIZE(mFormat), mFormat,
                  dest, format,
                  block, DitherType::none);
 
      dest += block * SAMPLE_SIZE(format);
      start = (start + block) % mBufferSize;
      samplesToCopy -= block;
      copied += block;
   }
 
   // Communicate to writer that we have consumed some data,
   // with nonrelaxed ordering
   mStart.store( start, std::memory_order_release );
 
   return copied;
}

References CopySamples(), details::end(), Filled(), anonymous_namespace{ExportPCM.cpp}::format, mBuffer, mBufferSize, mEnd, mFormat, min(), mStart, none, SampleBuffer::ptr(), and SAMPLE_SIZE.

Here is the call graph for this function:

GetUnflushed()

std::pair< samplePtr, size_t > RingBuffer::GetUnflushed

(

unsigned

iBlock

)

Get access to written but unflushed data, which is in at most two blocks Excludes the padding of the most recent Put()

Definition at line 187 of file RingBuffer.cpp.

{
   // This function is called by the writer
 
   // Find total number of samples unflushed:
   auto end = mEnd.load(std::memory_order_relaxed);
   const size_t size = Filled(end, mWritten) - mLastPadding;
 
   // How many in the first part:
   const size_t size0 = std::min(size, mBufferSize - end);
   // How many wrap around the ring buffer:
   const size_t size1 = size - size0;
 
   if (iBlock == 0)
      return {
         size0 ? mBuffer.ptr() + end * SAMPLE_SIZE(mFormat) : nullptr,
         size0 };
   else
      return {
         size1 ? mBuffer.ptr() : nullptr,
         size1 };
}

References details::end(), Filled(), mBuffer, mBufferSize, mEnd, mFormat, min(), mLastPadding, mWritten, SampleBuffer::ptr(), SAMPLE_SIZE, and size.

Here is the call graph for this function:

Put()

size_t RingBuffer::Put	(	constSamplePtr	buffer,
		sampleFormat	format,
		size_t	samples,
		size_t	padding = 0
	)

Does not apply dithering.

Definition at line 79 of file RingBuffer.cpp.

{
   mLastPadding = padding;
   auto start = mStart.load( std::memory_order_acquire );
   auto end = mWritten;
   const auto free = Free( start, end );
   samplesToCopy = std::min( samplesToCopy, free );
   padding = std::min( padding, free - samplesToCopy );
   auto src = buffer;
   size_t copied = 0;
   auto pos = end;
 
   while ( samplesToCopy ) {
      auto block = std::min( samplesToCopy, mBufferSize - pos );
 
      CopySamples(src, format,
                  mBuffer.ptr() + pos * SAMPLE_SIZE(mFormat), mFormat,
                  block, DitherType::none);
 
      src += block * SAMPLE_SIZE(format);
      pos = (pos + block) % mBufferSize;
      samplesToCopy -= block;
      copied += block;
   }
 
   while ( padding ) {
      const auto block = std::min( padding, mBufferSize - pos );
      ClearSamples( mBuffer.ptr(), mFormat, pos, block );
      pos = (pos + block) % mBufferSize;
      padding -= block;
      copied += block;
   }
 
   mWritten = pos;
   return copied;
}

References ClearSamples(), CopySamples(), details::end(), anonymous_namespace{ExportPCM.cpp}::format, Free(), staffpad::vo::free(), mBuffer, mBufferSize, mFormat, min(), mLastPadding, mStart, mWritten, none, SampleBuffer::ptr(), and SAMPLE_SIZE.

Here is the call graph for this function:

Unput()

size_t RingBuffer::Unput

(

size_t

size

)

Remove an initial segment of data that has been Put but not Flushed yet.

Returns

how many were unput

Definition at line 117 of file RingBuffer.cpp.

{
   const auto sampleSize = SAMPLE_SIZE(mFormat);
   const auto buffer = mBuffer.ptr();
 
   // un-put some of the un-flushed data which is from mEnd to mWritten
   // bound the result
   auto end = mEnd.load(std::memory_order_relaxed);
   size = std::min(size, Filled(end, mWritten));
   const auto result = size;
 
   // First memmove
   auto limit = end < mWritten ? mWritten : mBufferSize;
   // Source offset for move
   auto source = std::min(end + size, limit);
   // How many to move
   auto count = limit - source;
   auto pDst = buffer + end * sampleSize;
   auto pSrc = buffer + source * sampleSize;
   memmove(pDst, pSrc, count * sampleSize);
   // Discount how many really discarded
   size -= (source - end);
   
   if (end >= mWritten) {
      // The unflushed data were wrapped around, not contiguous
      end += count;
      auto pDst = buffer + end * sampleSize;
      // Rotate some samples from start of buffer, but discarding
      // any remaining number that must be un-put
      // Then shift samples near the start of buffer
      pSrc = buffer + size * sampleSize;
      auto toMove = mWritten - size;
      auto toMove1 = std::min(toMove, mBufferSize - end);
      auto toMove2 = toMove - toMove1;
      memmove(pDst, pSrc, toMove1 * sampleSize);
      memmove(buffer, pSrc + toMove1 * sampleSize, toMove2 * sampleSize);
   }
 
   // Move mWritten backwards by result
   mWritten = (mWritten + (mBufferSize - result)) % mBufferSize;
 
   // Adjust mLastPadding
   mLastPadding = std::min(mLastPadding, Filled(end, mWritten));
 
   return result;
}

References details::end(), Filled(), mBuffer, mBufferSize, mEnd, mFormat, min(), mLastPadding, mWritten, SampleBuffer::ptr(), SAMPLE_SIZE, and size.

Here is the call graph for this function:

WrittenForGet()

size_t RingBuffer::WrittenForGet

(

)

const

Reader may concurrently cause a decrease of what this returns.

Definition at line 73 of file RingBuffer.cpp.

{
   auto start = mStart.load( std::memory_order_relaxed );
   return Filled( start, mWritten );
}

References Filled(), mStart, and mWritten.

Referenced by AudioIoCallback::GetCommonlyWrittenForPlayback().

Here is the call graph for this function:

Here is the caller graph for this function:

Member Data Documentation

mBuffer

const SampleBuffer RingBuffer::mBuffer

private

Definition at line 67 of file RingBuffer.h.

Referenced by Clear(), Get(), GetUnflushed(), Put(), and Unput().

mBufferSize

const size_t RingBuffer::mBufferSize

private

Definition at line 64 of file RingBuffer.h.

Referenced by Clear(), Discard(), Filled(), Free(), Get(), GetUnflushed(), Put(), and Unput().

mEnd

NonInterfering< std::atomic<size_t> > RingBuffer::mEnd { 0 }

private

Definition at line 62 of file RingBuffer.h.

Referenced by AvailForGet(), Discard(), Flush(), Get(), GetUnflushed(), and Unput().

mFormat

const sampleFormat RingBuffer::mFormat

private

Definition at line 66 of file RingBuffer.h.

Referenced by Get(), GetUnflushed(), Put(), and Unput().

mLastPadding

size_t RingBuffer::mLastPadding {0}

private

Definition at line 59 of file RingBuffer.h.

Referenced by Flush(), GetUnflushed(), Put(), and Unput().

mStart

NonInterfering< std::atomic<size_t> > RingBuffer::mStart { 0 }

private

Definition at line 62 of file RingBuffer.h.

Referenced by AvailForGet(), AvailForPut(), Clear(), Discard(), Get(), Put(), and WrittenForGet().

mWritten

size_t RingBuffer::mWritten {0}

private

Definition at line 58 of file RingBuffer.h.

Referenced by AvailForPut(), Clear(), Flush(), GetUnflushed(), Put(), Unput(), and WrittenForGet().

---

The documentation for this class was generated from the following files:

• RingBuffer.h
• RingBuffer.cpp