/home/maxime/Projets/Mixxx/1.10/mixxx/src/util/pa_ringbuffer.h File Reference

Single-reader single-writer lock-free ring buffer. More...

Go to the source code of this file.

Classes
struct	PaUtilRingBuffer
Typedefs
typedef long	ring_buffer_size_t
typedef struct PaUtilRingBuffer	PaUtilRingBuffer
Functions
ring_buffer_size_t	PaUtil_InitializeRingBuffer (PaUtilRingBuffer *rbuf, ring_buffer_size_t elementSizeBytes, ring_buffer_size_t elementCount, void *dataPtr)
void	PaUtil_FlushRingBuffer (PaUtilRingBuffer *rbuf)
ring_buffer_size_t	PaUtil_GetRingBufferWriteAvailable (const PaUtilRingBuffer *rbuf)
ring_buffer_size_t	PaUtil_GetRingBufferReadAvailable (const PaUtilRingBuffer *rbuf)
ring_buffer_size_t	PaUtil_WriteRingBuffer (PaUtilRingBuffer *rbuf, const void *data, ring_buffer_size_t elementCount)
ring_buffer_size_t	PaUtil_ReadRingBuffer (PaUtilRingBuffer *rbuf, void *data, ring_buffer_size_t elementCount)
ring_buffer_size_t	PaUtil_GetRingBufferWriteRegions (PaUtilRingBuffer *rbuf, ring_buffer_size_t elementCount, void **dataPtr1, ring_buffer_size_t *sizePtr1, void **dataPtr2, ring_buffer_size_t *sizePtr2)
ring_buffer_size_t	PaUtil_AdvanceRingBufferWriteIndex (PaUtilRingBuffer *rbuf, ring_buffer_size_t elementCount)
ring_buffer_size_t	PaUtil_GetRingBufferReadRegions (PaUtilRingBuffer *rbuf, ring_buffer_size_t elementCount, void **dataPtr1, ring_buffer_size_t *sizePtr1, void **dataPtr2, ring_buffer_size_t *sizePtr2)
ring_buffer_size_t	PaUtil_AdvanceRingBufferReadIndex (PaUtilRingBuffer *rbuf, ring_buffer_size_t elementCount)

---

Detailed Description

Single-reader single-writer lock-free ring buffer.

PaUtilRingBuffer is a ring buffer used to transport samples between different execution contexts (threads, OS callbacks, interrupt handlers) without requiring the use of any locks. This only works when there is a single reader and a single writer (ie. one thread or callback writes to the ring buffer, another thread or callback reads from it).

The PaUtilRingBuffer structure manages a ring buffer containing N elements, where N must be a power of two. An element may be any size (specified in bytes).

The memory area used to store the buffer elements must be allocated by the client prior to calling PaUtil_InitializeRingBuffer() and must outlive the use of the ring buffer.

Definition in file pa_ringbuffer.h.

---

Typedef Documentation

typedef struct PaUtilRingBuffer PaUtilRingBuffer

typedef long ring_buffer_size_t

Definition at line 80 of file pa_ringbuffer.h.

---

Function Documentation

ring_buffer_size_t PaUtil_AdvanceRingBufferReadIndex	(	PaUtilRingBuffer *	rbuf,
		ring_buffer_size_t	elementCount
	)

Advance the read index to the next location to be read.

Parameters:

rbuf	The ring buffer.
elementCount	The number of elements to advance.

Returns:

The new position.

Definition at line 188 of file pa_ringbuffer.c.

Here is the caller graph for this function:

ring_buffer_size_t PaUtil_AdvanceRingBufferWriteIndex	(	PaUtilRingBuffer *	rbuf,
		ring_buffer_size_t	elementCount
	)

Advance the write index to the next location to be written.

Parameters:

rbuf	The ring buffer.
elementCount	The number of elements to advance.

Returns:

The new position.

Definition at line 140 of file pa_ringbuffer.c.

Here is the caller graph for this function:

void PaUtil_FlushRingBuffer

(

PaUtilRingBuffer *

rbuf

)

Reset buffer to empty. Should only be called when buffer is NOT being read or written.

Parameters:

rbuf	The ring buffer.

Definition at line 94 of file pa_ringbuffer.c.

Here is the caller graph for this function:

ring_buffer_size_t PaUtil_GetRingBufferReadAvailable

(

const PaUtilRingBuffer *

rbuf

)

