消息队列的协作图:

结构体
struct	xwmq_msg
	消息队列的消息更多...

struct	xwmq
	消息队列对象更多...

struct	xwmq_d
	消息队列对象描述符更多...

函数
xwer_t	xwmq_init (struct xwmq mq, struct xwmq_msg txq, xwsz_t num)
	XWMQ API：静态方式初始化消息队列

xwer_t	xwmq_fini (struct xwmq *mq)
	XWMQ API：销毁静态方式初始化的消息队列对象

xwer_t	xwmq_grab (struct xwmq *mq)
	XWMQ API：增加消息队列对象的引用计数

xwer_t	xwmq_put (struct xwmq *mq)
	XWMQ API：减少消息队列对象的引用计数

xwsq_t	xwmq_get_tik (struct xwmq *mq)
	XWMQ API：获取消息队列对象的标签

static xwmq_d	xwmq_get_d (struct xwmq *mq)
	XWMQ API：获取消息队列对象描述符

xwer_t	xwmq_acquire (xwmq_d mqd)
	XWMQ API：检查消息队列对象的标签并增加引用计数

xwer_t	xwmq_release (xwmq_d mqd)
	XWMQ API：检查消息队列对象的标签并减少引用计数

xwer_t	xwmq_eq (struct xwmq mq, xwsq_t topic, void data)
	XWMQ API：等待消息槽，成功后将消息发送到消息队列的尾端（入队）

xwer_t	xwmq_eq_to (struct xwmq mq, xwsq_t topic, void data, xwtm_t to)
	XWMQ API：限时等待消息槽，成功后将消息发送到消息队列的尾端（入队）

xwer_t	xwmq_eq_unintr (struct xwmq mq, xwsq_t topic, void data)
	XWMQ API：等待消息槽，且等待不可被中断，成功后将消息发送到消息队列的尾端（入队）

xwer_t	xwmq_tryeq (struct xwmq mq, xwsq_t topic, void data)
	XWMQ API：尝试获取消息槽，成功后将消息发送到消息队列的尾端（入队）

xwer_t	xwmq_jq (struct xwmq mq, xwsq_t topic, void data)
	XWMQ API：等待消息槽，成功后将消息发送到消息队列的首端（插队）

xwer_t	xwmq_jq_to (struct xwmq mq, xwsq_t topic, void data, xwtm_t to)
	XWMQ API：限时等待消息槽，成功后将消息发送到消息队列的首端（插队）

xwer_t	xwmq_jq_unintr (struct xwmq mq, xwsq_t topic, void data)
	XWMQ API：等待消息槽，且等待不可被中断，成功后将消息发送到消息队列的首端（插队）

xwer_t	xwmq_tryjq (struct xwmq mq, xwsq_t topic, void data)
	XWMQ API：尝试获取消息槽，成功后将消息发送到消息队列的首端（插队）

xwer_t	xwmq_dq (struct xwmq mq, xwsq_t topic, void **databuf)
	XWMQ API: 等待从消息队列首端接收一条消息

xwer_t	xwmq_dq_to (struct xwmq mq, xwsq_t topic, void **databuf, xwtm_t to)
	XWMQ API: 限时等待从消息队列首端接收一条消息

xwer_t	xwmq_dq_unintr (struct xwmq mq, xwsq_t topic, void **databuf)
	XWMQ API: 等待从消息队列首端接收一条消息，且等待不可被中断

xwer_t	xwmq_trydq (struct xwmq mq, xwsq_t topic, void **databuf)
	XWMQ API: 尝试从消息队列首端接收一条消息

xwer_t	xwmq_rq (struct xwmq mq, xwsq_t topic, void **databuf)
	XWMQ API: 等待从消息队列尾端接收一条消息

xwer_t	xwmq_rq_to (struct xwmq mq, xwsq_t topic, void **databuf, xwtm_t to)
	XWMQ API: 限时等待从消息队列尾端接收一条消息

xwer_t	xwmq_rq_unintr (struct xwmq mq, xwsq_t topic, void **databuf)
	XWMQ API: 等待从消息队列尾端接收一条消息，且等待不可被中断

xwer_t	xwmq_tryrq (struct xwmq mq, xwsq_t topic, void **databuf)
	XWMQ API: 尝试从消息队列尾端接收一条消息

详细描述

技术参考手册：消息队列

消息队列的静态初始化、销毁

xwmq_init() ：初始化
xwmq_fini() ：销毁

消息队列的动态创建、删除

XWOS并未提供基于动态内存管理的创建与删除CAPI。

发送消息

