十四、队列函数
1、概述
(1)使用队列的流程：创建队列、写队列、读队列、删除队列。
2、创建
队列的创建有两种方法：动态分配内存、静态分配内存。
2.1、动态分配内存
(1)函数：xQueueCreate，队列的内存再函数内部动态分配。
(2)函数原型如下：
QueueHandle_t xQueueCreate( UBaseType_t uxQueueLength, UBaseType_t uxItemSize );(3)参数说明
| 参数 | 说明 |
| uxQueueLength | 队列长度，最多能存放多少个数据(item) |
| uxItemSize | 每个数据(item)的大小：以字节为单位 |
| 返回值 | 非0：成功，返回句柄，以后使用句柄来操作队列 NULL：失败，因为内存不足 |
2.2、静态分配内存
(1)函数：xQueueCreateStatic，队列的内存要事先分配好。
(2)函数原型如下：
QueueHandle_t xQueueCreateStatic(
UBaseType_t uxQueueLength,
UBaseType_t uxItemSize,
uint8_t *pucQueueStorageBuffer,
StaticQueue_t *pxQueueBuffer
);(3)参数说明
| 参数 | 说明 |
| uxQueueLength | 队列长度，最多能存放多少个数据(item) |
| uxItemSize | 每个数据(item)的大小：以字节为单位 |
| pucQueueStorageBuffer | 如果uxItemSize非0，pucQueueStorageBuffer必须指向一个 uint8_t数组，此数组大小至少为"uxQueueLength * uxItemSize" |
| pxQueueBuffer | 必须执行一个StaticQueue_t结构体，用来保存队列的数据结构 |
| 返回值 | 非0：成功，返回句柄，以后使用句柄来操作队列 NULL：失败，因为pxQueueBuffer为NULL |
(4)示例代码
// 示例代码
#define QUEUE_LENGTH 10
#define ITEM_SIZE sizeof( uint32_t )
// xQueueBuffer用来保存队列结构体
StaticQueue_t xQueueBuffer;
// ucQueueStorage 用来保存队列的数据
// 大小为：队列长度 * 数据大小
uint8_t ucQueueStorage[ QUEUE_LENGTH * ITEM_SIZE ];
void vATask( void *pvParameters )
{
QueueHandle_t xQueue1;
// 创建队列: 可以容纳QUEUE_LENGTH个数据，每个数据大小是ITEM_SIZE
xQueue1 = xQueueCreateStatic( QUEUE_LENGTH,
ITEM_SIZE,
ucQueueStorage,
&xQueueBuffer );
}3、复位
(1)队列刚被创建时，里面没有数据；使用过程中可以调用 xQueueReset() 把队列恢复为初始状态。
(2)函数原型：
/* pxQueue: 复位哪个队列;
* 返回值: pdPASS(必定成功)
*/
BaseType_t xQueueReset( QueueHandle_t pxQueue);4、删除
(1)删除队列的函数为 vQueueDelete() ，只能删除使用动态方法创建的队列，它会释放内存。
(2)函数原型：
void vQueueDelete( QueueHandle_t xQueue );5、写队列
(1)可以把数据写到队列头部，也可以写到尾部，这些函数有两个版本：在任务中使用、在ISR中使用。
(2)函数原型：
/* 等同于xQueueSendToBack
* 往队列尾部写入数据，如果没有空间，阻塞时间为xTicksToWait
*/
BaseType_t xQueueSend(
QueueHandle_t xQueue,
const void *pvItemToQueue,
TickType_t xTicksToWait
);
/*
* 往队列尾部写入数据，如果没有空间，阻塞时间为xTicksToWait
*/
BaseType_t xQueueSendToBack(
QueueHandle_t xQueue,
const void *pvItemToQueue,
TickType_t xTicksToWait
);
/*
* 往队列尾部写入数据，此函数可以在中断函数中使用，不可阻塞
*/
BaseType_t xQueueSendToBackFromISR(
QueueHandle_t xQueue,
const void *pvItemToQueue,
BaseType_t *pxHigherPriorityTaskWoken
);
/*
* 往队列头部写入数据，如果没有空间，阻塞时间为xTicksToWait
*/
BaseType_t xQueueSendToFront(
QueueHandle_t xQueue,
const void *pvItemToQueue,
TickType_t xTicksToWait
);
/*
* 往队列头部写入数据，此函数可以在中断函数中使用，不可阻塞
*/
BaseType_t xQueueSendToFrontFromISR(
QueueHandle_t xQueue,
const void *pvItemToQueue,
BaseType_t *pxHigherPriorityTaskWoken
);(3)参数说明
| 参数 | 说明 |
| xQueue | 队列句柄，要写哪个队列 |
| pvItemToQueue | 数据指针，这个数据的值会被复制进队列， 复制多大的数据？在创建队列时已经指定了数据大小 |
| xTicksToWait | 如果队列满则无法写入新数据，可以让任务进入阻塞状态， xTicksToWait表示阻塞的最大时间(Tick Count)。 如果被设为0，无法写入数据时函数会立刻返回； 如果被设为portMAX_DELAY，则会一直阻塞直到有空间可写。 |
| 返回值 | pdPASS：数据成功写入了队列 errQUEUE_FULL：写入失败，因为队列满了。 |
6、读队列
(1)使用 xQueueReceive() 函数读队列，读到一个数据后，队列中该数据会被移除。这个函数有两个版本：在任务中使用、在ISR中使用。
(2)函数原型：
BaseType_t xQueueReceive( QueueHandle_t xQueue,
void * const pvBuffer,
TickType_t xTicksToWait );
BaseType_t xQueueReceiveFromISR( QueueHandle_t xQueue,
void *pvBuffer,
BaseType_t *pxTaskWoken );(3)参数说明
| 参数 | 说明 |
| xQueue | 队列句柄，要读哪个队列 |
| pvBuffer | bufer指针，队列的数据会被复制到这个buffer 复制多大的数据？在创建队列时已经指定了数据大小 |
| xTicksToWait | 如果队列空则无法读出数据，可以让任务进入阻塞状态， xTicksToWait表示阻塞的最大时间(Tick Count)。 如果被设为0，无法读出数据时函数会立刻返回； 如果被设为portMAX_DELAY，则会一直阻塞直到有数据可写 |
| 返回值 | pdPASS：从队列读出数据入 errQUEUE_EMPTY：读取失败，因为队列空了。 |
7、查询
(1)可以查询队列中有多少个数据、有多少空余空间。
(2)函数原型：
/*
* 返回队列中可用数据的个数
*/
UBaseType_t uxQueueMessagesWaiting( const QueueHandle_t xQueue );
/*
* 返回队列中可用空间的个数
*/
UBaseType_t uxQueueSpacesAvailable( const QueueHandle_t xQueue );8、覆盖/偷看
8.1、覆盖
(1)当队列长度为1时，可以使用 xQueueOverwrite() 或 xQueueOverwriteFormISR() 来覆盖数据。注意，队列长度必须为1。当队列满时，这些函数会覆盖里面的数据，这也意味着这些函数不会被阻塞。
(2)函数原型：
/* 覆盖队列
* xQueue: 写哪个队列
* pvItemToQueue: 数据地址
* 返回值: pdTRUE表示成功, pdFALSE表示失败
*/
BaseType_t xQueueOverwrite(
QueueHandle_t xQueue,
const void * pvItemToQueue
);
BaseType_t xQueueOverwriteFromISR(
QueueHandle_t xQueue,
const void * pvItemToQueue,
BaseType_t *pxHigherPriorityTaskWoken
);8.2、偷看
(1)如果想让队列中的数据供多方读取，也就是说读取时不要移除数据，要留给后来人。那么可以使用"窥视"，也就是 xQueuePeek() 或 xQueuePeekFromISR() 。这些函数会从队列中复制出数据，但是不移除数据。这也意味着，如果队列中没有数据，那么"偷看"时会导致阻塞；一旦队列中有数据，以后每次"偷看"都会成功。
(2)函数原型：
/* 偷看队列
* xQueue: 偷看哪个队列
* pvItemToQueue: 数据地址, 用来保存复制出来的数据
* xTicksToWait: 没有数据的话阻塞一会
* 返回值: pdTRUE表示成功, pdFALSE表示失败
*/
BaseType_t xQueuePeek(
QueueHandle_t xQueue,
void * const pvBuffer,
TickType_t xTicksToWait
);
BaseType_t xQueuePeekFromISR(
QueueHandle_t xQueue,
void *pvBuffer,
);