RingBuffer< T, N > Class Template Reference

#include <RingBuffer.h>

Collaboration diagram for RingBuffer< T, N >:

[legend]List of all members.

---

Detailed Description

template<typename T, int N = 1>
class RingBuffer< T, N >

RingBuffer implements a lock-free ring buffer for one writer and N readers, that is to be used to store a sample type T.

For efficiency, RingBuffer frequently initialises samples by writing zeroes into their memory space, so T should normally be a simple type that can safely be set to zero using memset.

Definition at line 45 of file RingBuffer.h.

Public Member Functions
	RingBuffer (size_t n)
	Create a ring buffer with room to write n samples.
virtual	~RingBuffer ()
size_t	getSize () const
	Return the total capacity of the ring buffer in samples.
void	resize (size_t newSize)
	Resize the ring buffer.
bool	mlock ()
	Lock the ring buffer into physical memory.
void	reset ()
	Reset read and write pointers, thus emptying the buffer.
size_t	getReadSpace (int R=0) const
	Return the amount of data available for reading by reader R, in samples.
size_t	getWriteSpace () const
	Return the amount of space available for writing, in samples.
size_t	read (T *destination, size_t n, int R=0)
	Read n samples from the buffer, for reader R.
size_t	readAdding (T *destination, size_t n, int R=0)
	Read n samples from the buffer, for reader R, adding them to the destination.
T	readOne (int R=0)
	Read one sample from the buffer, for reader R.
size_t	peek (T *destination, size_t n, int R=0) const
	Read n samples from the buffer, if available, for reader R, without advancing the read pointer -- i.e.
T	peekOne (int R=0) const
	Read one sample from the buffer, if available, without advancing the read pointer -- i.e.