入队
- xwmq_eq() ：等待消息槽，只能在线程上下文使用
- xwmq_eq_to() ：限时等待消息槽，只能在线程上下文使用
- xwmq_eq_unintr() ：不可中断地等待消息槽，只能在线程上下文使用
- xwmq_tryeq() ：尝试获取消息槽，可在任意上下文使用
插队
- xwmq_jq() ：等待消息槽，只能在线程上下文使用
- xwmq_jq_to() ：限时等待消息槽，只能在线程上下文使用
- xwmq_jq_unintr() ：不可中断地等待消息槽，只能在线程上下文使用
- xwmq_tryjq() ：尝试获取消息槽，可在任意上下文使用

接收消息

首端离队
- xwmq_dq() ：等待消息，只能在线程上下文使用
- xwmq_dq_to() ：限时等待消息，只能在线程上下文使用
- xwmq_dq_unintr() ：不可中断地等待消息，只能在线程上下文使用
- xwmq_trydq() ：尝试获取消息，可在任意上下文使用
尾端离队
- xwmq_rq() ：等待消息，只能在线程上下文使用
- xwmq_rq_to() ：限时等待消息，只能在线程上下文使用
- xwmq_rq_unintr() ：不可中断地等待消息，只能在线程上下文使用
- xwmq_tryrq() ：尝试获取消息，可在任意上下文使用

消息队列对象的生命周期管理

通过 对象指针 管理生命周期：
- xwmq_grab() ：增加引用计数
- xwmq_put() ：减少引用计数
通过 对象描述符 管理生命周期：
- xwmq_acquire() ：增加引用计数
- xwmq_release() ：减少引用计数

对象描述符和对象标签

已知消息队列对象的指针的情况下，可以通过 xwmq_get_d() 获取 xwmq_d ，或可以通过 xwmq_get_tik() 获取对象标签。

函数说明

◆ xwmq_acquire()

xwer_t xwmq_acquire ( xwmq_d mqd )

XWMQ API：检查消息队列对象的标签并增加引用计数

参数

[in] mqd 消息队列对象描述符

返回: 错误码

返回值

XWOK	没有错误
-ENILOBJD	空的对象描述符
-EOBJDEAD	对象无效
-EACCES	对象标签检查失败

注解

上下文：任意

在文件 xwmq.c 第 59 行定义.

{
        return xwos_object_acquire(&mqd.mq->xwobj, mqd.tik);
}

函数调用图:

◆ xwmq_dq()

xwer_t xwmq_dq	(	struct xwmq *	mq,
		xwsq_t *	topic,
		void **	databuf
	)

XWMQ API: 等待从消息队列首端接收一条消息

参数

[in]	mq	消息队列对象的指针
[out]	:topic	指向缓冲区的指针，通过此缓冲区返回接收消息的标题
[out]	:databuf	指向缓冲区的指针，通过此缓冲区返回接收消息的数据

返回: 错误码

返回值

XWOK	没有错误
-EFAULT	空指针
-EINTR	等待被中断
-ENOTTHDCTX	不在线程上下文中
-EDISIRQ	中断被关闭
-EDISPMPT	抢占被关闭
-EDISBH	中断底半部被关闭

注解

上下文：线程

若接收队列中没有消息，就阻塞接收线程，直到有新的消息或被中断。

接收消息后，会释放消息槽。若有发送线程正在等待消息槽，将唤醒发送线程。

如果等待被中断，此CAPI将返回 -EINTR 。

在文件 xwmq.c 第 388 行定义.

{
        return xwmq_dq_to(mq, topic, databuf, XWTM_MAX);
}

函数调用图:

◆ xwmq_dq_to()

xwer_t xwmq_dq_to	(	struct xwmq *	mq,
		xwsq_t *	topic,
		void **	databuf,
		xwtm_t	to
	)

XWMQ API: 限时等待从消息队列首端接收一条消息

参数

[in]	mq	消息队列对象的指针
[out]	:topic	指向缓冲区的指针，通过此缓冲区返回接收消息的标题
[out]	:databuf	指向缓冲区的指针，通过此缓冲区返回接收消息的数据
[in]	to	期望唤醒的时间点

返回: 错误码

返回值

XWOK	没有错误
-EFAULT	空指针
-EINTR	等待被中断
-ETIMEDOUT	超时
-ENOTTHDCTX	不在线程上下文中
-EDISIRQ	中断被关闭
-EDISPMPT	抢占被关闭
-EDISBH	中断底半部被关闭

注解

上下文：线程

若接收队列中没有消息，就阻塞接收线程，直到新的消息或被中断或超时。
接收消息后，会释放消息槽。若有发送线程正在等待消息槽，将唤醒发送线程。
如果等待被中断，此CAPI将返回 -EINTR 。
to 表示等待超时的时间点：
- to 通常是未来的时间，即 当前系统时间 + delta ，可以使用 xwtm_ft(delta) 表示；
- 如果 to 是过去的时间点，将直接返回 -ETIMEDOUT 。

<No error

在文件 xwmq.c 第 394 行定义.

