Menu
FreeRTOS Kernel
Developer Guide

Queue Management

Queues provide a task-to-task, task-to-interrupt, and interrupt-to-task communication mechanism. This section covers task-to-task communication. For information about task-to-interrupt and interrupt-to-task communication, see Interrupt Management.

This section covers:

  • How to create a queue.

  • How a queue manages the data it contains.

  • How to send data to a queue.

  • How to receive data from a queue.

  • What it means to block on a queue.

  • How to block on multiple queues.

  • How to overwrite data in a queue.

  • How to clear a queue.

  • The effect of task priorities when writing to and reading from a queue.

Characteristics of a Queue

Data Storage

A queue can hold a finite number of fixed-size data items. The maximum number of items a queue can hold is called its length. Both the length and the size of each data item are set when the queue is created.

Queues are normally used as first in, first out (FIFO) buffers, where data is written to the end (tail) of the queue and removed from the front (head) of the queue.

The following figure shows data being written to and read from a queue that is being used as a FIFO. It is also possible to write to the front of a queue and to overwrite data that is already at the front of a queue.

There are two ways to implement queue behavior:

  1. Queue by copy

    Data sent to the queue is copied byte for byte into the queue.

  2. Queue by reference

    The queue holds pointers to the data sent to the queue, not the data itself.

FreeRTOS uses queue by copy. This method is considered more powerful and simpler to use than queueing by reference because:

  • A stack variable can be sent directly to a queue, even though the variable will not exist after the function in which it is declared has exited.

  • Data can be sent to a queue without first allocating a buffer to hold the data, and then copying the data into the allocated buffer.

  • The sending task can immediately reuse the variable or buffer that was sent to the queue.

  • The sending task and the receiving task are completely decoupled. Application designers do not need to concern themselves with which task owns the data or which task is responsible for releasing the data.

  • Queuing by copy does not prevent the queue from also being used to queue by reference. For example, when the size of the data being queued makes it impractical to copy the data into the queue, then a pointer to the data can be copied into the queue instead.

  • RTOS takes complete responsibility for allocating the memory used to store data.

  • In a memory-protected system, the RAM that a task can access is restricted. In that case, queueing by reference can be used only if the sending and receiving tasks can access the RAM in which the data is stored. Queuing by copy does not impose that restriction. The kernel always runs with full privileges, allowing a queue to be used to pass data across memory protection boundaries.

Access by Multiple Tasks

Queues are objects that can be accessed by any task or Interrupt Service Register (ISR) that knows of their existence. Any number of tasks can write to the same queue, and any number of tasks can read from the same queue. It is very common for a queue to have multiple writers, but much less common for a queue to have multiple readers.

Blocking on Queue Reads

When a task attempts to read from a queue, it can optionally specify a block time. This is the time the task will be kept in the Blocked state to wait for data to be available from the queue, should the queue already be empty. A task in the Blocked state, waiting for data to become available from a queue, is automatically moved to the Ready state when another task or interrupt places data into the queue. The task will also be moved automatically from the Blocked state to the Ready state if the specified block time expires before data becomes available.

Queues can have multiple readers, so it is possible for a single queue to have more than one task blocked on it waiting for data. When this is the case, only one task will be unblocked when data becomes available. The task that is unblocked will always be the highest priority task that is waiting for data. If the blocked tasks have equal priority, then the task that has been waiting for data the longest will be unblocked.

Blocking on Queue Writes

Just as when reading from a queue, a task can optionally specify a block time when writing to a queue. In this case, the block time is the maximum time the task should be held in the Blocked state to wait for space to become available on the queue, should the queue already be full.

Queues can have multiple writers, so it is possible for a full queue to have more than one task blocked on it waiting to complete a send operation. When this is the case, only one task will be unblocked when space on the queue becomes available. The task that is unblocked will always be the highest priority task that is waiting for space. If the blocked tasks have equal priority, then the task that has been waiting for space the longest will be unblocked.

Blocking on Multiple Queues

Queues can be grouped into sets, allowing a task to enter the Blocked state to wait for data to become available on any of the queues in the set. For more information about queue sets, see Receiving from Multiple Queues.

Using a Queue

xQueueCreate() API Function

A queue must be explicitly created before it can be used.

Queues are referenced by handles, which are variables of type QueueHandle_t. The xQueueCreate() API function creates a queue and returns a QueueHandle_t that references the queue it created.

FreeRTOS V9.0.0 also includes the xQueueCreateStatic() function, which allocates the memory required to create a queue statically at compile time. FreeRTOS allocates RAM from the FreeRTOS heap when a queue is created. The RAM is used to hold both the queue data structures and the items that are contained in the queue. xQueueCreate() will return NULL if there is insufficient heap RAM available for the queue to be created.

The xQueueCreate() API function prototype is shown here.

QueueHandle_t xQueueCreate( UBaseType_t uxQueueLength, UBaseType_t uxItemSize );

The following table lists the xQueueCreate() parameters and return value.

Parameter Name

Description

uxQueueLength

The maximum number of items that the queue being created can hold at any one time.

uxItemSize

The size, in bytes, of each data item that can be stored in the queue.

Return Value

If NULL is returned, then the queue cannot be created because there is insufficient heap memory available for FreeRTOS to allocate the queue data structures and storage area.

If a non-NULL value is returned, the queue has been created successfully. The returned value should be stored as the handle to the created queue.

After a queue has been created, the xQueueReset() API function can be used to return the queue to its original empty state.

xQueueSendToBack() and xQueueSendToFront() API Functions

xQueueSendToBack() is used to send data to the back (tail) of a queue. xQueueSendToFront() is used to send data to the front (head) of a queue.

xQueueSend() is equivalent to, and exactly the same as, xQueueSendToBack().

Note: Do not call xQueueSendToFront() or xQueueSendToBack() from an interrupt service routine. Use the interrupt-safe versions, xQueueSendToFrontFromISR() and xQueueSendToBackFromISR(), instead.

The xQueueSendToFront() API function prototype is shown here.

BaseType_t xQueueSendToFront( QueueHandle_t xQueue, const void * pvItemToQueue, TickType_t xTicksToWait );

The xQueueSendToBack() API function prototype is shown here.

BaseType_t xQueueSendToBack( QueueHandle_t xQueue, const void * pvItemToQueue, TickType_t xTicksToWait );

The following table lists the xQueueSendToFront() and xQueueSendToBack() function parameters and return value.

Parameter Name/ Returned Value

Description

xQueue

The handle of the queue to which the data is being sent (written). The queue handle will have been returned from the call to xQueueCreate() used to create the queue.

pvItemToQueue

A pointer to the data to be copied into the queue.

The size of each item that the queue can hold is set when the queue is created, so this many bytes will be copied from pvItemToQueue into the queue storage area.

xTicksToWait

