File syn_mailbox.h¶

FileList > sched > syn_mailbox.h

Typed message queue — fixed-size SPSC ring for inter-task IPC. More...

#include "../common/syn_barrier.h"
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#include <string.h>

Classes¶

Type	Name
struct	SYN_Mailbox Typed message queue — fixed-size SPSC ring buffer.

Public Static Functions¶

Type	Name
bool	syn_mailbox_empty (const SYN_Mailbox * mb) Check if the mailbox is empty.
void	syn_mailbox_flush (SYN_Mailbox * mb) Flush all messages.
size_t	syn_mailbox_free (const SYN_Mailbox * mb) Number of free slots.
bool	syn_mailbox_full (const SYN_Mailbox * mb) Check if the mailbox is full.
void	syn_mailbox_init (SYN_Mailbox * mb, void * buf, size_t msg_size, size_t capacity) Initialize a mailbox at runtime.
uint32_t	syn_mailbox_overflows (const SYN_Mailbox * mb) Get overflow count.
const void *	syn_mailbox_peek (const SYN_Mailbox * mb) Peek at the next message without consuming it.
size_t	syn_mailbox_pending (const SYN_Mailbox * mb) Number of messages currently in the mailbox.
bool	syn_mailbox_post (SYN_Mailbox * mb, const void * msg) Post a message. ISR-safe (single producer).
bool	syn_mailbox_receive (SYN_Mailbox * mb, void * msg) Receive a message. Single consumer.

Macros¶

Type	Name
define	SYN_MAILBOX_DEFINE (name, type, count) `/* multi line expression /` Static mailbox definition macro.*

Detailed Description¶

Passes fixed-size messages between producer (ISR or task) and consumer (task). Lock-free single-producer single-consumer design.

When SYN_USE_MULTICORE is enabled, acquire/release memory barriers are inserted at every index access, making the mailbox safe for cross-core communication (core A posts, core B receives). When multicore is disabled (the default), these compile to plain volatile reads and writes — zero overhead.

** **

The mailbox has exactly two indices: * head — written ONLY by the producer * tail — written ONLY by the consumer

Producer syn_mailbox_post(): * Read tail (LOAD_ACQUIRE) — observe consumer's latest progress * If full, return false * memcpy message data into buf[head * msg_size] * Write head = next (STORE_RELEASE) — data committed before index

Consumer syn_mailbox_receive(): * Read head (LOAD_ACQUIRE) — observe producer's latest index * If empty, return false * memcpy message from buf[tail * msg_size] — safe: data visible * Write tail = next (STORE_RELEASE) — slot freed for producer

** **

typedef struct { uint16_t id; int32_t value; } SensorMsg;

// Static allocation
SYN_MAILBOX_DEFINE(sensor_mbox, SensorMsg, 8);

// Producer (ISR or other core):
SensorMsg msg = { .id = 1, .value = 2345 };
syn_mailbox_post(&sensor_mbox, &msg);

// Consumer (main loop or other core):
SensorMsg rx;
while (syn_mailbox_receive(&sensor_mbox, &rx)) {
    process(rx.id, rx.value);
}

Public Static Functions Documentation¶

function syn_mailbox_empty¶

Check if the mailbox is empty.

static inline bool syn_mailbox_empty (
    const SYN_Mailbox * mb
)

Parameters:

mb Mailbox.

Returns:

true if empty.

function syn_mailbox_flush¶

Flush all messages.

static inline void syn_mailbox_flush (
    SYN_Mailbox * mb
)

Parameters:

mb Mailbox.

function syn_mailbox_free¶

Number of free slots.

static inline size_t syn_mailbox_free (
    const SYN_Mailbox * mb
)

Parameters:

mb Mailbox.

Returns:

Free slot count.

function syn_mailbox_full¶

Check if the mailbox is full.

static inline bool syn_mailbox_full (
    const SYN_Mailbox * mb
)

Parameters:

mb Mailbox.

Returns:

true if full.

function syn_mailbox_init¶

Initialize a mailbox at runtime.

static inline void syn_mailbox_init (
    SYN_Mailbox * mb,
    void * buf,
    size_t msg_size,
    size_t capacity
)

Parameters:

mb Mailbox instance.
buf Message storage buffer.
msg_size Size of one message in bytes.
capacity Maximum number of messages.

function syn_mailbox_overflows¶

Get overflow count.

static inline uint32_t syn_mailbox_overflows (
    const SYN_Mailbox * mb
)

Parameters:

mb Mailbox.

Returns:

Number of dropped messages.

function syn_mailbox_peek¶

Peek at the next message without consuming it.

static inline const void * syn_mailbox_peek (
    const SYN_Mailbox * mb
)

Parameters:

mb Mailbox.

Returns:

Pointer to the message, or NULL if empty. Valid until the next receive().

function syn_mailbox_pending¶

Number of messages currently in the mailbox.

static inline size_t syn_mailbox_pending (
    const SYN_Mailbox * mb
)

Parameters:

mb Mailbox.

Returns:

Message count.

function syn_mailbox_post¶

Post a message. ISR-safe (single producer).

static inline bool syn_mailbox_post (
    SYN_Mailbox * mb,
    const void * msg
)

Uses STORE_RELEASE on the head update to ensure message data is committed before the consumer can see the new index.

Parameters:

mb Mailbox.
msg Pointer to message data (msg_size bytes copied).

Returns:

true if posted, false if full.

function syn_mailbox_receive¶

Receive a message. Single consumer.

static inline bool syn_mailbox_receive (
    SYN_Mailbox * mb,
    void * msg
)

Uses LOAD_ACQUIRE on the head read to ensure all message data written by the producer is visible. Uses STORE_RELEASE on the tail update to ensure the producer sees the freed slot.

Parameters:

mb Mailbox.
msg Pointer to receive buffer (msg_size bytes copied out).

Returns:

true if a message was received, false if empty.

Macro Definition Documentation¶

define SYN_MAILBOX_DEFINE¶

Static mailbox definition macro.

#define SYN_MAILBOX_DEFINE (
    name,
    type,
    count
) `/* multi line expression */`

Creates a mailbox instance with embedded storage.

Parameters:

name Variable name.
type Message struct type.
count Max number of messages.

The documentation for this class was generated from the following file src/syntropic/sched/syn_mailbox.h