Zephyr Project API  3.2.0
A Scalable Open Source RTOS
Files | Data Structures | Macros
RTIO SPSC API
RTIO

RTIO Single Producer Single Consumer (SPSC) Queue API. More...

Files

file  rtio_spsc.h
 A lock-free and type safe power of 2 fixed sized single producer single consumer (SPSC) queue using a ringbuffer and atomics to ensure coherency.
 

Macros

#define RTIO_SPSC_INITIALIZER(name, type, sz)
 Statically initialize an rtio_spsc. More...
 
#define RTIO_SPSC_DECLARE(name, type, sz)
 Declare an anonymous struct type for an rtio_spsc. More...
 
#define RTIO_SPSC_DEFINE(name, type, sz)    RTIO_SPSC_DECLARE(name, type, sz) name = RTIO_SPSC_INITIALIZER(name, type, sz);
 Define an rtio_spsc with a fixed size. More...
 
#define rtio_spsc_size(spsc)   ((spsc)->_spsc.mask + 1)
 Size of the SPSC queue. More...
 
#define rtio_spsc_reset(spsc)
 Initialize/reset a spsc such that its empty. More...
 
#define rtio_spsc_acquire(spsc)
 Acquire an element to produce from the SPSC. More...
 
#define rtio_spsc_produce(spsc)
 Produce one previously acquired element to the SPSC. More...
 
#define rtio_spsc_produce_all(spsc)
 Produce all previously acquired elements to the SPSC. More...
 
#define rtio_spsc_consume(spsc)
 Consume an element from the spsc. More...
 
#define rtio_spsc_release(spsc)
 Release a consumed element. More...
 
#define rtio_spsc_consumable(spsc)    ({ (spsc)->_spsc.in - (spsc)->_spsc.out - (spsc)->_spsc.consume; })
 Count of consumables in spsc. More...
 
#define rtio_spsc_peek(spsc)
 Peek at the first available item in queue. More...
 
#define rtio_spsc_next(spsc, item)
 Peek at the next item in the queue from a given one. More...
 
#define rtio_spsc_prev(spsc, item)
 Get the previous item in the queue from a given one. More...
 

Detailed Description

RTIO Single Producer Single Consumer (SPSC) Queue API.

Macro Definition Documentation

◆ rtio_spsc_acquire

#define rtio_spsc_acquire (   spsc)

#include <include/zephyr/rtio/rtio_spsc.h>

Value:
({ \
unsigned long idx = atomic_get(&(spsc)->_spsc.in) + (spsc)->_spsc.acquire; \
bool acq = (idx - atomic_get(&(spsc)->_spsc.out)) < rtio_spsc_size(spsc); \
if (acq) { \
(spsc)->_spsc.acquire += 1; \
} \
acq ? &((spsc)->buffer[z_rtio_spsc_mask(spsc, idx)]) : NULL; \
})
atomic_get
static ALWAYS_INLINE atomic_val_t atomic_get(const atomic_t *target)
Definition: atomic_xtensa.h:16
rtio_spsc_size
#define rtio_spsc_size(spsc)
Size of the SPSC queue.
Definition: rtio_spsc.h:120
buffer
static ZTEST_BMEM char buffer[8]
Definition: test_mbox_api.c:551

Acquire an element to produce from the SPSC.

Parameters
spscSPSC to acquire an element from for producing
Returns
A pointer to the acquired element or null if the spsc is full

◆ rtio_spsc_consumable

#define rtio_spsc_consumable (   spsc)     ({ (spsc)->_spsc.in - (spsc)->_spsc.out - (spsc)->_spsc.consume; })

#include <include/zephyr/rtio/rtio_spsc.h>

Count of consumables in spsc.

Parameters
spscSPSC to get item count for

◆ rtio_spsc_consume

#define rtio_spsc_consume (   spsc)

#include <include/zephyr/rtio/rtio_spsc.h>

Value:
({ \
unsigned long idx = atomic_get(&(spsc)->_spsc.out) + (spsc)->_spsc.consume; \
bool has_consumable = (idx != atomic_get(&(spsc)->_spsc.in)); \
if (has_consumable) { \
(spsc)->_spsc.consume += 1; \
} \
has_consumable ? &((spsc)->buffer[z_rtio_spsc_mask(spsc, idx)]) : NULL; \
})

Consume an element from the spsc.

Parameters
spscSpsc to consume from
Returns
Pointer to element or null if no consumable elements left

◆ RTIO_SPSC_DECLARE

#define RTIO_SPSC_DECLARE (   name,
  type,
  sz 
)

#include <include/zephyr/rtio/rtio_spsc.h>

Value:
struct rtio_spsc_ ## name { \
struct rtio_spsc _spsc; \
type buffer[sz]; \
}

Declare an anonymous struct type for an rtio_spsc.

Parameters
nameName of the spsc symbol to be provided
typeType stored in the spsc
szSize of the spsc, must be power of 2 (ex: 2, 4, 8)

◆ RTIO_SPSC_DEFINE

#define RTIO_SPSC_DEFINE (   name,
  type,
  sz 
)     RTIO_SPSC_DECLARE(name, type, sz) name = RTIO_SPSC_INITIALIZER(name, type, sz);

#include <include/zephyr/rtio/rtio_spsc.h>

Define an rtio_spsc with a fixed size.

