| Queue API Function | Description |
|---|---|
| xQueueCreate() | Create a dynamic queue |
| xQueueCreateStatic() | Create a static queue |
| xQueueSend() | Add an item to the back of a queue |
| xQueueSendToBack() | Add an item to the back of a queue |
| xQueueSendToFront() | Add an item to the front of a queue |
| xQueueOverwrite() | Add an item to a queue, overwriting the old one if full. |
| xQueueSendFromISR() | Add an item to the back of a queue from ISR |
| xQueueSendToBackFromISR() | Add an item to the back of a queue from ISR |
| xQueueSendToFrontFromISR() | Add an item to the front of a queue from ISR |
| xQueueOverwriteFromISR() | Add an item from an ISR, overwriting the old one if full. |
| xQueueReceive() | Receive and remove an item from a queue |
| xQueuePeek() | Receive an item from a queue without removing it |
| xQueueReceiveFromISR() | Receive and remove an item from a queue from ISR |
| xQueuePeekFromISR() | Receive an item from a queue from ISR without removing it |
| uxQueueSpacesAvailable() | Return the number of free spaces in a queue |
| uxQueueMessagesWaiting() | Return the number of items stored in a queue |
| Queue Set API Function | Description |
|---|---|
| xQueueCreateSet() | Create a queue set for monitoring multiple queues or semaphores |
| xQueueAddToSet() | Add a queue or semaphore to an existing queue set |
| xQueueSelectFromSet() | Wait for and return the queue-set member that becomes ready |
typedef struct QueueDefinition
{
int8_t *pcHead;
int8_t *pcWriteTo;
union
{
QueuePointers_t xQueue;
SemaphoreData_t xSemaphore;
} u;
List_t xTasksWaitingToSend;
List_t xTasksWaitingToReceive;
volatile UBaseType_t uxMessagesWaiting;
UBaseType_t uxLength;
UBaseType_t uxItemSize;
volatile int8_t cRxLock;
volatile int8_t cTxLock;
#if( ( configSUPPORT_STATIC_ALLOCATION == 1 ) && \
( configSUPPORT_DYNAMIC_ALLOCATION == 1 ) )
uint8_t ucStaticallyAllocated;
#endif
#if ( configUSE_QUEUE_SETS == 1 )
struct QueueDefinition *pxQueueSetContainer;
#endif
#if ( configUSE_TRACE_FACILITY == 1 )
UBaseType_t uxQueueNumber;
uint8_t ucQueueType;
#endif
} xQUEUE;
typedef xQUEUE Queue_t;
xQueueCreate() creates a queue using dynamically allocated memory from the FreeRTOS heap. It specifies the maximum number of items the queue can hold and the size of each item. The function returns a valid queue handle when creation succeeds or NULL if there is insufficient heap memory.
QueueHandle_t xQueueCreate(UBaseType_t uxQueueLength,
UBaseType_t uxItemSize)
// ---------------------- Example ----------------------
#define MESSAGE_Q_NUM 5
QueueHandle_t msgQueue;
msgQueue = xQueueCreate(MESSAGE_Q_NUM, sizeof(uint32_t)); xQueueCreateStatic() creates a queue using memory supplied by the application rather than memory allocated from the FreeRTOS heap. The application provides a storage buffer for the queue items and a StaticQueue_t structure for the queue control data. The function returns a queue handle when creation succeeds or NULL if the parameters are invalid.
QueueHandle_t xQueueCreateStatic(UBaseType_t uxQueueLength,
UBaseType_t uxItemSize,
uint8_t * pucQueueStorage,
StaticQueue_t * pxQueueBuffer)xQueueSend() sends an item to the back of a FreeRTOS queue. The item is copied into the queue, and the calling task can optionally wait for available space if the queue is full. The function returns pdPASS when the item is successfully added or errQUEUE_FULL if the operation fails.
BaseType_t xQueueSend(QueueHandle_t xQueue,
const void * pvItemToQueue,
TickType_t xTicksToWait)
// ---------------------- Example ----------------------
const TickType_t wait_time = pdMS_TO_TICKS(200);
BaseType_t qStatus = xQueueSend(msgQueue, &valToSend, wait_time);xQueueSendToBack() copies an item to the back of a FreeRTOS queue. If the queue is full, the calling task can wait for a specified number of ticks until space becomes available. The function returns pdPASS on success or errQUEUE_FULL if the item cannot be added.
BaseType_t xQueueSendToBack(QueueHandle_t xQueue,
const void* pvItemToQueue,
TickType_t xTicksToWait)xQueueSendToFront() copies an item to the front of a FreeRTOS queue, allowing it to be received before existing items. If the queue is full, the calling task can wait for a specified number of ticks until space becomes available. It returns pdPASS on success or errQUEUE_FULL if the item cannot be added.
BaseType_t xQueueSendToToFront(QueueHandle_t xQueue,
const void *pvItemToQueue,
TickType_t xTicksToWait)xQueueOverwrite() copies an item into a queue even when the queue is already full, replacing the existing item. It is intended for queues with a length of one, such as those storing the latest sensor value or system state. The function returns pdPASS and must not be called from an interrupt service routine.
BaseType_t xQueueOverwrite(QueueHandle_t xQueue,
const void * pvItemToQueue)
// ---------------------- Example ----------------------
#define KEYMSG_Q_NUM 1
QueueHandle_t keyQueue;
keyQueue = xQueueCreate(KEYMSG_Q_NUM, sizeof(uint8_t));
uint8_t keyState = HAL_GPIO_ReadPin(GPIOA, GPIO_PIN_0);
BaseType_t qStatus = xQueueOverwrite(keyQueue, &keyState);xQueueSendFromISR() copies an item to the back of a FreeRTOS queue from within an interrupt service routine. It does not block if the queue is full, and the pxHigherPriorityTaskWoken parameter indicates whether sending the item unblocked a higher-priority task that may require a context switch. It returns pdPASS on success or errQUEUE_FULL if the item cannot be added.
BaseType_t xQueueSendFromISR(QueueHandle_t xQueue,
const void * pvItemToQueue,
BaseType_t * pxHigherPriorityTaskWoken)xQueueSendToBackFromISR() copies an item to the back of a FreeRTOS queue from within an interrupt service routine. It never blocks if the queue is full, and pxHigherPriorityTaskWoken indicates whether a higher-priority task was unblocked and a context switch may be required. The function returns pdPASS on success or errQUEUE_FULL if the item cannot be added.
BaseType_t xQueueSendToBackFromISR(QueueHandle_t xQueue,
const void * pvItemToQueue,
BaseType_t * pxHigherPriorityTaskWoken)xQueueSendToFrontFromISR() copies an item to the front of a FreeRTOS queue from within an interrupt service routine, allowing it to be received before existing items. It does not block if the queue is full, and pxHigherPriorityTaskWoken indicates whether a higher-priority task was unblocked and a context switch may be required. The function returns pdPASS on success or errQUEUE_FULL if the item cannot be added.
BaseType_t xQueueSendToFrontFromISR(QueueHandle_t xQueue,
const void * pvItemToQueue,
BaseType_t * pxHigherPriorityTaskWoken)xQueueOverwriteFromISR() writes an item to a queue from within an interrupt service routine, replacing the existing item if the queue is already full. It is intended for queues with a length of one and never blocks. The pxHigherPriorityTaskWoken parameter indicates whether a higher-priority task was unblocked and a context switch may be required.
BaseType_t xQueueOverwriteFromISR(QueueHandle_t xQueue,
const void * pvItemToQueue,
BaseType_t * pxHigherPriorityTaskWoken)xQueueReceive() removes an item from the front of a FreeRTOS queue and copies it into a user-provided buffer. If the queue is empty, the calling task can wait for a specified number of ticks until an item becomes available. The function returns pdPASS on success or errQUEUE_EMPTY if no item is received.
BaseType_t xQueueReceive(QueueHandle_t xQueue,
void * pvBuffer,
TickType_t xTicksToWait)
// ---------------------- Example ----------------------
BaseType_t qStatus = xQueueReceive(msgQueue, &valToReceive, 0); xQueuePeek() copies an item from the front of a FreeRTOS queue without removing it, allowing the same item to be read again later. If the queue is empty, the calling task can wait for a specified number of ticks until an item becomes available. The function returns pdPASS on success or errQUEUE_EMPTY if no item is available.
BaseType_t xQueuePeek(QueueHandle_t xQueue,
void * pvBuffer,
TickType_t xTicksToWait)xQueueReceiveFromISR() removes an item from the front of a FreeRTOS queue and copies it into a user-provided buffer from within an interrupt service routine. It never blocks if the queue is empty, and pxHigherPriorityTaskWoken indicates whether receiving the item unblocked a higher-priority task that may require a context switch. The function returns pdPASS on success or pdFAIL if the queue is empty.
BaseType_t xQueueReceiveFromISR(QueueHandle_t xQueue,
void* pvBuffer,
BaseType_t * pxTaskWoken)xQueuePeekFromISR() copies an item from the front of a FreeRTOS queue into a user-provided buffer from within an interrupt service routine without removing it from the queue. It never blocks if the queue is empty and returns pdPASS when an item is successfully read or pdFAIL if no item is available.
BaseType_t xQueuePeekFromISR(QueueHandle_t xQueue,
void * pvBuffer)uxQueueSpacesAvailable() returns the number of free spaces currently available in a FreeRTOS queue.
UBaseType_t uxQueueSpacesAvailable(const QueueHandle_t xQueue)uxQueueMessagesWaiting() returns the number of items currently stored in a FreeRTOS queue.
UBaseType_t uxQueueMessagesWaiting(const QueueHandle_t xQueue)xQueueCreateSet() creates a queue set that can contain multiple queues and semaphores, allowing a task to block until any member becomes ready. The length of set should be large enough to hold the total number of items that all member queues and semaphores may contain.
QueueSetHandle_t xQueueCreateSet(const UBaseType_t uxEventQueueLength)
// ---------------------- Example ----------------------
QueueSetHandle_t xQueueSet = NULL;
QueueHandle_t xQueue1 = NULL, xQueue2 = NULL;
xQueue1 = xQueueCreate(1, sizeof(char*));
xQueue2 = xQueueCreate(1, sizeof(char*));
xQueueSet = xQueueCreateSet(1*2);xQueueAddToSet() adds a queue, semaphore, or mutex to an existing queue set so a task can monitor it together with other set members. The member should be empty when added, and the function returns pdPASS if successful or pdFAIL if it cannot be added.
BaseType_t xQueueAddToSet(QueueSetMemberHandle_t xQueueOrSemaphore,
QueueSetHandle_t xQueueSet)
// ---------------------- Example ----------------------
xQueueAddToSet(xQueue1, xQueueSet);
xQueueAddToSet(xQueue2, xQueueSet); xQueueSelectFromSet() blocks for a specified time until a queue or semaphore in a queue set becomes ready, then returns the handle of the ready member. A return value of NULL indicates that the timeout expired before any member became available.
QueueSetMemberHandle_t xQueueSelectFromSet(QueueSetHandle_t xQueueSet,
TickType_t const xTicksToWait)
// ---------------------- Example ----------------------
QueueHandle_t xQueueThatContainsData;
xQueueThatContainsData =
(QueueHandle_t)xQueueSelectFromSet(xQueueSet, portMAX_DELAY); Back to top of the page