Ring Buffer (ringbuffer)

Provides a two-dimensional circular buffer with homogeneous elements

See other classes’ docstrings for more information:

• RingBuffer: the buffer
• datatypes: supported datatypes
• BufferHeader: header structure
• BufferError: error definition

class ringbuffer.RingBuffer

Provides a two-dimensional circular buffer with homogeneous elements

The buffer can be used simultaneously by several processes, because both data and metadata are stored in a single sharectypes byte array. First, the buffer object is created and initialized in one of the processes. Second, its raw array is shared with others. Third, those processes create their own RingBuffer objects and initialize them so that they all point to the same shared raw array (see initialize_from_raw method’s docstring).

See also

initialize

allocate new buffer

initialize_from_raw

use another buffer’s raw array

Notes

The buffer consists of a buffer interface (self) and the raw sharectypes byte array which has header, data, and pocket subsections (self.raw).

1. header section Contains the metadata such as size of the sections, current write pointer, datatype, number of channels (number of columns) and total number of samples (not bytes) written

2. data section Contains the actual data in the buffer. When the write pointer reaches the end of the section it jumps to the beginning overwriting the old data.

3. pocket section The pocket section always contains the same data as the leftmost such chunk of the data section. This is done to avoid data copies when reading a data chunk (up to the size of the pocket) first part of which happens to be located at the end of the data section while the second - already in the beginning. This might be useful when reading the data with a sliding window.

Attributes

is_initialized	Indicates whether the buffer is initialized, read-only (bool)
nChannels	Dimensionality of a sample, read-only (int)
bufSize	The buffer capacity in samples, read-only (int)
pocketSize	Size of the buffer pocket in samples, read-only (int)
nptype	The type of the data in the buffer, read-only (string)
raw	Raw buffer array, read-only (sharedctypes, char)
writePtr	Current write pointer position, read-only (int)

Methods

check_availablility(sampleStart, sampleEnd)	Checks whether the requested data samples are available.
get_data(sampleStart, sampleEnd[, wprotect])	Gets the data from the buffer.
initialize(nChannels, nSamples[, ...])	Initializes the buffer with a new raw array
initialize_from_raw(raw)	Initializes the buffer with the compatible external raw array.
put_data(data)	Pushes the data to the buffer

bufSize

The buffer capacity in samples, read-only (int)

check_availablility(sampleStart, sampleEnd)

Checks whether the requested data samples are available.

Parameters :

sampleStart : int

first sample index (included)

sampleEnd : int

last samples index (excluded)

Returns :

0 :

if the data is available

2 :

if (part of) the data is already overwritten

3 :

if (part of) the data is not yet in the buffer

get_data(sampleStart, sampleEnd, wprotect=True)

Gets the data from the buffer. If possible, the data is returned in the form of a numpy view on the corresponding chunk (without copy). If the data is not available, rises an exception

Parameters :

sampleStart : int

first sample index (included)

sampleEnd : int

last samples index (excluded)

wprotect : bool, optional

protect returned views from occasional writes

Returns :

data : data chunk (numpy view or numpy array)

Raises :

BufferError :

If the data is not available

initialize(nChannels, nSamples, windowSize=1, nptype='float32')

Initializes the buffer with a new raw array

Parameters :

nChannels : int

dimensionality of a single sample

nSamples : int

the buffer capacity in samples

windowSize : int, optional

optional, the size of the window to be used for reading the data. The pocket of the this size will be created

nptype : string, optional

the type of the data to be stored

initialize_from_raw(raw)

Initializes the buffer with the compatible external raw array. All the metadata will be read from the header region of this array.

Parameters :

raw : sharedctypes char array

the raw array to initialize with

is_initialized

Indicates whether the buffer is initialized, read-only (bool)

nChannels

Dimensionality of a sample, read-only (int)

nSamplesWritten

nptype

The type of the data in the buffer, read-only (string)

pocketSize

Size of the buffer pocket in samples, read-only (int)

put_data(data)

Pushes the data to the buffer

Parameters :

data : ndarray

properly shaped numpy array

raw

Raw buffer array, read-only (sharedctypes, char)

writePtr

Current write pointer position, read-only (int)

class ringbuffer.BufferHeader

A ctypes structure describing the buffer header

Attributes

bufSizeBytes	Structure/Union member
pocketSizeBytes	Structure/Union member
dataType	Structure/Union member
nChannels	Structure/Union member
nSamplesWritten	Structure/Union member

bufSizeBytes

Structure/Union member

dataType

Structure/Union member

nChannels

Structure/Union member

nSamplesWritten

Structure/Union member

pocketSizeBytes

Structure/Union member

exception ringbuffer.BufferError(code)

Represents different types of buffer errors

class ringbuffer.datatypes

A helper class to interpret the typecode read from buffer header. To add new supported datatypes, add them to the ‘type’ dictionary

Methods

get_code(type)	Gets buffer typecode given numpy datatype
get_type(code)	Gets numpy datatype given a buffer typecode

classmethod get_code(type)

Gets buffer typecode given numpy datatype

Parameters :

type : string

numpy datatype (e.g. ‘float32’)

classmethod get_type(code)

Gets numpy datatype given a buffer typecode

Parameters :

code : int

typecode (e.g. 0)

types = {0: 'float32', 1: 'int16'}