The maximum amount of time the task should remain in the Blocked state to wait for space to become available on the queue, should the queue already be full.

Both xQueueSendToFront() and xQueueSendToBack() will return immediately if xTicksToWait is zero and the queue is already full.

The block time is specified in tick periods, so the absolute time it represents is dependent on the tick frequency. The macro pdMS_TO_TICKS() can be used to convert a time specified in milliseconds into a time specified in ticks.

Setting xTicksToWait to portMAX_DELAY will cause the task to wait indefinitely (without timing out), provided INCLUDE_vTaskSuspend is set to 1 in FreeRTOSConfig.h.

Returned value

There are two possible return values:

  1. pdPASS

    Returned only if data was successfully sent to the queue.

    If a block time was specified (xTicksToWait was not zero), then it is possible the calling task was placed into the Blocked state, to wait for space to become available in the queue, before the function returned, but data was successfully written to the queue before the block time expired.

  2. errQUEUE_FULL

    Returned if data could not be written to the queue because the queue was already full.

    If a block time was specified (xTicksToWait was not zero) then the calling task will have been placed into the Blocked state to wait for another task or interrupt to make space in the queue, but the specified block time expired before that happened.

xQueueReceive() API Function

xQueueReceive() is used to receive (read) an item from a queue. The item that is received is removed from the queue.

Note: Do not call xQueueReceive() from an interrupt service routine. Use the interrupt-safe xQueueReceiveFromISR() API function instead.

The xQueueReceive() API function prototype is shown here.

BaseType_t xQueueReceive( QueueHandle_t xQueue, void * const pvBuffer, TickType_t xTicksToWait );

The following table lists the xQueueReceive() function parameters and return values.

Parameter Name/ Returned value

Description

xQueue

The handle of the queue from which the data is being received (read). The queue handle will have been returned from the call to xQueueCreate() used to create the queue.

pvBuffer

A pointer to the memory into which the received data will be copied.

The size of each data item that the queue holds is set when the queue is created. The memory pointed to by pvBuffer must be at least large enough to hold that many bytes.

xTicksToWait

The maximum amount of time the task should remain in the Blocked state to wait for data to become available on the queue, should the queue already be empty.

If xTicksToWait is zero, then xQueueReceive() will return immediately if the queue is already empty.

The block time is specified in tick periods, so the absolute time it represents depends on the tick frequency. The macro pdMS_TO_TICKS() can be used to convert a time specified in milliseconds into ticks.

Setting xTicksToWait to portMAX_DELAY will cause the task to wait indefinitely (without timing out), provided INCLUDE_vTaskSuspend is set to 1 in FreeRTOSConfig.h.

Returned value

There are two possible return values:

  1. pdPASS

    Returned only if data was successfully read from the queue.

    If a block time was specified (xTicksToWait was not zero), then it is possible the calling task was placed into the Blocked state, to wait for data to become available on the queue, but data was successfully read from the queue before the block time expired.

  2. errQUEUE_EMPTY

    Returned if data cannot be read from the queue because the queue is already empty.

    If a block time was specified (xTicksToWait was not zero,) then the calling task will have been placed into the Blocked state to wait for another task or interrupt to send data to the queue, but the block time expired before that happened.

uxQueueMessagesWaiting() API Function

uxQueueMessagesWaiting() is used to query the number of items that are currently in a queue.

Note: Do not call uxQueueMessagesWaiting() from an interrupt service routine. Use the interrupt-safe uxQueueMessagesWaitingFromISR() instead.

The uxQueueMessagesWaiting() API function prototype is shown here.

UBaseType_t uxQueueMessagesWaiting( QueueHandle_t xQueue );

The following table lists the uxQueueMessagesWaiting() function parameter and return value.

Parameter Name/ Returned Value

Description

xQueue

The handle of the queue being queried. The queue handle will have been returned from the call to xQueueCreate() used to create the queue.

Returned value

The number of items that the queue being queried is currently holding. If zero is returned, then the queue is empty.

Blocking When Receiving from a Queue (Example 10)

This example demonstrates a queue being created, data being sent to the queue from multiple tasks, and data being received from the queue. The queue is created to hold data items of type int32_t. The tasks that send to the queue do not specify a block time, but the task that receives from the queue does.

The priority of the tasks that send to the queue are lower than the priority of the task that receives from the queue. This means the queue should never contain more than one item because, as soon as data is sent to the queue, the receiving task will unblock, preempt the sending task, and remove the data, leaving the queue empty again.

The following code shows the implementation of the task that writes to the queue. Two instances of this task are created: one that writes continuously the value 100 to the queue and another that writes continuously the value 200 to the same queue. The task parameter is used to pass these values into each task instance.

static void vSenderTask( void *pvParameters ) { int32_t lValueToSend; BaseType_t xStatus; /* Two instances of this task are created so the value that is sent to the queue is passed in through the task parameter. This way, each instance can use a different value. The queue was created to hold values of type int32_t, so cast the parameter to the required type. */ lValueToSend = ( int32_t ) pvParameters; /* As per most tasks, this task is implemented within an infinite loop. */ for( ;; ) { /* Send the value to the queue. The first parameter is the queue to which data is being sent. The queue was created before the scheduler was started, so before this task started to execute. The second parameter is the address of the data to be sent, in this case the address of lValueToSend. The third parameter is the Block time, the time the task should be kept in the Blocked state to wait for space to become available on the queue should the queue already be full. In this case a block time is not specified because the queue should never contain more than one item, and therefore never be full. */ xStatus = xQueueSendToBack( xQueue, &lValueToSend, 0 ); if( xStatus != pdPASS ) { /* The send operation could not complete because the queue was full. This must be an error because the queue should never contain more than one item! */ vPrintString( "Could not send to the queue.\r\n" ); } } }

The following code shows the implementation of the task that receives data from the queue. The receiving task specifies a block time of 100 milliseconds, so it will enter the Blocked state to wait for data to become available. It will leave the Blocked state when either data is available on the queue or 100 milliseconds passes without data becoming available. In this example, the 100 milliseconds timeout should never expire because there are two tasks continuously writing to the queue.

static void vReceiverTask( void *pvParameters ) { /* Declare the variable that will hold the values received from the queue. */ int32_t lReceivedValue; BaseType_t xStatus; const TickType_t xTicksToWait = pdMS_TO_TICKS( 100 ); /* This task is also defined within an infinite loop. */ for( ;; ) { /* This call should always find the queue empty because this task will immediately remove any data that is written to the queue. */ if( uxQueueMessagesWaiting( xQueue ) != 0 ) { vPrintString( "Queue should have been empty!\r\n" ); } /* Receive data from the queue. The first parameter is the queue from which data is to be received. The queue is created before the scheduler is started, and therefore before this task runs for the first time. The second parameter is the buffer into which the received data will be placed. In this case the buffer is simply the address of a variable that has the required size to hold the received data. The last parameter is the block time, the maximum amount of time that the task will remain in the Blocked state to wait for data to be available should the queue already be empty. */ xStatus = xQueueReceive( xQueue, &lReceivedValue, xTicksToWait ); if( xStatus == pdPASS ) { /* Data was successfully received from the queue, print out the received value. */ vPrintStringAndNumber( "Received = ", lReceivedValue ); } else { /* Data was not received from the queue even after waiting for 100ms.This must be an error because the sending tasks are free running and will be continuously writing to the queue. */ vPrintString( "Could not receive from the queue.\r\n" ); } } }

