消息队列¶

功能概述¶

消息队列支持多生产者、多消费者模型。它采用先进先出的数据结构，适用于需要在多线程间安全交换消息的场景，常用于消息异步处理。例如，接收数据的线程为避免阻塞，只是将数据写入队列；另一个线程则专门处理队列中的消息。

消息队列API¶

头文件¶

qosa_sys.h

函数概览¶

函数名	功能描述
qosa_msgq_create()	创建消息队列
qosa_msgq_delete()	删除消息队列
qosa_msgq_release()	发送消息到队列
qosa_msgq_wait()	从队列接收消息
qosa_msgq_get_cnt()	获取当前队列中的消息数量

函数详解¶

qosa_msgq_create¶

功能描述
创建消息队列，并指定消息大小和队列容量。
函数原型

int qosa_msgq_create(qosa_msgq_t *msgQRef, qosa_uint32_t size, qosa_uint32_t maxNumber)

参数说明

参数名	输入/输出	类型	说明
msgQRef	输入	qosa_msgq_t *	消息队列句柄指针
size	输入	qosa_uint32_t	存储的数据类型的长度
maxNumber	输入	qosa_uint32_t	消息队列的最大消息数

返回值说明
QOSA_ERROR_OK：函数执行成功
QOSA_ERROR_MSGQ_INVALID_ERR：参数无效
QOSA_ERROR_MSGQ_CREATE_ERR：创建失败

qosa_msgq_delete¶

功能描述
删除消息队列，并释放所有相关资源。
函数原型

int qosa_msgq_delete(qosa_msgq_t msgQRef)

参数说明

参数名	输入/输出	类型	说明
msgQRef	输入	qosa_msgq_t	消息队列句柄

返回值说明
QOSA_ERROR_OK：函数执行成功
QOSA_ERROR_MSGQ_INVALID_ERR：参数无效

备注

调用此函数前，请确保没有任何任务正在阻塞等待或访问该队列。
队列被删除时，其中未处理的消息会被丢弃。
删除成功后，该句柄将立即失效。

qosa_msgq_release¶

功能描述
发送消息到队列。
函数原型

int qosa_msgq_release(qosa_msgq_t msgQRef, qosa_uint32_t size, qosa_uint8_t *value, qosa_uint32_t timeout)

参数说明

参数名	输入/输出	类型	说明
msgQRef	输入	qosa_msgq_t	消息队列句柄
size	输入	qosa_uint32_t	发送消息的大小（必须与创建队列时指定的 size 一致）
value	输入	qosa_uint8_t *	指向消息数据的指针
timeout	输入	qosa_uint32_t	等待超时时间。单位：毫秒 QOSA_WAIT_FOREVER：永久等待 QOSA_NO_WAIT：不等待

返回值说明
QOSA_ERROR_OK：函数执行成功
QOSA_ERROR_MSGQ_INVALID_ERR：参数无效
QOSA_ERROR_EVENT_SIZE_ERR：消息大小与队列定义不符
QOSA_ERROR_MSGQ_FULL_ERR：消息队列已满，无法继续写入消息
QOSA_ERROR_MSGQ_CREATE_ERR：创建失败

qosa_msgq_wait¶

功能描述
从队列接收消息（消费者操作），支持超时等待。
函数原型

int qosa_msgq_wait(qosa_msgq_t msgQRef, qosa_uint8_t *value, qosa_uint32_t size, qosa_uint32_t timeout)

参数说明

参数名	输入/输出	类型	说明
msgQRef	输入	qosa_msgq_t	消息队列句柄
value	输入	qosa_uint8_t *	存储接收消息的缓冲区指针
size	输入	qosa_uint32_t	接收缓冲区的大小（必须与创建队列时指定的 size 一致）
timeout	输入	qosa_uint32_t	等待超时时间。单位：毫秒 QOSA_WAIT_FOREVER：永久等待 QOSA_NO_WAIT：不等待

返回值说明
QOSA_ERROR_OK：函数执行成功
QOSA_ERROR_MSGQ_INVALID_ERR：参数无效
QOSA_ERROR_MSGQ_TIMEOUT_ERR：操作等待超时
QOSA_ERROR_MSGQ_RECV_ERR：接收消息失败

qosa_msgq_get_cnt¶

功能描述
获取当前队列中的消息数量。
函数原型

int qosa_msgq_get_cnt(qosa_msgq_t msgQRef, qosa_uint32_t *cnt_ptr)

参数说明

参数名	输入/输出	类型	说明
msgQRef	输入	qosa_msgq_t	消息队列句柄
cnt_ptr	输出	qosa_uint32_t *	存储消息数量的指针

返回值说明
QOSA_ERROR_OK：函数执行成功
QOSA_ERROR_MSGQ_INVALID_ERR：参数无效

备注

该函数返回的是调用瞬间的消息数量快照。
在多任务环境下，获取到的消息数量在函数返回后可能立即发生变化。

枚举定义¶

qosa_errcode_os_e¶

错误码枚举定义如下：

typedef enum
{
    QOSA_ERROR_OK = 0,                                        
    ...
    QOSA_ERROR_MSGQ_CREATE_ERR = 1 | QOSA_ERRCODE_OS_BASE,    
    QOSA_ERROR_MSGQ_FULL_ERR,                                 
    QOSA_ERROR_MSGQ_RECV_ERR,                                
    QOSA_ERROR_MSGQ_TIMEOUT_ERR,                              
    QOSA_ERROR_MSGQ_INVALID_ERR,                              
    QOSA_ERROR_MSGQ_DELETE_ERR,                               
    QOSA_ERROR_MSGQ_RESET_ERR,                               
    ...
}qosa_errcode_os_e;

成员	说明
QOSA_ERROR_OK	函数执行成功
QOSA_ERROR_MSGQ_CREATE_ERR	创建失败
QOSA_ERROR_MSGQ_FULL_ERR	消息队列已满，无法继续写入消息
QOSA_ERROR_MSGQ_RECV_ERR	接收消息失败
QOSA_ERROR_MSGQ_TIMEOUT_ERR	操作等待超时
QOSA_ERROR_MSGQ_INVALID_ERR	参数无效
QOSA_ERROR_MSGQ_DELETE_ERR	删除失败
QOSA_ERROR_MSGQ_RESET_ERR	重置失败

应用逻辑流程图¶

示例代码¶

完整示例代码请查看 https://github.com/UniRTOS/UniRTOS-Doc-Examples/blob/main/system/sync_comm/queue/messque_demo.c 。

消息队列¶

功能概述¶

消息队列API¶

头文件¶

函数概览¶

函数详解¶

qosa_msgq_create¶

qosa_msgq_delete¶

qosa_msgq_release¶

qosa_msgq_wait¶

qosa_msgq_get_cnt¶

枚举定义¶

qosa_errcode_os_e¶

应用逻辑流程图¶

示例代码¶

目录

本页