RingBuffer Class Reference

A ring buffer. More...

#include <ringbuffer.hpp>

Public Member Functions
	RingBuffer (int power, int size)
	Constructs a RingBuffer. More...
	~RingBuffer ()
	Destructs a PaRingBuffer.
	RingBuffer (const RingBuffer &)=delete
	Deleted copy constructor.
RingBuffer &	operator= (const RingBuffer &)=delete
	Deleted copy-assignment.
size_t	WriteCapacity () const
	The current write capacity. More...
size_t	ReadCapacity () const
	The current read capacity. More...
unsigned long	Write (const char *start, unsigned long count)
	Writes samples from an array into the ring buffer. More...
unsigned long	Read (char *start, unsigned long count)
	Reads samples from the ring buffer into an array. More...
void	Flush ()
	Empties the ring buffer.

Static Private Member Functions
static unsigned long	CountCast (ring_buffer_size_t count)
	Converts a ring buffer size into an external size. More...

Private Attributes
char *	buffer
	The array used by the ringbuffer.
PaUtilRingBuffer *	rb
	The internal PortAudio ringbuffer.

Detailed Description

A ring buffer.

This ring buffer is based on the PortAudio ring buffer, provided in the contrib/ directory. This is stable and performs well, but, as it is C code, necessitates some hoop jumping to integrate and could do with being replaced with a native solution.

Definition at line 24 of file ringbuffer.hpp.

Constructor & Destructor Documentation

RingBuffer()

RingBuffer::RingBuffer	(	int	power,
		int	size
	)

Constructs a RingBuffer.

• Precondition: 0 < power, 0 < size.
• Postcondition: The RingBuffer is fully initialised.

Parameters

power	n, where 2^n is the number of elements in the ring buffer.
size	The size of one element in the ring buffer.

Definition at line 19 of file ringbuffer.cpp.

References buffer, MSG_OUTPUT_RINGINIT, and rb.

{
    if (power <= 0) throw InternalError("ringbuffer power must be positive");
    if (size <= 0) throw InternalError("ringbuffer element size must be positive");

    this->rb = new PaUtilRingBuffer;
    this->buffer = new char[(1 << power) * size];

    if (PaUtil_InitializeRingBuffer(
                this->rb, size, static_cast<ring_buffer_size_t>(1 << power),
                this->buffer) != 0) {
        throw new InternalError(MSG_OUTPUT_RINGINIT);
    }

    assert(this->rb != nullptr);
    assert(this->buffer != nullptr);
}

Member Function Documentation

CountCast()

unsigned long RingBuffer::CountCast ( ring_buffer_size_t  count )

staticprivate

Converts a ring buffer size into an external size.

Parameters

count

The size/count in PortAudio form.

Returns

The size/count after casting to unsigned long.

Definition at line 80 of file ringbuffer.cpp.

Referenced by Read(), ReadCapacity(), Write(), and WriteCapacity().

{
    return static_cast<unsigned long>(count);
}

Read()

unsigned long RingBuffer::Read	(	char *	start,
		unsigned long	count
	)

Reads samples from the ring buffer into an array.

To read one sample, pass a count of 1 and take a pointer to the sample variable.

• Precondition: start points to a valid array, 0 < count <= the size of the block of memory pointed to by start, count <= ReadCapacity().
• Postcondition: The block of memory pointed to by start and bounded by count and ReadCapacity() has been filled with the appropriate number of samples from the front of the ring buffer.

Parameters

start	The start of the array buffer to which we write samples. Must not be nullptr.
count	The number of samples to read. This must not exceed the minimum of ReadCapacity() and the length of the array.

Returns

The number of samples read, which should not exceed count.

See also

ReadCapacity

Definition at line 65 of file ringbuffer.cpp.

References CountCast(), rb, and ReadCapacity().

Referenced by SdlAudioSink::Callback().

{
    if (count == 0) throw InternalError("tried to read 0 items from ringbuffer");
    if (ReadCapacity() < count) throw InternalError("ringbuffer underflow");

    return CountCast(PaUtil_ReadRingBuffer(
            this->rb, start, static_cast<ring_buffer_size_t>(count)));
}

ReadCapacity()

size_t RingBuffer::ReadCapacity

(

)

const

The current read capacity.

Returns

The number of samples available in this ring buffer.

See also

Read

Definition at line 51 of file ringbuffer.cpp.

References CountCast(), and rb.

Referenced by SdlAudioSink::Callback(), Flush(), and Read().

{
    return CountCast(PaUtil_GetRingBufferReadAvailable(this->rb));
}

Write()

unsigned long RingBuffer::Write	(	const char *	start,
		unsigned long	count
	)

Writes samples from an array into the ring buffer.

To write one sample, pass a count of 1 and take a pointer to the sample variable. Note that start pointer is not constant. This is because the underlying implementation of the ring buffer might not guarantee that the array is left untouched.

• Precondition: start points to a valid array, 0 < count <= the size of the block of memory pointed to by start, count <= WriteCapacity().
• Postcondition: The ringbuffer has been written to with the contents of the memory pointed to by start and bounded by count and WriteCapacity().

Parameters

start	The start of the array buffer from which we read samples. Must not be nullptr.
count	The number of samples to write. This must not exceed the minimum of WriteCapacity() and the length of the array.

Returns

The number of samples written, which should not exceed count.

See also

WriteCapacity

Definition at line 56 of file ringbuffer.cpp.

References CountCast(), rb, and WriteCapacity().

Referenced by SdlAudioSink::Transfer().

{
    if (count == 0) throw InternalError("tried to store 0 items in ringbuffer");
    if (WriteCapacity() < count) throw InternalError("ringbuffer overflow");

    return CountCast(PaUtil_WriteRingBuffer(
            this->rb, start, static_cast<ring_buffer_size_t>(count)));
}

WriteCapacity()

size_t RingBuffer::WriteCapacity

(

)

const

The current write capacity.

Returns

The number of samples this ring buffer has space to store.

See also

Write

Definition at line 46 of file ringbuffer.cpp.

References CountCast(), and rb.

Referenced by SdlAudioSink::Transfer(), and Write().

{
    return CountCast(PaUtil_GetRingBufferWriteAvailable(this->rb));
}

---

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

• src/audio/ringbuffer.hpp
• src/audio/ringbuffer.cpp