Chapter 2. API Reference
const char *pcQueueGetName(QueueHandle_t xQueue)
The queue registry is provided as a means for kernel aware debuggers to locate queues, semaphores and mutexes.
Call pcQueueGetName() to look up and return the name of a queue in the queue registry from the queue’s
handle.
Return If the queue is in the registry then a pointer to the name of the queue is returned. If the queue is not
in the registry then NULL is returned.
Parameters
• xQueue: The handle of the queue the name of which will be returned.
QueueHandle_t xQueueGenericCreate(const UBaseType_t uxQueueLength, const UBaseType_t
uxItemSize, const uint8_t ucQueueType)
Generic version of the function used to create a queue using dynamic memory allocation. This is called by
other functions and macros that create other RTOS objects that use the queue structure as their base.
QueueHandle_t xQueueGenericCreateStatic(const UBaseType_t uxQueueLength, const
UBaseType_t uxItemSize, uint8_t *pucQueueStorage,
StaticQueue_t *pxStaticQueue, const uint8_t
ucQueueType)
Generic version of the function used to create a queue using dynamic memory allocation. This is called by
other functions and macros that create other RTOS objects that use the queue structure as their base.
QueueSetHandle_t xQueueCreateSet(const UBaseType_t uxEventQueueLength)
Queue sets provide a mechanism to allow a task to block (pend) on a read operation from multiple queues or
semaphores simultaneously.
See FreeRTOS/Source/Demo/Common/Minimal/QueueSet.c for an example using this function.
A queue set must be explicitly created using a call to xQueueCreateSet() before it can be used. Once cre-
ated, standard FreeRTOS queues and semaphores can be added to the set using calls to xQueueAddToSet().
xQueueSelectFromSet() is then used to determine which, if any, of the queues or semaphores contained in the
set is in a state where a queue read or semaphore take operation would be successful.
Note 1: See the documentation on https://www.FreeRTOS.org/RTOS-queue-sets.html for reasons why queue
sets are very rarely needed in practice as there are simpler methods of blocking on multiple objects.
Note 2: Blocking on a queue set that contains a mutex will not cause the mutex holder to inherit the priority
of the blocked task.
Note 3: An additional 4 bytes of RAM is required for each space in a every queue added to a queue set.
Therefore counting semaphores that have a high maximum count value should not be added to a queue set.
Note 4: A receive (in the case of a queue) or take (in the case of a semaphore) operation must not be performed
on a member of a queue set unless a call to xQueueSelectFromSet() has first returned a handle to that set
member.
Return If the queue set is created successfully then a handle to the created queue set is returned. Otherwise
NULL is returned.
Parameters
• uxEventQueueLength: Queue sets store events that occur on the queues and semaphores con-
tained in the set. uxEventQueueLength specifies the maximum number of events that can be queued
at once. To be absolutely certain that events are not lost uxEventQueueLength should be set to the
total sum of the length of the queues added to the set, where binary semaphores and mutexes have
a length of 1, and counting semaphores have a length set by their maximum count value. Examples:
– If a queue set is to hold a queue of length 5, another queue of length 12, and a binary semaphore,
then uxEventQueueLength should be set to (5 + 12 + 1), or 18.
– If a queue set is to hold three binary semaphores then uxEventQueueLength should be set to (1
+ 1 + 1 ), or 3.
– If a queue set is to hold a counting semaphore that has a maximum count of 5, and a counting
semaphore that has a maximum count of 3, then uxEventQueueLength should be set to (5 + 3),
or 8.
BaseType_t xQueueAddToSet(QueueSetMemberHandle_t xQueueOrSemaphore, QueueSetHandle_t
xQueueSet)
Adds a queue or semaphore to a queue set that was previously created by a call to xQueueCreateSet().
Espressif Systems 890
Submit Document Feedback
Release v4.4
To Next Page
Loading...