MityDSP::tcDspCircBuffer Class Reference

The tcDspCircBuffer class provides a thread safe circular buffer interface supporting arbitrary size and arbitrary read/write requests. More...

#include <DspCircBuffer.h>

List of all members.

Public Member Functions
	tcDspCircBuffer (unsigned int size, void *mpData=NULL, SEM_Handle ahNotifyHandle=NULL)
	The constructor for the circular buffer class.
	~tcDspCircBuffer (void)
	The Destructor for the circular buffer class.
int	Read (void *buffer, int maxlen, unsigned int timeout=SYS_FOREVER)
	Read a block of data from the circular buffer.
int	Write (void *buffer, int len, unsigned int timeout=SYS_FOREVER)
	Write a block of data to the circular buffer.
int	BytesInBuffer (unsigned int timeout=SYS_FOREVER)
	Determine the number of bytes sitting in the buffer.

---

Detailed Description

The tcDspCircBuffer class provides a thread safe circular buffer interface supporting arbitrary size and arbitrary read/write requests.

The buffer is built on the heap, or may be passed in for special cases (e.g., using L2 memory as a buffer).

---

Constructor & Destructor Documentation

tcDspCircBuffer::tcDspCircBuffer	(	unsigned int	size,
		void *	apData = NULL,
		SEM_Handle	ahNotifyHandle = NULL
	)

The constructor for the circular buffer class.

Parameters:

[in]	size	length of buffer in bytes
[in]	apData	pointer to buffer buffer to use. If NULL (default) a buffer will be allocated on the heap of size size.
[in]	ahNotifyHandle	a SEM_handle reference to be SEM_post()'d when data is written to the buffer. May be (default is) NULL.

Returns:

N/A

See also:

DspCircBuffer.h

tcDspCircBuffer::~tcDspCircBuffer

(

void

)

The Destructor for the circular buffer class.

---

Member Function Documentation

int tcDspCircBuffer::Read	(	void *	buffer,
		int	maxlen,
		unsigned int	timeout = SYS_FOREVER
	)

Read a block of data from the circular buffer.

The buffer pointers are automatically advanced following the read.

Parameters:

[in]	buffer	location to place the data read
[in]	maxlen	maximum number of bytes to read into the buffer
[in]	timeout	number of system clock ticks to wait for access to the buffer class (default is SYS_FOREVER).

Return values:

if

successful, the number of bytes actually read into the buffer. This could be from 0 bytes to maxlen bytes. If unsuccessful, e.g. the buffer is locked by another thread, a value of -1 is returned.

int tcDspCircBuffer::Write	(	void *	buffer,
		int	len,
		unsigned int	timeout = SYS_FOREVER
	)

Write a block of data to the circular buffer.

The buffer pointers are automatically advanced following the write. If non-zero bytes are written the Notify Handle passed into the constructor will be posted.

Parameters:

[in]	buffer	location read the data to write to buffer
[in]	len	number of bytes to write into the buffer
[in]	timeout	number of system clock ticks to wait for access to the buffer class (default is SYS_FOREVER).

Return values:

if

successful, the number of bytes actually written into the buffer. This could be from 0 bytes to len bytes. If unsuccessful, e.g. the buffer is locked by another thread, a value of -1 is returned.

Warning:

if a call to Write returns a length less than len, there is no guarantee that a followup call to Write() with the remainder will pack the remaining bytes directly behind those written the first time. I.E., it's possible for another thread to call Write() in-between. This condition is an indicator that there is a peak load problem and that the circular buffer is undersized (or is dangerously close to being undersized).

int tcDspCircBuffer::BytesInBuffer

(

unsigned int

timeout = SYS_FOREVER

)

Determine the number of bytes sitting in the buffer.

Parameters:

[in]

timeout

number of system clock ticks to wait for access to the buffer class (default is SYS_FOREVER).

Return values:

if

successful, the number of bytes sitting in the buffer (for reading) at the time of the call.

Note:

in general, there is only one reader thread for a circular buffer any potentially many writers. Given this model, the value returned from BytesInBuffer() should typically imply a minimum amount of data that should be available for a call to the Read() method.