ring_buffer.h — Maple v0.0.12 Documentation

### Navigation

- next
- previous |
- LeafLabs |
- Index »
- `libmaple` »
- APIs »

# `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.

### Navigation

- next
- previous |
- LeafLabs |
- Index »
- `libmaple` »
- APIs »