Circular integer buffer interface. More...

Detailed Description

Circular integer buffer interface.

This structure provides an organizational interface and combined with an memory array forms a circular buffer.

Author: Kaspar Schleiser kaspa.nosp@m.r@sc.nosp@m.hleis.nosp@m.er.d.nosp@m.e

Warning: This API is NOT thread-safe.

Note: It may appear that the functions would be thread safe if the management data structure is only ever accessed by a single consumer and a singler producer on platforms where loads and stores to unsigned int is atomic. But even this is not the case, as this would require careful use of memory barriers to ensure correct order of memory accesses. So: Just make sure to use either a mutex or to disable interrupts to ensure exclusive access as indicated in the API doc.

Definition in file cib.h.

#include "assert.h"

Include dependency graph for cib.h:

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

Go to the source code of this file.

Data Structures
struct	cib_t
	circular integer buffer structure More...

#define	CIB_INIT(SIZE) { 0, 0, (SIZE)-1 }
	Initialize cib_t to a given size. More...

static void	cib_init (cib_t *__restrict cib, unsigned int size)
	Initialize `cib` to 0 and set buffer size to `size`. More...

static unsigned int	cib_size (const cib_t *cib)
	Returns the total capacity (`size` parameter of cib_init()) of a cib_t. More...

static unsigned int	cib_avail (const cib_t *cib)
	Calculates difference between cib_put() and cib_get() accesses. More...

static unsigned int	cib_full (const cib_t *cib)
	Check if cib is full. More...

static int	cib_get (cib_t *__restrict cib)
	Get the index of the next item in buffer. More...

static int	cib_peek_at_unsafe (const cib_t *__restrict cib, unsigned offset)
	Get the index of an item in the buffer without removing anything. More...

static int	cib_peek_at (const cib_t *__restrict cib, unsigned offset)
	Get the index of an item in the buffer without removing anything. More...

static int	cib_peek_unsafe (const cib_t *__restrict cib)
	Get the index of the next item in buffer without removing it. More...

static int	cib_peek (const cib_t *__restrict cib)
	Get the index of the next item in buffer without removing it. More...

static int	cib_get_unsafe (cib_t *cib)
	Get the index of the next item in buffer. More...

static int	cib_put (cib_t *__restrict cib)
	Get index for item in buffer to put to. More...

static int	cib_put_unsafe (cib_t *cib)
	Get index for item in buffer to put to. More...

Macro Definition Documentation

◆ CIB_INIT

#define CIB_INIT ( SIZE ) { 0, 0, (SIZE)-1 }

Initialize cib_t to a given size.

Parameters

[in] SIZE Size of the buffer, must not exceed (UINT_MAX + 1) / 2. Should be equal to 0 or power of 2.

Definition at line 57 of file cib.h.

Function Documentation

◆ cib_avail()

static unsigned int cib_avail ( const cib_t * cib )

inlinestatic

Calculates difference between cib_put() and cib_get() accesses.

Parameters

[in] cib the cib_t to check. Must not be NULL.

Returns: How often cib_get() can be called before cib is empty.

Warning: This function is not thread safe. (The caller needs to ensure exclusive access to the cib_t.)

Definition at line 101 of file cib.h.

◆ cib_full()

static unsigned int cib_full ( const cib_t * cib )

inlinestatic

Check if cib is full.

Parameters

[in] cib the cib_t to check. Must not be NULL.

Returns: 1 if cib_put() would return "-1", 0 otherwise

Warning: This function is not thread safe. (The caller needs to ensure exclusive access to the cib_t.)

Definition at line 116 of file cib.h.

◆ cib_get()

static int cib_get ( cib_t *__restrict cib )

inlinestatic

Get the index of the next item in buffer.

Parameters

[in,out] cib corresponding cib to buffer. Must not be NULL.

Returns: index of next item

Return values

-1	if the buffer is empty

Warning: This function is not thread safe. (The caller needs to ensure exclusive access to the cib_t.)

Definition at line 132 of file cib.h.

◆ cib_get_unsafe()

static int cib_get_unsafe ( cib_t * cib )

inlinestatic

Get the index of the next item in buffer.

Unsafe version, must not be called if buffer is empty!

Parameters

[in,out] cib corresponding cib to buffer. Must not be NULL.

Returns: index of next item

Warning: This function is not thread safe. (The caller needs to ensure exclusive access to the cib_t.)

Definition at line 238 of file cib.h.

