RingBuffer Class Reference

#include <RingBuffer.h>

List of all members.

Public Member Functions

 RingBuffer (size_t size)
void get_read_vector (ringbuffer_data_t *vec)
void get_write_vector (ringbuffer_data_t *vec)
size_t read (char *dest, size_t cnt)
size_t peek (char *dest, size_t cnt)
void read_advance (size_t cnt)
size_t read_space ()
int mlock_buffer ()
void reset ()
size_t write (const char *src, size_t cnt)
void write_advance (size_t cnt)
size_t write_space ()

Detailed Description

The key attribute of a ringbuffer is that it can be safely accessed by two threads simultaneously -- one reading from the buffer and the other writing to it -- without using any synchronization or mutual exclusion primitives. For this to work correctly, there can only be a single reader and a single writer thread. Their identities cannot be interchanged.

Member Function Documentation

void RingBuffer::get_read_vector ( ringbuffer_data_t *  vec  ) 

Fill a data structure with a description of the current readable data held in the ringbuffer. This description is returned in a two element array of ringbuffer_data_t. Two elements are needed because the data to be read may be split across the end of the ringbuffer.

The first element will always contain a valid len field, which may be zero or greater. If the len field is non-zero, then data can be read in a contiguous fashion using the address given in the corresponding buf field.

If the second element has a non-zero len field, then a second contiguous stretch of data can be read from the address given in its corresponding buf field.

Parameters:
vec a pointer to a 2 element array of ringbuffer_data_t.

void RingBuffer::get_write_vector ( ringbuffer_data_t *  vec  ) 

Fill a data structure with a description of the current writable space in the ringbuffer. The description is returned in a two element array of ringbuffer_data_t. Two elements are needed because the space available for writing may be split across the end of the ringbuffer.

The first element will always contain a valid len field, which may be zero or greater. If the len field is non-zero, then data can be written in a contiguous fashion using the address given in the corresponding buf field.

If the second element has a non-zero len field, then a second contiguous stretch of data can be written to the address given in the corresponding buf field.

Parameters:
vec a pointer to a 2 element array of ringbuffer_data_t.

size_t RingBuffer::read ( char *  dest,
size_t  cnt 
)

Read data from the ringbuffer.

Parameters:
dest a pointer to a buffer where data read from the ringbuffer will go.
cnt the number of bytes to read.
Returns:
the number of bytes read, which may range from 0 to cnt.

References read_space().

Referenced by DiskIO::get_cpu_time(), and AudioChannel::get_peak_value().

size_t RingBuffer::peek ( char *  dest,
size_t  cnt 
)

Read data from the ringbuffer. Opposed to read() this function does not move the read pointer. Thus it's a convenient way to inspect data in the ringbuffer in a continous fashion. The price is that the data is copied into a user provided buffer. For "raw" non-copy inspection of the data in the ringbuffer use get_read_vector().

Parameters:
dest a pointer to a buffer where data read from the ringbuffer will go.
cnt the number of bytes to read.
Returns:
the number of bytes read, which may range from 0 to cnt.

References read_space().

void RingBuffer::read_advance ( size_t  cnt  ) 

Advance the read pointer.

After data have been read from the ringbuffer using the pointers returned by get_read_vector(), use this function to advance the buffer pointers, making that space available for future write operations.

Parameters:
cnt the number of bytes read.

size_t RingBuffer::read_space (  ) 

Return the number of bytes available for reading.

Returns:
the number of bytes available to read.

Referenced by DiskIO::get_cpu_time(), AudioChannel::get_peak_value(), peek(), and read().

int RingBuffer::mlock_buffer (  ) 

Lock a ringbuffer data block into memory.

Uses the mlock() system call. This is not a realtime operation.

void RingBuffer::reset (  ) 

Reset the read and write pointers, making an empty buffer.

This is not thread safe.

size_t RingBuffer::write ( const char *  src,
size_t  cnt 
)

Write data into the ringbuffer.

Parameters:
src a pointer to the data to be written to the ringbuffer.
cnt the number of bytes to write.
Returns:
the number of bytes write, which may range from 0 to cnt

References write_space().

void RingBuffer::write_advance ( size_t  cnt  ) 

Advance the write pointer.

After data have been written the ringbuffer using the pointers returned by get_write_vector(), use this function to advance the buffer pointer, making the data available for future read operations.

Parameters:
cnt the number of bytes written.

size_t RingBuffer::write_space (  ) 

Return the number of bytes available for writing.

Returns:
the amount of free space (in bytes) available for writing.

Referenced by write().

The documentation for this class was generated from the following files:
Generated on Sun Mar 8 12:44:05 2009 for traverso by  doxygen 1.5.5