Circular Buffer

Defines
#define	BUFFER_FULL(buf)   (buffer_nbytes(buf) == ((buf)->size - 1))
#define	BUFFER_EMPTY(buf)   ((buf)->front == (buf)->back)
Functions
void	buffer_add (BUFFER *buf, char val)
BUFFER *	buffer_create (uint16_t size)
void	buffer_flush (BUFFER *buf)
uint16_t	buffer_nbytes (BUFFER *buf)
char	buffer_remove (BUFFER *buf)
void	buffer_reset (BUFFER *buf, uint16_t front, uint16_t back)
int8_t	buffer_state (BUFFER *buf)

---

Define Documentation

#define BUFFER_EMPTY

(

buf

)

((buf)->front == (buf)->back)

Indicate whether the buffer is empty

Parameters:

buf

A pointer to an existing and initialized BUFFER structure.

Returns:

1 if the buffer is empty (with 0 bytes), or
0 if the buffer is not empty

Author:

Andrew H. Fagg (fagg@cs.ou.edu)

Referenced by buffer_flush(), buffer_remove(), and buffer_state().

#define BUFFER_FULL

(

buf

)

(buffer_nbytes(buf) == ((buf)->size - 1))

Indicate whether the buffer is full

Parameters:

buf

A pointer to an existing and initialized BUFFER structure.

Returns:

1 if the buffer is full (with size-1 bytes), or
0 if the buffer is not full

Author:

Andrew H. Fagg (fagg@cs.ou.edu)

Referenced by buffer_add(), and buffer_state().

---

Function Documentation

void buffer_add	(	BUFFER *	buf,
		char	val
	)

Add a byte to the buffer. Will busy wait if there is no room in the buffer.

Parameters:

	buf	A pointer to an existing and initialized BUFFER structure.
	val	A character value to insert into the buffer.

Author:

Andrew H. Fagg (fagg@cs.ou.edu)

References BUFFER::back, BUFFER::buffer, BUFFER_FULL, and BUFFER::size.

BUFFER* buffer_create

(

uint16_t

size

)

Create and initialize a circular buffer object. Allocates the buffer object space from the heap.

Parameters:

size

The number of bytes in the circular buffer. Note that a full buffer has size-1 bytes in it.

Returns:

A pointer to an existing and initialized BUFFER structure.
NULL if an error has occurred

Author:

Andrew H. Fagg (fagg@cs.ou.edu)

References BUFFER::back, BUFFER::buffer, BUFFER::front, and BUFFER::size.

void buffer_flush

(

BUFFER *

buf

)

Remove all elements in the specified buffer

Parameters:

buf

A pointer to an existing and initialized BUFFER structure.

Author:

Andrew H. Fagg (fagg@cs.ou.edu)

References BUFFER_EMPTY, and buffer_remove().

uint16_t buffer_nbytes

(

BUFFER *

buf

)

Return the number of bytes that are currently stored in the buffer.

Parameters:

buf

A pointer to an existing and initialized BUFFER structure.

Returns:

The number of bytes in the buffer.

Author:

Andrew H. Fagg (fagg@cs.ou.edu)

References BUFFER::back, BUFFER::front, and BUFFER::size.

char buffer_remove

(

BUFFER *

buf

)

Return the next element in the buffer. Will busy wait until there is something to return

Parameters:

buf

A pointer to an existing and initialized BUFFER structure.

Returns:

The next value in the buffer

Author:

Andrew H. Fagg (fagg@cs.ou.edu)

References BUFFER::buffer, BUFFER_EMPTY, BUFFER::front, and BUFFER::size.

Referenced by buffer_flush().

void buffer_reset	(	BUFFER *	buf,
		uint16_t	front,
		uint16_t	back
	)

Reset the state of the buffer indices (for internal use). Note: must guarantee that no reader or writer is currently accessing this object (such as an ISR)

Parameters:

	buf	A pointer to an existing and initialized BUFFER structure.
	front	The index of the next byte in the buffer (0 ... size-1)
	back	The index of the next avaiable space in the buffer (0 ... size-1).

Author:

Andrew H. Fagg (fagg@cs.ou.edu)

References BUFFER::back, and BUFFER::front.

int8_t buffer_state

(

BUFFER *

buf

)

Return the state of the specified buffer.

Parameters:

buf

A pointer to an existing and initialized BUFFER structure.

Returns:

-1 if buffer is empty
0 if buffer is not empty nor full
1 if buffer is full

Author:

Andrew H. Fagg (fagg@cs.ou.edu)

References BUFFER_EMPTY, and BUFFER_FULL.