{
        xwer_t rc;
        struct xwmq_msg * msg;
 
        XWOS_VALIDATE((mq), "nullptr", -EFAULT);
        XWOS_VALIDATE((topic), "nullptr", -EFAULT);
        XWOS_VALIDATE((databuf), "nullptr", -EFAULT);
 
        rc = xwos_sem_wait_to(&mq->rxqsem, to);
        if (rc < 0) {
                goto err_sem_wait_to;
        }
        msg = xwmq_choose_head(mq);
        *databuf = msg->data;
        if (NULL != topic) {
                *topic = msg->topic;
        }
        xwmq_msg_put(mq, msg);
        xwos_sem_post(&mq->txqsem);
        return XWOK;
 
err_sem_wait_to:
        return rc;
}

函数调用图:

这是这个函数的调用关系图:

◆ xwmq_dq_unintr()

xwer_t xwmq_dq_unintr	(	struct xwmq *	mq,
		xwsq_t *	topic,
		void **	databuf
	)

XWMQ API: 等待从消息队列首端接收一条消息，且等待不可被中断

参数

[in]	mq	消息队列对象的指针
[out]	:topic	指向缓冲区的指针，通过此缓冲区返回接收消息的标题
[out]	:databuf	指向缓冲区的指针，通过此缓冲区返回接收消息的数据

返回: 错误码

返回值

XWOK	没有错误
-EFAULT	空指针
-ENOTTHDCTX	不在线程上下文中
-EDISIRQ	中断被关闭
-EDISPMPT	抢占被关闭
-EDISBH	中断底半部被关闭

注解

上下文：线程

若接收队列中没有消息，就阻塞接收线程，直到有新的消息。并且接收线程的等待不可被中断。

接收消息后，会释放消息槽。若有发送线程正在等待消息槽，将唤醒发送线程。

<No error

在文件 xwmq.c 第 421 行定义.

{
        xwer_t rc;
        struct xwmq_msg * msg;
 
        XWOS_VALIDATE((mq), "nullptr", -EFAULT);
        XWOS_VALIDATE((topic), "nullptr", -EFAULT);
        XWOS_VALIDATE((databuf), "nullptr", -EFAULT);
 
        rc = xwos_sem_wait_unintr(&mq->rxqsem);
        if (rc < 0) {
                goto err_sem_wait_unintr;
        }
        msg = xwmq_choose_head(mq);
        *databuf = msg->data;
        if (NULL != topic) {
                *topic = msg->topic;
        }
        xwmq_msg_put(mq, msg);
        xwos_sem_post(&mq->txqsem);
        return XWOK;
 
err_sem_wait_unintr:
        return rc;
}

函数调用图:

◆ xwmq_eq()

xwer_t xwmq_eq	(	struct xwmq *	mq,
		xwsq_t	topic,
		void *	data
	)

XWMQ API：等待消息槽，成功后将消息发送到消息队列的尾端（入队）

参数

[in]	mq	消息队列对象的指针
[in]	topic	消息的标题
[in]	data	消息的数据

返回: 错误码

返回值

XWOK	没有错误
-EFAULT	空指针
-EINTR	等待被中断
-ENOTTHDCTX	不在线程上下文中
-EDISIRQ	中断被关闭
-EDISPMPT	抢占被关闭
-EDISBH	中断底半部被关闭

注解

上下文：线程

若消息槽队列中没有空闲的消息槽，就阻塞发送线程，直到有空闲的消息槽或被中断。

如果等待被中断，此CAPI将返回 -EINTR 。

在文件 xwmq.c 第 176 行定义.

{
        return xwmq_eq_to(mq, topic, data, XWTM_MAX);
}

函数调用图:

◆ xwmq_eq_to()

xwer_t xwmq_eq_to	(	struct xwmq *	mq,
		xwsq_t	topic,
		void *	data,
		xwtm_t	to
	)

XWMQ API：限时等待消息槽，成功后将消息发送到消息队列的尾端（入队）

参数

[in]	mq	消息队列对象的指针
[in]	topic	消息的标题
[in]	data	消息的数据
[in]	to	期望唤醒的时间点

返回: 错误码

返回值

XWOK	没有错误
-EFAULT	空指针
-EINTR	等待被中断
-ETIMEDOUT	超时
-ENOTTHDCTX	不在线程上下文中
-EDISIRQ	中断被关闭
-EDISPMPT	抢占被关闭
-EDISBH	中断底半部被关闭

注解

上下文：线程

若消息槽队列中没有空闲的消息槽，就阻塞发送线程，直到有空闲的消息槽或被中断或超时。
如果等待被中断，此CAPI将返回 -EINTR 。
to 表示等待超时的时间点：
- to 通常是未来的时间，即 当前系统时间 + delta ，可以使用 xwtm_ft(delta) 表示；
- 如果 to 是过去的时间点，将直接返回 -ETIMEDOUT 。

<No error

在文件 xwmq.c 第 182 行定义.