The following code contains the definition of the main() function. This simply creates the queue and the three tasks before starting the scheduler. The queue is created to hold a maximum of five int32_t values, even though the priorities of the tasks are set in such a way that the queue will never contain more than one item at a time.

/* Declare a variable of type QueueHandle_t. This is used to store the handle to the queue that is accessed by all three tasks. */ QueueHandle_t xQueue; int main( void ) { /* The queue is created to hold a maximum of 5 values, each of which is large enough to hold a variable of type int32_t. */ xQueue = xQueueCreate( 5, sizeof( int32_t ) ); if( xQueue != NULL ) { /* Create two instances of the task that will send to the queue. The task parameter is used to pass the value that the task will write to the queue, so one task will continuously write 100 to the queue while the other task will continuously write 200 to the queue. Both tasks are created at priority 1. */ xTaskCreate( vSenderTask, "Sender1", 1000, ( void * ) 100, 1, NULL ); xTaskCreate( vSenderTask, "Sender2", 1000, ( void * ) 200, 1, NULL ); /* Create the task that will read from the queue. The task is created with priority 2, so above the priority of the sender tasks. */ xTaskCreate( vReceiverTask, "Receiver", 1000, NULL, 2, NULL ); /* Start the scheduler so the created tasks start executing. */ vTaskStartScheduler(); } else { /* The queue could not be created. */ } /* If all is well then main() will never reach here as the scheduler will now be running the tasks. If main() does reach here then it is likely that there was insufficient FreeRTOS heap memory available for the idle task to be created. For more information, see Heap Memory Management. */ for( ;; ); }

Both tasks that send to the queue have an identical priority. This causes the two sending tasks to send data to the queue in turn.

The following figure shows the sequence of execution.

Receiving Data from Multiple Sources

It is common in FreeRTOS designs for a task to receive data from more than one source. The receiving task must know where the data came from to determine how the data should be processed. An easy design solution is to use a single queue to transfer structures with both the value of the data and the source of the data contained in the structure's fields.

The following figure shows an example scenario where structures are sent on a queue.

  • A queue is created that holds structures of type Data_t. The structure members allow a data value and an enumerated type to be sent to the queue in one message. The enumerated type is used to indicate what the data means.

  • A central Controller task is used to perform the primary system function. This has to react to inputs and changes to the system state communicated to it on the queue.

  • A CAN bus task is used to encapsulate the CAN bus interfacing functionality. When the CAN bus task has received and decoded a message, it sends the already decoded message to the Controller task in a Data_t structure. The eDataID member of the transferred structure is used to let the Controller task know what the data is (in this case, a motor speed value). The lDataValue member of the transferred structure is used to let the Controller task know the motor speed value.

  • A Human Machine Interface (HMI) task is used to encapsulate all the HMI functionality. The machine operator can probably input commands and query values in a number of ways that have to be detected and interpreted within the HMI task. When a new command is input, the HMI task sends the command to the Controller task in a Data_t structure. The eDataID member of the transferred structure is used to let the Controller task know what the data is (in this case, a new set point value). The lDataValue member of the transferred structure is used to let the Controller task know the set point value.

Blocking When Sending to a Queue and Sending Structures on a Queue (Example 11)

This example is similar to the previous example, but the task priorities are reversed, so the receiving task has a lower priority than the sending tasks. Also, the queue is used to pass structures rather than integers.

The following code shows the definition of the structure that is to be passed on a queue and the declaration of two variables.

/* Define an enumerated type used to identify the source of the data.*/ typedef enum { eSender1, eSender2 } DataSource_t; /* Define the structure type that will be passed on the queue. */ typedef struct { uint8_t ucValue; DataSource_t eDataSource; } Data_t; /* Declare two variables of type Data_t that will be passed on the queue. */ static const Data_t xStructsToSend[ 2 ] = { { 100, eSender1 }, /* Used by Sender1. */ { 200, eSender2 } /* Used by Sender2. */ };

In the previous example, the receiving task has the highest priority, so the queue never contains more than one item. This results from the receiving task preempting the sending tasks as soon as data is placed into the queue. In the following example, the sending tasks have the higher priority, so the queue will normally be full. This is because as soon as the receiving task removes an item from the queue, it is preempted by one of the sending tasks, which then immediately refills the queue. The sending task then re-enters the Blocked state to wait for space to become available on the queue again.

The following code shows the implementation of the sending task. The sending task specifies a block time of 100 milliseconds, so it enters the Blocked state to wait for space to become available each time the queue becomes full. It leaves the Blocked state when either space is available on the queue or 100 milliseconds passes without space becoming available. In this example, the 100 milliseconds timeout should never expire because the receiving task is continuously making space by removing items from the queue.

static void vSenderTask( void *pvParameters ) { BaseType_t xStatus; const TickType_t xTicksToWait = pdMS_TO_TICKS( 100 ); /* As per most tasks, this task is implemented within an infinite loop.*/ for( ;; ) { /* Send to the queue. The second parameter is the address of the structure being sent. The address is passed in as the task parameter so pvParameters is used directly. The third parameter is the Block time, the time the task should be kept in the Blocked state to wait for space to become available on the queue if the queue is already full. A block time is specified because the sending tasks have a higher priority than the receiving task so the queue is expected to become full. The receiving task will remove items from the queue when both sending tasks are in the Blocked state. */ xStatus = xQueueSendToBack( xQueue, pvParameters, xTicksToWait ); if( xStatus != pdPASS ) { /* The send operation could not complete, even after waiting for 100 ms. This must be an error because the receiving task should make space in the queue as soon as both sending tasks are in the Blocked state. */ vPrintString( "Could not send to the queue.\r\n" ); } } }

The receiving task has the lowest priority, so it will run only when both sending tasks are in the Blocked state. The sending tasks will enter the Blocked state only when the queue is full, so the receiving task will execute only when the queue is already full. Therefore, it always expects to receive data even when it does not specify a block time.

The following code shows the implementation of the receiving task.

