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
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.
void	ove_queue_deinit (ove_queue_t q)
	Release resources held by a queue initialised with ove_queue_init().
int	ove_queue_create (ove_queue_t *q, size_t item_size, unsigned int max_items)
	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().
int	ove_queue_send (ove_queue_t q, const void *data, uint32_t timeout_ms)
	Send an item to the back of the queue, blocking if it is full.
int	ove_queue_receive (ove_queue_t q, void *buf, uint32_t timeout_ms)
	Receive (remove) an item from the front of the queue, blocking if it is empty.
int	ove_queue_send_from_isr (ove_queue_t q, const void *data)
	Send an item to the queue from an interrupt service routine.
int	ove_queue_receive_from_isr (ove_queue_t q, void *buf)
	Receive an item from the queue from an interrupt service routine.

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() — unified API that works in both heap and zero-heap mode. In zero-heap mode these are macros that generate per-call-site static storage; size parameters (item count, item size) must be compile-time constants.
• _init() / _deinit() — explicit storage control with caller-supplied buffers. Use when creating objects in loops, arrays, or structs.

Function Documentation

ove_queue_init()

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()

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()

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()

int ove_queue_send	(	ove_queue_t	q,
		const void *	data,
		uint32_t	timeout_ms
	)

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_ms milliseconds.

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_ms	Maximum time to wait in milliseconds if the queue is full. Pass OVE_WAIT_FOREVER to block indefinitely.

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_receive()

int ove_queue_receive	(	ove_queue_t	q,
		void *	buf,
		uint32_t	timeout_ms
	)

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_ms milliseconds.

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_ms	Maximum time to wait in milliseconds if the queue is empty. Pass OVE_WAIT_FOREVER to block indefinitely.

Returns

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

See also

ove_queue_send, ove_queue_receive_from_isr

ove_queue_send_from_isr()

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()

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_TIMEOUT if the queue is empty, or another negative error code.

See also

ove_queue_receive