Queues

A queue is a first-in first-out (FIFO) collection of objects. Objects can be inserted or removed from a queue from both a thread or an ISR. A queue supports the ability to block a calling thread when either the queue is full or when it is empty depending on the call.

Use QUEUE_Create() to create and initialize a queue. When creating a queue, it is required to provide an allocated array of slots that are used by the queue to reference (pointers) each of the objects contained within the queue. By providing slots during the creation of the queue, it keeps each queue and it's memory requirements completely independent from one another.

To insert an object into a queue, use QUEUE_Enqueue(). An object can be inserted from either a thread or an ISR. If from a thread, use the timeout parameter to block and wait for a free slot if the queue happens to be full. Since the queue does not copy the object into the queue, it is required that the object remains valid during the entire time it is referenced from a queue (i.e. not created on stack memory that is lost on breaking scope).

To remove an object from a queue, use QUEUE_Dequeue(). An object can be removed from either a thread or an ISR. If from a thread, use the timeout parameter to block and wait for an object to arrive if the queue happens to be empty.

Basic Usage

When creating a queue, an array of slots must be provided that are used to reference (pointers) each object contained within the queue. By providing the slots during creation, each queue can have a unique maximum capacity and there is no worst-case allocation occurring within the kernel.

#include "Kernel/kernel_queue.h"
#include <assert.h>

static QUEUE queue;                 /* Allocate a queue */

void APP_Example(void)
{
    static QUEUESLOT slots[10];     /* Allocate the slots to be used by the queue */
    STATUS status;


    status = QUEUE_Create(&queue,   /* Create the queue */
                          slots,    /* Provide a pointer to the slots for the queue */
                          10);      /* The max capacity for the queue  (should match number of slots) */

    assert(status == SUCCESS);
}

A queue only contains a reference (pointer) to each object contained within the queue and therefore it is important that each object remains valid during the entire time the object is contained within the queue. The example snippet below allocates an object (type MYSAMPLE) using a memory pool and places the sample into a queue to be processed later.

#include "Kernel/kernel_queue.h"
#include <assert.h>

/* An application-defined object */
typedef struct MYSAMPLE {
    UINT32 timestamp;
    UINT32 value;
} MYSAMPLE;

void APP_TakeSample(void)
{
    MYSAMPLE* sample;
    STATUS status;


    sample = POOL_Alloc(&pool, INFINITE);           /* Allocate a sample object */
    if (sample) {                                   /* Successfully allocated? */

        sample->timestamp = KERNEL_Timestamp();     /* Timestamp the sample */
        sample->value = APP_TakeMeasurement();      /* Make some measurement for example */

        status = QUEUE_Enqueue(&queue,              /* Place the sample into the queue */
                               sample,              /* A pointer to the object to be placed into the queue */
                               INFINITE);           /* Amount of time to block if the queue is full */

        assert(status == SUCCESS);
    }
}

Continuing from the code snippet above, the snippet below shows a thread that is blocked indefinitely waiting for the sample objects to arrive within the queue to be processed. If a sample is received, the thread can process the sample and then when finished, it returns the sample back to the memory pool in which it was allocated.

void APP_ExampleThread(void* arg)
{
    MYSAMPLE* sample;


    for(;;) {
	
        sample = QUEUE_Dequeue(&queue, INFINITE);   /* Wait indefinitely for a sample to arrive */
        if (sample) {                               /* Verify a valid object */

            APP_ProcessSample(sample);              /* Process the received sample */
            POOL_Free(&pool, sample);               /* Return the memory back to the pool */
        }
    }
}