size_t	skip (size_t n, int R=0)
	Pretend to read n samples from the buffer, for reader R, without actually returning them (i.e.
size_t	write (const T *source, size_t n)
	Write n samples to the buffer.
size_t	zero (size_t n)
	Write n zero-value samples to the buffer.
Protected Attributes
T *	m_buffer
volatile size_t	m_writer
volatile size_t	m_readers [N]
size_t	m_size
bool	m_mlocked
Static Protected Attributes
static Scavenger< ScavengerArrayWrapper< T > >	m_scavenger
Private Member Functions
	RingBuffer (const RingBuffer &)
RingBuffer &	operator= (const RingBuffer &)

---

Constructor & Destructor Documentation

template<typename T, int N>

RingBuffer< T, N >::RingBuffer

(

size_t

n

)

Create a ring buffer with room to write n samples.

Note that the internal storage size will actually be n+1 samples, as one element is unavailable for administrative reasons. Since the ring buffer performs best if its size is a power of two, this means n should ideally be some power of two minus one.

Definition at line 178 of file RingBuffer.h.

References RingBuffer< T, N >::m_readers, RingBuffer< T, N >::m_scavenger, and Scavenger< T >::scavenge().

template<typename T, int N>

RingBuffer< T, N >::~RingBuffer

(

)

[virtual]

Definition at line 194 of file RingBuffer.h.

References RingBuffer< T, N >::m_buffer, RingBuffer< T, N >::m_mlocked, RingBuffer< T, N >::m_scavenger, RingBuffer< T, N >::m_size, MUNLOCK, and Scavenger< T >::scavenge().

template<typename T, int N = 1>

RingBuffer< T, N >::RingBuffer

(

const RingBuffer< T, N > &

)

[private]

---

Member Function Documentation

template<typename T, int N>

size_t RingBuffer< T, N >::getSize

(

)

const

Return the total capacity of the ring buffer in samples.

(This is the argument n passed to the constructor.)

Definition at line 210 of file RingBuffer.h.

References RingBuffer< T, N >::m_size.

Referenced by OSCQueue::postMessage().

template<typename T, int N>

void RingBuffer< T, N >::resize

(

size_t

newSize

)

Resize the ring buffer.

This also empties it. Actually swaps in a new, larger buffer; the old buffer is scavenged after a seemly delay. Should be called from the write thread.

Definition at line 221 of file RingBuffer.h.

References Scavenger< T >::claim(), RingBuffer< T, N >::m_buffer, RingBuffer< T, N >::m_mlocked, RingBuffer< T, N >::m_scavenger, RingBuffer< T, N >::m_size, MLOCK, MUNLOCK, RingBuffer< T, N >::reset(), and Scavenger< T >::scavenge().

template<typename T, int N>

bool RingBuffer< T, N >::mlock

(

)

Lock the ring buffer into physical memory.

Returns true for success.

Definition at line 248 of file RingBuffer.h.

References RingBuffer< T, N >::m_buffer, RingBuffer< T, N >::m_mlocked, RingBuffer< T, N >::m_size, and MLOCK.

template<typename T, int N>

void RingBuffer< T, N >::reset

(

)

Reset read and write pointers, thus emptying the buffer.

Should be called from the write thread.

Definition at line 257 of file RingBuffer.h.

References RingBuffer< T, N >::m_readers, and RingBuffer< T, N >::m_writer.

Referenced by DSSIPluginInstance::clearEvents(), DSSIPluginInstance::discardEvents(), and RingBuffer< T, N >::resize().

template<typename T, int N>

size_t RingBuffer< T, N >::getReadSpace

(

int

R = 0

)

const

Return the amount of data available for reading by reader R, in samples.

Definition at line 269 of file RingBuffer.h.

References RingBuffer< T, N >::m_readers, RingBuffer< T, N >::m_size, and RingBuffer< T, N >::m_writer.

Referenced by OSCQueue::getMessagesAvailable(), AudioCallbackPlaySource::getSourceSamples(), RingBuffer< T, N >::getWriteSpace(), RingBuffer< T, N >::peek(), RingBuffer< T, N >::read(), RingBuffer< T, N >::readAdding(), DSSIPluginInstance::run(), RingBuffer< T, N >::skip(), AudioCallbackPlaySource::unifyRingBuffers(), and OSCQueue::~OSCQueue().

template<typename T, int N>

size_t RingBuffer< T, N >::getWriteSpace

(

)

const

Return the amount of space available for writing, in samples.

Definition at line 287 of file RingBuffer.h.

References RingBuffer< T, N >::getReadSpace(), RingBuffer< T, N >::m_readers, RingBuffer< T, N >::m_size, and RingBuffer< T, N >::m_writer.

Referenced by OSCQueue::postMessage(), RingBuffer< T, N >::write(), and RingBuffer< T, N >::zero().

template<typename T, int N>

size_t RingBuffer< T, N >::read	(	T *	destination,
		size_t	n,
		int	R = 0
	)

Read n samples from the buffer, for reader R.

If fewer than n are available, the remainder will be zeroed out. Returns the number of samples actually read.

Definition at line 312 of file RingBuffer.h.

References RingBuffer< T, N >::getReadSpace(), RingBuffer< T, N >::m_buffer, RingBuffer< T, N >::m_readers, and RingBuffer< T, N >::m_size.

Referenced by AudioCallbackPlaySource::getSourceSamples().

template<typename T, int N>

size_t RingBuffer< T, N >::readAdding	(	T *	destination,
		size_t	n,
		int	R = 0
	)

Read n samples from the buffer, for reader R, adding them to the destination.

If fewer than n are available, the remainder will be left alone. Returns the number of samples actually read.

Definition at line 348 of file RingBuffer.h.

References RingBuffer< T, N >::getReadSpace(), RingBuffer< T, N >::m_buffer, RingBuffer< T, N >::m_readers, and RingBuffer< T, N >::m_size.

template<typename T, int N>

T RingBuffer< T, N >::readOne

(

int

R = 0

)

Read one sample from the buffer, for reader R.

If no sample is available, this will silently return zero. Calling this repeatedly is obviously slower than calling read once, but it may be good enough if you don't want to allocate a buffer to read into.

Definition at line 385 of file RingBuffer.h.

References RingBuffer< T, N >::m_buffer, RingBuffer< T, N >::m_readers, RingBuffer< T, N >::m_size, and RingBuffer< T, N >::m_writer.

Referenced by OSCQueue::readMessage(), and OSCQueue::~OSCQueue().

template<typename T, int N>

size_t RingBuffer< T, N >::peek	(	T *	destination,
		size_t	n,
		int	R = 0
	)			const

Read n samples from the buffer, if available, for reader R, without advancing the read pointer -- i.e.

a subsequent read() or skip() will be necessary to empty the buffer. If fewer than n are available, the remainder will be zeroed out. Returns the number of samples actually read.

Definition at line 407 of file RingBuffer.h.

References RingBuffer< T, N >::getReadSpace(), RingBuffer< T, N >::m_buffer, RingBuffer< T, N >::m_readers, and RingBuffer< T, N >::m_size.

template<typename T, int N>

T RingBuffer< T, N >::peekOne

(

int

R = 0

)

const

Read one sample from the buffer, if available, without advancing the read pointer -- i.e.

a subsequent read() or skip() will be necessary to empty the buffer. Returns zero if no sample was available.

Definition at line 441 of file RingBuffer.h.

References RingBuffer< T, N >::m_buffer, RingBuffer< T, N >::m_readers, and RingBuffer< T, N >::m_writer.

Referenced by DSSIPluginInstance::run().

template<typename T, int N>

size_t RingBuffer< T, N >::skip	(	size_t	n,
		int	R = 0
	)

Pretend to read n samples from the buffer, for reader R, without actually returning them (i.e.

discard the next n samples). Returns the number of samples actually available for discarding.

Definition at line 462 of file RingBuffer.h.

References RingBuffer< T, N >::getReadSpace(), RingBuffer< T, N >::m_readers, and RingBuffer< T, N >::m_size.

Referenced by DSSIPluginInstance::run().

template<typename T, int N>

size_t RingBuffer< T, N >::write	(	const T *	source,
		size_t	n
	)

Write n samples to the buffer.

If insufficient space is available, not all samples may actually be written. Returns the number of samples actually written.

Definition at line 483 of file RingBuffer.h.

References RingBuffer< T, N >::getWriteSpace(), RingBuffer< T, N >::m_buffer, RingBuffer< T, N >::m_size, and RingBuffer< T, N >::m_writer.

Referenced by AudioCallbackPlaySource::fillBuffers(), OSCQueue::postMessage(), and DSSIPluginInstance::sendEvent().

template<typename T, int N>

size_t RingBuffer< T, N >::zero

(

size_t

n

)

Write n zero-value samples to the buffer.

If insufficient space is available, not all zeros may actually be written. Returns the number of zeroes actually written.

Definition at line 518 of file RingBuffer.h.

References RingBuffer< T, N >::getWriteSpace(), RingBuffer< T, N >::m_buffer, RingBuffer< T, N >::m_size, and RingBuffer< T, N >::m_writer.

template<typename T, int N = 1>

RingBuffer& RingBuffer< T, N >::operator=

(

const RingBuffer< T, N > &

)

[private]

---

Member Data Documentation

template<typename T, int N = 1>

T* RingBuffer< T, N >::m_buffer [protected]

Definition at line 161 of file RingBuffer.h.

Referenced by RingBuffer< T, N >::mlock(), RingBuffer< T, N >::peek(), RingBuffer< T, N >::peekOne(), RingBuffer< T, N >::read(), RingBuffer< T, N >::readAdding(), RingBuffer< T, N >::readOne(), RingBuffer< T, N >::resize(), RingBuffer< T, N >::write(), RingBuffer< T, N >::zero(), and RingBuffer< T, N >::~RingBuffer().

template<typename T, int N = 1>

volatile size_t RingBuffer< T, N >::m_writer [protected]

Definition at line 162 of file RingBuffer.h.

Referenced by RingBuffer< T, N >::getReadSpace(), RingBuffer< T, N >::getWriteSpace(), RingBuffer< T, N >::peekOne(), RingBuffer< T, N >::readOne(), RingBuffer< T, N >::reset(), RingBuffer< T, N >::write(), and RingBuffer< T, N >::zero().

template<typename T, int N = 1>

volatile size_t RingBuffer< T, N >::m_readers[N] [protected]

Definition at line 163 of file RingBuffer.h.

Referenced by RingBuffer< T, N >::getReadSpace(), RingBuffer< T, N >::getWriteSpace(), RingBuffer< T, N >::peek(), RingBuffer< T, N >::peekOne(), RingBuffer< T, N >::read(), RingBuffer< T, N >::readAdding(), RingBuffer< T, N >::readOne(), RingBuffer< T, N >::reset(), RingBuffer< T, N >::RingBuffer(), and RingBuffer< T, N >::skip().

template<typename T, int N = 1>

size_t RingBuffer< T, N >::m_size [protected]

Definition at line 164 of file RingBuffer.h.

Referenced by RingBuffer< T, N >::getReadSpace(), RingBuffer< T, N >::getSize(), RingBuffer< T, N >::getWriteSpace(), RingBuffer< T, N >::mlock(), RingBuffer< T, N >::peek(), RingBuffer< T, N >::read(), RingBuffer< T, N >::readAdding(), RingBuffer< T, N >::readOne(), RingBuffer< T, N >::resize(), RingBuffer< T, N >::skip(), RingBuffer< T, N >::write(), RingBuffer< T, N >::zero(), and RingBuffer< T, N >::~RingBuffer().

template<typename T, int N = 1>

bool RingBuffer< T, N >::m_mlocked [protected]

Definition at line 165 of file RingBuffer.h.

Referenced by RingBuffer< T, N >::mlock(), RingBuffer< T, N >::resize(), and RingBuffer< T, N >::~RingBuffer().

template<typename T, int N = 1>

Scavenger< ScavengerArrayWrapper< T > > RingBuffer< T, N >::m_scavenger [static, protected]

Definition at line 167 of file RingBuffer.h.

Referenced by RingBuffer< T, N >::resize(), RingBuffer< T, N >::RingBuffer(), and RingBuffer< T, N >::~RingBuffer().

---

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

• RingBuffer.h

---