◆ cib_init()

static void cib_init	(	cib_t *__restrict	cib,
		unsigned int	size
	)

inlinestatic

Initialize cib to 0 and set buffer size to size.

Parameters

[out]	cib	Buffer to initialize. Must not be NULL.
[in]	size	Size of the buffer, must not exceed (`UINT_MAX` + 1) / 2. Should be equal to 0 or power of 2.

Definition at line 68 of file cib.h.

◆ cib_peek()

static int cib_peek ( const cib_t *__restrict cib )

inlinestatic

Get the index of the next item in buffer without removing it.

Parameters

[in,out] cib corresponding cib to buffer. Must not be NULL.

Returns: index of next item

Return values

-1	if the buffer is empty

Warning: This function is not thread safe. (The caller needs to ensure exclusive access to the cib_t.)

Definition at line 221 of file cib.h.

◆ cib_peek_at()

static int cib_peek_at	(	const cib_t *__restrict	cib,
		unsigned	offset
	)

inlinestatic

Get the index of an item in the buffer without removing anything.

Offset 0 is the next item in the buffer that would be returned by cip_get(), offset 1 would be the following, and so on.

Parameters

[in,out]	cib	corresponding cib to buffer. Must not be NULL.
[in]	offset	offset from front of buffer

Returns: index of item

Return values

-1	if no item at `offset` exists in the buffer

Warning: This function is not thread safe. (The caller needs to ensure exclusive access to the cib_t.)

Definition at line 182 of file cib.h.

◆ cib_peek_at_unsafe()

static int cib_peek_at_unsafe	(	const cib_t *__restrict	cib,
		unsigned	offset
	)

inlinestatic

Get the index of an item in the buffer without removing anything.

Offset 0 is the next item in the buffer that would be returned by cip_get(), offset 1 would be the following, and so on.

Unsafe version, must not pass an offset that is larger than the number of items currently in the buffer!

Parameters

[in,out]	cib	corresponding cib to buffer. Must not be NULL.
[in]	offset	offset from front of buffer

Returns: index of item

Return values

-1	if no item at `offset` exists in the buffer

Warning: This function is not thread safe. (The caller needs to ensure exclusive access to the cib_t and must not release that exclusive access between the call to cib_avail and this function.)

Definition at line 161 of file cib.h.

◆ cib_peek_unsafe()

static int cib_peek_unsafe ( const cib_t *__restrict cib )

inlinestatic

Get the index of the next item in buffer without removing it.

Unsafe version, must not be called if buffer is empty!

Parameters

[in,out] cib corresponding cib to buffer. Must not be NULL.

Returns: index of next item

Return values

-1	if the buffer is empty

Warning: This function is not thread safe. (The caller needs to ensure exclusive access to the cib_t and must not release that exclusive access between the call to cib_avail and this function.)

Definition at line 205 of file cib.h.

◆ cib_put()

static int cib_put ( cib_t *__restrict cib )

inlinestatic

Get index for item in buffer to put to.

Parameters

[in,out] cib corresponding cib to buffer. Must not be NULL.

Returns: index of item to put to

Return values

-1	if the buffer is full

Warning: This function is not thread safe. (The caller needs to ensure exclusive access to the cib_t.)

Definition at line 254 of file cib.h.

◆ cib_put_unsafe()

static int cib_put_unsafe ( cib_t * cib )

inlinestatic

Get index for item in buffer to put to.

Unsafe version, must not be called if buffer is full!

Parameters

[in,out] cib corresponding cib to buffer. Must not be NULL.

Returns: index of item to put to

Warning: This function is not thread safe. (The caller needs to ensure exclusive access to the cib_t.)

Definition at line 278 of file cib.h.

◆ cib_size()

static unsigned int cib_size ( const cib_t * cib )

inlinestatic

Returns the total capacity (size parameter of cib_init()) of a cib_t.

Parameters

[in] cib the cib_t to check. Must not be NULL.

Returns: The total size of cib.

Definition at line 86 of file cib.h.

Detailed Description

Data Structures

Macro Definition Documentation

◆ CIB_INIT

Function Documentation

◆ cib_avail()

◆ cib_full()

◆ cib_get()

◆ cib_get_unsafe()

◆ cib_init()

◆ cib_peek()

◆ cib_peek_at()

◆ cib_peek_at_unsafe()

◆ cib_peek_unsafe()

◆ cib_put()

◆ cib_put_unsafe()

◆ cib_size()