Queues

poco provides a coroutine aware general purpose bounded length queuing primitive. This is the main mechanism for data transmissions between coroutines.

Queues are a multi-consumer multi-producer data structure. Usage includes sending data between coroutines and sending data between ISRs and coroutines.

This functionality is available from the specific <poco/queue.h> or the global <poco/poco.h> headers.

Creating a Queue

To create a queue, either the dynamic constructor queue_create() or the static constructor queue_create_static() can be used. In both cases, creating a queue requires the caller know the maximum number of items and the size of each item.

The dynamically created queue can be freed using queue_free(), which handles all internally allocated items too.

Putting Items

Any item placed in the queue is copied into the queue’s internal buffer. Once an item has been queued, it does not need to be preserved in the caller’s scope.

Warning

Queues perform a shallow copy when putting and getting items.

Use queue_put() to place an item in the queue. If within an ISR, use the ISR aware variant queue_put_from_isr().

Getting Items

Items obtained from the queue are removed from the queue once extracted. Similar to the put functions, queue_get() can be used to fetch an item from the queue, or the ISR aware variant queue_get_from_isr().

Inspecting the Length

The queue’s used length can also be inspected. Care is to be taken when using these functions, as they may not be accurate depending on the types of producers and consumers using the queue.

For example, an ISR producer may cause the queue_item_count() value to be invalid as the function may return a count lower than the true count.

Raw Functions

To facilitate general use of queues, the raw API is also available using the header <poco/queue_raw.h>. This special header exposes the non coroutine aware base API for use in specialised applications.

No Wait Variants

The queue API also provides the no wait variants of put and get.