svcore  1.9
RingBuffer< T, N > Class Template Reference

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

#include <RingBuffer.h>

List of all members.

Public Member Functions

 RingBuffer (int n)
 Create a ring buffer with room to write n samples.
virtual ~RingBuffer ()
int getSize () const
 Return the total capacity of the ring buffer in samples.
RingBuffer< T, N > * resized (int newSize) const
 Return a new ring buffer (allocated with "new" -- caller must delete when no longer needed) of the given size, containing the same data as this one as perceived by reader 0 of this buffer.
bool mlock ()
 Lock the ring buffer into physical memory.
void reset ()
 Reset read and write pointers, thus emptying the buffer.
int getReadSpace (int R=0) const
 Return the amount of data available for reading by reader R, in samples.
int getWriteSpace () const
 Return the amount of space available for writing, in samples.
int read (T *destination, int n, int R=0)
 Read n samples from the buffer, for reader R.
int readAdding (T *destination, int n, int R=0)
 Read n samples from the buffer, for reader R, adding them to the destination.
readOne (int R=0)
 Read one sample from the buffer, for reader R.
int peek (T *destination, int n, int R=0) const
 Read n samples from the buffer, if available, for reader R, without advancing the read pointer -- i.e.
peekOne (int R=0) const
 Read one sample from the buffer, if available, without advancing the read pointer -- i.e.
int skip (int n, int R=0)
 Pretend to read n samples from the buffer, for reader R, without actually returning them (i.e.
int write (const T *source, int n)
 Write n samples to the buffer.
int zero (int n)
 Write n zero-value samples to the buffer.

Protected Attributes

T * m_buffer
bool m_mlocked
int m_writer
int * m_readers
int m_size
int m_spare

Private Member Functions

 RingBuffer (const RingBuffer &)
RingBufferoperator= (const RingBuffer &)

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 46 of file RingBuffer.h.


Constructor & Destructor Documentation

template<typename T , int N>
RingBuffer< T, N >::RingBuffer ( int  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 179 of file RingBuffer.h.

References RingBuffer< T, N >::m_readers.

template<typename T , int N>
RingBuffer< T, N >::~RingBuffer ( ) [virtual]

Definition at line 204 of file RingBuffer.h.

References MUNLOCK.

template<typename T, int N = 1>
RingBuffer< T, N >::RingBuffer ( const RingBuffer< T, N > &  ) [private]

Member Function Documentation

template<typename T , int N>
int 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 220 of file RingBuffer.h.

Referenced by MIDIInput::postEvent(), and OSCQueue::postMessage().

template<typename T , int N>
RingBuffer< T, N > * RingBuffer< T, N >::resized ( int  newSize) const

Return a new ring buffer (allocated with "new" -- caller must delete when no longer needed) of the given size, containing the same data as this one as perceived by reader 0 of this buffer.

If another thread reads from or writes to this buffer during the call, the contents of the new buffer may be incomplete or inconsistent. If this buffer's data will not fit in the new size, the contents are undefined.

Definition at line 231 of file RingBuffer.h.

References RingBuffer< T, N >::write().

template<typename T , int N>
bool RingBuffer< T, N >::mlock ( )

Lock the ring buffer into physical memory.

Returns true for success.

Definition at line 253 of file RingBuffer.h.

References 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 262 of file RingBuffer.h.

Referenced by DSSIPluginInstance::clearEvents(), and DSSIPluginInstance::discardEvents().

template<typename T , int N>
int RingBuffer< T, N >::getReadSpace ( int  R = 0) const

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

Definition at line 274 of file RingBuffer.h.

Referenced by MIDIInput::getEventsAvailable(), OSCQueue::getMessagesAvailable(), DSSIPluginInstance::run(), DSSIPluginInstance::runGrouped(), and OSCQueue::~OSCQueue().

template<typename T , int N>
int RingBuffer< T, N >::getWriteSpace ( ) const

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

Definition at line 292 of file RingBuffer.h.

Referenced by MIDIInput::postEvent(), and OSCQueue::postMessage().

template<typename T, int N>
int RingBuffer< T, N >::read ( T *  destination,
int  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 317 of file RingBuffer.h.

References MBARRIER.

template<typename T, int N>
int RingBuffer< T, N >::readAdding ( T *  destination,
int  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 354 of file RingBuffer.h.

References MBARRIER.

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 392 of file RingBuffer.h.

References MBARRIER.

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

template<typename T, int N>
int RingBuffer< T, N >::peek ( T *  destination,
int  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 415 of file RingBuffer.h.

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 449 of file RingBuffer.h.

Referenced by DSSIPluginInstance::run(), and DSSIPluginInstance::runGrouped().

template<typename T , int N>
int RingBuffer< T, N >::skip ( int  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 470 of file RingBuffer.h.

Referenced by DSSIPluginInstance::run(), and DSSIPluginInstance::runGrouped().

template<typename T, int N>
int RingBuffer< T, N >::write ( const T *  source,
int  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 491 of file RingBuffer.h.

References MBARRIER.

Referenced by MIDIInput::postEvent(), OSCQueue::postMessage(), RingBuffer< T, N >::resized(), and DSSIPluginInstance::sendEvent().

template<typename T , int N>
int RingBuffer< T, N >::zero ( int  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 527 of file RingBuffer.h.

References MBARRIER.

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 166 of file RingBuffer.h.

template<typename T, int N = 1>
bool RingBuffer< T, N >::m_mlocked [protected]

Definition at line 167 of file RingBuffer.h.

template<typename T, int N = 1>
int RingBuffer< T, N >::m_writer [protected]

Definition at line 168 of file RingBuffer.h.

template<typename T, int N = 1>
int* RingBuffer< T, N >::m_readers [protected]

Definition at line 169 of file RingBuffer.h.

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

template<typename T, int N = 1>
int RingBuffer< T, N >::m_size [protected]

Definition at line 170 of file RingBuffer.h.

template<typename T, int N = 1>
int RingBuffer< T, N >::m_spare [protected]

Definition at line 171 of file RingBuffer.h.


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