Queue Sets

Group that contains macros & functions for managing queue sets. More...

Collaboration diagram for Queue Sets:

Functions
QueueSetHandle_t	xQueueCreateSet (const UBaseType_t uxEventQueueLength) PRIVILEGED_FUNCTION
BaseType_t	xQueueAddToSet (QueueSetMemberHandle_t xQueueOrSemaphore, QueueSetHandle_t xQueueSet) PRIVILEGED_FUNCTION
BaseType_t	xQueueRemoveFromSet (QueueSetMemberHandle_t xQueueOrSemaphore, QueueSetHandle_t xQueueSet) PRIVILEGED_FUNCTION
QueueSetMemberHandle_t	xQueueSelectFromSet (QueueSetHandle_t xQueueSet, const TickType_t xTicksToWait) PRIVILEGED_FUNCTION
QueueSetMemberHandle_t	xQueueSelectFromSetFromISR (QueueSetHandle_t xQueueSet) PRIVILEGED_FUNCTION

Detailed Description

Group that contains macros & functions for managing queue sets.

Function Documentation

xQueueAddToSet()

BaseType_t xQueueAddToSet	(	QueueSetMemberHandle_t	xQueueOrSemaphore,
		QueueSetHandle_t	xQueueSet
	)

#include <queue.h>

Adds a queue or semaphore to a queue set that was previously created by a call to xQueueCreateSet().

See FreeRTOS/Source/Demo/Common/Minimal/QueueSet.c for an example using this function.

Note 1: 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.

Parameters

xQueueOrSemaphore	The handle of the queue or semaphore being added to the queue set (cast to an QueueSetMemberHandle_t type).
xQueueSet	The handle of the queue set to which the queue or semaphore is being added.

Returns

If the queue or semaphore was successfully added to the queue set then pdPASS is returned. If the queue could not be successfully added to the queue set because it is already a member of a different queue set then pdFAIL is returned.

xQueueCreateSet()

QueueSetHandle_t xQueueCreateSet

(

const UBaseType_t

uxEventQueueLength

)

#include <queue.h>

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 created, 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 http://wwwFreeRTOS.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.

Parameters

uxEventQueueLength

Queue sets store events that occur on the queues and semaphores contained 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.

Returns

If the queue set is created successfully then a handle to the created queue set is returned. Otherwise NULL is returned.

xQueueRemoveFromSet()

BaseType_t xQueueRemoveFromSet	(	QueueSetMemberHandle_t	xQueueOrSemaphore,
		QueueSetHandle_t	xQueueSet
	)

#include <queue.h>

Removes a queue or semaphore from a queue set. A queue or semaphore can only be removed from a set if the queue or semaphore is empty.

See FreeRTOS/Source/Demo/Common/Minimal/QueueSet.c for an example using this function.

Parameters

xQueueOrSemaphore	The handle of the queue or semaphore being removed from the queue set (cast to an QueueSetMemberHandle_t type).
xQueueSet	The handle of the queue set in which the queue or semaphore is included.

Returns

If the queue or semaphore was successfully removed from the queue set then pdPASS is returned. If the queue was not in the queue set, or the queue (or semaphore) was not empty, then pdFAIL is returned.

xQueueSelectFromSet()

QueueSetMemberHandle_t xQueueSelectFromSet	(	QueueSetHandle_t	xQueueSet,
		const TickType_t	xTicksToWait
	)

#include <queue.h>

xQueueSelectFromSet() selects from the members of a queue set a queue or semaphore that either contains data (in the case of a queue) or is available to take (in the case of a semaphore). xQueueSelectFromSet() effectively allows a task to block (pend) on a read operation on all the queues and semaphores in a queue set simultaneously.

See FreeRTOS/Source/Demo/Common/Minimal/QueueSet.c for an example using this function.

Note 1: See the documentation on http://wwwFreeRTOS.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: 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.

Parameters

xQueueSet	The queue set on which the task will (potentially) block.
xTicksToWait	The maximum time, in ticks, that the calling task will remain in the Blocked state (with other tasks executing) to wait for a member of the queue set to be ready for a successful queue read or semaphore take operation.

Returns

xQueueSelectFromSet() will return the handle of a queue (cast to a QueueSetMemberHandle_t type) contained in the queue set that contains data, or the handle of a semaphore (cast to a QueueSetMemberHandle_t type) contained in the queue set that is available, or NULL if no such queue or semaphore exists before before the specified block time expires.

xQueueSelectFromSetFromISR()

QueueSetMemberHandle_t xQueueSelectFromSetFromISR

(

QueueSetHandle_t

xQueueSet

)

#include <queue.h>

A version of xQueueSelectFromSet() that can be used from an ISR.