Message queue

Fixed-size item FIFO queue for inter-thread and ISR-to-thread communication. More...

Typedefs
typedef struct ove_queue *	ove_queue_t
	Opaque handle for a message queue object.

Functions
OVE_NODISCARD int	ove_queue_init (ove_queue_t *q, ove_queue_storage_t *storage, void *buffer, size_t item_size, unsigned int max_items) OVE_NONNULL(1
	Initialise a queue using caller-supplied static storage and data buffer.
OVE_NODISCARD int void	ove_queue_deinit (ove_queue_t q)
	Release resources held by a queue initialised with ove_queue_init().
OVE_NODISCARD int	ove_queue_create (ove_queue_t *q, size_t item_size, unsigned int max_items) OVE_NONNULL(1)
	Allocate and initialise a queue from the heap.
void	ove_queue_destroy (ove_queue_t q)
	Destroy and free a queue allocated with ove_queue_create().
OVE_NODISCARD int	ove_queue_send (ove_queue_t q, const void *data, uint64_t timeout_ns) OVE_NONNULL(1
	Send an item to the back of the queue, blocking if it is full.
OVE_NODISCARD int static OVE_NODISCARD int	ove_queue_send_until (ove_queue_t q, const void *data, uint64_t deadline_ns)
	Deadline-based variant of ove_queue_send.
OVE_NODISCARD int	ove_queue_receive (ove_queue_t q, void *buf, uint64_t timeout_ns) OVE_NONNULL(1
	Receive (remove) an item from the front of the queue, blocking if it is empty.
OVE_NODISCARD int static OVE_NODISCARD int	ove_queue_receive_until (ove_queue_t q, void *buf, uint64_t deadline_ns)
	Deadline-based variant of ove_queue_receive.
OVE_NODISCARD int	ove_queue_send_from_isr (ove_queue_t q, const void *data) OVE_NONNULL(1
	Send an item to the queue from an interrupt service routine.
OVE_NODISCARD int OVE_NODISCARD int	ove_queue_receive_from_isr (ove_queue_t q, void *buf) OVE_NONNULL(1
	Receive an item from the queue from an interrupt service routine.
OVE_NODISCARD int OVE_NODISCARD int int	ove_queue_set_notify (ove_queue_t q, ove_notify_cb cb, void *user_data) OVE_NONNULL(1)
	Register a notify callback fired after every successful send.

Detailed Description

Fixed-size item FIFO queue for inter-thread and ISR-to-thread communication.

Note

All functions in this group require CONFIG_OVE_QUEUE to be defined. When CONFIG_OVE_QUEUE is not set, every function is replaced by a static inline stub that returns OVE_ERR_NOT_SUPPORTED.

Two allocation strategies are available:

• _create() / _destroy() — heap-allocated. Available only when OVE_HEAP_QUEUE is defined (i.e. CONFIG_OVE_ZERO_HEAP is not set).
• _init() / _deinit() — caller-supplied storage and data buffer. Available in both modes. See OVE_QUEUE_DEFINE_STATIC for a one-step static-allocation helper.

Function Documentation

ove_queue_init()

OVE_NODISCARD int ove_queue_init	(	ove_queue_t *	q,
		ove_queue_storage_t *	storage,
		void *	buffer,
		size_t	item_size,
		unsigned int	max_items
	)

Initialise a queue using caller-supplied static storage and data buffer.

No heap allocation is performed. The buffer must be at least item_size * max_items bytes and remain valid for the lifetime of the queue.

Note

Requires CONFIG_OVE_QUEUE.

Parameters

[out]	q	Receives the opaque queue handle on success.
[in]	storage	Pointer to statically allocated backend storage. Must remain valid for the lifetime of the queue.
[in]	buffer	Caller-allocated data buffer of at least item_size * max_items bytes.
[in]	item_size	Size in bytes of each queue item. Must be > 0.
[in]	max_items	Maximum number of items the queue can hold. Must be > 0.

Returns

OVE_OK on success, or a negative error code on failure.

See also

ove_queue_deinit, ove_queue_create

ove_queue_deinit()

OVE_NODISCARD int void ove_queue_deinit

(

ove_queue_t

q

)

Release resources held by a queue initialised with ove_queue_init().

The static storage and data buffer supplied at init time are not freed.

Note

Requires CONFIG_OVE_QUEUE.

Parameters

[in]

q

Handle returned by ove_queue_init().

See also

ove_queue_init

ove_queue_create()

OVE_NODISCARD int ove_queue_create	(	ove_queue_t *	q,
		size_t	item_size,
		unsigned int	max_items
	)

Allocate and initialise a queue from the heap.

Both the backend storage and the item data buffer are allocated from the heap.

Note

Requires CONFIG_OVE_QUEUE and OVE_HEAP_QUEUE (i.e. CONFIG_OVE_ZERO_HEAP must not be set).

Parameters

[out]	q	Receives the opaque queue handle on success.
[in]	item_size	Size in bytes of each queue item. Must be > 0.
[in]	max_items	Maximum number of items the queue can hold. Must be > 0.

Returns

OVE_OK on success, or a negative error code on failure.

See also

ove_queue_destroy, ove_queue_init

ove_queue_destroy()

void ove_queue_destroy

(

ove_queue_t

q

)

Destroy and free a queue allocated with ove_queue_create().

Note

Requires CONFIG_OVE_QUEUE and OVE_HEAP_QUEUE.

Parameters

[in]

q

Handle returned by ove_queue_create().

See also

ove_queue_create

ove_queue_send()

OVE_NODISCARD int ove_queue_send	(	ove_queue_t	q,
		const void *	data,
		uint64_t	timeout_ns
	)

Send an item to the back of the queue, blocking if it is full.

Copies item_size bytes from data into the queue. If the queue is full, the caller blocks for up to timeout_ns nanoseconds.

Note

Must not be called from an ISR — use ove_queue_send_from_isr() instead.

Requires CONFIG_OVE_QUEUE.

Parameters

[in]	q	Queue handle.
[in]	data	Pointer to the item to copy into the queue.
[in]	timeout_ns	Maximum time to wait in nanoseconds if the queue is full. Pass OVE_WAIT_FOREVER to block indefinitely. Use OVE_MS(n) / OVE_SEC(n) helpers for ergonomic values.

Returns

OVE_OK on success, OVE_ERR_TIMEOUT if the queue remained full for the entire wait period, OVE_ERR_QUEUE_FULL if the queue is full and the timeout is zero, or another negative error code.

See also

ove_queue_receive, ove_queue_send_from_isr

ove_queue_send_until()

OVE_NODISCARD int static OVE_NODISCARD int ove_queue_send_until ( ove_queue_t  q, const void *  data, uint64_t  deadline_ns  )

inlinestatic

Deadline-based variant of ove_queue_send.

Equivalent to calling ove_queue_send with the time remaining until deadline_ns (a steady-clock value from ove_time_now_steady_ns). Pass OVE_WAIT_FOREVER for an indefinite block.

Note

Requires CONFIG_OVE_QUEUE.

Parameters

[in]	q	Queue handle.
[in]	data	Pointer to the item to copy into the queue.
[in]	deadline_ns	Absolute deadline against ove_time_now_steady_ns, or OVE_WAIT_FOREVER.

Returns

Same set of return codes as ove_queue_send.

ove_queue_receive()

OVE_NODISCARD int ove_queue_receive	(	ove_queue_t	q,
		void *	buf,
		uint64_t	timeout_ns
	)

Receive (remove) an item from the front of the queue, blocking if it is empty.

Copies item_size bytes out of the queue into buf. If the queue is empty, the caller blocks for up to timeout_ns nanoseconds.

Note

Must not be called from an ISR — use ove_queue_receive_from_isr() instead.

Requires CONFIG_OVE_QUEUE.

Parameters

[in]	q	Queue handle.
[out]	buf	Buffer to copy the received item into. Must be at least item_size bytes.
[in]	timeout_ns	Maximum time to wait in nanoseconds if the queue is empty. Pass OVE_WAIT_FOREVER to block indefinitely. Use OVE_MS(n) / OVE_SEC(n) helpers for ergonomic values.

Returns

OVE_OK on success, OVE_ERR_TIMEOUT if the queue remained empty for the entire wait period, OVE_ERR_QUEUE_EMPTY if the queue is empty and the timeout is zero, or another negative error code.

See also

ove_queue_send, ove_queue_receive_from_isr

ove_queue_receive_until()

OVE_NODISCARD int static OVE_NODISCARD int ove_queue_receive_until ( ove_queue_t  q, void *  buf, uint64_t  deadline_ns  )

inlinestatic

Deadline-based variant of ove_queue_receive.

Equivalent to calling ove_queue_receive with the time remaining until deadline_ns (a steady-clock value from ove_time_now_steady_ns). Pass OVE_WAIT_FOREVER for an indefinite block.

Note

Requires CONFIG_OVE_QUEUE.

Parameters

[in]	q	Queue handle.
[out]	buf	Buffer to receive the item; must be at least item_size bytes.
[in]	deadline_ns	Absolute deadline against ove_time_now_steady_ns, or OVE_WAIT_FOREVER.

Returns

Same set of return codes as ove_queue_receive.

ove_queue_send_from_isr()

OVE_NODISCARD int ove_queue_send_from_isr	(	ove_queue_t	q,
		const void *	data
	)

Send an item to the queue from an interrupt service routine.

Non-blocking ISR-safe variant of ove_queue_send(). Returns immediately if the queue is full.

Note

Requires CONFIG_OVE_QUEUE.

Parameters

[in]	q	Queue handle.
[in]	data	Pointer to the item to copy into the queue.

Returns

OVE_OK on success, OVE_ERR_QUEUE_FULL if the queue has no space, or another negative error code.

See also

ove_queue_send

ove_queue_receive_from_isr()

OVE_NODISCARD int OVE_NODISCARD int ove_queue_receive_from_isr	(	ove_queue_t	q,
		void *	buf
	)

Receive an item from the queue from an interrupt service routine.

Non-blocking ISR-safe variant of ove_queue_receive(). Returns immediately if the queue is empty.

Note

Requires CONFIG_OVE_QUEUE.

Parameters

[in]	q	Queue handle.
[out]	buf	Buffer to copy the received item into. Must be at least item_size bytes.

Returns

OVE_OK on success, OVE_ERR_QUEUE_EMPTY if the queue is empty, or another negative error code.

See also

ove_queue_receive

ove_queue_set_notify()

OVE_NODISCARD int OVE_NODISCARD int int ove_queue_set_notify	(	ove_queue_t	q,
		ove_notify_cb	cb,
		void *	user_data
	)

Register a notify callback fired after every successful send.

The callback is invoked at the tail of ove_queue_send and ove_queue_send_from_isr — once an item has been enqueued. Only one slot per queue; a later call replaces an earlier registration. Pass cb=NULL to clear.

Designed for async runtimes that need a wake hook (the Rust binding uses it to call AtomicWaker::wake on a task awaiting AsyncQueue::recv).

The callback runs in whatever context the originating send used — thread or ISR. Implementations must be non-blocking and ISR-safe.

Parameters

[in]	q	Queue handle.
[in]	cb	Callback to invoke after successful sends, or NULL to clear.
[in]	user_data	Opaque pointer forwarded to cb.

Returns

OVE_OK on success, negative error code on failure.