ring_buffer.h

Simple circular byte buffer. This implementation is not thread-safe. In particular, none of these functions is guaranteed to be re-entrant.

Ring Buffer Type

struct ring_buffer

Ring buffer type.

The buffer is empty when head == tail.

The buffer is full when the head is one byte in front of the tail, modulo buffer length.

One byte is left free to distinguish empty from full.

Public Members

uint8 * buf

Buffer items are stored into.

uint16 head

Index of the next item to remove.

uint16 tail

Index where the next item will get inserted.

uint16 size

Buffer capacity minus one.

Ring Buffer Operations

void rb_init(ring_buffer * rb, uint16 size, uint8 * buf)

Initialise a ring buffer.

Parameters:

• rb -

  Instance to initialise

• size -

  Number of items in buf. The ring buffer will always leave one element unoccupied, so the maximum number of elements it can store will be size - 1. Thus, size must be at least 2.

• buf -

  Buffer to store items into

uint16 rb_full_count(ring_buffer * rb)

Return the number of elements stored in the ring buffer.

Parameters:

• rb -

  Buffer whose elements to count.

int rb_is_full(ring_buffer * rb)

Returns true if and only if the ring buffer is full.

Parameters:

• rb -

  Buffer to test.

int rb_is_empty(ring_buffer * rb)

Returns true if and only if the ring buffer is empty.

Parameters:

• rb -

  Buffer to test.

void rb_insert(ring_buffer * rb, uint8 element)

Append element onto the end of a ring buffer.

Parameters:

• rb -

  Buffer to append onto.

• element -

  Value to append.

uint8 rb_remove(ring_buffer * rb)

Remove and return the first item from a ring buffer.

Parameters:

• rb -

  Buffer to remove from, must contain at least one element.

int16 rb_safe_remove(ring_buffer * rb)

Attempt to remove the first item from a ring buffer.

If the ring buffer is nonempty, removes and returns its first item. If it is empty, does nothing and returns a negative value.

Parameters:

• rb -

  Buffer to attempt to remove from.

int rb_safe_insert(ring_buffer * rb, uint8 element)

Attempt to insert an element into a ring buffer.

Parameters:

• rb -

  Buffer to insert into.

• element -

  Value to insert into rb.

Side Effects::

If rb is not full, appends element onto buffer.

Return:

If element was appended, then true; otherwise, false.

int rb_push_insert(ring_buffer * rb, uint8 element)

Append an item onto the end of a non-full ring buffer.

If the buffer is full, removes its first item, then inserts the new element at the end.

Parameters:

• rb -

  Ring buffer to insert into.

• element -

  Value to insert into ring buffer.

Return:

On success, returns -1. If an element was popped, returns the popped value.

void rb_reset(ring_buffer * rb)

Discard all items from a ring buffer.

Parameters:

• rb -

  Ring buffer to discard all items from.