Queue blocking behavior (timeout) in FreeRTOS - Step-by-Step Execution

Concept Flow - Queue blocking behavior (timeout)

Task tries to send to queue

↓

Is queue full?

No→Send item immediately

Yes↓

Wait for space with timeout

↓

Space available

↓

Send item

↓

Task continues

The task tries to send to a queue. If full, it waits up to a timeout for space. If space frees before timeout, it sends; else it fails.

Execution Sample

FreeRTOS

xQueueSend(queue, &item, pdMS_TO_TICKS(100));
// Task waits max 100ms if queue full
// Returns pdTRUE if sent, pdFALSE if timeout

Task attempts to send an item to a queue, waiting up to 100ms if the queue is full.

Execution Table

Step	Action	Queue State (items/count)	Timeout Counter (ms)	Result	Task State
1	Task calls xQueueSend	Full (5/5)	100	Wait for space	Blocked, waiting
2	Timeout decremented by 20ms	Full (5/5)	80	Still waiting	Blocked, waiting
3	Timeout decremented by 20ms	Full (5/5)	60	Still waiting	Blocked, waiting
4	One item removed from queue	Not full (4/5)	60	Space available	Unblocked
5	Task sends item	Full (5/5)	60	pdTRUE	Running
6	Task continues normal execution	Full (5/5)	N/A	Success	Running
7	Later, task calls xQueueSend again	Full (5/5)	100	Wait for space	Blocked, waiting
8	Timeout decremented by 100ms	Full (5/5)	0	Timeout reached	Unblocked
9	Task fails to send	Full (5/5)	0	pdFALSE	Running
10	Task handles failure	Full (5/5)	N/A	Failure handled	Running

💡 Execution stops when task either sends item successfully or timeout expires without space.

Variable Tracker

Variable	Start	After Step 2	After Step 4	After Step 5	After Step 8	Final
Queue items count	5	5	4	5	5	5
Timeout counter (ms)	100	80	60	60	0	0
Task state	Running	Blocked	Unblocked	Running	Unblocked	Running
xQueueSend result	N/A	N/A	N/A	pdTRUE	N/A	pdFALSE

Key Moments - 3 Insights

Why does the task block when the queue is full?

Because the queue has no space to add new items, the task waits (blocks) until space frees or timeout expires, as shown in steps 1 and 2 in the execution table.

What happens if the timeout expires before space is available?

The task stops waiting and xQueueSend returns failure (pdFALSE), as shown in steps 8 and 9 where timeout reaches zero and sending fails.

How does the task know when space is available in the queue?

When another task or interrupt removes an item, the queue is no longer full, unblocking the waiting task to send its item, as seen in step 4 where queue count drops and task unblocks.

Visual Quiz - 3 Questions

Look at the execution table, what is the queue item count after step 4?

A 0 items

B 5 items

C 4 items

D Cannot tell

💡 Hint

Check the 'Queue State' column at step 4 in the execution table.

At which step does the task stop waiting because the timeout expired?

A Step 8

B Step 5

C Step 3

D Step 10

💡 Hint

Look for when 'Timeout counter' reaches 0 and 'Result' says 'Timeout reached' in the execution table.

If the queue never frees space, what will xQueueSend return after timeout?

A pdTRUE

B pdFALSE

C Block forever

D Crash

💡 Hint

Refer to the 'Result' column at step 9 where timeout expired without space.

Concept Snapshot

xQueueSend(queue, &item, timeout) tries to send item to queue.
If queue full, task blocks up to timeout waiting for space.
If space frees before timeout, item is sent and function returns pdTRUE.
If timeout expires first, function returns pdFALSE.
Task state changes from running to blocked and back accordingly.
Timeout is in ticks, often converted from ms with pdMS_TO_TICKS().

Full Transcript

This visual trace shows how a FreeRTOS task tries to send an item to a queue using xQueueSend with a timeout. Initially, if the queue is full, the task blocks and waits for space. The timeout counter decreases as time passes. If another task removes an item, space becomes available, the task unblocks, sends its item, and continues running. If the timeout expires before space frees, the task unblocks but the send fails, returning pdFALSE. Variables tracked include queue item count, timeout counter, task state, and send result. Key moments clarify why blocking happens, what occurs on timeout, and how the task detects space availability. The quiz tests understanding of queue state changes, timeout expiration, and return values. The snapshot summarizes the behavior and usage of xQueueSend with timeout in FreeRTOS.

Practice

1. What does the xTicksToWait parameter control in FreeRTOS queue functions like xQueueReceive() or xQueueSend()?

easy

A. The number of items currently in the queue.

B. The size of the queue in bytes.

C. The maximum time a task will wait for the queue operation before timing out.

D. The priority of the task accessing the queue.

Solution

1. Step 1: Understand the role of xTicksToWait

   This parameter specifies how long a task should wait if the queue is full (for send) or empty (for receive).

2. Step 2: Relate to queue blocking behavior

   If the queue operation cannot proceed immediately, the task blocks for up to xTicksToWait ticks before timing out.

3. Final Answer:

   The maximum time a task will wait for the queue operation before timing out. -> Option C

4. Quick Check:

   Timeout duration = xTicksToWait [OK]

Hint: Remember: xTicksToWait sets wait time before giving up [OK]

Common Mistakes:

• Confusing xTicksToWait with queue size
• Thinking it sets task priority
• Assuming it counts queue items