static void vReceiverTask( void *pvParameters ) { /* Declare the structure that will hold the values received from the queue. */ Data_t xReceivedStructure; BaseType_t xStatus; /* This task is also defined within an infinite loop. */ for( ;; ) { /* Because it has the lowest priority, this task will only run when the sending tasks are in the Blocked state. The sending tasks will only enter the Blocked state when the queue is full so this task always expects the number of items in the queue to be equal to the queue length, which is 3 in this case. */ if( uxQueueMessagesWaiting( xQueue ) != 3 ) { vPrintString( "Queue should have been full!\r\n" ); } /* Receive from the queue. The second parameter is the buffer into which the received data will be placed. In this case, the buffer is simply the address of a variable that has the required size to hold the received structure. The last parameter is the block time, the maximum amount of time that the task will remain in the Blocked state to wait for data to be available if the queue is already empty. In this case, a block time is not required because this task will only run when the queue is full. */ xStatus = xQueueReceive( xQueue, &xReceivedStructure, 0 ); if( xStatus == pdPASS ) { /* Data was successfully received from the queue, print out the received value and the source of the value. */ if( xReceivedStructure.eDataSource == eSender1 ) { vPrintStringAndNumber( "From Sender 1 = ", xReceivedStructure.ucValue ); } else { vPrintStringAndNumber( "From Sender 2 = ", xReceivedStructure.ucValue ); } } else { /* Nothing was received from the queue. This must be an error because this task should only run when the queue is full. */ vPrintString( "Could not receive from the queue.\r\n" ); } } }

main() changes only slightly from the previous example. The queue is created to hold three Data_t structures, and the priorities of the sending and receiving tasks are reversed. The implementation of main() is shown here.

int main( void ) { /* The queue is created to hold a maximum of 3 structures of type Data_t. */ xQueue = xQueueCreate( 3, sizeof( Data_t ) ); if( xQueue != NULL ) { /* Create two instances of the task that will write to the queue. The parameter is used to pass the structure that the task will write to the queue, so one task will continuously send xStructsToSend[ 0 ] to the queue while the other task will continuously send xStructsToSend[ 1 ]. Both tasks are created at priority 2, which is above the priority of the receiver. */ xTaskCreate( vSenderTask, "Sender1", 1000, &( xStructsToSend[ 0 ] ), 2, NULL ); xTaskCreate( vSenderTask, "Sender2", 1000, &( xStructsToSend[ 1 ] ), 2, NULL ); /* Create the task that will read from the queue. The task is created with priority 1, so below the priority of the sender tasks. */ xTaskCreate( vReceiverTask, "Receiver", 1000, NULL, 1, NULL ); /* Start the scheduler so the created tasks start executing. */ vTaskStartScheduler(); } else { /* The queue could not be created. */ } /* If all is well then main() will never reach here as the scheduler will now be running the tasks. If main() does reach here then it is likely that there was insufficient heap memory available for the idle task to be created. Chapter 2 provides more information on heap memory management. */ for( ;; ); }

The following figure shows the sequence of execution that results from having the priority of the sending tasks above the priority of the receiving task.

This table describes why the first four message originate from the same task.

Time

Description

t1

Task Sender 1 executes and sends three data items to the queue.

t2

The queue is full so Sender 1 enters the Blocked state to wait for its next send to complete. Task Sender 2 is now the highest priority task that is able to run, so enters the Running state.

t3

Task Sender 2 finds the queue is already full, so enters the Blocked state to wait for its first send to complete. Task Receiver is now the highest priority task that is able to run, so enters the Running state.

t4

Two tasks that have a priority higher than the receiving task's priority are waiting for space to become available on the queue, resulting in task Receiver being preempted as soon as it has removed one item from the queue. Tasks Sender 1 and Sender 2 have the same priority, so the scheduler selects the task that has been waiting the longest as the task that will enter the Running state (in this case, that is task Sender 1).

t5

Task Sender 1 sends another data item to the queue. There was only one space in the queue, so task Sender 1 enters the Blocked state to wait for its next send to complete. Task Receiver is again the highest priority task that is able to run so enters the Running state.

Task Sender 1 has now sent four items to the queue, and task Sender 2 is still waiting to send its first item to the queue.

t6

Two tasks that have a priority higher than the receiving task's priority are waiting for space to become available on the queue, so task Receiver is preempted as soon as it has removed one item from the queue. This time Sender 2 has been waiting longer than Sender 1, so Sender 2 enters the Running state.

t7

Task Sender 2 sends a data item to the queue. There was only one space in the queue, so Sender 2 enters the Blocked state to wait for its next send to complete. Both tasks Sender 1 and Sender 2 are waiting for space to become available on the queue, so task Receiver is the only task that can enter the Running state.

Working with Large or Variable-Sized Data

Queuing Pointers

If the size of the data being stored in the queue is large, then it is better to use the queue to transfer pointers to the data rather than copy the data into and out of the queue byte by byte. Transferring pointers is more efficient in both processing time and the amount of RAM required to create the queue. However, when you are queuing pointers, make sure that:

  • The owner of the RAM being pointed to is clearly defined.

When using a pointer to share memory between tasks, you must make sure that both tasks do not modify the memory contents simultaneously, or take any other action that could cause the memory contents to be invalid or inconsistent. Ideally, only the sending task should be permitted to access the memory until a pointer to the memory has been queued, and only the receiving task should be permitted to access the memory after the pointer has been received from the queue.

  • The RAM being pointed to remains valid.

If the memory being pointed to was allocated dynamically or obtained from a pool of preallocated buffers, then exactly one task should be responsible for freeing the memory. No tasks should attempt to access the memory after it has been freed.

You should never use a pointer to access data that has been allocated on a task stack. The data will not be valid after the stack frame has changed.

The following code examples demonstrate how to use a queue to send a pointer to a buffer from one task to another.

The following code creates a queue that can hold up to five pointers.

/* Declare a variable of type QueueHandle_t to hold the handle of the queue being created. */ QueueHandle_t xPointerQueue; /* Create a queue that can hold a maximum of 5 pointers (in this case, character pointers). */ xPointerQueue = xQueueCreate( 5, sizeof( char * ) );

The following code allocates a buffer, writes a string to the buffer, and then sends a pointer to the buffer to the queue.

/* A task that obtains a buffer, writes a string to the buffer, and then sends the address of the buffer to the queue created in the previous listing. */ void vStringSendingTask( void *pvParameters ) { char *pcStringToSend; const size_t xMaxStringLength = 50; BaseType_t xStringNumber = 0; for( ;; ) { /* Obtain a buffer that is at least xMaxStringLength characters big. The implementation of prvGetBuffer() is not shown. It might obtain the buffer from a pool of preallocated buffers or just allocate the buffer dynamically. */ pcStringToSend = ( char * ) prvGetBuffer( xMaxStringLength ); /* Write a string into the buffer. */ snprintf( pcStringToSend, xMaxStringLength, "String number %d\r\n", xStringNumber ); /* Increment the counter so the string is different on each iteration of this task. */ xStringNumber++; /* Send the address of the buffer to the queue that was created in the previous listing. The address of the buffer is stored in the pcStringToSend variable.*/ xQueueSend( xPointerQueue, /* The handle of the queue. */ &pcStringToSend, /* The address of the pointer that points to the buffer. */ portMAX_DELAY ); } }

