Group baton_queue¶

Byte ring of variable-size event records, used by Node .More...

Classes¶

Type	Name
struct	baton_queue Queue state.
struct	baton_record Header of one event record.

Public Functions¶

Type	Name
bool	baton_queue_alloc (struct baton_queue * queue, uint16_t need, uint16_t * offset) Reserve `need` bytes at the tail.
uint8_t *	baton_queue_data (struct baton_queue * queue, uint16_t offset) Data bytes of the record at `offset` .
uint16_t	baton_queue_first (const struct baton_queue * queue, uint16_t head, uint16_t tail) Offset of the first record for a head/tail snapshot.
void	baton_queue_init (struct baton_queue * queue, uint8_t * memory, uint16_t size) Initialize an empty queue over `memory` .
uint16_t	baton_queue_next (const struct baton_queue * queue, uint16_t offset, uint16_t tail) Offset of the record after the one at `offset` .
void	baton_queue_read (const struct baton_queue * queue, uint16_t offset, struct baton_record * record) Read the header of the record at `offset` .
uint16_t	baton_queue_record_size (uint8_t length) Bytes a record with `length` data bytes occupies.
void	baton_queue_set_flags (struct baton_queue * queue, uint16_t offset, uint8_t flags) Update only the flags of the record at `offset` .
void	baton_queue_set_masks (struct baton_queue * queue, uint16_t offset, uint32_t pending, uint32_t inflight) Update only the node masks of the record at `offset` .
uint16_t	baton_queue_used (const struct baton_queue * queue) Bytes currently in use.
void	baton_queue_write (struct baton_queue * queue, uint16_t offset, const struct baton_record * record) Write the complete header of the record at `offset` .

Macros¶

Type	Name
define	BATON_REC_HEADER_SIZE `16U` Serialized size of a record header in bytes.
define	BATON_REC_SKIP `0x02U` Marker at the end of the buffer: continue at offset 0.
define	BATON_REC_VALID `0x01U` Record is complete and visible to the consumer.

Detailed Description¶

Layout rules: * A record is a 16-byte header (baton_record, serialized byte by byte) followed by the data, padded to a multiple of 4 bytes. * A record is never split at the end of the buffer. If it does not fit at the end, a SKIP marker is written there (when a header fits) and the record goes to offset 0. A reader that reaches an offset without room for a header, or a SKIP marker, continues at 0. * head == tail means empty; the producer resets both to 0 when the queue is empty, so the wrapped state never starts from a stale head. * Records are released only from the head.

The producer (baton_node_send()) may run in an interrupt; it calls baton_queue_alloc with the critical section held and publishes a record by setting BATON_REC_VALID last.

Public Functions Documentation¶

function baton_queue_alloc¶

Reserve need bytes at the tail.

bool baton_queue_alloc (
    struct baton_queue * queue,
    uint16_t need,
    uint16_t * offset
)

Call with the critical section held.

Parameters:

queue Queue state.
need Record size from baton_queue_record_size().
offset Receives the record offset.

Returns:

true when the space was reserved.

function baton_queue_data¶

Data bytes of the record at offset .

uint8_t * baton_queue_data (
    struct baton_queue * queue,
    uint16_t offset
)

function baton_queue_first¶

Offset of the first record for a head/tail snapshot.

uint16_t baton_queue_first (
    const struct baton_queue * queue,
    uint16_t head,
    uint16_t tail
)

Returns:

Offset of the first record, or tail when the queue is empty.

function baton_queue_init¶

Initialize an empty queue over memory .

void baton_queue_init (
    struct baton_queue * queue,
    uint8_t * memory,
    uint16_t size
)

Parameters:

queue Queue state.
memory Storage of size bytes.
size Storage size; rounded down to a multiple of 4.

function baton_queue_next¶

Offset of the record after the one at offset .

uint16_t baton_queue_next (
    const struct baton_queue * queue,
    uint16_t offset,
    uint16_t tail
)

Returns:

Offset of the next record, or tail after the last one.

function baton_queue_read¶

Read the header of the record at offset .

void baton_queue_read (
    const struct baton_queue * queue,
    uint16_t offset,
    struct baton_record * record
)

function baton_queue_record_size¶

Bytes a record with length data bytes occupies.

uint16_t baton_queue_record_size (
    uint8_t length
)

function baton_queue_set_flags¶

Update only the flags of the record at offset .

void baton_queue_set_flags (
    struct baton_queue * queue,
    uint16_t offset,
    uint8_t flags
)

function baton_queue_set_masks¶

Update only the node masks of the record at offset .

void baton_queue_set_masks (
    struct baton_queue * queue,
    uint16_t offset,
    uint32_t pending,
    uint32_t inflight
)

function baton_queue_used¶

Bytes currently in use.

uint16_t baton_queue_used (
    const struct baton_queue * queue
)

function baton_queue_write¶

Write the complete header of the record at offset .

void baton_queue_write (
    struct baton_queue * queue,
    uint16_t offset,
    const struct baton_record * record
)

Macro Definition Documentation¶

define BATON_REC_HEADER_SIZE¶

Serialized size of a record header in bytes.

#define BATON_REC_HEADER_SIZE `16U`

define BATON_REC_SKIP¶

Marker at the end of the buffer: continue at offset 0.

#define BATON_REC_SKIP `0x02U`

define BATON_REC_VALID¶

Record is complete and visible to the consumer.

#define BATON_REC_VALID `0x01U`