ringbuffer.h File Reference

A utility for storing and retrieving byte data using a ring buffer. More...

Detailed Description

A utility for storing and retrieving byte data using a ring buffer.

Author
Kaspar Schleiser kaspa.nosp@m.r@sc.nosp@m.hleis.nosp@m.er.d.nosp@m.e
René Kijewski rene..nosp@m.kije.nosp@m.wski@.nosp@m.fu-b.nosp@m.erlin.nosp@m..de

The ringbuffer is useful for buffering data in the same thread context but it is not thread-safe. For a thread-safe ring buffer, see Thread safe ringbuffer in the System library.

Definition in file ringbuffer.h.

+ This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures

struct  ringbuffer_t
 Ringbuffer. More...
 

Macros

#define RINGBUFFER_INIT(BUF)   { (BUF), sizeof(BUF), 0, 0 }
 Initialize a ringbuffer. More...
 

Functions

static void ringbuffer_init (ringbuffer_t *__restrict rb, char *buffer, unsigned bufsize)
 Initialize a ringbuffer. More...
 
int ringbuffer_add_one (ringbuffer_t *__restrict rb, char c)
 Add an element to the ringbuffer. More...
 
unsigned ringbuffer_add (ringbuffer_t *__restrict rb, const char *buf, unsigned n)
 Add a number of elements to the ringbuffer. More...
 
int ringbuffer_get_one (ringbuffer_t *__restrict rb)
 Peek and remove oldest element from the ringbuffer. More...
 
unsigned ringbuffer_get (ringbuffer_t *__restrict rb, char *buf, unsigned n)
 Read and remove a number of elements from the ringbuffer. More...
 
unsigned ringbuffer_remove (ringbuffer_t *__restrict rb, unsigned n)
 Remove a number of elements from the ringbuffer. More...
 
static int ringbuffer_empty (const ringbuffer_t *__restrict rb)
 Test if the ringbuffer is empty. More...
 
static int ringbuffer_full (const ringbuffer_t *__restrict rb)
 Test if the ringbuffer is full. More...
 
static unsigned int ringbuffer_get_free (const ringbuffer_t *__restrict rb)
 Return available space in ringbuffer. More...
 
int ringbuffer_peek_one (const ringbuffer_t *__restrict rb)
 Read, but don't remove, the oldest element in the buffer. More...
 
unsigned ringbuffer_peek (const ringbuffer_t *__restrict rb, char *buf, unsigned n)
 Read, but don't remove, the a number of element of the buffer. More...
 

Macro Definition Documentation

◆ RINGBUFFER_INIT

#define RINGBUFFER_INIT (   BUF)    { (BUF), sizeof(BUF), 0, 0 }

Initialize a ringbuffer.

This macro is meant for static ringbuffers.

Parameters
[in]BUFBuffer to use for the ringbuffer. The size is deduced through sizeof (BUF).
Returns
The static initializer.

Definition at line 50 of file ringbuffer.h.

Function Documentation

◆ ringbuffer_add()

unsigned ringbuffer_add ( ringbuffer_t *__restrict  rb,
const char *  buf,
unsigned  n 
)

Add a number of elements to the ringbuffer.

Only so many elements are added as fit in the ringbuffer. No elements get overwritten. If this is not the intended behavior, then use ringbuffer_add_one() in a loop instead.

Parameters
[in,out]rbRingbuffer to operate on.
[in]bufBuffer to add elements from.
[in]nMaximum number of elements to add.
Returns
Number of elements actually added. 0 if rb is full.

◆ ringbuffer_add_one()

int ringbuffer_add_one ( ringbuffer_t *__restrict  rb,
char  c 
)

Add an element to the ringbuffer.

If rb is full, then the oldest element gets overwritten. Test ringbuffer_full() first if overwriting is not intended.

Parameters
[in,out]rbRingbuffer to operate on.
[in]cElement to add.
Returns
The element that was dropped, iff the buffer was full. -1 iff the buffer was not full.

◆ ringbuffer_empty()

static int ringbuffer_empty ( const ringbuffer_t *__restrict  rb)
inlinestatic

Test if the ringbuffer is empty.

Parameters
[in,out]rbRingbuffer to operate on.
Returns
0 iff not empty

Definition at line 120 of file ringbuffer.h.

◆ ringbuffer_full()

static int ringbuffer_full ( const ringbuffer_t *__restrict  rb)
inlinestatic

Test if the ringbuffer is full.

Parameters
[in,out]rbRingbuffer to operate on.
Returns
0 iff not full

Definition at line 130 of file ringbuffer.h.

◆ ringbuffer_get()

unsigned ringbuffer_get ( ringbuffer_t *__restrict  rb,
char *  buf,
unsigned  n 
)

Read and remove a number of elements from the ringbuffer.

Parameters
[in,out]rbRingbuffer to operate on.
[out]bufBuffer to write into.
[in]nRead at most n elements.
Returns
Number of elements actually read.

◆ ringbuffer_get_free()

static unsigned int ringbuffer_get_free ( const ringbuffer_t *__restrict  rb)
inlinestatic

Return available space in ringbuffer.

Parameters
[in,out]rbRingbuffer to query.
Returns
number of available bytes

Definition at line 140 of file ringbuffer.h.

◆ ringbuffer_get_one()

int ringbuffer_get_one ( ringbuffer_t *__restrict  rb)

Peek and remove oldest element from the ringbuffer.

Parameters
[in,out]rbRingbuffer to operate on.
Returns
The oldest element that was added, or -1 if rb is empty.

◆ ringbuffer_init()

static void ringbuffer_init ( ringbuffer_t *__restrict  rb,
char *  buffer,
unsigned  bufsize 
)
inlinestatic

Initialize a ringbuffer.

Parameters
[out]rbDatum to initialize.
[in]bufferBuffer to use by rb.
[in]bufsizesizeof (buffer)

Definition at line 58 of file ringbuffer.h.

◆ ringbuffer_peek()

unsigned ringbuffer_peek ( const ringbuffer_t *__restrict  rb,
char *  buf,
unsigned  n 
)

Read, but don't remove, the a number of element of the buffer.

Parameters
[in]rbRingbuffer to operate on.
[out]bufBuffer to write into.
[in]nRead at most n elements.
Returns
Same as ringbuffer_get()

◆ ringbuffer_peek_one()

int ringbuffer_peek_one ( const ringbuffer_t *__restrict  rb)

Read, but don't remove, the oldest element in the buffer.

Parameters
[in]rbRingbuffer to operate on.
Returns
Same as ringbuffer_get_one()

◆ ringbuffer_remove()

unsigned ringbuffer_remove ( ringbuffer_t *__restrict  rb,
unsigned  n 
)

Remove a number of elements from the ringbuffer.

Parameters
[in,out]rbRingbuffer to operate on.
[in]nRead at most n elements.
Returns
Number of elements actually removed.