Queue set for monitoring multiple queues in FreeRTOS

Introduction

A queue set lets you watch many queues at once. You can see which queue has data ready without checking each one separately.

You have several queues and want to wait for data from any of them.

You want to simplify your code by handling multiple queues with one wait.

You need to react quickly when any queue gets new data.

You want to save CPU time by not polling each queue repeatedly.

Syntax

FreeRTOS

/* Create a queue set */
QueueSetHandle_t xQueueSet = xQueueCreateSet( totalNumberOfItems );

/* Add queues to the set */
xQueueAddToSet( xQueueHandle, xQueueSet );

/* Wait for any queue in the set to have data */
QueueHandle_t xActivatedQueue = xQueueSelectFromSet( xQueueSet, xTicksToWait );

xQueueCreateSet needs the total number of items all queues can hold combined.

xQueueSelectFromSet blocks until any queue in the set has data or timeout expires.

Examples

This example creates a queue set that can hold 10 items total from two queues.

FreeRTOS

/* Create a queue set for 10 items total */
QueueSetHandle_t xQueueSet = xQueueCreateSet( 10 );

/* Add two queues to the set */
xQueueAddToSet( xQueue1, xQueueSet );
xQueueAddToSet( xQueue2, xQueueSet );

This waits without timeout until any queue in the set has data.

FreeRTOS

/* Wait forever for any queue in the set to have data */
QueueHandle_t xActivatedQueue = xQueueSelectFromSet( xQueueSet, portMAX_DELAY );

Always check if the queue set was created successfully before using it.

FreeRTOS

/* Handle empty queue set case */
if (xQueueSet == NULL) {
    // Handle error: queue set not created
}

Sample Program

This program creates two queues and a queue set to monitor them. It sends data to both queues, waits for any queue to have data, then prints which queue received data and the value.

FreeRTOS

#include "FreeRTOS.h"
#include "queue.h"
#include "task.h"
#include <stdio.h>

/* Create two queues and a queue set to monitor both */
void vQueueSetExample(void *pvParameters) {
    QueueHandle_t xQueue1 = xQueueCreate( 5, sizeof(int) );
    QueueHandle_t xQueue2 = xQueueCreate( 5, sizeof(int) );

    if (xQueue1 == NULL || xQueue2 == NULL) {
        printf("Failed to create queues\n");
        vTaskDelete(NULL);
    }

    QueueSetHandle_t xQueueSet = xQueueCreateSet( 10 );
    if (xQueueSet == NULL) {
        printf("Failed to create queue set\n");
        vTaskDelete(NULL);
    }

    xQueueAddToSet( xQueue1, xQueueSet );
    xQueueAddToSet( xQueue2, xQueueSet );

    int value1 = 100;
    int value2 = 200;

    /* Send data to queues */
    xQueueSend( xQueue1, &value1, 0 );
    xQueueSend( xQueue2, &value2, 0 );

    printf("Waiting for data on any queue in the set...\n");

    QueueHandle_t xActivatedQueue = xQueueSelectFromSet( xQueueSet, portMAX_DELAY );

    if (xActivatedQueue == xQueue1) {
        int receivedValue;
        xQueueReceive( xQueue1, &receivedValue, 0 );
        printf("Data received from Queue 1: %d\n", receivedValue);
    } else if (xActivatedQueue == xQueue2) {
        int receivedValue;
        xQueueReceive( xQueue2, &receivedValue, 0 );
        printf("Data received from Queue 2: %d\n", receivedValue);
    } else {
        printf("No queue activated\n");
    }

    vTaskDelete(NULL);
}

int main(void) {
    xTaskCreate( vQueueSetExample, "QueueSetTask", configMINIMAL_STACK_SIZE, NULL, 1, NULL );
    vTaskStartScheduler();
    return 0;
}

Important Notes

The time complexity of xQueueSelectFromSet is efficient because it blocks until data is available, avoiding busy waiting.

Space complexity depends on the total size of all queues combined in the set.

Common mistake: forgetting to add queues to the queue set before waiting on it.

Use queue sets when you want to wait on multiple queues simultaneously instead of checking each queue separately.

Summary

Queue sets let you watch many queues with one wait call.

They help write simpler and more efficient code when handling multiple queues.

Always create the queue set with enough total size and add all queues before waiting.

Practice

1. What is the main purpose of a Queue Set in FreeRTOS?

easy

A. To monitor multiple queues with a single wait call

B. To increase the size of a single queue

C. To create a queue that stores different data types

D. To prioritize tasks based on queue length

Solution

1. Step 1: Recall the purpose of a Queue Set

   A Queue Set allows monitoring multiple queues or semaphores with one blocking call.

2. Step 2: Match options to the Queue Set purpose

   Only "To monitor multiple queues with a single wait call" correctly describes this purpose; others describe unrelated features.

3. Final Answer:

   To monitor multiple queues with a single wait call -> Option A

4. Quick Check:

   Queue Set = single wait for many queues [OK]

Hint: Queue Set = watch many queues with one wait [OK]

Common Mistakes:

• Thinking Queue Set increases queue size
• Confusing Queue Set with task priority
• Believing Queue Set stores mixed data types

2. Which of the following is the correct way to create a queue set for monitoring two queues in FreeRTOS?

