fifobuf.h File Reference

General pourpose FIFO buffer implemented with a ring buffer. More...

#include <cpu/types.h>
#include <cpu/irq.h>
#include <cfg/debug.h>

Go to the source code of this file.


Functions

bool fifo_isempty (const FIFOBuffer *fb)
 Check whether the fifo is empty.
bool fifo_isfull (const FIFOBuffer *fb)
 Check whether the fifo is full.
void fifo_push (FIFOBuffer *fb, unsigned char c)
 Push a character on the fifo buffer.
unsigned char fifo_pop (FIFOBuffer *fb)
 Pop a character from the fifo buffer.
void fifo_flush (FIFOBuffer *fb)
 Make the fifo empty, discarding all its current contents.
bool fifo_isfull_locked (const FIFOBuffer *_fb)
 Thread safe version of fifo_isfull().
void fifo_init (FIFOBuffer *fb, unsigned char *buf, size_t size)
 FIFO Initialization.
size_t fifo_len (FIFOBuffer *fb)

Detailed Description

General pourpose FIFO buffer implemented with a ring buffer.

  • begin points to the first buffer element;
  • end points to the last buffer element (unlike the STL convention);
  • head points to the element to be extracted next;
  • tail points to the location following the last insertion;
  • when any of the pointers advances beyond end, it is reset back to begin.
  +-----------------------------------+
  |  empty  |   valid data   |  empty |
  +-----------------------------------+
  ^         ^                ^        ^
  begin    head             tail     end

The buffer is EMPTY when head and tail point to the same location: 

 head == tail

The buffer is FULL when tail points to the location immediately after head: 

 tail == head - 1

The buffer is also FULL when tail points to the last buffer location and head points to the first one: 

 head == begin && tail == end

Version:
Id
fifobuf.h 1532 2008-08-04 07:21:26Z bernie
Author:
Bernie Innocenti <bernie@codewiz.org>

Definition in file fifobuf.h.

Function Documentation

bool fifo_isempty ( const FIFOBuffer *  fb  )  [inline]

Check whether the fifo is empty.

Note:
Calling fifo_isempty() is safe while a concurrent execution context is calling fifo_push() or fifo_pop() only if the CPU can atomically update a pointer (which the AVR and other 8-bit processors can't do).
See also:
fifo_isempty_locked

Definition at line 102 of file fifobuf.h.

bool fifo_isfull ( const FIFOBuffer *  fb  )  [inline]

Check whether the fifo is full.

Note:
Calling fifo_isfull() is safe while a concurrent execution context is calling fifo_pop() and the CPU can update a pointer atomically. It is NOT safe when the other context calls fifo_push(). This limitation is not usually problematic in a consumer/producer scenario because the fifo_isfull() and fifo_push() are usually called in the producer context.

Definition at line 122 of file fifobuf.h.

size_t fifo_len ( FIFOBuffer *  fb  )  [inline]

Returns:
Lenght of the FIFOBuffer fb.

Definition at line 295 of file fifobuf.h.

unsigned char fifo_pop ( FIFOBuffer *  fb  )  [inline]

Pop a character from the fifo buffer.

Note:
Calling fifo_pop() on an empty buffer is undefined. The caller must make sure the buffer contains at least one character before calling this function.

It is safe to call fifo_pop() and fifo_push() from concurrent contexts.

Definition at line 174 of file fifobuf.h.

void fifo_push ( FIFOBuffer *  fb,
unsigned char  c 
) [inline]

Push a character on the fifo buffer.

Note:
Calling fifo_push() on a full buffer is undefined. The caller must make sure the buffer has at least one free slot before calling this function.

It is safe to call fifo_pop() and fifo_push() from concurrent contexts, unless the CPU can't update a pointer atomically (which the AVR and other 8-bit processors can't do).

See also:
fifo_push_locked

Definition at line 145 of file fifobuf.h.