The following code receives a pointer to a buffer from the queue, and then prints the string contained in the buffer.

/* A task that receives the address of a buffer from the queue created in the first listing and written to in the second listing. The buffer contains a string, which is printed out. */ void vStringReceivingTask( void *pvParameters ) { char *pcReceivedString; for( ;; ) { /* Receive the address of a buffer. */ xQueueReceive( xPointerQueue, /* The handle of the queue. */ &pcReceivedString, /* Store the buffer's address in pcReceivedString. */ portMAX_DELAY ); /* The buffer holds a string. Print it out. */ vPrintString( pcReceivedString ); /* The buffer is not required anymore. Release it so it can be freed or reused. */ prvReleaseBuffer( pcReceivedString ); } }

Using a Queue to Send Different Types and Lengths of Data

Sending structures to a queue and sending pointers to a queue are two powerful design patterns. When you combine these techniques, a task can use a single queue to receive any data type from any data source. The implementation of the FreeRTOS+TCP TCP/IP stack provides a practical example for doing this.

The TCP/IP stack, which runs in its own task, must process events from many different sources. Different event types are associated with different types and lengths of data. All events that occur outside of the TCP/IP task are described by a structure of type IPStackEvent_t, and sent to the TCP/IP task on a queue. The pvData member of the IPStackEvent_t structure is a pointer that can be used to hold a value directly or point to a buffer.

The IPStackEvent_t structure used to send events to the TCP/IP stack task in FreeRTOS+TCP is shown here.

/* A subset of the enumerated types used in the TCP/IP stack to identify events. */ typedef enum { eNetworkDownEvent = 0, /* The network interface has been lost or needs (re)connecting. */ eNetworkRxEvent, /* A packet has been received from the network. */ eTCPAcceptEvent, /* FreeRTOS_accept() called to accept or wait for a new client. */ /* Other event types appear here but are not shown in this listing. */ } eIPEvent_t; /* The structure that describes events and is sent on a queue to the TCP/IP task. */ typedef struct IP_TASK_COMMANDS { /* An enumerated type that identifies the event. See the eIPEvent_t definition. */ eIPEvent_t eEventType; /* A generic pointer that can hold a value or point to a buffer. */ void *pvData; } IPStackEvent_t;

Example TCP/IP events and their associated data include:

  • eNetworkRxEvent: A packet of data has been received from the network.

    Data received from the network is sent to the TCP/IP task using a structure of type IPStackEvent_t. The structure's eEventType member is set to eNetworkRxEvent. The structure's pvData member is used to point to the buffer that contains the received data.

    This pseudo code shows how an IPStackEvent_t structure is used to send data received from the network to the TCP/IP task.

    void vSendRxDataToTheTCPTask( NetworkBufferDescriptor_t *pxRxedData ) { IPStackEvent_t xEventStruct; /* Complete the IPStackEvent_t structure. The received data is stored in pxRxedData. */ xEventStruct.eEventType = eNetworkRxEvent; xEventStruct.pvData = ( void * ) pxRxedData; /* Send the IPStackEvent_t structure to the TCP/IP task. */ xSendEventStructToIPTask( &xEventStruct ); }
  • eTCPAcceptEvent: A socket is to accept or wait for a connection from a client.

    Accept events are sent from the task that called FreeRTOS_accept() to the TCP/IP task using a structure of type IPStackEvent_t. The structure's eEventType member is set to eTCPAcceptEvent. The structure's pvData member is set to the handle of the socket that is accepting a connection.

    This pseudo code shows how an IPStackEvent_t structure is used to send the handle of a socket that is accepting a connection to the TCP/IP task.

    void vSendAcceptRequestToTheTCPTask( Socket_t xSocket ) { IPStackEvent_t xEventStruct; /* Complete the IPStackEvent_t structure. */ xEventStruct.eEventType = eTCPAcceptEvent; xEventStruct.pvData = ( void * ) xSocket; /* Send the IPStackEvent_t structure to the TCP/IP task. */ xSendEventStructToIPTask( &xEventStruct ); }
  • eNetworkDownEvent: The network needs connecting or reconnecting.

    Network down events are sent from the network interface to the TCP/IP task using a structure of type IPStackEvent_t. The structure's eEventType member is set to eNetworkDownEvent. Network down events are not associated with any data, so the structure's pvData member is not used.

    This pseudo code shows how an IPStackEvent_t structure is used to send a network down event to the TCP/IP task.

    void vSendNetworkDownEventToTheTCPTask( Socket_t xSocket ) { IPStackEvent_t xEventStruct; /* Complete the IPStackEvent_t structure. */ xEventStruct.eEventType = eNetworkDownEvent; xEventStruct.pvData = NULL; /* Not used, but set to NULL for completeness. */ /* Send the IPStackEvent_t structure to the TCP/IP task. */ xSendEventStructToIPTask( &xEventStruct ); }

The code that receives and processes these events within the TCP/IP task is shown here. The eEventType member of the IPStackEvent_t structures received from the queue is used to determine how the pvData member is to be interpreted. This pseudo code shows how an IPStackEvent_t structure is used to send a network down to the TCP/IP task.

IPStackEvent_t xReceivedEvent; /* Block on the network event queue until either an event is received, or xNextIPSleep ticks pass without an event being received. eEventType is set to eNoEvent in case the call to xQueueReceive() returns because it timed out, rather than because an event was received. */ xReceivedEvent.eEventType = eNoEvent; xQueueReceive( xNetworkEventQueue, &xReceivedEvent, xNextIPSleep ); /* Which event was received, if any? */ switch( xReceivedEvent.eEventType ) { case eNetworkDownEvent : /* Attempt to (re)establish a connection. This event is not associated with any data. */ prvProcessNetworkDownEvent(); break; case eNetworkRxEvent: /* The network interface has received a new packet. A pointer to the received data is stored in the pvData member of the received IPStackEvent_t structure. Process the received data. */ prvHandleEthernetPacket( ( NetworkBufferDescriptor_t * )( xReceivedEvent.pvData ) ); break; case eTCPAcceptEvent: /* The FreeRTOS_accept() API function was called. The handle of the socket that is accepting a connection is stored in the pvData member of the received IPStackEvent_t structure. */ xSocket = ( FreeRTOS_Socket_t * ) ( xReceivedEvent.pvData ); xTCPCheckNewClient( pxSocket ); break; /* Other event types are processed in the same way, but are not shown here. */ }

Receiving from Multiple Queues