Retrieve the number of elements available in the ring buffer for reading.

Parameters:

rbuf	The ring buffer.

Returns:

The number of elements available for reading.

Definition at line 81 of file pa_ringbuffer.c.

Here is the caller graph for this function:

ring_buffer_size_t PaUtil_GetRingBufferReadRegions	(	PaUtilRingBuffer *	rbuf,
		ring_buffer_size_t	elementCount,
		void **	dataPtr1,
		ring_buffer_size_t *	sizePtr1,
		void **	dataPtr2,
		ring_buffer_size_t *	sizePtr2
	)

Get address of region(s) from which we can read data.

Parameters:

rbuf	The ring buffer.
elementCount	The number of elements desired.
dataPtr1	The address where the first (or only) region pointer will be stored.
sizePtr1	The address where the first (or only) region length will be stored.
dataPtr2	The address where the second region pointer will be stored if the first region is too small to satisfy elementCount.
sizePtr2	The address where the second region length will be stored if the first region is too small to satisfy elementCount.

Returns:

The number of elements available for reading.

Definition at line 155 of file pa_ringbuffer.c.

Here is the call graph for this function:

Here is the caller graph for this function:

ring_buffer_size_t PaUtil_GetRingBufferWriteAvailable

(

const PaUtilRingBuffer *

rbuf

)

Retrieve the number of elements available in the ring buffer for writing.

Parameters:

rbuf	The ring buffer.

Returns:

The number of elements available for writing.

Definition at line 87 of file pa_ringbuffer.c.

Here is the call graph for this function:

Here is the caller graph for this function:

ring_buffer_size_t PaUtil_GetRingBufferWriteRegions	(	PaUtilRingBuffer *	rbuf,
		ring_buffer_size_t	elementCount,
		void **	dataPtr1,
		ring_buffer_size_t *	sizePtr1,
		void **	dataPtr2,
		ring_buffer_size_t *	sizePtr2
	)

Get address of region(s) to which we can write data.

Parameters:

rbuf	The ring buffer.
elementCount	The number of elements desired.
dataPtr1	The address where the first (or only) region pointer will be stored.
sizePtr1	The address where the first (or only) region length will be stored.
dataPtr2	The address where the second region pointer will be stored if the first region is too small to satisfy elementCount.
sizePtr2	The address where the second region length will be stored if the first region is too small to satisfy elementCount.

Returns:

The room available to be written or elementCount, whichever is smaller.

Definition at line 105 of file pa_ringbuffer.c.

Here is the call graph for this function:

Here is the caller graph for this function:

ring_buffer_size_t PaUtil_InitializeRingBuffer	(	PaUtilRingBuffer *	rbuf,
		ring_buffer_size_t	elementSizeBytes,
		ring_buffer_size_t	elementCount,
		void *	dataPtr
	)

Initialize Ring Buffer to empty state ready to have elements written to it.

Parameters:

rbuf	The ring buffer.
elementSizeBytes	The size of a single data element in bytes.
elementCount	The number of elements in the buffer (must be a power of 2).
dataPtr	A pointer to a previously allocated area where the data will be maintained. It must be elementCount*elementSizeBytes long.

Returns:

-1 if elementCount is not a power of 2, otherwise 0.

Definition at line 67 of file pa_ringbuffer.c.

Here is the call graph for this function:

Here is the caller graph for this function:

ring_buffer_size_t PaUtil_ReadRingBuffer	(	PaUtilRingBuffer *	rbuf,
		void *	data,
		ring_buffer_size_t	elementCount
	)

Read data from the ring buffer.

Parameters:

rbuf	The ring buffer.
data	The address where the data should be stored.
elementCount	The number of elements to be read.

Returns:

The number of elements read.

Definition at line 221 of file pa_ringbuffer.c.

Here is the call graph for this function:

Here is the caller graph for this function:

ring_buffer_size_t PaUtil_WriteRingBuffer	(	PaUtilRingBuffer *	rbuf,
		const void *	data,
		ring_buffer_size_t	elementCount
	)

Write data to the ring buffer.

Parameters:

rbuf	The ring buffer.
data	The address of new data to write to the buffer.
elementCount	The number of elements to be written.

Returns:

The number of elements written.

Definition at line 199 of file pa_ringbuffer.c.

Here is the call graph for this function:

Here is the caller graph for this function: