1. 概述
队列又称消息队列，是一种常用于任务间通信的数据结构，实现了接收来自任务或中断的不固定长度的消息，并根据不同的接口选择传递消息是否存放在自己空间。任务能够从队列里面读取消息，当队列中的消息是空时，挂起读取任务；当队列中有新消息时，挂起的读取任务被唤醒并处理新消息。
用户在处理业务时，消息队列提供了异步处理机制，允许将一个消息放入队列，但并不立即处理它，同时队列还能起到缓冲消息作用。
Huawei LiteOS中使用队列数据结构实现任务异步通信工作，具有如下特性：
- 消息以先进先出方式排队，支持异步读写工作方式。
- 读队列和写队列都支持超时机制。
- 发送消息类型由通信双方约定，可以允许不同长度（不超过队列节点最大值）消
息。 - 一个任务能够从任意一个消息队列接收和发送消息。
- 多个任务能够从同一个消息队列接收和发送消息。
- 当队列使用结束后，如果是动态申请的内存，需要通过释放内存函数回收。
2. 运作机制
2.1 队列控制块
/**
* @ingroup los_queue
* Queue information block structure
*/
typedef struct tagQueueCB
{
UINT8 *pucQueue; /**< 队列指针 */
UINT16 usQueueState; /**< 队列状态 */
UINT16 usQueueLen; /**< 队列中消息个数 */
UINT16 usQueueSize; /**< 消息节点大小 */
UINT16 usQueueHead; /**< 消息头节点位置（数组下标）*/
UINT16 usQueueTail; /**< 消息尾节点位置（数组下标）*/
UINT16 usWritableCnt; /**< 队列中可写消息数*/
UINT16 usReadableCnt; /**< 队列中可读消息数*/
UINT16 usReserved; /**< 保留字段 */
LOS_DL_LIST stWriteList; /**< 写入消息任务等待链表*/
LOS_DL_LIST stReadList; /**< 读取消息任务等待链表*/
LOS_DL_LIST stMemList; /**< MailBox模块使用 */
} QUEUE_CB_S;
每个队列控制块中都含有队列状态，表示该队列的使用情况：
- OS_QUEUE_UNUSED：队列没有使用
- OS_QUEUE_INUSED：队列被使用
2.2 队列运作原理
创建队列时，根据用户传入队列长度和消息节点大小来开辟相应的内存空间以供该队列使用，返回队列ID。
在队列控制块中维护一个消息头节点位置Head和一个消息尾节点位置Tail来表示当前队列中消息存储情况。 Head表示队列中被占用消息的起始位置。 Tail表示队列中被空闲消息的起始位置。刚创建时Head和Tail均指向队列起始位置。
写队列时，根据Tail找到被占用消息节点末尾的空闲节点作为数据写入对象。如果Tail已经指向队列尾则采用回卷方式。根据usWritableCnt判断队列是否可以写入，不能对已满（usWritableCnt为0）队列进行写队列操作。
读队列时，根据Head找到最先写入队列中的消息节点进行读取。如果Head已经指向队如果Head已经指向队列尾则采用回卷方式。根据usReadableCnt判断队列是否有消息读取，对全部空闲（usReadableCnt为0）队列进行读队列操作会引起任务挂起。
删除队列时，根据传入的队列ID寻找到对应的队列，把队列状态置为未使用，释放原队列所占的空间，对应的队列控制头置为初始状态。
图 3-7 队列读写数据操作示意图
3. 开发指导
3.1 功能
Huawei LiteOS中Message消息处理模块提供了以下功能。
| 功能分类 | 接口名 | 描述 |
|---|---|---|
| 创建消息队列 | LOS_QueueCreate | 创建一个消息队列。 |
| 读队列（不带拷贝） | LOS_QueueRead | 读取指定队列中的数据。（buff里存放的是队列节点的地址）。 |
| 写队列（不带拷贝） | LOS_QueueWrite | 向指定队列写数据。（写入队列节点中的是buff的地址）。 |
| 读队列（带拷贝） | LOS_QueueReadCopy | 读取指定队列中的数据。（buff里存放的是队列节点中的数据）。 |
| 写队列（带拷贝） | LOS_QueueWriteCopy | 向指定队列写数据。（写入队列节点中的是buff中的数据）。 |
| 写队列（头部） | LOS_QueueWriteHead | 向指定队列的头部写数据 |
| 删除队列 | LOS_QueueDelete | 删除一个指定的队列。 |
| 获取队列信息 | LOS_QueueInfoGet | 获取指定队列信息。 |
3.2 开发流程
使用队列模块的典型流程如下：
- 创建消息队列LOS_QueueCreate。
创建成功后，可以得到消息队列的ID值。
- 写队列操作函数LOS_QueueWrite。
- 读队列操作函数LOS_QueueRead。
- 获取队列信息函数LOS_QueueInfoGet。
- 删除队列LOS_QueueDelete
3.3 QUEUE 错误码
对队列存在失败可能性的操作，包括创建队列、删除队列等等，均需要返回对应的错误码，以便快速定位错误原因。
| 序 号 | 定义 | 实际数值 | 描述 | 参考解决方案 |
|---|---|---|---|---|
| 1 | LOS_ERRNO_QUEUE_MAXNUM_ZERO | 0x02000600 | 队列资源的最大数目配置为0 | 配置要大于0的队列资源的最大数量。如果不使用队列模块，则将配置项设置为将队列资源的最大数量的剪裁设置为NO。 |
| 2 | LOS_ERRNO_QUEUE_NO_MEMORY | 0x02000601 | 队列块内存无法初始化 | 为队列块分配更大的内存分区，或减少队列资源的最大数量。 |
| 3 | LOS_ERRNO_QUEUE_CREATE_NO_MEMORY | 0x02000602 | 队列创建的内存未能被请求 | 为队列分配更多的内存，或减少要创建的队列中的队列长度和节点的数目。 |
| 4 | LOS_ERRNO_QUEUE_SIZE_TOO_BIG | 0x02000603 | 队列创建时 | 消息长度超过上限更改创建队列中最大消息的大小至不超过上线 |
| 5 | LOS_ERRNO_QUEUE_CB_UNAVAILABLE | 0x02000604 | 已超过创建的队列的数量的上限 | 增加队列的配置资源数量 |
| 6 | LOS_ERRNO_QUEUE_NOT_FOUND | 0x02000605 | 无效的队列 | 确保队列ID是有效的 |
| 7 | LOS_ERRNO_QUEUE_PEND_IN_LOCK | 0x02000606 | 当任务被锁定时，禁止在队列中被阻塞 | 使用队列前解锁任务 |
| 8 | LOS_ERRNO_QUEUE_TIMEOUT | 0x02000607 | 等待处理队列的时间超时 | 检查设置的超时时间是否合适 |
| 9 | LOS_ERRNO_QUEUE_IN_TSKUSE | 0x02000608 | 阻塞任务的队列不能被删除 | 使任务能够获得资源而不是在队列中被阻塞 |
| 10 | LOS_ERRNO_QUEUE_WRITE_IN_INTERRUPT | 0x02000609 | 在中断处理程序中不能写队列 | 将写队列设为非阻塞模式 |
| 11 | LOS_ERRNO_QUEUE_NOT_CREATE | 0x0200060a | 队列未创建 | 检查队列中传递的句柄是否有效 |
| 12 | LOS_ERRNO_QUEUE_IN_TSKWRITE | 0x0200060b | 队列读写不同步 | 同步队列的读写 |
| 13 | LOS_ERRNO_QUEUE_CREAT_PTR_NULL | 0x0200060c | 队列创建过程中传递的参数为空指针 | 确保传递的参数不为空指针 |
| 14 | LOS_ERRNO_QUEUE_PARA_ISZERO | 0x0200060d | 队列创建过程中传递的队列长度或消息节点大小为0 | 传入正确的队列长度和消息节点大小 |
| 15 | LOS_ERRNO_QUEUE_READ_INVALID | 0x0200060e | 读取的队列的handle无效 | 检查队列中传递的handle是否有效 |
| 16 | LOS_ERRNO_QUEUE_READ_PTR_NULL | 0x0200060f | 队列读取过程中传递的指针为空 | 检查指针中传递的是否为空 |
| 17 | LOS_ERRNO_QUEUE_READSIZE_ISZERO | 0x02000610 | 队列读取过程中传递的缓冲区大小为0 | 通过一个正确的缓冲区大小 |
| 18 | LOS_ERRNO_QUEUE_WRITE_INVALID | 0x02000611 | 队列写入过程中传递的队列handle无效 检查队列中传递的handle是否有效 | |
| 19 | LOS_ERRNO_QUEUE_WRITE_PTR_NULL | 0x02000612 | 队列写入过程中传递的指针为空 | 检查指针中传递的是否为空 |
| 20 | LOS_ERRNO_QUEUE_WRITESIZE_ISZERO | 0x02000613 | 队列写入过程中传递的缓冲区大小为0 | 通过一个正确的缓冲区大小 |
| 21 | LOS_ERRNO_QUEUE_WRITE_NOT_CREATE | 0x02000614 | 写入数据的队列未创建 | 传入有效队列ID |
| 22 | LOS_ERRNO_QUEUE_WRITE_SIZE_TOO_BIG | 0x02000615 | 队列写入过程中传递的缓冲区大小比队列大小要大 | 减少缓冲区大小，或增大队列节点 |
| 23 | LOS_ERRNO_QUEUE_ISFULL | 0x02000616 | 在队列写入过程中没有可用的空闲节点 | 确保在队列写入之前，可以使用空闲的节点 |
| 24 | LOS_ERRNO_QUEUE_PTR_NULL | 0x02000617 | 正在获取队列信息时传递的指针为空 | 检查指针中传递的是否为空 |
| 25 | LOS_ERRNO_QUEUE_READ_IN_INTERRUPT | 0x02000618 | 在中断处理程序中不能读队列 | 将读队列设为非阻塞模式 |
| 26 | LOS_ERRNO_QUEUE_MAIL_HANDLE_INVALID | 0x02000619 | 正在释放队列的内存时传递的队列的handle无效 | 检查队列中传递的handle是否有效 |
| 27 | LOS_ERRNO_QUEUE_MAIL_PTR_INVALID | 0x0200061a | 传入的消息内存池指针为空 | 检查指针是否为空 |
| 28 | LOS_ERRNO_QUEUE_MAIL_FREE_ERROR | 0x0200061b | membox内存释放失败 | 传入非空membox内存指针 |
| 29 | LOS_ERRNO_QUEUE_READ_NOT_CREATE | 0x0200061c | 待读取的队列未创建 | 传入有效队列ID |
| 30 | LOS_ERRNO_QUEUE_ISEMPTY | 0x0200061d | 队列已空 | 确保在读取队列时包含消息 |
| 31 | LOS_ERRNO_QUEUE_READ_SIZE_TOO_SMALL | 0x0200061f | 读缓冲区大小小于队列大小 | 增加缓冲区大小，或减小队列节点大小 |
3.4 注意事项
- 系统可配置的队列资源个数是指：整个系统的队列资源总个数，而非用户能使用的个数。例如：系统软件定时器多占用一个队列资源，那么系统可配置的队列资源就会减少一个。
- 调用 LOS_QueueCreate 函数时所传入的队列名暂时未使用，作为以后的预留参
数。 - 队列接口函数中的入参uwTimeOut是指相对时间。
- LOS_QueueReadCopy和LOS_QueueWriteCopy是一组接口， LOS_QueueRead和LOS_QueueWrite是一组接口，两组接口需要配套使用。
- 鉴于LOS_QueueWrite和LOS_QueueRead这组接口实际操作的是数据地址，用户必须保证调用LOS_QueueRead获取到的指针所指向内存区域在读队列期间没有被异常修改或释放，否则可能会导致不可预知的后果。
3.5 编程实例
3.5.1 实例描述
创建一个队列，两个任务。任务1调用发送接口发送消息；任务2通过接收接口接收消息。
- 通过LOS_TaskCreate创建任务1和任务2。
- 通过LOS_QueueCreate创建一个消息队列。
- 在任务1 send_Entry中发送消息。
- 在任务2 recv_Entry中接收消息。
- 通过LOS_QueueDelete删除队列。
3.5.2 编程示例
#include "los_task.h"
#include "los_queue.h"
static UINT32 g_uwQueue;
CHAR abuf[] = "test is message x";
/*任务1发送数据*/
void *send_Entry(void *arg)
{
UINT32 i = 0,uwRet = 0;
UINT32 uwlen = sizeof(abuf);
while (i <5)
{
abuf[uwlen -2] = '0' + i;
i++;
/*将abuf里的数据写入队列*/
uwRet = LOS_QueueWrite(g_uwQueue, abuf, uwlen, 0);
if(uwRet != LOS_OK)
{
dprintf("send message failure,error:%x
",uwRet);
}
LOS_TaskDelay(5);
}
}
/*任务2接收数据*/
void *recv_Entry(void *arg)
{
UINT32 uwReadbuf;
UINT32 uwRet = 0;
while (1)
{
/*读取队列里的数据存入uwReadbuf里*/
uwRet = LOS_QueueRead(g_uwQueue, &uwReadbuf, 50, 0);
if(uwRet != LOS_OK)
{
dprintf("recv message failure,error:%x
",uwRet);
break;
}
dprintf("recv message:%s
", (char *)uwReadbuf);
LOS_TaskDelay(5);
}
/*删除队列*/
while (LOS_OK != LOS_QueueDelete(g_uwQueue))
{
LOS_TaskDelay(1);
}
dprintf("delete the queue success!
");
}
int Example_creat_task(void)
{
UINT32 uwRet = 0;
UINT32 uwTask1, uwTask2;
TSK_INIT_PARAM_S stInitParam1;
/*创建任务1*/
stInitParam1.pfnTaskEntry = send_Entry;
stInitParam1.usTaskPrio = 9;
stInitParam1.uwStackSize = 0x400;
stInitParam1.pcName = "sendQueue";
stInitParam1.uwResved = LOS_TASK_STATUS_DETACHED;
LOS_TaskLock();//锁住任务，防止新创建的任务比本任务高而发生调度
uwRet = LOS_TaskCreate(&uwTask1, &stInitParam1);
if(uwRet != LOS_OK)
{
dprintf("create task1 failed!,error:%x
",uwRet);
return uwRet;
}
/*创建任务2*/
stInitParam1.pfnTaskEntry = recv_Entry;
uwRet = LOS_TaskCreate(&uwTask2, &stInitParam1);
if(uwRet != LOS_OK)
{
dprintf("create task2 failed!,error:%x
",uwRet);
return uwRet;
}
/*创建队列*/
uwRet = LOS_QueueCreate("queue", 5, &g_uwQueue, 0, 50);
if(uwRet != LOS_OK)
{
dprintf("create queue failure!,error:%x
",uwRet);
}
dprintf("create the queue success!
");
LOS_TaskUnlock();//解锁任务，只有队列创建后才开始任务调度
}
3.5.3 结果验证