easy

A. xQueueSetCreate( queue1Length + queue2Length, itemSize )

B. xQueueSetCreate( queue1Length * queue2Length, itemSize )

C. xQueueSetCreate( queue1Length + queue2Length, sizeof(void*) )

D. xQueueSetCreate( queue1Length + queue2Length, 0 )

Solution

1. Step 1: Review parameters of xQueueSetCreate

   The first parameter is the total number of items the set can hold, usually sum of queue lengths. The second is the size of a pointer (sizeof(void*)) because queue sets hold references to queues.

2. Step 2: Evaluate each option

   xQueueSetCreate( queue1Length + queue2Length, sizeof(void*) ) correctly uses sum of lengths and pointer size. Others are incorrect: itemSize, multiplication, or zero size.

3. Final Answer:

   xQueueSetCreate( queue1Length + queue2Length, sizeof(void*) ) -> Option C

4. Quick Check:

   Queue set size = sum lengths, item size = pointer size [OK]

Hint: Queue set size = sum of queues, item size = pointer size [OK]

Common Mistakes:

• Using item size instead of pointer size
• Multiplying queue lengths instead of adding
• Setting item size to zero

3. Given the code snippet:

QueueHandle_t queue1 = xQueueCreate(5, sizeof(int));
QueueHandle_t queue2 = xQueueCreate(3, sizeof(int));
QueueSetHandle_t queueSet = xQueueSetCreate(8, sizeof(void*));
xQueueAddToSet(queue1, queueSet);
xQueueAddToSet(queue2, queueSet);
QueueSetMemberHandle_t activatedQueue = xQueueSelectFromSet(queueSet, portMAX_DELAY);

What does activatedQueue represent after xQueueSelectFromSet returns?

medium

A. A pointer to the data item received

B. A handle to the queue that has data available

C. The total number of items in all queues

D. NULL if no queues have data

Solution

1. Step 1: Analyze xQueueSelectFromSet behavior

   This function blocks until any queue in the set has data, then returns a handle to that queue.

2. Step 2: Determine what activatedQueue holds

   It holds the queue handle that has data ready to be read, not the data itself or count.

3. Final Answer:

   A handle to the queue that has data available -> Option B

4. Quick Check:

   xQueueSelectFromSet returns queue handle with data [OK]

Hint: xQueueSelectFromSet returns queue handle with data ready [OK]

Common Mistakes:

• Thinking it returns data pointer
• Confusing with total item count
• Expecting NULL when data is available

4. What is wrong with this code snippet for using a queue set?

QueueSetHandle_t set = xQueueSetCreate(5, sizeof(void*));
QueueHandle_t q1 = xQueueCreate(3, sizeof(int));
xQueueAddToSet(q1, set);
QueueSetMemberHandle_t member = xQueueSelectFromSet(set, portMAX_DELAY);
int value;
xQueueReceive(set, &value, 0);

medium

A. xQueueCreate uses wrong item size

B. Queue set size is too small for the queue length

C. xQueueAddToSet is missing for q1

D. xQueueReceive is called with a queue set handle instead of a queue handle

Solution

1. Step 1: Examine the xQueueReceive call

   The code calls xQueueReceive(set, &value, 0), passing the queue set handle 'set'.

2. Step 2: Recall the return value of xQueueSelectFromSet

   It returns 'member', a handle to the queue with data available.

3. Step 3: Identify the mistake

   xQueueReceive must use the queue handle 'member', not the queue set handle 'set'.

4. Final Answer:

   xQueueReceive is called with a queue set handle instead of a queue handle -> Option D

5. Quick Check:

   xQueueReceive uses queue handle from set, not set itself [OK]

Hint: xQueueSelectFromSet returns queue handle for xQueueReceive [OK]

Common Mistakes:

• Confusing queue set handle with queue handle
• Assuming queue set size must match queue length
• Missing xQueueAddToSet call

5. You want to monitor three queues with lengths 4, 5, and 6 using a queue set. Which of the following is the best practice to create and use the queue set correctly?

hard

A. Create queue set with size 15, add all queues, then call xQueueSelectFromSet to wait

B. Create queue set with size 6, add all queues, then call xQueueSelectFromSet to wait

C. Create queue set with size 4, add only the largest queue, then call xQueueSelectFromSet

D. Create queue set with size 15, add queues after calling xQueueSelectFromSet

Solution

1. Step 1: Calculate total queue set size

   The queue set size must be at least the sum of all queue lengths: 4 + 5 + 6 = 15.

2. Step 2: Add all queues before waiting

   All queues must be added to the set before calling xQueueSelectFromSet to monitor them properly.

3. Step 3: Evaluate options

   Create queue set with size 15, add all queues, then call xQueueSelectFromSet to wait follows best practice: correct size, all queues added, then wait. Others fail on size, timing, or completeness.

4. Final Answer:

   Create queue set with size 15, add all queues, then call xQueueSelectFromSet to wait -> Option A

5. Quick Check:

   Queue set size = sum lengths, add all queues first [OK]

Hint: Queue set size = sum of queues; add all before waiting [OK]

Common Mistakes:

• Using queue set size smaller than total queue lengths
• Adding queues after waiting
• Adding only some queues to the set