{
        xwer_t rc;
        xwreg_t cpuirq;
        struct xwmq_msg * msg;
 
        XWOS_VALIDATE((mq), "nullptr", -EFAULT);
        XWOS_VALIDATE((data), "nullptr", -EFAULT);
 
        rc = xwos_sem_wait_to(&mq->txqsem, to);
        if (rc < 0) {
                goto err_sem_wait_to;
        }
        msg = xwmq_msg_get(mq);
        msg->topic = topic;
        msg->data = data;
        xwos_splk_lock_cpuirqsv(&mq->rxqlock, &cpuirq);
        xwlib_bclst_add_tail(&mq->rxq, &msg->node);
        xwos_splk_unlock_cpuirqrs(&mq->rxqlock, cpuirq);
        xwos_sem_post(&mq->rxqsem);
        return XWOK;
 
err_sem_wait_to:
        return rc;
}

函数调用图:

这是这个函数的调用关系图:

◆ xwmq_eq_unintr()

xwer_t xwmq_eq_unintr	(	struct xwmq *	mq,
		xwsq_t	topic,
		void *	data
	)

XWMQ API：等待消息槽，且等待不可被中断，成功后将消息发送到消息队列的尾端（入队）

参数

[in]	mq	消息队列对象的指针
[in]	topic	消息的标题
[in]	data	消息的数据

返回: 错误码

返回值

XWOK	没有错误
-EFAULT	空指针
-ENOTTHDCTX	不在线程上下文中
-EDISIRQ	中断被关闭
-EDISPMPT	抢占被关闭
-EDISBH	中断底半部被关闭

注解

上下文：线程

若消息槽队列中没有空闲的消息槽，就阻塞发送线程，直到有空闲的消息槽。并且发送线程的等待不可被中断。

<No error

在文件 xwmq.c 第 209 行定义.

{
        xwer_t rc;
        xwreg_t cpuirq;
        struct xwmq_msg * msg;
 
        XWOS_VALIDATE((mq), "nullptr", -EFAULT);
        XWOS_VALIDATE((data), "nullptr", -EFAULT);
 
        rc = xwos_sem_wait_unintr(&mq->txqsem);
        if (rc < 0) {
                goto err_sem_wait_unintr;
        }
        msg = xwmq_msg_get(mq);
        msg->topic = topic;
        msg->data = data;
        xwos_splk_lock_cpuirqsv(&mq->rxqlock, &cpuirq);
        xwlib_bclst_add_tail(&mq->rxq, &msg->node);
        xwos_splk_unlock_cpuirqrs(&mq->rxqlock, cpuirq);
        xwos_sem_post(&mq->rxqsem);
        return XWOK;
 
err_sem_wait_unintr:
        return rc;
}

函数调用图:

◆ xwmq_fini()

xwer_t xwmq_fini ( struct xwmq * mq )

XWMQ API：销毁静态方式初始化的消息队列对象

参数

[in] mq 消息队列对象的指针

返回: 错误码

返回值

XWOK	没有错误
-EFAULT	空指针

注解

上下文：任意

在文件 xwmq.c 第 131 行定义.

{
        XWOS_VALIDATE((mq), "nullptr", -EFAULT);
        return xwmq_put(mq);
}

函数调用图:

◆ xwmq_get_d()

static xwmq_d xwmq_get_d ( struct xwmq * mq )

inlinestatic

XWMQ API：获取消息队列对象描述符

参数

[in] mq 消息队列对象的指针

返回: 消息队列对象描述符

注解

上下文：任意

在文件 mif.h 第 180 行定义.

{
        xwmq_d mqd;
 
        mqd.mq = mq;
        mqd.tik = xwmq_get_tik(mq);
        return mqd;
}

函数调用图:

◆ xwmq_get_tik()

xwsq_t xwmq_get_tik ( struct xwmq * mq )

XWMQ API：获取消息队列对象的标签

参数

[in] mq 消息队列对象的指针

返回: 消息队列对象的标签

注解

上下文：任意

在文件 xwmq.c 第 46 行定义.

{
        xwsq_t tik;
 
        if (NULL != mq) {
                tik = mq->xwobj.tik;
        } else {
                tik = 0;
        }
        return tik;
}

这是这个函数的调用关系图:

◆ xwmq_grab()

xwer_t xwmq_grab ( struct xwmq * mq )

XWMQ API：增加消息队列对象的引用计数

参数

[in] mq 消息队列控制块对象指针

返回: 错误码

返回值

XWOK	没有错误
-EFAULT	空指针
-EOBJDEAD	对象无效

注解

上下文：任意

在文件 xwmq.c 第 71 行定义.

{
        XWOS_VALIDATE((mq), "nullptr", -EFAULT);
 
        return xwos_object_grab(&mq->xwobj);
}

函数调用图:

◆ xwmq_init()

xwer_t xwmq_init	(	struct xwmq *	mq,
		struct xwmq_msg *	txq,
		xwsz_t	num
	)

XWMQ API：静态方式初始化消息队列

参数

[in]	mq	消息队列对象的指针
[in]	txq	消息槽内存池
[in]	num	消息槽数量

返回: 错误码

返回值

XWOK	没有错误
-EFAULT	空指针
-EINVAL	无效参数

注解

上下文：任意

在文件 xwmq.c 第 121 行定义.

{
        XWOS_VALIDATE((mq), "nullptr", -EFAULT);
        XWOS_VALIDATE((txq), "nullptr", -EFAULT);
 
        xwmq_construct(mq);
        return xwmq_activate(mq, txq, num, xwmq_gc);
}

函数调用图:

◆ xwmq_jq()

xwer_t xwmq_jq	(	struct xwmq *	mq,
		xwsq_t	topic,
		void *	data
	)

XWMQ API：等待消息槽，成功后将消息发送到消息队列的首端（插队）

参数

[in]	mq	消息队列对象的指针
[in]	topic	消息的标题
[in]	data	消息的数据

返回: 错误码

返回值

XWOK	没有错误
-EFAULT	空指针
-EINTR	等待被中断
-ENOTTHDCTX	不在线程上下文中
-EDISIRQ	中断被关闭
-EDISPMPT	抢占被关闭
-EDISBH	中断底半部被关闭

注解

上下文：线程

若消息槽队列中没有空闲的消息槽，就阻塞发送线程，直到有空闲的消息槽或被中断。

如果等待被中断，此CAPI将返回 -EINTR 。

在文件 xwmq.c 第 263 行定义.

{
        return xwmq_jq_to(mq, topic, data, XWTM_MAX);
}

函数调用图:

◆ xwmq_jq_to()

xwer_t xwmq_jq_to	(	struct xwmq *	mq,
		xwsq_t	topic,
		void *	data,
		xwtm_t	to
	)

XWMQ API：限时等待消息槽，成功后将消息发送到消息队列的首端（插队）

参数

[in]	mq	消息队列对象的指针
[in]	topic	消息的标题
[in]	data	消息的数据
[in]	to	期望唤醒的时间点

返回: 错误码

返回值

XWOK	没有错误
-EFAULT	空指针
-EINTR	等待被中断
-ETIMEDOUT	超时
-ENOTTHDCTX	不在线程上下文中
-EDISIRQ	中断被关闭
-EDISPMPT	抢占被关闭
-EDISBH	中断底半部被关闭

注解

上下文：线程

若消息槽队列中没有空闲的消息槽，就阻塞发送线程，直到有空闲的消息槽或被中断或超时。
如果等待被中断，此CAPI将返回 -EINTR 。
to 表示等待超时的时间点：
- to 通常是未来的时间，即 当前系统时间 + delta ，可以使用 xwtm_ft(delta) 表示；
- 如果 to 是过去的时间点，将直接返回 -ETIMEDOUT 。

<No error

在文件 xwmq.c 第 269 行定义.

{
        xwer_t rc;
        xwreg_t cpuirq;
        struct xwmq_msg * msg;
 
        XWOS_VALIDATE((mq), "nullptr", -EFAULT);
        XWOS_VALIDATE((data), "nullptr", -EFAULT);
 
        rc = xwos_sem_wait_to(&mq->txqsem, to);
        if (rc < 0) {
                goto err_sem_wait_to;
        }
        msg = xwmq_msg_get(mq);
        msg->topic = topic;
        msg->data = data;
        xwos_splk_lock_cpuirqsv(&mq->rxqlock, &cpuirq);
        xwlib_bclst_add_head(&mq->rxq, &msg->node);
        xwos_splk_unlock_cpuirqrs(&mq->rxqlock, cpuirq);
        xwos_sem_post(&mq->rxqsem);
        return XWOK;
 
err_sem_wait_to:
        return rc;
}

函数调用图:

这是这个函数的调用关系图:

◆ xwmq_jq_unintr()

xwer_t xwmq_jq_unintr	(	struct xwmq *	mq,
		xwsq_t	topic,
		void *	data
	)

XWMQ API：等待消息槽，且等待不可被中断，成功后将消息发送到消息队列的首端（插队）

参数

[in]	mq	消息队列对象的指针
[in]	topic	消息的标题
[in]	data	消息的数据

返回: 错误码

返回值

XWOK	没有错误
-EFAULT	空指针
-ENOTTHDCTX	不在线程上下文中
-EDISIRQ	中断被关闭
-EDISPMPT	抢占被关闭
-EDISBH	中断底半部被关闭

注解

上下文：线程

若消息槽队列中没有空闲的消息槽，就阻塞发送线程，直到有空闲的消息槽。并且发送线程的等待不可被中断。

<No error

在文件 xwmq.c 第 296 行定义.

