visr::rbbl::CircularBuffer< DataType > Class Template Reference

#include <circular_buffer.hpp>

Classes
class	Impl

Public Types
using	DelayIndexType = std::size_t

Public Member Functions
	CircularBuffer (std::size_t numberOfChannels, std::size_t length, std::size_t alignment=0)
	~CircularBuffer ()
std::size_t	numberOfChannels () const
std::size_t	length () const
std::size_t	stride () const
void	write (DataType const *const *writeData, std::size_t numberOfChannels, std::size_t numberOfSamples, std::size_t alignmentElements=0)
void	write (DataType const *writeData, std::size_t channelStrideElements, std::size_t numberOfChannels, std::size_t numberOfSamples, std::size_t alignmentElements=0)
void	write (efl::BasicMatrix< DataType > const &writeData)
DataType *	getFirstWritePointer ()
void	getWritePointers (DataType **writePointers)
void	commitWrite (std::size_t numberOfElementsWritten)
void	getReadPointers (DelayIndexType delay, DataType const **readPointers) const
void	getReadPointers (DelayIndexType const *const delay, DataType const **readPointers) const
DataType const *	getReadPointer (std::size_t channelIndex, DelayIndexType delay) const

Detailed Description

template<typename DataType>
class visr::rbbl::CircularBuffer< DataType >

A generic data type to emulate contiguous memory buffers. It enables a linear, wraparound-free access to the whole allocated size of the buffer. It is implemented as a multichannel buffer with an arbitrary number of channels and a common write position for all channels. Read access is relative to the write position and can be channel-specific. Note that the write index is at the position of the next write operation, i.e., one in front of the most recently written input. This class is optimized for multiple read accesses (i.e., more frequent random reads than write operations.) The basic C++ implementation duplicates the written data two times, but platform-specific implementations might be more sophisticated, e.g., combining shared memory segments to form a contiguous memory area.

Template Parameters

DataType

The floating-point element type for the contained samples.

Member Typedef Documentation

DelayIndexType

template<typename DataType>

using visr::rbbl::CircularBuffer< DataType >::DelayIndexType = std::size_t

The index type used to address the read samples relative to the write index. Positive values denote past samples. Since this type is unsigned, passing a negative value to this parameter results in a hugely misplaced read operation.

Constructor & Destructor Documentation

CircularBuffer()

template<typename DataType >

visr::rbbl::CircularBuffer< DataType >::CircularBuffer ( std::size_t  numberOfChannels, std::size_t  length, std::size_t  alignment = 0  )

explicit

Constructor.

Parameters

numberOfChannels	The number of simultaneous channels contained in the circular buffer.
length	The requested size of the ringbuffer. The actual length might be larger, but this does not affect the functionality of the ringbuffer (if not accessed outside the requested size).
alignment	The alignment in multiples of the element data type (must be an integer power of two). Determines the address of the underlying memory buffer and possibly also the total length of the ringbuffer, i.e., the buffer is padded to the next multiple of the alignment.

~CircularBuffer()

template<typename DataType >

visr::rbbl::CircularBuffer< DataType >::~CircularBuffer

(

)

Destructor.

Member Function Documentation

commitWrite()

template<typename DataType >

void visr::rbbl::CircularBuffer< DataType >::commitWrite

(

std::size_t

numberOfElementsWritten

)

Finish a write operation by advancing the write index. Depending on the underlying operation, this call might also trigger other operations, e.g., copying/duplication of sample data.

Parameters

numberOfElementsWritten

The advance of the write index (given as number of elements)

getFirstWritePointer()

template<typename DataType >

DataType * visr::rbbl::CircularBuffer< DataType >::getFirstWritePointer

(

)

Get the address of the current write position for the first channel. The positions of the other channels can be determinde from this value using stride(). This method can be used to write directly into the matrix.

Note

To take effect, writing the data into the buffer must be concluded by a commitWriteOperation() call.

Read accesses between writing new data and calling commitWriteOperation() might lead to incorrect values, because data within the allocated length of the ringbuffeer might be overwritten before advancing the write pointer.

getReadPointer()

template<typename DataType>

DataType const* visr::rbbl::CircularBuffer< DataType >::getReadPointer ( std::size_t  channelIndex, DelayIndexType  delay  ) const

inline

Retrieve a read pointer for a certain channel.

Parameters

