Queue library

This is auxiliary implementation of queue. More...

Data Structures
struct	Queue
	Generic queue structure. More...
struct	BasicQueue
	Queue with 256 bytes of storage preallocated. More...

Macros
#define	QUEUE_LENGTH   256
#define	STATIC_QUEUE_T(name, size)
	Create queue type with custom storage allocation size.

Functions
bool	queue_init (struct Queue *queue, uint8_t depth, uint8_t item_size)
	Initialize queue structure.
bool	queue_send (struct Queue *queue, const void *data)
	Send data via the queue.
bool	queue_send_silent (struct Queue *queue, const void *data)
	Fills queue without notifying receivers.
bool	queue_receive_timeout (struct Queue *queue, void *data, uint32_t timeout_us)
	Receive data from queue with timeout.
static bool	queue_receive (struct Queue *queue, void *data)
	Receive data from queue.
bool	queue_empty (struct Queue *queue)
	Returns queue status.
bool	queue_full (struct Queue *queue)
	Tell if queue is already full.

Detailed Description

This is auxiliary implementation of queue.

CMRX does not offer queues as an inherent service provided by the kernel as this does not fit the microkernel nature of CMRX RTOS.

CMRX natively supports lower communication and synchronization primitives than queues.

This implementation offers single producer-single consumer safe implementation of queue that is usable even from interrupt context.

This library will find uses if you need to implement queue between threads of single process and/or you need to push data into queue from ISR handler.

If you need a queue that works across processes then see aux_queue_server which wraps this library into RPC interface and thus is usable globally.

Macro Definition Documentation

QUEUE_LENGTH

#define QUEUE_LENGTH   256

STATIC_QUEUE_T

#define STATIC_QUEUE_T	(		name,
			size
	)

Value:

typedef struct {\
    union {\
        struct Queue q;\
        unsigned char buffer[sizeof(struct Queue) + size];\
    };\
} name

Create queue type with custom storage allocation size.

This is a helper macro that defines type for queue with developer-specified size of the queue data storage. Suitable for cases where fixed allocation size of 256 bytes of BasicQueue is either too much or too little.

Parameters

name	resulting name of queue variable
size	size of the buffer in bytes

Function Documentation

queue_empty()

bool queue_empty

(

struct Queue *

queue

)

Returns queue status.

Parameters

[in]

queue

pointer to queue queried

Returns

true if queue is empty, false otherwise

queue_full()

bool queue_full

(

struct Queue *

queue

)

Tell if queue is already full.

Parameters

[in]

queue

pointer to queue queried

Returns

true if queue is full false otherwise

queue_init()

bool queue_init	(	struct Queue *	queue,
		uint8_t	depth,
		uint8_t	item_size
	)

Initialize queue structure.

This call will initialize queue structure. It does not examine previous state of the structure, thus any previous existing state is erased.

Parameters

[in]	queue	pointer to queue being initialized
[in]	depth	amount of entries queue should be able to store
[in]	item_size	size of each item in bytes

Returns

true if queue was initialized. Returns false if queue storage capacity is not sufficient for requested depth and item size

queue_receive()

static bool queue_receive ( struct Queue *  queue, void *  data  )

inlinestatic

Receive data from queue.

This will copy the oldest data out of the queue. If queue is empty then this call will block until queue is filled with at least one entry of data.

Parameters

[in]	queue	pointer to queue data is retrieved from
[out]	data	pointer to place where data will be written

Returns

true. Returns false in case spurious interrupt occurred and queue is still empty.

queue_receive_timeout()

bool queue_receive_timeout	(	struct Queue *	queue,
		void *	data,
		uint32_t	timeout_us
	)

Receive data from queue with timeout.

This will copy the oldest data out of the queue. If queue is empty then this call will block until queue is filled with data or until specified amount of time passed with no new data in the queue.

Parameters

[in]	queue	pointer to queue data is retrieved from
[out]	data	pointer to place where data will be written
[in]	timeout_us	amount of time to wait for the data. If 0 is passed as timeout, then the function will wait indefinitely.

Returns

true if data were read from queue. Returns false in case specified amount of time elapsed and no new data is available.

queue_send()

bool queue_send	(	struct Queue *	queue,
		const void *	data
	)

Send data via the queue.

This will copy data into queue. Queue must be initialized before this call is made. The size of data is determined based on value of item_size used during queue initialization.

Parameters

[in]	queue	pointer to queue data is being sent into
[in]	data	pointer to data

Returns

true if data was copied into queue and false if queue is already full

queue_send_silent()

bool queue_send_silent	(	struct Queue *	queue,
		const void *	data
	)

Fills queue without notifying receivers.

This method performs the same action as queue_send() without actually performing notification of clients waiting for queue data to be available. This function may be useful e.g. in the interrupt context where calling notify_object() is not possible.

Warning

It is caller responsibility to perform suitable version of notification on the queue object, otherwise any potential receivers which are waiting for the data to arrive will keep waiting.

Parameters

	queue	pointer to queue data is being sent into
[in]	data	pointer to data

Returns

true if data was copied into queue and false if queue is already full