Queue Creation

Group that contains macros & functions for creating queues. More...

Collaboration diagram for Queue Creation:

Macros
#define	xQueueCreate(uxQueueLength, uxItemSize)   xQueueGenericCreate( ( uxQueueLength ), ( uxItemSize ), ( queueQUEUE_TYPE_BASE ) )
#define	xQueueCreateStatic(uxQueueLength, uxItemSize, pucQueueStorage, pxQueueBuffer)   xQueueGenericCreateStatic( ( uxQueueLength ), ( uxItemSize ), ( pucQueueStorage ), ( pxQueueBuffer ), ( queueQUEUE_TYPE_BASE ) )

Functions
QueueHandle_t	xQueueGenericCreate (const UBaseType_t uxQueueLength, const UBaseType_t uxItemSize, const uint8_t ucQueueType) PRIVILEGED_FUNCTION
QueueHandle_t	xQueueGenericCreateStatic (const UBaseType_t uxQueueLength, const UBaseType_t uxItemSize, uint8_t *pucQueueStorage, StaticQueue_t *pxStaticQueue, const uint8_t ucQueueType) PRIVILEGED_FUNCTION

Detailed Description

Group that contains macros & functions for creating queues.

Macro Definition Documentation

xQueueCreate

#define xQueueCreate	(		uxQueueLength,
			uxItemSize
	)		xQueueGenericCreate( ( uxQueueLength ), ( uxItemSize ), ( queueQUEUE_TYPE_BASE ) )

#include <queue.h>

QueueHandle_t xQueueCreate(
                             UBaseType_t uxQueueLength,
                             UBaseType_t uxItemSize
                         );

Creates a new queue instance, and returns a handle by which the new queue can be referenced.

Internally, within the FreeRTOS implementation, queues use two blocks of memory. The first block is used to hold the queue's data structures. The second block is used to hold items placed into the queue. If a queue is created using xQueueCreate() then both blocks of memory are automatically dynamically allocated inside the xQueueCreate() function. (see http://www.freertos.org/a00111.html). If a queue is created using xQueueCreateStatic() then the application writer must provide the memory that will get used by the queue. xQueueCreateStatic() therefore allows a queue to be created without using any dynamic memory allocation.

http://www.FreeRTOS.org/Embedded-RTOS-Queues.html

Parameters

uxQueueLength	The maximum number of items that the queue can contain.
uxItemSize	The number of bytes each item in the queue will require. Items are queued by copy, not by reference, so this is the number of bytes that will be copied for each posted item. Each item on the queue must be the same size.

Returns

If the queue is successfully create then a handle to the newly created queue is returned. If the queue cannot be created then 0 is returned.

Example usage:

struct AMessage
{
   char ucMessageID;
   char ucData[ 20 ];
};
 
void vATask( void *pvParameters )
{
QueueHandle_t xQueue1, xQueue2;
 
   // Create a queue capable of containing 10 uint32_t values.
   xQueue1 = xQueueCreate( 10, sizeof( uint32_t ) );
   if( xQueue1 == 0 )
   {
       // Queue was not created and must not be used.
   }
 
   // Create a queue capable of containing 10 pointers to AMessage structures.
   // These should be passed by pointer as they contain a lot of data.
   xQueue2 = xQueueCreate( 10, sizeof( struct AMessage * ) );
   if( xQueue2 == 0 )
   {
       // Queue was not created and must not be used.
   }
 
   // ... Rest of task code.
}

xQueueCreateStatic

#define xQueueCreateStatic	(		uxQueueLength,
			uxItemSize,
			pucQueueStorage,
			pxQueueBuffer
	)		xQueueGenericCreateStatic( ( uxQueueLength ), ( uxItemSize ), ( pucQueueStorage ), ( pxQueueBuffer ), ( queueQUEUE_TYPE_BASE ) )

#include <queue.h>

QueueHandle_t xQueueCreateStatic(
                             UBaseType_t uxQueueLength,
                             UBaseType_t uxItemSize,
                             uint8_t *pucQueueStorageBuffer,
                             StaticQueue_t *pxQueueBuffer
                         );

Creates a new queue instance, and returns a handle by which the new queue can be referenced.

Internally, within the FreeRTOS implementation, queues use two blocks of memory. The first block is used to hold the queue's data structures. The second block is used to hold items placed into the queue. If a queue is created using xQueueCreate() then both blocks of memory are automatically dynamically allocated inside the xQueueCreate() function. (see http://www.freertos.org/a00111.html). If a queue is created using xQueueCreateStatic() then the application writer must provide the memory that will get used by the queue. xQueueCreateStatic() therefore allows a queue to be created without using any dynamic memory allocation.

http://www.FreeRTOS.org/Embedded-RTOS-Queues.html

Parameters

uxQueueLength	The maximum number of items that the queue can contain.
uxItemSize	The number of bytes each item in the queue will require. Items are queued by copy, not by reference, so this is the number of bytes that will be copied for each posted item. Each item on the queue must be the same size.
pucQueueStorageBuffer	If uxItemSize is not zero then pucQueueStorageBuffer must point to a uint8_t array that is at least large enough to hold the maximum number of items that can be in the queue at any one time - which is ( uxQueueLength * uxItemsSize ) bytes. If uxItemSize is zero then pucQueueStorageBuffer can be NULL.
pxQueueBuffer	Must point to a variable of type StaticQueue_t, which will be used to hold the queue's data structure.

Returns

If the queue is created then a handle to the created queue is returned. If pxQueueBuffer is NULL then NULL is returned.

Example usage:

struct AMessage
{
   char ucMessageID;
   char ucData[ 20 ];
};
 
#define QUEUE_LENGTH 10
#define ITEM_SIZE sizeof( uint32_t )
 
// xQueueBuffer will hold the queue structure.
StaticQueue_t xQueueBuffer;
 
// ucQueueStorage will hold the items posted to the queue.  Must be at least
// [(queue length) * ( queue item size)] bytes long.
uint8_t ucQueueStorage[ QUEUE_LENGTH * ITEM_SIZE ];
 
void vATask( void *pvParameters )
{
QueueHandle_t xQueue1;
 
   // Create a queue capable of containing 10 uint32_t values.
   xQueue1 = xQueueCreate( QUEUE_LENGTH, // The number of items the queue can hold.
                           ITEM_SIZE     // The size of each item in the queue
                           &( ucQueueStorage[ 0 ] ), // The buffer that will hold the items in the queue.
                           &xQueueBuffer ); // The buffer that will hold the queue structure.
 
   // The queue is guaranteed to be created successfully as no dynamic memory
   // allocation is used.  Therefore xQueue1 is now a handle to a valid queue.
 
   // ... Rest of task code.
}

Function Documentation

xQueueGenericCreate()

QueueHandle_t xQueueGenericCreate	(	const UBaseType_t	uxQueueLength,
		const UBaseType_t	uxItemSize,
		const uint8_t	ucQueueType
	)

#include <queue.h>

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.

xQueueGenericCreateStatic()

QueueHandle_t xQueueGenericCreateStatic	(	const UBaseType_t	uxQueueLength,
		const UBaseType_t	uxItemSize,
		uint8_t *	pucQueueStorage,
		StaticQueue_t *	pxStaticQueue,
		const uint8_t	ucQueueType
	)

#include <queue.h>

Generic version of the function used to creaet 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.