{
        xwer_t rc;
        xwreg_t cpuirq;
        struct xwmq_msg * msg;
 
        XWOS_VALIDATE((mq), "nullptr", -EFAULT);
        XWOS_VALIDATE((data), "nullptr", -EFAULT);
 
        rc = xwos_sem_wait_unintr(&mq->txqsem);
        if (rc < 0) {
                goto err_sem_wait_unintr;
        }
        msg = xwmq_msg_get(mq);
        msg->topic = topic;
        msg->data = data;
        xwos_splk_lock_cpuirqsv(&mq->rxqlock, &cpuirq);
        xwlib_bclst_add_head(&mq->rxq, &msg->node);
        xwos_splk_unlock_cpuirqrs(&mq->rxqlock, cpuirq);
        xwos_sem_post(&mq->rxqsem);
        return XWOK;
 
err_sem_wait_unintr:
        return rc;
}

函数调用图:

◆ xwmq_put()

xwer_t xwmq_put ( struct xwmq * mq )

XWMQ API：减少消息队列对象的引用计数

参数

[in] mq 消息队列控制块对象指针

返回: 错误码

返回值

XWOK	没有错误
-EOBJDEAD	对象无效

注解

上下文：任意

在文件 xwmq.c 第 79 行定义.

{
        XWOS_VALIDATE((mq), "nullptr", -EFAULT);
 
        return xwos_object_put(&mq->xwobj);
}

函数调用图:

这是这个函数的调用关系图:

◆ xwmq_release()

xwer_t xwmq_release ( xwmq_d mqd )

XWMQ API：检查消息队列对象的标签并减少引用计数

参数

[in] mqd 消息队列对象描述符

返回: 错误码

返回值

XWOK	没有错误
-ENILOBJD	空的对象描述符
-EOBJDEAD	对象无效
-EACCES	对象标签检查失败

注解

上下文：任意

在文件 xwmq.c 第 65 行定义.

{
        return xwos_object_release(&mqd.mq->xwobj, mqd.tik);
}

函数调用图:

◆ xwmq_rq()

xwer_t xwmq_rq	(	struct xwmq *	mq,
		xwsq_t *	topic,
		void **	databuf
	)

XWMQ API: 等待从消息队列尾端接收一条消息

参数

[in]	mq	消息队列对象的指针
[out]	:topic	指向缓冲区的指针，通过此缓冲区返回接收消息的标题
[out]	:databuf	指向缓冲区的指针，通过此缓冲区返回接收消息的数据

返回: 错误码

返回值

XWOK	没有错误
-EFAULT	空指针
-EINTR	等待被中断
-ENOTTHDCTX	不在线程上下文中
-EDISIRQ	中断被关闭
-EDISPMPT	抢占被关闭
-EDISBH	中断底半部被关闭

注解

上下文：线程

若接收队列中没有消息，就阻塞接收线程，直到有新的消息或被中断。

接收消息后，会释放消息槽。若有发送线程正在等待消息槽，将唤醒发送线程。

如果等待被中断，此CAPI将返回 -EINTR 。

在文件 xwmq.c 第 475 行定义.

{
        return xwmq_rq_to(mq, topic, databuf, XWTM_MAX);
}

函数调用图:

◆ xwmq_rq_to()

xwer_t xwmq_rq_to	(	struct xwmq *	mq,
		xwsq_t *	topic,
		void **	databuf,
		xwtm_t	to
	)

XWMQ API: 限时等待从消息队列尾端接收一条消息

参数

[in]	mq	消息队列对象的指针
[out]	:topic	指向缓冲区的指针，通过此缓冲区返回接收消息的标题
[out]	:databuf	指向缓冲区的指针，通过此缓冲区返回接收消息的数据
[in]	to	期望唤醒的时间点

返回: 错误码

返回值

XWOK	没有错误
-EFAULT	空指针
-EINTR	等待被中断
-ETIMEDOUT	超时
-ENOTTHDCTX	不在线程上下文中
-EDISIRQ	中断被关闭
-EDISPMPT	抢占被关闭
-EDISBH	中断底半部被关闭

注解

上下文：线程

若接收队列中没有消息，就阻塞接收线程，直到新的消息或被中断或超时。
接收消息后，会释放消息槽。若有发送线程正在等待消息槽，将唤醒发送线程。
如果等待被中断，此CAPI将返回 -EINTR 。
to 表示等待超时的时间点：
- to 通常是未来的时间，即 当前系统时间 + delta ，可以使用 xwtm_ft(delta) 表示；
- 如果 to 是过去的时间点，将直接返回 -ETIMEDOUT 。

<No error

在文件 xwmq.c 第 481 行定义.