Queue Sets

Application designs often require a single task to receive data of different sizes, data of different meaning, and data from different sources. The previous section described how you can do this in a neat and efficient way by using a single queue that receives structures. However, sometimes you might be working with constraints that limit your design choices, requiring the use of a separate queue for some data sources. For example, third-party code that is being integrated into a design might assume the presence of a dedicated queue. In such cases, you can use a queue set.

Queue sets allow a task to receive data from more than one queue without the task polling each queue in turn to determine which, if any, contains data.

A design that uses a queue set to receive data from multiple sources is less neat and efficient than a design that achieves the same functionality using a single queue that receives structures. For that reason, we recommend that you use queue sets only used if your design constraints make their use absolutely necessary.

The following sections describe how to:

  1. Create a queue set.

  2. Add queues to the set.

    You can also add semaphores to a queue set. Semaphores are described in Interrupt Management.

  3. Read from the queue set to determine which queues within the set contain data.

    When a queue that is a member of a set receives data, the handle of the receiving queue is sent to the queue set, and returned when a task calls a function that reads from the queue set. Therefore, if a queue handle is returned from a queue set, then the queue referenced by the handle is known to contain data, and the task can then read from the queue directly.

    Note: If a queue is a member of a queue set, then do not read data from the queue unless the queue's handle has first been read from the queue set.

To enable queue set functionality, in FreeRTOSConfig.h, set the configUSE_QUEUE_SETS compile-time configuration constant to 1.

xQueueCreateSet() API Function

A queue set must be explicitly created before it can be used.

Queues sets are referenced by handles, which are variables of type QueueSetHandle_t. The xQueueCreateSet() API function creates a queue set and returns a QueueSetHandle_t that references the queue set it created.

The xQueueCreateSet() API function prototype is shown here.

QueueSetHandle_t xQueueCreateSet( const UBaseType_t uxEventQueueLength);

The following table lists the xQueueCreateSet() parameters and return value.

Parameter Name

Description

uxEventQueueLength

When a queue that is a member of a queue set receives data, the handle of the receiving queue is sent to the queue set. uxEventQueueLength defines the maximum number of queue handles the queue set being created can hold at any one time.

Queue handles are only sent to a queue set when a queue within the set receives data. A queue cannot receive data if it is full, so no queue handles can be sent to the queue set if all the queues in the set are full. Therefore, the maximum number of items the queue set will ever have to hold at one time is the sum of the lengths of every queue in the set.

As an example, if there are three empty queues in the set, and each queue has a length of five, then in total the queues in the set can receive fifteen items (three queues multiplied by five items each) before all the queues in the set are full. In that example, uxEventQueueLength must be set to fifteen to guarantee the queue set can receive every item sent to it.

Semaphores can also be added to a queue set. Binary and counting semaphores are covered later in this guide. For the purposes of calculating the uxEventQueueLength, the length of a binary semaphore is one, and the length of a counting semaphore is given by the semaphore's maximum count value.

As another example, if a queue set will contain a queue that has a length of three, and a binary semaphore (which has a length of one), uxEventQueueLength must be set to four (three plus one).

Return Value

If NULL is returned, then the queue set cannot be created because there is insufficient heap memory available for FreeRTOS to allocate the queue set data structures and storage area.

If a non-NULL value is returned, the queue set has been created successfully. The returned value should be stored as the handle to the created queue set.

xQueueAddToSet() API Function

xQueueAddToSet() adds a queue or semaphore to a queue set. For information about semaphores, see Interrupt Management.

The xQueueAddToSet() API function prototype is shown here.

BaseType_t xQueueAddToSet( QueueSetMemberHandle_t xQueueOrSemaphore, QueueSetHandle_t xQueueSet );

The following table lists the xQueueAddToSet() parameters and return value.

xQueueSelectFromSet() API Function

xQueueSelectFromSet() reads a queue handle from the queue set.

When a queue or semaphore that is a member of a set receives data, the handle of the receiving queue or semaphore is sent to the queue set, and returned when a task calls xQueueSelectFromSet(). If a handle is returned from a call to xQueueSelectFromSet(), then the queue or semaphore referenced by the handle is known to contain data and the calling task must then read from the queue or semaphore directly.

Note: Do not read data from a queue or semaphore that is a member of a set unless the handle of the queue or semaphore has first been returned from a call to xQueueSelectFromSet(). Only read one item from a queue or semaphore each time the queue handle or semaphore handle is returned from a call to xQueueSelectFromSet().

The xQueueSelectFromSet() API function prototype is shown here.

QueueSetMemberHandle_t xQueueSelectFromSet( QueueSetHandle_t xQueueSet, const TickType_t xTicksToWait );

The following lists the xQueueSelectFromSet() parameters and return value.

xQueueSet

The handle of the queue set from which a queue handle or semaphore handle is being received (read). The queue set handle will have been returned from the call to xQueueCreateSet() used to create the queue set.

xTicksToWait

The maximum amount of time the calling task should remain in the Blocked state to wait to receive a queue or semaphore handle from the queue set, if all the queues and semaphore in the set are empty. If xTicksToWait is zero, then xQueueSelectFromSet() will return immediately if all the queues and semaphores in the set are empty. The block time is specified in tick periods, so the absolute time it represents depends on the tick frequency. The macro pdMS_TO_TICKS() can be used to convert a time specified in milliseconds to ticks. Setting xTicksToWait to portMAX_DELAY will cause the task to wait indefinitely (without timing out) provided INCLUDE_vTaskSuspend is set to 1 in FreeRTOSConfig.h.

Return Value

A return value that is not NULL will be the handle of a queue or semaphore that is known to contain data. If a block time was specified (xTicksToWait was not zero), then it is possible that the calling task was placed into the Blocked state to wait for data to become available from a queue or semaphore in the set, but a handle was successfully read from the queue set before the block time expired. Handles are returned as a QueueSetMemberHandle_t type, which can be cast to either a QueueHandle_t type or SemaphoreHandle_t type.

If the return value is NULL, then a handle could not be read from the queue set. If a block time was specified (xTicksToWait was not zero), then the calling task will have been placed into the Blocked state to wait for another task or interrupt to send data to a queue or semaphore in the set, but the block time expired before that happened.

Using a Queue Set (Example 12)

This example creates two sending tasks and one receiving task. The sending tasks send data to the receiving task on two separate queues, one queue for each task. The two queues are added to a queue set, and the receiving task reads from the queue set to determine which of the two queues contain data.

The tasks, queues, and the queue set are all created in main().