2. Which of the following is the correct way to call xQueueReceive() with a timeout of 10 ticks?

easy

A. xQueueReceive(queueHandle, &data);

B. xQueueReceive(queueHandle, data, 10);

C. xQueueReceive(queueHandle, &data, "10");

D. xQueueReceive(queueHandle, &data, 10);

Solution

1. Step 1: Check function parameters

   xQueueReceive() requires the queue handle, pointer to data buffer, and timeout in ticks as a number.

2. Step 2: Validate correct syntax

   xQueueReceive(queueHandle, &data, 10); correctly passes the address of data and numeric timeout 10 ticks.

3. Final Answer:

   xQueueReceive(queueHandle, &data, 10); -> Option D

4. Quick Check:

   Correct parameters and timeout type = xQueueReceive(queueHandle, &data, 10); [OK]

Hint: Use &data and numeric timeout for xQueueReceive [OK]

Common Mistakes:

• Passing data instead of &data
• Using string "10" instead of number 10
• Omitting timeout parameter

3. Consider this code snippet:

if(xQueueReceive(queue, &item, 5) == pdPASS) {
    process(item);
} else {
    handleTimeout();
}

What happens if the queue is empty and no item arrives within 5 ticks?

medium

A. The function returns after 5 ticks with a failure code, and handleTimeout() is called.

B. The task blocks indefinitely waiting for an item.

C. The function returns immediately with pdPASS.

D. The queue is deleted automatically.

Solution

1. Step 1: Analyze xQueueReceive behavior with timeout

   If the queue is empty, the task waits up to 5 ticks for an item to arrive.

2. Step 2: Understand return values

   If no item arrives in 5 ticks, xQueueReceive() returns a failure code (not pdPASS), so handleTimeout() runs.

3. Final Answer:

   The function returns after 5 ticks with a failure code, and handleTimeout() is called. -> Option A

4. Quick Check:

   Timeout triggers failure return = The function returns after 5 ticks with a failure code, and handleTimeout() is called. [OK]

Hint: Timeout means failure return, so else branch runs [OK]

Common Mistakes:

• Assuming indefinite block without timeout
• Thinking pdPASS is returned on timeout
• Believing queue deletes itself

4. Which of the following correctly describes this code snippet:

BaseType_t result = xQueueSend(queue, &data, 0);
if(result == pdFAIL) {
    // handle failure
}

medium

A. Using 0 as timeout means the task will wait forever.

B. Using 0 as timeout means the function returns immediately if the queue is full.

C. The timeout parameter should be a pointer, not a number.

D. The return value should be compared to pdPASS, not pdFAIL.

Solution

1. Step 1: Understand timeout=0 behavior in xQueueSend

   A timeout of 0 means the function does not block; it returns immediately if the queue is full.

2. Step 2: Check the error handling logic

   If the queue is full, xQueueSend() returns pdFAIL immediately, so the failure handling code runs correctly.

3. Final Answer:

   Using 0 as timeout means the function returns immediately if the queue is full. -> Option B

4. Quick Check:

   Timeout 0 means no wait, immediate return = Using 0 as timeout means the function returns immediately if the queue is full. [OK]

Hint: Timeout 0 means no wait, immediate fail if full [OK]

Common Mistakes:

• Thinking 0 means wait forever
• Confusing timeout type with pointer
• Comparing return to wrong constant

5. You want a task to send data to a queue but only wait up to 20 ticks if the queue is full. If the queue remains full after 20 ticks, the task should perform an alternative action. Which code snippet correctly implements this behavior?

hard

A. if(xQueueSend(queue, &data, 20) == pdPASS) {
// sent successfully
} else {
// alternative action
}

B. if(xQueueSend(queue, &data, 0) == pdFAIL) {
// alternative action
} else {
// sent successfully
}

C. if(xQueueSend(queue, &data, portMAX_DELAY) == pdPASS) {
// sent successfully
} else {
// alternative action
}

D. if(xQueueSend(queue, &data, 20) == pdFAIL) {
// sent successfully
} else {
// alternative action
}

Solution

1. Step 1: Understand desired behavior

   The task should wait up to 20 ticks to send data, then do alternative action if it fails.

2. Step 2: Analyze each option

   if(xQueueSend(queue, &data, 20) == pdPASS) { // sent successfully } else { // alternative action } waits 20 ticks and checks for pdPASS to confirm success; else runs alternative action. if(xQueueSend(queue, &data, 0) == pdFAIL) { // alternative action } else { // sent successfully } waits 0 ticks (no wait). if(xQueueSend(queue, &data, portMAX_DELAY) == pdPASS) { // sent successfully } else { // alternative action } waits forever. if(xQueueSend(queue, &data, 20) == pdFAIL) { // sent successfully } else { // alternative action } reverses success/failure logic.

3. Final Answer:

   if(xQueueSend(queue, &data, 20) == pdPASS) { // sent successfully } else { // alternative action } -> Option A

4. Quick Check:

   Wait 20 ticks, success check = if(xQueueSend(queue, &data, 20) == pdPASS) { // sent successfully } else { // alternative action } [OK]

Hint: Wait 20 ticks, check for pdPASS to confirm send success [OK]

Common Mistakes:

• Using 0 ticks instead of 20
• Waiting forever with portMAX_DELAY
• Mixing up pdPASS and pdFAIL checks