channelIndex	The channel for which the pointer is requested.
delay	The delay (relative to the write position)

Note

This method is inline and does not check for the correct range of the arguments (except in debug builds).

getReadPointers() [1/2]

template<typename DataType>

void visr::rbbl::CircularBuffer< DataType >::getReadPointers	(	DelayIndexType	delay,
		DataType const **	readPointers
	)		const

Retrieve read pointers relative to the current write position.

Parameters

	delay	Common delay for all channels. As the write index is one position after the last written value, a delay value of 1 corresponds to the most recently written value.
[out]	readPointers	A pointer array to hold the read positions for all channels. Must provide space for numberOfChannels() elements.

Exceptions

std::invalid_argument

If delay exceeds the length of the circular buffer.

getReadPointers() [2/2]

template<typename DataType>

void visr::rbbl::CircularBuffer< DataType >::getReadPointers	(	DelayIndexType const *const	delay,
		DataType const **	readPointers
	)		const

Retrieve read pointers relative to the current write position.

Parameters

	delay	An array of delay values, one for each channel. Must contain numberOfChannels() elements. As the write index is one position after the last written value, a delay value of 1 corresponds to the most recently written value.
[out]	readPointers	A pointer array to hold the read positions for all channels. Must provide space for numberOfChannels() elements.

Exceptions

std::invalid_argument

If any element of delay exceeds the length of the circular buffer.

getWritePointers()

template<typename DataType>

void visr::rbbl::CircularBuffer< DataType >::getWritePointers

(

DataType **

writePointers

)

Get the addresses of the current write position for all channels. This method can be used to write directly into the matrix.

Parameters

[out]

writePointers

The write positions. The argument must provide room for numberOfChannels() pointers.

Note

To take effect, writing the data into the buffer must be concluded by a commitWriteOperation call.

length()

template<typename DataType>

std::size_t visr::rbbl::CircularBuffer< DataType >::length ( ) const

inline

Return the (requested) length of the ringbuffer.

numberOfChannels()

template<typename DataType>

std::size_t visr::rbbl::CircularBuffer< DataType >::numberOfChannels ( ) const

inline

Return the number of simultaneous data channels.

stride()

template<typename DataType>

std::size_t visr::rbbl::CircularBuffer< DataType >::stride ( ) const

inline

Return the address difference (in multiples of the element size) between the same position for two adjacent channels.

write() [1/3]

template<typename DataType>

void visr::rbbl::CircularBuffer< DataType >::write	(	DataType const *const *	writeData,
		std::size_t	numberOfChannels,
		std::size_t	numberOfSamples,
		std::size_t	alignmentElements = 0
	)

Write a given number of samples for all contained channels into the circular buffer and advance the write pointer afterwards.

Parameters

writeData	The data to be written. The vector must contain at least numberOfChannels pointers, and each pointers must point to an array of at least numberOfSamples samples.
numberOfChannels	The number of signal channels, must match the number of channels of the matrix.
numberOfSamples	The number of samples per channel to be written.
alignmentElements	A alignment guarantee (measure in samples) for the arrays pointed to by writeData.

Exceptions

std::invalid_argument

If the numberOfChannels argument does not match the object's number of channels, or if numberOfSamples exceeds the requested length of the circular buffer.

write() [2/3]

template<typename DataType>

void visr::rbbl::CircularBuffer< DataType >::write	(	DataType const *	writeData,
		std::size_t	channelStrideElements,
		std::size_t	numberOfChannels,
		std::size_t	numberOfSamples,
		std::size_t	alignmentElements = 0
	)

write() [3/3]

template<typename DataType>

void visr::rbbl::CircularBuffer< DataType >::write

(

efl::BasicMatrix< DataType > const &

writeData

)

Write samples from a matrix object into the circular buffer and advance the write index afterwards.

Parameters

writeData

A matrix containing the samples to be written.

Exceptions

std::invalid_argument

If writeData.numberOfChannels() does not match the object's number of channels, or if writeData.numberOfColumns() exceeds the requested length of the circular buffer.

Note

The alignment of the input matrix is determined from the alignElements() method of writeData.

---

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

• /Users/williammorris/builds/bc5dce7e/0/s3a/VISR/src/librbbl/circular_buffer.hpp
• /Users/williammorris/builds/bc5dce7e/0/s3a/VISR/src/librbbl/circular_buffer.cpp