/* Declare two variables of type QueueHandle_t. Both queues are added to the same queue set. */ static QueueHandle_t xQueue1 = NULL, xQueue2 = NULL; /* Declare a variable of type QueueSetHandle_t. This is the queue set to which the two queues are added. */ static QueueSetHandle_t xQueueSet = NULL; int main( void ) { /* Create the two queues, both of which send character pointers. The priority of the receiving task is above the priority of the sending tasks, so the queues will never have more than one item in them at any one time*/ xQueue1 = xQueueCreate( 1, sizeof( char * ) ); xQueue2 = xQueueCreate( 1, sizeof( char * ) ); /* Create the queue set. Two queues will be added to the set, each of which can contain 1 item, so the maximum number of queue handles the queue set will ever have to hold at one time is 2 (2 queues multiplied by 1 item per queue). */ xQueueSet = xQueueCreateSet( 1 * 2 ); /* Add the two queues to the set. */ xQueueAddToSet( xQueue1, xQueueSet ); xQueueAddToSet( xQueue2, xQueueSet ); /* Create the tasks that send to the queues. */ xTaskCreate( vSenderTask1, "Sender1", 1000, NULL, 1, NULL ); xTaskCreate( vSenderTask2, "Sender2", 1000, NULL, 1, NULL ); /* Create the task that reads from the queue set to determine which of the two queues contain data. */ xTaskCreate( vReceiverTask, "Receiver", 1000, NULL, 2, NULL ); /* Start the scheduler so the created tasks start executing. */ vTaskStartScheduler(); /* As normal, vTaskStartScheduler() should not return, so the following lines will never execute. */ for( ;; ); return 0; }

The first sending task uses xQueue1 to send a character pointer to the receiving task every 100 milliseconds. The second sending task uses xQueue2 to send a character pointer to the receiving task every 200 milliseconds. The character pointers are set to point to a string that identifies the sending task. The implementation of both sending tasks is shown here.

void vSenderTask1( void *pvParameters ) { const TickType_t xBlockTime = pdMS_TO_TICKS( 100 ); const char * const pcMessage = "Message from vSenderTask1\r\n"; /* As per most tasks, this task is implemented within an infinite loop. */ for( ;; ) { /* Block for 100ms. */ vTaskDelay( xBlockTime ); /* Send this task's string to xQueue1. It is not necessary to use a block time, even though the queue can only hold one item. This is because the priority of the task that reads from the queue is higher than the priority of this task. As soon as this task writes to the queue, it will be preempted by the task that reads from the queue, so the queue will already be empty again by the time the call to xQueueSend() returns. The block time is set to 0. */ xQueueSend( xQueue1, &pcMessage, 0 ); } } /*-----------------------------------------------------------*/ void vSenderTask2( void *pvParameters ) { const TickType_t xBlockTime = pdMS_TO_TICKS( 200 ); const char * const pcMessage = "Message from vSenderTask2\r\n"; /* As per most tasks, this task is implemented within an infinite loop. */ for( ;; ) { /* Block for 200ms. */ vTaskDelay( xBlockTime ); /* Send this task's string to xQueue2. It is not necessary to use a block time, even though the queue can only hold one item. This is because the priority of the task that reads from the queue is higher than the priority of this task. As soon as this task writes to the queue, it will be preempted by the task that reads from the queue, so the queue will already be empty again by the time the call to xQueueSend() returns. The block time is set to 0. */ xQueueSend( xQueue2, &pcMessage, 0 ); } }

The queues that are written to by the sending tasks are members of the same queue set. Each time a task sends to one of the queues, the handle of the queue is sent to the queue set. The receiving task calls xQueueSelectFromSet() to read the queue handles from the queue set. After the receiving task has received a queue handle from the set, it knows the queue referenced by the received handle contains data, so it reads the data from the queue directly. The data it reads from the queue is a pointer to a string, which the receiving task prints out.

If a call to xQueueSelectFromSet() times out, then it will return NULL. In the preceding code, xQueueSelectFromSet() is called with an indefinite block time, so will never time out and can only return a valid queue handle. Therefore, the receiving task does not need to check to see if xQueueSelectFromSet() returned NULL before the return value is used.

xQueueSelectFromSet() will only return a queue handle if the queue referenced by the handle contains data, so it is not necessary to use a block time when reading from the queue.

The implementation of the receive task is shown here.

void vReceiverTask( void *pvParameters ) { QueueHandle_t xQueueThatContainsData; char *pcReceivedString; /* As per most tasks, this task is implemented within an infinite loop.*/ for( ;; ) { /* Block on the queue set to wait for one of the queues in the set to contain data. Cast the QueueSetMemberHandle_t value returned from xQueueSelectFromSet() to a QueueHandle_t because it is known all the members of the set are queues (the queue set does not contain any semaphores). */ xQueueThatContainsData = ( QueueHandle_t ) xQueueSelectFromSet(xQueueSet, portMAX_DELAY ); /* An indefinite block time was used when reading from the queue set, so xQueueSelectFromSet() will not have returned unless one of the queues in the set contained data, and xQueueThatContainsData cannot be NULL. Read from the queue. It is not necessary to specify a block time because it is known the queue contains data. The block time is set to 0. */ xQueueReceive( xQueueThatContainsData, &pcReceivedString, 0 ); /* Print the string received from the queue. */ vPrintString( pcReceivedString ); } }

The output is shown here. The receiving task receives strings from both sending tasks. The block time used by vSenderTask1() is half of the block time used by vSenderTask2(), causing the strings sent by vSenderTask1() to be printed out twice as often as those sent by vSenderTask2().

More Realistic Queue Set Use Cases

In the previous example, the queue set contained two queues only. The queues were used to send a character pointer. In a real application, a queue set might contain both queues and semaphores, and the queues might not all hold the same data type. When this is the case, you need to test the value returned by xQueueSelectFromSet() before the returned value is used.

The following code shows how to use the value returned from xQueueSelectFromSet() when the set has the following members:

  1. A binary semaphore.

  2. A queue from which character pointers are read.

  3. A queue from which uint32_t values are read.

This code assumes the queues and semaphore have already been created and added to the queue set.