{
        xwer_t rc;
        struct xwmq_msg * msg;
 
        XWOS_VALIDATE((mq), "nullptr", -EFAULT);
        XWOS_VALIDATE((topic), "nullptr", -EFAULT);
        XWOS_VALIDATE((databuf), "nullptr", -EFAULT);
 
        rc = xwos_sem_wait_to(&mq->rxqsem, to);
        if (rc < 0) {
                goto err_sem_wait_to;
        }
        msg = xwmq_choose_tail(mq);
        *databuf = msg->data;
        if (NULL != topic) {
                *topic = msg->topic;
        }
        xwmq_msg_put(mq, msg);
        xwos_sem_post(&mq->txqsem);
        return XWOK;
 
err_sem_wait_to:
        return rc;
}

函数调用图:

这是这个函数的调用关系图:

◆ xwmq_rq_unintr()

xwer_t xwmq_rq_unintr	(	struct xwmq *	mq,
		xwsq_t *	topic,
		void **	databuf
	)

XWMQ API: 等待从消息队列尾端接收一条消息，且等待不可被中断

参数

[in]	mq	消息队列对象的指针
[out]	:topic	指向缓冲区的指针，通过此缓冲区返回接收消息的标题
[out]	:databuf	指向缓冲区的指针，通过此缓冲区返回接收消息的数据

返回: 错误码

返回值

XWOK	没有错误
-EFAULT	空指针
-ENOTTHDCTX	不在线程上下文中
-EDISIRQ	中断被关闭
-EDISPMPT	抢占被关闭
-EDISBH	中断底半部被关闭

注解

上下文：线程

若接收队列中没有消息，就阻塞接收线程，直到有新的消息。并且接收线程的等待不可被中断。

接收消息后，会释放消息槽。若有发送线程正在等待消息槽，将唤醒发送线程。

<No error

在文件 xwmq.c 第 508 行定义.

{
        xwer_t rc;
        struct xwmq_msg * msg;
 
        XWOS_VALIDATE((mq), "nullptr", -EFAULT);
        XWOS_VALIDATE((topic), "nullptr", -EFAULT);
        XWOS_VALIDATE((databuf), "nullptr", -EFAULT);
 
        rc = xwos_sem_wait_unintr(&mq->rxqsem);
        if (rc < 0) {
                goto err_sem_wait_unintr;
        }
        msg = xwmq_choose_tail(mq);
        *databuf = msg->data;
        if (NULL != topic) {
                *topic = msg->topic;
        }
        xwmq_msg_put(mq, msg);
        xwos_sem_post(&mq->txqsem);
        return XWOK;
 
err_sem_wait_unintr:
        return rc;
}

函数调用图:

◆ xwmq_trydq()

xwer_t xwmq_trydq	(	struct xwmq *	mq,
		xwsq_t *	topic,
		void **	databuf
	)

XWMQ API: 尝试从消息队列首端接收一条消息

参数

[in]	mq	消息队列对象的指针
[out]	:topic	指向缓冲区的指针，通过此缓冲区返回接收消息的标题
[out]	:databuf	指向缓冲区的指针，通过此缓冲区返回接收消息的数据

返回: 错误码

返回值

XWOK	没有错误
-EFAULT	空指针
-ENODATA	接收队列为空

注解

上下文：任意

若接收队列中没有新的消息，就立即返回 -ENODATA ，此CAPI可在中断中使用。

接收消息后，会释放消息槽。若有发送线程正在等待消息槽，将唤醒发送线程。

<No error

在文件 xwmq.c 第 448 行定义.

{
        xwer_t rc;
        struct xwmq_msg * msg;
 
        XWOS_VALIDATE((mq), "nullptr", -EFAULT);
        XWOS_VALIDATE((topic), "nullptr", -EFAULT);
        XWOS_VALIDATE((databuf), "nullptr", -EFAULT);
 
        rc = xwos_sem_trywait(&mq->rxqsem);
        if (rc < 0) {
                goto err_sem_trywait;
        }
        msg = xwmq_choose_head(mq);
        *databuf = msg->data;
        if (NULL != topic) {
                *topic = msg->topic;
        }
        xwmq_msg_put(mq, msg);
        xwos_sem_post(&mq->txqsem);
        return XWOK;
 
err_sem_trywait:
        return rc;
}

函数调用图:

◆ xwmq_tryeq()

xwer_t xwmq_tryeq	(	struct xwmq *	mq,
		xwsq_t	topic,
		void *	data
	)

XWMQ API：尝试获取消息槽，成功后将消息发送到消息队列的尾端（入队）

参数

[in]	mq	消息队列对象的指针
[in]	topic	消息的标题
[in]	data	消息的数据

返回: 错误码

返回值

XWOK	没有错误
-EFAULT	空指针
-ENODATA	接收队列为空

注解

上下文：任意

若消息槽队列中没有空闲的消息槽，就立即返回 -ENODATA，此CAPI可在中断中使用。

<No error

在文件 xwmq.c 第 236 行定义.

