队列适配器的相关操作

queue_adapter.c是一个和队列queue相关的文件，里面主要涉及到消息队列的创建等功能的实现。
文件路径：distributedschedule_samgr_lite\samgr\adapter\cmsis\queue_adapter.c
队列的作用：

基于FreeRTOS的应用程序是由一系列独立或交互的任务构成的，每个任务都拥有自
己相对独立的资源。
FreeRTOS中大多数通信和同步都是基于队列实现的。
通常队列被作为FIFO使用，即数据由队列尾写入，从队列首读出。

相关知识

本部分队列适配器主要是指消息队列，message quene。
利用 MSMQ（Microsoft Message Queue），应用程序开发人员可以通过发送和接收消息方便地与应用程序进行快速可靠的通信。消息处理为您提供了有保障的消息传递和执行许多业务处理的可靠的防故障方法。
MSMQ与XML Web Services和.Net Remoting一样，是一种分布式开发技术。但是在使用XML Web Services或.Net Remoting组件时，Client端需要和Server端实时交换信息，Server需要保持联机。MSMQ则可以在Server离线的情况下工作，将Message临时保存在Client端的消息队列中，以后联机时再发送到Server端处理。
显然，MSMQ不适合于Client需要Server端及时响应的这种情况，MSMQ以异步的方式和Server端交互，不用担心等待Server端的长时间处理过程。
虽然XML Web Services和.Net Remoting都提供了[OneWay]属性来处理异步调用，用来解决Server端长方法调用长时间阻碍Client端。但是不能解决大量Client负载的问题，此时Server接受的请求快于处理请求。
一般情况下，[OneWay]属性不用于专门的消息服务中

一些术语

1.消息:“消息”是在两台计算机间传送的数据单位。消息可以非常简单，例如只包含文本字符串；也可以更复杂，可能包含嵌入对象。
消息被发送到队列中。“消息队列”是在消息的传输过程中保存消息的容器。消息队列管理器在将消息从它的源中继到它的目标时充当中间人。队列的主要目的是提供路由并保证消息的传递；如果发送消息时接收者不可用，消息队列会保留消息，直到可以成功地传递它。
2.消息队列： 是 Microsoft 的消息处理技术，它在任何安装了 Microsoft Windows 的计算机组合中，为任何应用程序提供消息处理和消息队列功能，无论这些计算机是否在同一个网络上或者是否同时联机。
3.消息队列网络： 是能够相互间来回发送消息的任何一组计算机。网络中的不同计算机在确保消息顺利处理的过程中扮演不同的角色。它们中有些提供路由信息以确定如何发送消息，有些保存整个网络的重要信息，而有些只是发送和接收消息。
“消息队列”安装期间，管理员确定哪些服务器可以互相通信，并设置特定服务器的特殊角色。构成此“消息队列”网络的计算机称为“站点”，它们之间通过“站点链接”相互连接。每个站点链接都有一个关联的“开销”，它由管理员确定，指示了经过此站点链接传递消息的频率。
“消息队列”管理员还在网络中设置一台或多台作为“路由服务器”的计算机。路由服务器查看各站点链接的开销，确定经过多个站点传递消息的最快和最有效的方法，以此决定如何传递消息。

队列的类型

有两种主要的队列类型：由您或网络中的其他用户创建的队列和系统队列。
1.用户创建的队列有下面几种：

“公共队列” 在整个“消息队列”网络中复制，并且有可能由网络连接的所有站点访问。
“专用队列” 不在整个网络中发布。相反，它们仅在所驻留的本地计算机上可用。专用队列只能由知道队列的完整路径名或标签的应用程序访问。
“管理队列” 包含确认在给定“消息队列”网络中发送的消息回执的消息。指定希望 MessageQueue 组件使用的管理队列（如果有的话）。
“响应队列” 包含目标应用程序接收到消息时返回给发送应用程序的响应消息。指定希望 MessageQueue 组件使用的响应队列（如果有的话）。

2.系统生成的队列

“日记队列” 可选地存储发送消息的副本和从队列中移除的消息副本。每个“消息队列”客户端上的单个日记队列存储从该计算机发送的消息副本。在服务器上为每个队列创建了一个单独的日记队列。此日记跟踪从该队列中移除的消息。
“死信队列” 存储无法传递或已过期的消息的副本。如果过期或无法传递的消息是事务性消息，则被存储在一种特殊的死信队列中，称为“事务性死信队列”。死信存储在过期消息所在的计算机上。有关超时期限和过期消息的更多信息，请参见默认消息属性。
“报告队列” 包含指示消息到达目标所经过的路由的消息，还可以包含测试消息。每台计算机上只能有一个报告队列。
“专用系统队列” 是一系列存储系统执行消息处理操作所需的管理和通知消息的专用队列。
在应用程序中进行的大多数工作都涉及访问公共队列及其消息。但是，根据应用程序的日记记录、确认和其他特殊处理需要，在日常操作中很可能要使用几种不同的系统队列。

