Queue

Thread-safe FIFO coordination between producers and consumers. More...

Collaboration diagram for Queue:

Typedefs
typedef void *	sys_event_t
	Event payload stored in a queue. More...
typedef struct sys_event_queue_t	sys_event_queue_t
	Opaque event queue.

Lifecycle
sys_event_queue_t *	sys_event_queue_init (size_t capacity)
	Allocate a new event queue. More...
void	sys_event_queue_deinit (sys_event_queue_t *queue)
	Deinitialize an event queue and release its resources. More...

Methods
bool	sys_event_queue_push (sys_event_queue_t *queue, sys_event_t event)
	Push an event, overwriting the oldest entry if the queue is full. More...
bool	sys_event_queue_try_push (sys_event_queue_t *queue, sys_event_t event)
	Try to push an event without overwriting. More...
sys_event_t	sys_event_queue_peek (sys_event_queue_t *queue)
	Peek at the next queued event without removing it. More...
sys_event_t	sys_event_queue_pop (sys_event_queue_t *queue)
	Pop the next event, blocking until one is available or shutdown. More...
sys_event_t	sys_event_queue_try_pop (sys_event_queue_t *queue)
	Pop the next event without blocking. More...
sys_event_t	sys_event_queue_timed_pop (sys_event_queue_t *queue, uint32_t timeout_ms)
	Pop the next event with a timeout. More...
size_t	sys_event_queue_size (sys_event_queue_t *queue)
	Return the current event count. More...
bool	sys_event_queue_empty (sys_event_queue_t *queue)
	Report whether a queue is empty. More...
void	sys_event_queue_shutdown (sys_event_queue_t *queue)
	Prevent future pushes and wake blocked consumers. More...
bool	sys_event_queue_lock (sys_event_queue_t *queue)
	Lock a queue for manual inspection. More...
bool	sys_event_queue_unlock (sys_event_queue_t *queue)
	Unlock a queue after manual inspection. More...

Detailed Description

Thread-safe FIFO coordination between producers and consumers.

Event queues provide thread-safe FIFO coordination between producers and consumers.

Queue behavior summary:

• sys_event_queue_push() guarantees insertion and may overwrite the oldest item when full.
• sys_event_queue_try_push() never overwrites and fails when full.
• sys_event_queue_pop() blocks until an event is available or shutdown is observed.
• sys_event_queue_timed_pop() supports bounded waiting.
• sys_event_queue_shutdown() prevents future pushes and wakes blocked consumers.

Typical flow:

1. Allocate with sys_event_queue_init(capacity).
2. Push events from producer threads/interrupt-safe contexts as supported.
3. Pop events in one or more consumer workers.
4. Call sys_event_queue_shutdown() to stop intake and unblock waiters.
5. Deinitialize with sys_event_queue_deinit().

Typedef Documentation

sys_event_t

typedef void* sys_event_t

Event payload stored in a queue.

NULL is reserved to report an empty queue, timeout, or shutdown, so pushed events must be non-NULL.

Definition at line 68 of file event.h.

Function Documentation

sys_event_queue_deinit()

void sys_event_queue_deinit

(

sys_event_queue_t *

queue

)

Deinitialize an event queue and release its resources.

Parameters

queue

Queue to deinitialize.

sys_event_queue_empty()

bool sys_event_queue_empty

(

sys_event_queue_t *

queue

)

Report whether a queue is empty.

Parameters

queue

Queue to inspect.

Returns

true if the queue is empty, false otherwise.

sys_event_queue_init()

sys_event_queue_t* sys_event_queue_init

(

size_t

capacity

)

Allocate a new event queue.

Parameters

capacity

Maximum number of events retained by the queue.

Returns

New queue, or NULL on allocation or initialization failure.

sys_event_queue_lock()

bool sys_event_queue_lock

(

sys_event_queue_t *

queue

)

Lock a queue for manual inspection.

Parameters

queue

Queue to lock.

Returns

true on success, false on error.

Required around sys_event_queue_peek(), the only operation that does not lock internally - every other operation here (sys_event_queue_push(), sys_event_queue_pop(), etc.) is safe to call without holding this lock.

Thread-context use only (this may block); never call from an IRQ handler. On backends where pushes are IRQ-safe, this does not exclude a concurrent push/pop, only other sys_event_queue_lock() callers - it coordinates callers of this function with each other, not with the queue's own internal operations.

sys_event_queue_peek()

sys_event_t sys_event_queue_peek

(

sys_event_queue_t *

queue

)

Peek at the next queued event without removing it.

Parameters

queue

Queue to inspect.

Returns

Next event, or NULL if none is available.

The caller is responsible for holding the queue lock while peeking.

sys_event_queue_pop()

sys_event_t sys_event_queue_pop

(

sys_event_queue_t *

queue

)

Pop the next event, blocking until one is available or shutdown.

Parameters

queue

Queue to read from.

Returns

Next event, or NULL if the queue is shut down and drained.

sys_event_queue_push()

bool sys_event_queue_push	(	sys_event_queue_t *	queue,
		sys_event_t	event
	)

Push an event, overwriting the oldest entry if the queue is full.

Parameters

queue	Queue to write to.
event	Non-NULL event payload.

Returns

true on success, false on error or after shutdown.

sys_event_queue_shutdown()

void sys_event_queue_shutdown

(

sys_event_queue_t *

queue

)

Prevent future pushes and wake blocked consumers.

Parameters

queue

Queue to shut down.

sys_event_queue_size()

size_t sys_event_queue_size

(

sys_event_queue_t *

queue

)

Return the current event count.

Parameters

queue

Queue to inspect.

Returns

Snapshot of the current number of queued events.

sys_event_queue_timed_pop()

sys_event_t sys_event_queue_timed_pop	(	sys_event_queue_t *	queue,
		uint32_t	timeout_ms
	)

Pop the next event with a timeout.

Parameters

queue	Queue to read from.
timeout_ms	Timeout in milliseconds. 0 waits indefinitely.

Returns

Next event, or NULL on timeout, invalid queue, or shutdown.

sys_event_queue_try_pop()

sys_event_t sys_event_queue_try_pop

(

sys_event_queue_t *

queue

)

Pop the next event without blocking.

Parameters

queue

Queue to read from.

Returns

Next event, or NULL if empty or invalid.

sys_event_queue_try_push()

bool sys_event_queue_try_push	(	sys_event_queue_t *	queue,
		sys_event_t	event
	)

Try to push an event without overwriting.

Parameters

queue	Queue to write to.
event	Non-NULL event payload.

Returns

true on success, false if full, invalid, or shut down.

sys_event_queue_unlock()

bool sys_event_queue_unlock

(

sys_event_queue_t *

queue

)

Unlock a queue after manual inspection.

Parameters

queue

Queue to unlock.

Returns

true on success, false on error.