{
        xwer_t rc;
        xwreg_t cpuirq;
        struct xwmq_msg * msg;
 
        XWOS_VALIDATE((mq), "nullptr", -EFAULT);
        XWOS_VALIDATE((data), "nullptr", -EFAULT);
 
        rc = xwos_sem_trywait(&mq->txqsem);
        if (rc < 0) {
                goto err_sem_trywait;
        }
        msg = xwmq_msg_get(mq);
        msg->topic = topic;
        msg->data = data;
        xwos_splk_lock_cpuirqsv(&mq->rxqlock, &cpuirq);
        xwlib_bclst_add_tail(&mq->rxq, &msg->node);
        xwos_splk_unlock_cpuirqrs(&mq->rxqlock, cpuirq);
        xwos_sem_post(&mq->rxqsem);
        return XWOK;
 
err_sem_trywait:
        return rc;
}

函数调用图:

◆ xwmq_tryjq()

xwer_t xwmq_tryjq	(	struct xwmq *	mq,
		xwsq_t	topic,
		void *	data
	)

XWMQ API：尝试获取消息槽，成功后将消息发送到消息队列的首端（插队）

参数

[in]	mq	消息队列对象的指针
[in]	topic	消息的标题
[in]	data	消息的数据

返回: 错误码

返回值

XWOK	没有错误
-EFAULT	空指针
-ENODATA	接收队列为空

注解

上下文：任意

若消息槽队列中没有空闲的消息槽，就立即返回 -ENODATA，此CAPI可在中断中使用。

<No error

在文件 xwmq.c 第 323 行定义.

{
        xwer_t rc;
        xwreg_t cpuirq;
        struct xwmq_msg * msg;
 
        XWOS_VALIDATE((mq), "nullptr", -EFAULT);
        XWOS_VALIDATE((data), "nullptr", -EFAULT);
 
        rc = xwos_sem_trywait(&mq->txqsem);
        if (rc < 0) {
                goto err_sem_trywait;
        }
        msg = xwmq_msg_get(mq);
        msg->topic = topic;
        msg->data = data;
        xwos_splk_lock_cpuirqsv(&mq->rxqlock, &cpuirq);
        xwlib_bclst_add_head(&mq->rxq, &msg->node);
        xwos_splk_unlock_cpuirqrs(&mq->rxqlock, cpuirq);
        xwos_sem_post(&mq->rxqsem);
        return XWOK;
 
err_sem_trywait:
        return rc;
}

函数调用图:

◆ xwmq_tryrq()

xwer_t xwmq_tryrq	(	struct xwmq *	mq,
		xwsq_t *	topic,
		void **	databuf
	)

XWMQ API: 尝试从消息队列尾端接收一条消息

参数

[in]	mq	消息队列对象的指针
[out]	:topic	指向缓冲区的指针，通过此缓冲区返回接收消息的标题
[out]	:databuf	指向缓冲区的指针，通过此缓冲区返回接收消息的数据

返回: 错误码

返回值

XWOK	没有错误
-EFAULT	空指针
-ENODATA	接收队列为空

注解

上下文：任意

若接收队列中没有新的消息，就立即返回 -ENODATA ，此CAPI可在中断中使用。

接收消息后，会释放消息槽。若有发送线程正在等待消息槽，将唤醒发送线程。

<No error

在文件 xwmq.c 第 535 行定义.

{
        xwer_t rc;
        struct xwmq_msg * msg;
 
        XWOS_VALIDATE((mq), "nullptr", -EFAULT);
        XWOS_VALIDATE((topic), "nullptr", -EFAULT);
        XWOS_VALIDATE((databuf), "nullptr", -EFAULT);
 
        rc = xwos_sem_trywait(&mq->rxqsem);
        if (rc < 0) {
                goto err_sem_trywait;
        }
        msg = xwmq_choose_tail(mq);
        *databuf = msg->data;
        if (NULL != topic) {
                *topic = msg->topic;
        }
        xwmq_msg_put(mq, msg);
        xwos_sem_post(&mq->txqsem);
        return XWOK;
 
err_sem_trywait:
        return rc;
}

函数调用图:

结构体

函数

详细描述

消息队列的静态初始化、销毁

消息队列的动态创建、删除

发送消息

接收消息

消息队列对象的生命周期管理

对象描述符和对象标签

函数说明

◆ xwmq_acquire()

◆ xwmq_dq()

◆ xwmq_dq_to()

◆ xwmq_dq_unintr()

◆ xwmq_eq()

◆ xwmq_eq_to()

◆ xwmq_eq_unintr()

◆ xwmq_fini()

◆ xwmq_get_d()

◆ xwmq_get_tik()

◆ xwmq_grab()

◆ xwmq_init()

◆ xwmq_jq()

◆ xwmq_jq_to()

◆ xwmq_jq_unintr()

◆ xwmq_put()

◆ xwmq_release()

◆ xwmq_rq()

◆ xwmq_rq_to()

◆ xwmq_rq_unintr()

◆ xwmq_trydq()

◆ xwmq_tryeq()

◆ xwmq_tryjq()

◆ xwmq_tryrq()