同步和异步通信

队列通信天生就是异步的，因为将消息发送到队列和从队列中接收消息是在不同的进程中完成的。另外，可以异步执行接收操作，因为要接收消息的人可以对任何给定的队列调用 BeginReceive 方法，然后立即继续其他任务而不用等待答复。这与人们所了解的“同步通信”截然不同。
在同步通信中，请求的发送方在执行其他任务前，必须等待来自预定接收方的响应。发送方等待的时间完全取决于接收方处理请求和发送响应所用的时间。

同消息队列交互

消息处理和消息为基于服务器的应用程序组件之间的进程间通信提供了强大灵活的机制。同组件间的直接调用相比，它们具有若干优点，其中包括：

稳定性 — 组件失败对消息的影响程度远远小于组件间的直接调用，因为消息存储在队列中并一直留在那里，直到被适当地处理。消息处理同事务处理相似，因为消息处理是有保证的。
消息优先级 — 更紧急或更重要的消息可在相对不重要的消息之前接收，因此可以为关键的应用程序保证足够的响应时间。
脱机能力 — 发送消息时，它们可被发送到临时队列中并一直留在那里，直到被成功地传递。当因任何原因对所需队列的访问不可用时，用户可以继续执行操作。同时，其他操作可以继续进行，如同消息已经得到了处理一样，这是因为网络连接恢复时消息传递是有保证的。
事务性消息处理 — 将多个相关消息耦合为单个事务，确保消息按顺序传递、只传递一次并且可以从它们的目标队列中被成功地检索。如果出现任何错误，将取消整个事务。
安全性 — MessageQueue 组件基于的消息队列技术使用 Windows 安全来保护访问控制，提供审核，并对组件发送和接收的消息进行加密和验证。

代码部分

QUEUE_Create函数，是实现消息队列的创建。

函数参数：

name：队列名
size：队列的大小
count：队列数目

//实现队列的创建
MQueueId QUEUE_Create(const char *name, int size, int count)
{
    
    
    osMessageQueueAttr_t queueAttr = {
    
    name, 0, NULL, 0, NULL, 0};
    return (MQueueId)osMessageQueueNew(count, size, &queueAttr);
}

QUEUE_Put函数

函数主要实现讲一个元素传入队列，相当于正常队列的push操作。将消息放入队列或在队列已满时实现超时的标记。
函数参数：

queueId：为队列指定一个id
element：带有要放入队列的消息的缓冲区指针。
pri：信息优先级用来表示消息的优先级
waitTime：CMSIS_RTOS_TimeOutValue，没有超时则为0

int QUEUE_Put(MQueueId queueId, const void *element, uint8 pri, int timeout)
{
    
    
    uint32_t waitTime = (timeout <= 0) ? 0 : (uint32_t)timeout;
    osStatus_t ret = osMessageQueuePut(queueId, element, pri, waitTime);
    if (ret != osOK) {
    
    
        return EC_BUSBUSY;
    }
    return EC_SUCCESS;
}

QUEUE_Pop函数

函数主要是从队列中获取消息，如果队列为空则获取超时。
函数参数：

queueId：为队列指定一个id
element：带有要放入队列的消息的缓冲区指针。
pri：为消息优先级或NULL指向缓冲区的指针。这个要区别于上一个函数的pri，这里的是*pri，表示是有指针情况的出现
waitTime：CMSIS_RTOS_TimeOutValue，没有超时则为0

//队列元素的弹出（出队列）
int QUEUE_Pop(MQueueId queueId, void *element, uint8 *pri, int timeout)
{
    
    
    uint32_t waitTime = (timeout <= 0) ? osWaitForever : (uint32_t)timeout;
    osStatus_t evt = osMessageQueueGet(queueId, element, pri, waitTime);
    if (evt != osOK) {
    
    
        return EC_BUSBUSY;
    }
    return EC_SUCCESS;
}

QUEUE_Destroy函数

函数功能：删除消息队列对象。
函数参数只有一个消息队列的id，这个id可以唯一指定一个队列，具有唯一性

//队列的摧毁
int QUEUE_Destroy(MQueueId queueId)
{
    
    
    osStatus_t evt = osMessageQueueDelete(queueId);
    if (evt != osOK) {
    
    
        return EC_FAILURE;
    }
    return EC_SUCCESS;
}

该文件中主要是消息队列的一部分函数，并未实现所有功能的封装。只实现了最基础的创建、出队、入队、删除队列等操作。cmsisi_os2.h文件中标注了更多的消息队列相关函数，大家想进一步了解的可以查阅cmsisi_os2.h文件。其中还定义了不少关于mutex的互斥函数，因为消息队列往往会伴随互斥体互斥锁等操作的出现。感谢阅读和点赞！

鸿蒙源码分析（五十四）