/* The handle of the queue from which character pointers are received. */ QueueHandle_t xCharPointerQueue; /* The handle of the queue from which uint32_t values are received.*/ QueueHandle_t xUint32tQueue; /* The handle of the binary semaphore. */ SemaphoreHandle_t xBinarySemaphore; /* The queue set to which the two queues and the binary semaphore belong. */ QueueSetHandle_t xQueueSet; void vAMoreRealisticReceiverTask( void *pvParameters ) { QueueSetMemberHandle_t xHandle; char *pcReceivedString; uint32_t ulRecievedValue; const TickType_t xDelay100ms = pdMS_TO_TICKS( 100 ); for( ;; ) { /* Block on the queue set for a maximum of 100ms to wait for one of the members of the set to contain data. */ xHandle = xQueueSelectFromSet( xQueueSet, xDelay100ms ); /* Test the value returned from xQueueSelectFromSet(). If the returned value is NULL, then the call to xQueueSelectFromSet() timed out. If the returned value is not NULL, then the returned value will be the handle of one of the set's members. The QueueSetMemberHandle_t value can be cast to either a QueueHandle_t or a SemaphoreHandle_t. Whether an explicit cast is required depends on the compiler. */ if( xHandle == NULL ) { /* The call to xQueueSelectFromSet() timed out. */ } else if( xHandle == ( QueueSetMemberHandle_t ) xCharPointerQueue ) { /* The call to xQueueSelectFromSet() returned the handle of the queue that receives character pointers. Read from the queue. The queue is known to contain data, so a block time of 0 is used. */ xQueueReceive( xCharPointerQueue, &pcReceivedString, 0 ); /* The received character pointer can be processed here... */ } else if( xHandle == ( QueueSetMemberHandle_t ) xUint32tQueue ) { /* The call to xQueueSelectFromSet() returned the handle of the queue that receives uint32_t types. Read from the queue. The queue is known to contain data, so a block time of 0 is used. */ xQueueReceive(xUint32tQueue, &ulRecievedValue, 0 ); /* The received value can be processed here... */ } else if( xHandle == ( QueueSetMemberHandle_t ) xBinarySemaphore ) { /* The call to xQueueSelectFromSet() returned the handle of the binary semaphore. Take the semaphore now. The semaphore is known to be available, so a block time of 0 is used. */ xSemaphoreTake( xBinarySemaphore, 0 ); /* Whatever processing is necessary when the semaphore is taken can be performed here... */ } } }

Using a Queue to Create a Mailbox

There is no consensus in the embedded community on the meaning of the term mailbox. In this guide, we use the term to refer to a queue that has a length of one. A queue might get described as a mailbox because of the way it is used in the application, rather than because it has a functional difference to a queue.

  • A queue is used to send data from one task to another task, or from an interrupt service routine to a task. The sender places an item in the queue, and the receiver removes the item from the queue. The data passes through the queue from the sender to the receiver.

  • A mailbox is used to hold data that can be read by any task or interrupt service routine. The data does not pass through the mailbox. Instead, it remains in the mailbox until it is overwritten. The sender overwrites the value in the mailbox. The receiver reads the value from the mailbox, but does not remove the value from the mailbox.

The xQueueOverwrite() and xQueuePeek() API functions allow a queue to be used as a mailbox.

The following code shows a queue being created for use as a mailbox.

/* A mailbox can hold a fixed-size data item. The size of the data item is set when the mailbox (queue) is created. In this example, the mailbox is created to hold an Example_t structure. Example_t includes a timestamp to allow the data held in the mailbox to note the time at which the mailbox was last updated. The timestamp used in this example is for demonstration purposes only. A mailbox can hold any data the application writer wants, and the data does not need to include a timestamp. */ typedef struct xExampleStructure { TickType_t xTimeStamp; uint32_t ulValue; } Example_t; /* A mailbox is a queue, so its handle is stored in a variable of type QueueHandle_t. */ QueueHandle_t xMailbox; void vAFunction( void ) { /* Create the queue that is going to be used as a mailbox. The queue has a length of 1 to allow it to be used with the xQueueOverwrite() API function, which is described below. */ xMailbox = xQueueCreate( 1, sizeof( Example_t ) ); }

xQueueOverwrite() API Function

Like the xQueueSendToBack() API function, the xQueueOverwrite() API function sends data to a queue. Unlike xQueueSendToBack(), if the queue is already full, then xQueueOverwrite() will overwrite data that is already in the queue.

xQueueOverwrite() should only be used with queues that have a length of one. That restriction avoids the need for the function's implementation to make an arbitrary decision as to which item in the queue to overwrite if the queue is full.

Note: Do not call xQueueOverwrite() from an interrupt service routine. Use the interrupt-safe version, xQueueOverwriteFromISR(), instead.

The xQueueOverwrite() API function prototype is shown here.

BaseType_t xQueueOverwrite( QueueHandle_t xQueue, const void * pvItemToQueue );

The following table lists the xQueueOverwrite() parameters and return value.

Parameter Name/ Returned Value

Description

xQueue

The handle of the queue to which the data is being sent (written). The queue handle will have been returned from the call to xQueueCreate() used to create the queue.

pvItemToQueue

A pointer to the data to be copied into the queue.

The size of each item that the queue can hold is set when the queue is created, so this many bytes will be copied from pvItemToQueue into the queue storage area.

Returned value

xQueueOverwrite() will write to the queue even when the queue is full, so pdPASS is the only possible return value.

The following code shows xQueueOverwrite() being used to write to the mailbox (queue) that was created earlier.

void vUpdateMailbox( uint32_t ulNewValue ) { /* Example_t was defined in the earlier code example. */ Example_t xData; /* Write the new data into the Example_t structure.*/ xData.ulValue = ulNewValue; /* Use the RTOS tick count as the timestamp stored in the Example_t structure. */ xData.xTimeStamp = xTaskGetTickCount(); /* Send the structure to the mailbox, overwriting any data that is already in the mailbox. */ xQueueOverwrite( xMailbox, &xData ); }

xQueuePeek() API Function

xQueuePeek() is used to receive (read) an item from a queue without the item being removed from the queue. xQueuePeek() receives data from the head of the queue without modifying the data stored in the queue or the order in which data is stored in the queue.

Note: Do not call xQueuePeek() from an interrupt service routine. Use the interrupt-safe version, xQueuePeekFromISR(), instead.

xQueuePeek() has the same function parameters and return value as xQueueReceive().

The following code shows xQueuePeek() being used to receive the item posted to the mailbox (queue) created in a previous sample.

BaseType_t vReadMailbox( Example_t *pxData ) { TickType_t xPreviousTimeStamp; BaseType_t xDataUpdated; /* This function updates an Example_t structure with the latest value received from the mailbox. Record the timestamp already contained in *pxData before it gets overwritten by the new data. */ xPreviousTimeStamp = pxData->xTimeStamp; /* Update the Example_t structure pointed to by pxData with the data contained in the mailbox. If xQueueReceive() was used here, then the mailbox would be left empty and the data could not then be read by any other tasks. Using xQueuePeek() instead of xQueueReceive() ensures the data remains in the mailbox. A block time is specified, so the calling task will be placed in the Blocked state to wait for the mailbox to contain data should the mailbox be empty. An infinite block time is used, so it is not necessary to check the value returned from xQueuePeek(). xQueuePeek() will only return when data is available. */ xQueuePeek( xMailbox, pxData, portMAX_DELAY ); /* Return pdTRUE if the value read from the mailbox has been updated since this function was last called. Otherwise, return pdFALSE. */ if( pxData->xTimeStamp > xPreviousTimeStamp ) { xDataUpdated = pdTRUE; } else { xDataUpdated = pdFALSE; } return xDataUpdated; }