Parameters
nameName of the spsc symbol to be provided
typeType stored in the spsc
szSize of the spsc, must be power of 2 (ex: 2, 4, 8)

◆ RTIO_SPSC_INITIALIZER

#define RTIO_SPSC_INITIALIZER (   name,
  type,
  sz 
)

#include <include/zephyr/rtio/rtio_spsc.h>

Value:
{ ._spsc = { \
.acquire = 0, \
.consume = 0, \
.in = ATOMIC_INIT(0), \
.out = ATOMIC_INIT(0), \
.mask = sz - 1, \
} \
}
ATOMIC_INIT
#define ATOMIC_INIT(i)
Initialize an atomic variable.
Definition: atomic.h:62

Statically initialize an rtio_spsc.

Parameters
nameName of the spsc symbol to be provided
typeType stored in the spsc
szSize of the spsc, must be power of 2 (ex: 2, 4, 8)

◆ rtio_spsc_next

#define rtio_spsc_next (   spsc,
  item 
)

#include <include/zephyr/rtio/rtio_spsc.h>

Value:
({ \
unsigned long idx = ((item) - (spsc)->buffer); \
bool has_next = z_rtio_spsc_mask(spsc, (idx + 1)) != \
(z_rtio_spsc_mask(spsc, atomic_get(&(spsc)->_spsc.in))); \
has_next ? &((spsc)->buffer[z_rtio_spsc_mask((spsc), idx + 1)]) : NULL; \
})

Peek at the next item in the queue from a given one.

Parameters
spscSPSC to peek at
itemPointer to an item in the queue
Returns
Pointer to element or null if none left

◆ rtio_spsc_peek

#define rtio_spsc_peek (   spsc)

#include <include/zephyr/rtio/rtio_spsc.h>

Value:
({ \
unsigned long idx = atomic_get(&(spsc)->_spsc.out) + (spsc)->_spsc.consume; \
bool has_consumable = (idx != atomic_get(&(spsc)->_spsc.in)); \
has_consumable ? &((spsc)->buffer[z_rtio_spsc_mask(spsc, idx)]) : NULL; \
})

Peek at the first available item in queue.

Parameters
spscSpsc to peek into
Returns
Pointer to element or null if no consumable elements left

◆ rtio_spsc_prev

#define rtio_spsc_prev (   spsc,
  item 
)

#include <include/zephyr/rtio/rtio_spsc.h>

Value:
({ \
unsigned long idx = ((item) - &(spsc)->buffer[0]) / sizeof((spsc)->buffer[0]); \
bool has_prev = idx != z_rtio_spsc_mask(spsc, atomic_get(&(spsc)->_spsc.out)); \
has_prev ? &((spsc)->buffer[z_rtio_spsc_mask(spsc, idx - 1)]) : NULL; \
})

Get the previous item in the queue from a given one.

Parameters
spscSPSC to peek at
itemPointer to an item in the queue
Returns
Pointer to element or null if none left

◆ rtio_spsc_produce

#define rtio_spsc_produce (   spsc)

#include <include/zephyr/rtio/rtio_spsc.h>

Value:
({ \
if ((spsc)->_spsc.acquire > 0) { \
(spsc)->_spsc.acquire -= 1; \
atomic_add(&(spsc)->_spsc.in, 1); \
} \
})
atomic_add
static ALWAYS_INLINE atomic_val_t atomic_add(atomic_t *target, atomic_val_t value)
Definition: atomic_xtensa.h:76

Produce one previously acquired element to the SPSC.

This makes one element available to the consumer immediately

Parameters
spscSPSC to produce the previously acquired element or do nothing

◆ rtio_spsc_produce_all

#define rtio_spsc_produce_all (   spsc)

#include <include/zephyr/rtio/rtio_spsc.h>

Value:
({ \
if ((spsc)->_spsc.acquire > 0) { \
unsigned long acquired = (spsc)->_spsc.acquire; \
(spsc)->_spsc.acquire = 0; \
atomic_add(&(spsc)->_spsc.in, acquired); \
} \
})

Produce all previously acquired elements to the SPSC.

This makes all previous acquired elements available to the consumer immediately

Parameters
spscSPSC to produce all previously acquired elements or do nothing

◆ rtio_spsc_release

#define rtio_spsc_release (   spsc)

#include <include/zephyr/rtio/rtio_spsc.h>

Value:
({ \
if ((spsc)->_spsc.consume > 0) { \
(spsc)->_spsc.consume -= 1; \
atomic_add(&(spsc)->_spsc.out, 1); \
} \
})

Release a consumed element.

Parameters
spscSPSC to release consumed element or do nothing

◆ rtio_spsc_reset

#define rtio_spsc_reset (   spsc)

#include <include/zephyr/rtio/rtio_spsc.h>

Value:
({ \
(spsc)->_spsc.consume = 0; \
(spsc)->_spsc.acquire = 0; \
atomic_set(&(spsc)->_spsc.in, 0); \
atomic_set(&(spsc)->_spsc.out, 0); \
})

Initialize/reset a spsc such that its empty.

Note that this is not safe to do while being used in a producer/consumer situation with multiple calling contexts (isrs/threads).

Parameters
spscSPSC to initialize/reset

◆ rtio_spsc_size

#define rtio_spsc_size (   spsc)    ((spsc)->_spsc.mask + 1)

#include <include/zephyr/rtio/rtio_spsc.h>

Size of the SPSC queue.

Parameters
spscSPSC reference