循环队列的协作图:

模块
	XWCQ C++ Lib

结构体
struct	xwcq
	循环队列对象更多...

struct	xwcq_d
	循环队列对象描述符更多...

宏定义
#define	XWCQ_DEF_MEMPOOL(name, slotsize, slotnum) __xwcc_alignl1cache xwu8_t name[(slotsize) * (slotnum)]
	定义循环队列缓冲区

函数
xwer_t	xwcq_init (struct xwcq cq, xwsz_t slotsize, xwsz_t slotnum, xwu8_t mem)
	XWCQ API：初始化循环队列

xwer_t	xwcq_fini (struct xwcq *cq)
	XWCQ API：销毁循环队列对象

xwsq_t	xwcq_get_tik (struct xwcq *cq)
	XWCQ API：获取循环队列对象的标签

static xwcq_d	xwcq_get_d (struct xwcq *cq)
	XWCQ API：获取循环队列对象描述符

xwer_t	xwcq_acquire (xwcq_d cqd)
	XWCQ API：检查循环队列对象的标签并增加引用计数

xwer_t	xwcq_release (xwcq_d cqd)
	XWCQ API：检查循环队列对象的标签并增加引用计数

xwer_t	xwcq_grab (struct xwcq *cq)
	XWCQ API：增加循环队列对象的引用计数

xwer_t	xwcq_put (struct xwcq *cq)
	XWCQ API：减少循环队列对象的引用计数

xwer_t	xwcq_eq (struct xwcq cq, const xwu8_t data, xwsz_t *size)
	XWCQ API：将数据发送到循环队列的尾端 (入队，EnQueue)

xwer_t	xwcq_jq (struct xwcq cq, const xwu8_t data, xwsz_t *size)
	XWCQ API：将数据发送循环队列的首端 (插队，Jump the Queue)

xwer_t	xwcq_dq (struct xwcq cq, xwu8_t data, xwsz_t *size)
	XWCQ API: 等待从循环队列的首端接收数据 (离队，DeQueue)

xwer_t	xwcq_dq_to (struct xwcq cq, xwu8_t data, xwsz_t *size, xwtm_t to)
	XWCQ API: 限时等待从循环队列的首端接收数据 (离队，DeQueue)

xwer_t	xwcq_dq_unintr (struct xwcq cq, xwu8_t data, xwsz_t *size)
	XWCQ API: 等待从循环队列的首端接收数据 (离队，DeQueue)，并且等待不可被中断

xwer_t	xwcq_trydq (struct xwcq cq, xwu8_t data, xwsz_t *size)
	XWCQ API: 尝试从循环队列的首端接收数据 (离队，DeQueue)

xwer_t	xwcq_rq (struct xwcq cq, xwu8_t data, xwsz_t *size)
	XWCQ API: 等待从循环队列的尾端接收数据 (反向离队，Reversely deQueue)

xwer_t	xwcq_rq_to (struct xwcq cq, xwu8_t data, xwsz_t *size, xwtm_t to)
	XWCQ API: 限时等待从循环队列的尾端接收数据 (反向离队，Reversely deQueue)

xwer_t	xwcq_rq_unintr (struct xwcq cq, xwu8_t data, xwsz_t *size)
	XWCQ API: 等待从循环队列的尾端接收数据 (反向离队，Reversely deQueue)，并且等待不可被中断

xwer_t	xwcq_tryrq (struct xwcq cq, xwu8_t data, xwsz_t *size)
	XWCQ API: 尝试从循环队列的尾端接收数据 (反向离队，Reversely deQueue)

xwer_t	xwcq_pfq (struct xwcq cq, xwu8_t data, xwsz_t *size)
	XWCQ API: 等待从循环队列头端拷贝数据 (Peek at the Front of Queue)

xwer_t	xwcq_pfq_to (struct xwcq cq, xwu8_t data, xwsz_t *size, xwtm_t to)
	XWCQ API: 限时等待从循环队列头端拷贝数据 (Peek at the Front of Queue)

xwer_t	xwcq_pfq_unintr (struct xwcq cq, xwu8_t data, xwsz_t *size)
	XWCQ API: 等待从循环队列头端拷贝数据 (Peek at the Front of Queue)，并且等待不可被中断

xwer_t	xwcq_trypfq (struct xwcq cq, xwu8_t data, xwsz_t *size)
	XWCQ API: 尝试从循环队列头端拷贝数据 (Peek at the Front of Queue)

xwer_t	xwcq_prq (struct xwcq cq, xwu8_t data, xwsz_t *size)
	XWCQ API: 等待从循环队列尾端拷贝数据 (Peek at the Rear of Queue)

xwer_t	xwcq_prq_to (struct xwcq cq, xwu8_t data, xwsz_t *size, xwtm_t to)
	XWCQ API: 限时等待从循环队列尾端拷贝数据 (Peek at the Rear of Queue)

xwer_t	xwcq_prq_unintr (struct xwcq cq, xwu8_t data, xwsz_t *size)
	XWCQ API: 等待从循环队列尾端拷贝数据 (Peek at the Rear of Queue)，并且等待不可被中断

xwer_t	xwcq_tryprq (struct xwcq cq, xwu8_t data, xwsz_t *size)
	XWCQ API: 尝试从循环队列尾端拷贝数据 (Peek at the Rear of Queue)

xwer_t	xwcq_flush (struct xwcq *cq)
	XWCQ API: 清空循环队列

xwer_t	xwcq_get_capacity (struct xwcq cq, xwsz_t capbuf)
	XWCQ API: 获取循环队列的容量

xwer_t	xwcq_get_size (struct xwcq cq, xwsz_t szbuf)
	XWCQ API: 获取循环队列的单个数据槽的大小

xwer_t	xwcq_get_availability (struct xwcq cq, xwsz_t avbbuf)
	XWCQ API: 获取循环队列中有效数据槽的数量

xwer_t	xwcq_bind (struct xwcq cq, struct xwos_sel sel, xwsq_t pos)
	XWOS API：绑定循环队列对象到信号选择器

xwer_t	xwcq_unbind (struct xwcq cq, struct xwos_sel sel)
	XWOS API：从信号选择器上解绑循环队列对象

详细描述

技术参考手册：循环队列

循环队列的静态初始化、销毁

xwcq_init() ：初始化
xwcq_fini() ：销毁

循环队列的动态创建、删除

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

发送消息

xwcq_eq() ：入队，可在任意上下文使用
xwcq_jq() ：插队，可在任意上下文使用

接收消息

首端接收
- xwcq_dq() ：等待消息，只能在线程上下文使用
- xwcq_dq_to() ：限时等待消息，只能在线程上下文使用
- xwcq_dq_unintr() ：不可中断地等待消息，只能在线程上下文使用
- xwcq_trydq() ：尝试获取消息，可在任意上下文使用
尾端离队
- xwcq_rq() ：等待消息，只能在线程上下文使用
- xwcq_rq_to() ：限时等待消息，只能在线程上下文使用
- xwcq_rq_unintr() ：不可中断地等待消息，只能在线程上下文使用
- xwcq_tryrq() ：尝试获取消息，可在任意上下文使用

拷贝消息

首端拷贝
- xwcq_pfq() ：等待消息，只能在线程上下文使用
- xwcq_pfq_to() ：限时等待消息，只能在线程上下文使用
- xwcq_pfq_unintr() ：不可中断地等待消息，只能在线程上下文使用
- xwcq_trypfq() ：尝试获取消息，可在任意上下文使用
尾端拷贝
- xwcq_prq() ：等待消息，只能在线程上下文使用
- xwcq_prq_to() ：限时等待消息，只能在线程上下文使用
- xwcq_prq_unintr() ：不可中断地等待消息，只能在线程上下文使用
- xwcq_tryprq() ：尝试获取消息，可在任意上下文使用

清空循环队列

xwcq_flush() ：将循环队列恢复到初始化状态

获取循环队列容量

xwcq_get_capacity() ：获取循环队列的容量

获取循环队列单个数据槽的大小

xwcq_get_size() ：获取单个数据槽的大小

获取循环队列中有效数据槽的数量

xwcq_get_availability() ：获取循环队列中有效数据槽的数量

循环队列对象的生命周期管理

通过 对象指针 管理生命周期：
- xwcq_grab() ：增加引用计数
- xwcq_put() ：减少引用计数
通过 对象描述符 管理生命周期：
- xwcq_acquire() ：增加引用计数
- xwcq_release() ：减少引用计数

对象描述符和对象标签

已知循环队列对象的指针的情况下，可以通过 xwcq_get_d() 获取 xwcq_d ，或可以通过 xwcq_get_tik() 获取对象标签。

宏定义说明

◆ XWCQ_DEF_MEMPOOL

#define XWCQ_DEF_MEMPOOL	(	name,
		slotsize,
		slotnum
	)	__xwcc_alignl1cache xwu8_t name[(slotsize) * (slotnum)]

定义循环队列缓冲区

参数

[in]	name	变量名称
[in]	slotsize	数据槽的大小
[in]	slotnum	数据槽的个数

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

函数说明

◆ xwcq_acquire()

xwer_t xwcq_acquire ( xwcq_d cqd )

XWCQ API：检查循环队列对象的标签并增加引用计数

参数

[in] cqd 循环队列对象描述符

返回: 错误码

返回值

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

注解

同步/异步：同步
上下文：中断、中断底半部、线程
重入性：可重入

在文件 xwcq.c 第 127 行定义.

{
        return xwos_object_acquire(&cqd.cq->xwobj, cqd.tik);
}

函数调用图:

◆ xwcq_bind()

xwer_t xwcq_bind	(	struct xwcq *	cq,
		struct xwos_sel *	sel,
		xwsq_t	pos
	)

XWOS API：绑定循环队列对象到信号选择器

参数

[in]	cq	循环队列对象的指针
[in]	sel	信号选择器的指针
[in]	pos	循环队列对象对象映射到位图中的位置

返回: 错误码

返回值

XWOK	没有错误
-EFAULT	空指针
-ECHRNG	位置超出范围
-EALREADY	同步对象已经绑定到事件对象
-EBUSY	通道已经被其他同步对象独占

注解

上下文：任意
绑定方式：独占绑定

在文件 xwcq.c 第 675 行定义.

{
        xwer_t rc;
 
        rc = xwcq_grab(cq);
        if (rc < 0) {
                goto err_cq_grab;
        }
        rc = xwos_sem_bind(&cq->sem, sel, pos);
 
err_cq_grab:
        return rc;
}

函数调用图:

◆ xwcq_dq()

xwer_t xwcq_dq	(	struct xwcq *	cq,
		xwu8_t *	data,
		xwsz_t *	size
	)

XWCQ API: 等待从循环队列的首端接收数据 (离队，DeQueue)

参数

[in]	cq	循环队列对象的指针
[out]	data	指向缓冲区的指针，此缓冲区用于接收数据
[in,out]	size	指向缓冲区的指针，此缓冲区： (I) 作为输入时，表示接收缓冲区的大小 (O) 作为输出时，返回实际接收的数据大小

返回: 错误码

返回值

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

注解

上下文：线程

若循环队列中数据为空，调用此CAPI的线程会阻塞等待，直到循环队列中有消息可取出，或等待被中断。
如果等待被中断，此CAPI将返回 -EINTR 。

在文件 xwcq.c 第 217 行定义.

{
        return xwcq_dq_to(cq, buf, size, XWTM_MAX);
}

函数调用图:

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

◆ xwcq_dq_to()

xwer_t xwcq_dq_to	(	struct xwcq *	cq,
		xwu8_t *	data,
		xwsz_t *	size,
		xwtm_t	to
	)

XWCQ API: 限时等待从循环队列的首端接收数据 (离队，DeQueue)

参数

[in]	cq	循环队列对象的指针
[out]	data	指向缓冲区的指针，此缓冲区用于接收数据
[in,out]	size	指向缓冲区的指针，此缓冲区： (I) 作为输入时，表示接收缓冲区的大小 (O) 作为输出时，返回实际接收的数据大小
[in]	to	期望唤醒的时间点

返回: 错误码

返回值

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

注解

上下文：线程

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

<No error

在文件 xwcq.c 第 223 行定义.

{
        xwreg_t cpuirq;
        xwsz_t bufsz;
        xwsz_t cpsz;
        xwer_t rc;
 
        XWOS_VALIDATE(cq, "nullptr", -EFAULT);
        XWOS_VALIDATE(buf, "nullptr", -EFAULT);
        XWOS_VALIDATE(size, "nullptr", -EFAULT);
 
        bufsz = *size;
        cpsz = (bufsz > cq->slotsize) ? cq->slotsize : bufsz;
        rc = xwos_sem_wait_to(&cq->sem, to);
        if (rc < 0) {
                goto err_sem_wait_to;
        }
        xwos_splk_lock_cpuirqsv(&cq->lock, &cpuirq);
        // cppcheck-suppress [misra-c2012-17.7]
        memcpy(buf, &cq->q[(xwsz_t)cq->front * cq->slotsize], cpsz);
        cq->front++;
        if (cq->front >= (xwssz_t)cq->slotnum) {
                cq->front = 0;
        }
        xwos_splk_unlock_cpuirqrs(&cq->lock, cpuirq);
        *size = cpsz;
        return XWOK;
 
err_sem_wait_to:
        return rc;
}

函数调用图:

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

◆ xwcq_dq_unintr()

xwer_t xwcq_dq_unintr	(	struct xwcq *	cq,
		xwu8_t *	data,
		xwsz_t *	size
	)

XWCQ API: 等待从循环队列的首端接收数据 (离队，DeQueue)，并且等待不可被中断

参数

[in]	cq	循环队列对象的指针
[out]	data	指向缓冲区的指针，此缓冲区用于接收数据
[in,out]	size	指向缓冲区的指针，此缓冲区： (I) 作为输入时，表示接收缓冲区的大小 (O) 作为输出时，返回实际接收的数据大小

返回: 错误码

返回值

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

注解

上下文：线程

若循环队列中数据为空，调用此CAPI的线程会阻塞等待，直到循环队列中有消息可取出。
调用此CAPI的线程的阻塞等待不可被中断。

<No error

在文件 xwcq.c 第 256 行定义.

{
        xwsz_t bufsz;
        xwsz_t cpsz;
        xwreg_t cpuirq;
        xwer_t rc;
 
        XWOS_VALIDATE(cq, "nullptr", -EFAULT);
        XWOS_VALIDATE(buf, "nullptr", -EFAULT);
        XWOS_VALIDATE(size, "nullptr", -EFAULT);
 
        bufsz = *size;
        cpsz = (bufsz > cq->slotsize) ? cq->slotsize : bufsz;
        rc = xwos_sem_wait_unintr(&cq->sem);
        if (rc < 0) {
                goto err_sem_wait_unintr;
        }
        xwos_splk_lock_cpuirqsv(&cq->lock, &cpuirq);
        // cppcheck-suppress [misra-c2012-17.7]
        memcpy(buf, &cq->q[(xwsz_t)cq->front * cq->slotsize], cpsz);
        cq->front++;
        if (cq->front >= (xwssz_t)cq->slotnum) {
                cq->front = 0;
        }
        xwos_splk_unlock_cpuirqrs(&cq->lock, cpuirq);
        *size = cpsz;
        return XWOK;
 
err_sem_wait_unintr:
        return rc;
}

函数调用图:

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

◆ xwcq_eq()

xwer_t xwcq_eq	(	struct xwcq *	cq,
		const xwu8_t *	data,
		xwsz_t *	size
	)

XWCQ API：将数据发送到循环队列的尾端 (入队，EnQueue)

参数

[in]	cq	循环队列对象的指针
[in]	data	数据
[in,out]	size	指向缓冲区的指针，此缓冲区： (I) 作为输入时，表示待入队的数据大小 (O) 作为输出时，返回实际入队的数据大小

返回: 错误码

返回值

XWOK	没有错误
-EFAULT	空指针

注解

上下文：任意

如果传入的数据大小 *size 超过初始化循环队列时指定的 slotsize ，数据将被截断。
如果循环队列数据已被填满，循环队列会循环回队列首端的位置，覆盖掉原数据。
此CAPI不会阻塞调用者，因此可以在中断中使用。

<No error

在文件 xwcq.c 第 153 行定义.

{
        xwreg_t cpuirq;
        xwsz_t eqsize;
 
        XWOS_VALIDATE((cq), "nullptr", -EFAULT);
        XWOS_VALIDATE((data), "nullptr", -EFAULT);
        XWOS_VALIDATE((size), "nullptr", -EFAULT);
 
        eqsize = *size;
        eqsize = (eqsize > cq->slotsize) ? cq->slotsize : eqsize;
        xwos_splk_lock_cpuirqsv(&cq->lock, &cpuirq);
        // cppcheck-suppress [misra-c2012-17.7]
        memcpy(&cq->q[(xwsz_t)cq->rear * cq->slotsize], data, eqsize);
        cq->rear++;
        if (cq->rear >= (xwssq_t)cq->slotnum) {
                cq->rear = 0;
        }
        if (cq->rear == cq->front) {
                /* Queue is overflow. Discard the oldest data */
                cq->front++;
                if (cq->front >= (xwssq_t)cq->slotnum) {
                        cq->front = 0;
                }
        }
        xwos_splk_unlock_cpuirqrs(&cq->lock, cpuirq);
        xwos_sem_post(&cq->sem);
        *size = eqsize;
        return XWOK;
}

函数调用图:

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

◆ xwcq_fini()

xwer_t xwcq_fini ( struct xwcq * cq )

XWCQ API：销毁循环队列对象

参数

[in] cq 循环队列对象的指针

返回: 错误码

返回值

XWOK	没有错误
-EFAULT	空指针

注解

上下文：任意

在文件 xwcq.c 第 107 行定义.

{
        XWOS_VALIDATE((cq), "nullptr", -EFAULT);
 
        return xwcq_put(cq);
}

函数调用图:

◆ xwcq_flush()

xwer_t xwcq_flush ( struct xwcq * cq )

XWCQ API: 清空循环队列

参数

[in] cq 循环队列对象的指针

返回: 错误码

返回值

XWOK	没有错误
-EFAULT	空指针

注解

上下文：任意

<No error

在文件 xwcq.c 第 633 行定义.

{
        XWOS_VALIDATE(cq, "nullptr", -EFAULT);
 
        xwos_sem_freeze(&cq->sem);
        cq->rear = 0;
        cq->front = 0;
        xwos_sem_thaw(&cq->sem);
        return XWOK;
}

函数调用图:

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

◆ xwcq_get_availability()

xwer_t xwcq_get_availability	(	struct xwcq *	cq,
		xwsz_t *	avbbuf
	)

XWCQ API: 获取循环队列中有效数据槽的数量

参数

[in]	cq	循环队列对象的指针
[out]	szbuf	指向缓冲区的指针，此缓冲区用于返回数量

返回: 错误码

返回值

XWOK	没有错误
-EFAULT	空指针

注解

上下文：任意

有效数据槽是指包含了可被接收数据的数据槽。

<No error

在文件 xwcq.c 第 662 行定义.

{
        XWOS_VALIDATE(cq, "nullptr", -EFAULT);
        XWOS_VALIDATE(avbbuf, "nullptr", -EFAULT);
 
        if (cq->rear >= cq->front) {
                *avbbuf = (xwsz_t)cq->rear - (xwsz_t)cq->front;
        } else {
                *avbbuf = cq->slotnum - (xwsz_t)cq->front + (xwsz_t)cq->rear;
        }
        return XWOK;
}

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

◆ xwcq_get_capacity()

xwer_t xwcq_get_capacity	(	struct xwcq *	cq,
		xwsz_t *	capbuf
	)

XWCQ API: 获取循环队列的容量

参数

[in]	cq	循环队列对象的指针
[out]	capbuf	指向缓冲区的指针，此缓冲区用于返回容量

返回: 错误码

返回值

XWOK	没有错误
-EFAULT	空指针

注解

上下文：任意

循环队列的容量即是数据槽的数量，是在调用 xwcq_init() 初始化时，通过参数 slotnum 指定的。

<No error

在文件 xwcq.c 第 644 行定义.

{
        XWOS_VALIDATE(cq, "nullptr", -EFAULT);
        XWOS_VALIDATE(capbuf, "nullptr", -EFAULT);
 
        *capbuf = cq->slotnum;
        return XWOK;
}

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

◆ xwcq_get_d()

static xwcq_d xwcq_get_d ( struct xwcq * cq )

inlinestatic

XWCQ API：获取循环队列对象描述符

参数

[in] cq 循环队列对象的指针

返回: 循环队列对象描述符

注解

上下文：任意

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

{
        xwcq_d cqd;
 
        cqd.cq = cq;
        cqd.tik = xwcq_get_tik(cq);
        return cqd;
}

函数调用图:

◆ xwcq_get_size()

xwer_t xwcq_get_size	(	struct xwcq *	cq,
		xwsz_t *	szbuf
	)

XWCQ API: 获取循环队列的单个数据槽的大小

参数

[in]	cq	循环队列对象的指针
[out]	szbuf	指向缓冲区的指针，此缓冲区用于返回单个数据槽的大小

返回: 错误码

返回值

XWOK	没有错误
-EFAULT	空指针

注解

上下文：任意

数据槽的大小是在调用 xwcq_init() 初始化时，通过参数 slotsize 指定的。

<No error

在文件 xwcq.c 第 653 行定义.

{
        XWOS_VALIDATE(cq, "nullptr", -EFAULT);
        XWOS_VALIDATE(szbuf, "nullptr", -EFAULT);
 
        *szbuf = cq->slotsize;
        return XWOK;
}

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

◆ xwcq_get_tik()

xwsq_t xwcq_get_tik ( struct xwcq * cq )

XWCQ API：获取循环队列对象的标签

参数

[in] cq 循环队列对象的指针

返回: 循环队列对象的标签

注解

上下文：任意

在文件 xwcq.c 第 114 行定义.

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

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

◆ xwcq_grab()

xwer_t xwcq_grab ( struct xwcq * cq )

XWCQ API：增加循环队列对象的引用计数

参数

[in] cq 循环队列控制块对象指针

返回: 错误码

返回值

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

注解

上下文：任意

在文件 xwcq.c 第 139 行定义.

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

函数调用图:

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

◆ xwcq_init()

xwer_t xwcq_init	(	struct xwcq *	cq,
		xwsz_t	slotsize,
		xwsz_t	slotnum,
		xwu8_t *	mem
	)

XWCQ API：初始化循环队列

参数

[in]	cq	循环队列对象的指针
[in]	slotsize	每个数据槽的大小
[in]	slotnum	数据槽的数量
[in]	mem	数据缓冲区的指针，

返回: 错误码

返回值

XWOK	没有错误
-EFAULT	空指针
-ESIZE	`slotsize` 或 `slotnum` 为 `0`
-EALIGN	`slotsize` 不是 `XWMMCFG_ALIGNMENT` 的整数倍

注解

上下文：任意

循环队列由 slotnum 个数据槽构成，每个数据槽能容纳 slotsize 字节的数据。
数据缓冲区 mem 大小不能小于 slotsize * slotnum ，用户应该使用宏 XWCQ_DEF_MEMPOOL() 来定义数据缓冲区。
单个数据槽的大小 slotsize 必须是系统配置 XWMMCFG_ALIGNMENT 的整数倍，错误的大小将返回错误码 -EALIGN 。

<Size error

< 内存管理对齐的字节数

< 内存管理未对齐掩码

<Not aligned

在文件 xwcq.c 第 94 行定义.

{
        XWOS_VALIDATE((cq), "nullptr", -EFAULT);
        XWOS_VALIDATE((mem), "nullptr", -EFAULT);
        XWOS_VALIDATE((slotsize > 0), "zero-size", -ESIZE);
        XWOS_VALIDATE((slotnum > 0), "zero-num", -ESIZE);
        XWOS_VALIDATE(!(slotsize & XWMM_UNALIGNED_MASK), "size-not-aligned", -EALIGN);
 
        xwcq_construct(cq, mem);
        return xwcq_activate(cq, slotsize, slotnum, xwcq_gc);
}

函数调用图:

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

◆ xwcq_jq()

xwer_t xwcq_jq	(	struct xwcq *	cq,
		const xwu8_t *	data,
		xwsz_t *	size
	)

XWCQ API：将数据发送循环队列的首端 (插队，Jump the Queue)

参数

[in]	cq	循环队列对象的指针
[in]	data	数据
[in]	size	数据的大小

返回: 错误码

返回值

XWOK	没有错误
-EFAULT	空指针

注解

上下文：任意

如果传入的数据大小 *size 超过初始化循环队列时指定的 slotsize ，数据将被截断。
如果循环队列数据已被填满，循环队列会循环回队列尾端的位置，覆盖掉原数据。
此CAPI不会阻塞调用者，因此可以在中断中使用。

<No error

在文件 xwcq.c 第 185 行定义.

{
        xwreg_t cpuirq;
        xwsz_t eqsize;
 
        XWOS_VALIDATE((cq), "nullptr", -EFAULT);
        XWOS_VALIDATE((data), "nullptr", -EFAULT);
        XWOS_VALIDATE((size), "nullptr", -EFAULT);
 
        eqsize = *size;
        eqsize = (eqsize > cq->slotsize) ? cq->slotsize : eqsize;
        xwos_splk_lock_cpuirqsv(&cq->lock, &cpuirq);
        cq->front--;
        if (cq->front < 0) {
                cq->front = (xwssz_t)cq->slotnum - 1;
        }
        if (cq->front == cq->rear) {
                /* Queue is overflow. Discard the newest data */
                cq->rear--;
                if (cq->rear < 0) {
                        cq->rear = (xwssz_t)cq->slotnum;
                }
        }
        // cppcheck-suppress [misra-c2012-17.7]
        memcpy(&cq->q[(xwsz_t)cq->front * cq->slotsize], data, eqsize);
        xwos_splk_unlock_cpuirqrs(&cq->lock, cpuirq);
        xwos_sem_post(&cq->sem);
        *size = eqsize;
        return XWOK;
}

函数调用图:

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

◆ xwcq_pfq()

xwer_t xwcq_pfq	(	struct xwcq *	cq,
		xwu8_t *	data,
		xwsz_t *	size
	)

XWCQ API: 等待从循环队列头端拷贝数据 (Peek at the Front of Queue)

参数

[in]	cq	循环队列对象的指针
[out]	data	指向缓冲区的指针，此缓冲区用于接收数据
[in,out]	size	指向缓冲区的指针，此缓冲区： (I) 作为输入时，表示接收缓冲区的大小 (O) 作为输出时，返回实际接收的数据大小

返回: 错误码

返回值

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

注解

上下文：线程

拷贝数据不会取走数据，也不会释放数据槽，数据可被重复拷贝，也可继续被接收。
若循环队列中数据为空，调用此CAPI的线程会阻塞等待，直到循环队列中有消息可取出，或等待被中断。
如果等待被中断，此CAPI将返回 -EINTR 。

在文件 xwcq.c 第 427 行定义.

{
        return xwcq_pfq_to(cq, buf, size, XWTM_MAX);
}

函数调用图:

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

◆ xwcq_pfq_to()

xwer_t xwcq_pfq_to	(	struct xwcq *	cq,
		xwu8_t *	data,
		xwsz_t *	size,
		xwtm_t	to
	)

XWCQ API: 限时等待从循环队列头端拷贝数据 (Peek at the Front of Queue)

参数

[in]	cq	循环队列对象的指针
[out]	data	指向缓冲区的指针，此缓冲区用于接收数据
[in,out]	size	指向缓冲区的指针，此缓冲区： (I) 作为输入时，表示接收缓冲区的大小 (O) 作为输出时，返回实际接收的数据大小
[in]	to	期望唤醒的时间点

返回: 错误码

返回值

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

注解

上下文：线程

拷贝数据不会取走数据，也不会释放数据槽，数据可被重复拷贝，也可继续被接收。
若循环队列中数据为空，调用此CAPI的线程会阻塞等待，直到循环队列中有消息可取出，或等待被中断，或等待超时。
如果等待被中断，此CAPI将返回 -EINTR 。
to 表示等待超时的时间点：
- to 通常是未来的时间，即 当前系统时间 + delta ，可以使用 xwtm_ft(delta) 表示；
- 如果 to 是过去的时间点，将直接返回 -ETIMEDOUT 。

<No error

在文件 xwcq.c 第 433 行定义.

{
        xwreg_t cpuirq;
        xwsz_t bufsz;
        xwsz_t cpsz;
        xwer_t rc;
 
        XWOS_VALIDATE(cq, "nullptr", -EFAULT);
        XWOS_VALIDATE(buf, "nullptr", -EFAULT);
        XWOS_VALIDATE(size, "nullptr", -EFAULT);
 
        bufsz = *size;
        cpsz = (bufsz > cq->slotsize) ? cq->slotsize : bufsz;
        rc = xwos_sem_wait_to(&cq->sem, to);
        if (rc < 0) {
                goto err_sem_wait_to;
        }
        xwos_splk_lock_cpuirqsv(&cq->lock, &cpuirq);
        // cppcheck-suppress [misra-c2012-17.7]
        memcpy(buf, &cq->q[(xwsz_t)cq->front * cq->slotsize], cpsz);
        xwos_splk_unlock_cpuirqrs(&cq->lock, cpuirq);
        xwos_sem_post(&cq->sem);
        *size = cpsz;
        return XWOK;
 
err_sem_wait_to:
        return rc;
}

函数调用图:

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

◆ xwcq_pfq_unintr()

xwer_t xwcq_pfq_unintr	(	struct xwcq *	cq,
		xwu8_t *	data,
		xwsz_t *	size
	)

XWCQ API: 等待从循环队列头端拷贝数据 (Peek at the Front of Queue)，并且等待不可被中断

参数

[in]	cq	循环队列对象的指针
[out]	data	指向缓冲区的指针，此缓冲区用于接收数据
[in,out]	size	指向缓冲区的指针，此缓冲区： (I) 作为输入时，表示接收缓冲区的大小 (O) 作为输出时，返回实际接收的数据大小

返回: 错误码

返回值

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

注解

上下文：线程

拷贝数据不会取走数据，也不会释放数据槽，数据可被重复拷贝，也可继续被接收。
若循环队列中数据为空，调用此CAPI的线程会阻塞等待，直到循环队列中有消息可取出。
调用此CAPI的线程的阻塞等待不可被中断。

<No error

在文件 xwcq.c 第 463 行定义.

{
        xwreg_t cpuirq;
        xwsz_t bufsz;
        xwsz_t cpsz;
        xwer_t rc;
 
        XWOS_VALIDATE(cq, "nullptr", -EFAULT);
        XWOS_VALIDATE(buf, "nullptr", -EFAULT);
        XWOS_VALIDATE(size, "nullptr", -EFAULT);
 
        bufsz = *size;
        cpsz = (bufsz > cq->slotsize) ? cq->slotsize : bufsz;
        rc = xwos_sem_wait_unintr(&cq->sem);
        if (rc < 0) {
                goto err_sem_wait_unintr;
        }
        xwos_splk_lock_cpuirqsv(&cq->lock, &cpuirq);
        // cppcheck-suppress [misra-c2012-17.7]
        memcpy(buf, &cq->q[(xwsz_t)cq->front * cq->slotsize], cpsz);
        xwos_splk_unlock_cpuirqrs(&cq->lock, cpuirq);
        xwos_sem_post(&cq->sem);
        *size = cpsz;
        return XWOK;
 
err_sem_wait_unintr:
        return rc;
}

函数调用图:

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

◆ xwcq_prq()

xwer_t xwcq_prq	(	struct xwcq *	cq,
		xwu8_t *	data,
		xwsz_t *	size
	)

XWCQ API: 等待从循环队列尾端拷贝数据 (Peek at the Rear of Queue)

参数

[in]	cq	循环队列对象的指针
[out]	data	指向缓冲区的指针，此缓冲区用于接收数据
[in,out]	size	指向缓冲区的指针，此缓冲区： (I) 作为输入时，表示接收缓冲区的大小 (O) 作为输出时，返回实际接收的数据大小

返回: 错误码

返回值

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

注解

上下文：线程

拷贝数据不会取走数据，也不会释放数据槽，数据可被重复拷贝，也可继续被接收。
若循环队列中数据为空，调用此CAPI的线程会阻塞等待，直到循环队列中有消息可取出，或等待被中断。
如果等待被中断，此CAPI将返回 -EINTR 。

在文件 xwcq.c 第 523 行定义.

{
        return xwcq_prq_to(cq, buf, size, XWTM_MAX);
}

函数调用图:

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

◆ xwcq_prq_to()

xwer_t xwcq_prq_to	(	struct xwcq *	cq,
		xwu8_t *	data,
		xwsz_t *	size,
		xwtm_t	to
	)

XWCQ API: 限时等待从循环队列尾端拷贝数据 (Peek at the Rear of Queue)

参数

[in]	cq	循环队列对象的指针
[out]	data	指向缓冲区的指针，此缓冲区用于接收数据
[in,out]	size	指向缓冲区的指针，此缓冲区： (I) 作为输入时，表示接收缓冲区的大小 (O) 作为输出时，返回实际接收的数据大小
[in]	to	期望唤醒的时间点

返回: 错误码

返回值

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

注解

上下文：线程

拷贝数据不会取走数据，也不会释放数据槽，数据可被重复拷贝，也可继续被接收。
若循环队列中数据为空，调用此CAPI的线程会阻塞等待，直到循环队列中有消息可取出，或等待被中断，或等待超时。
如果等待被中断，此CAPI将返回 -EINTR 。
to 表示等待超时的时间点：
- to 通常是未来的时间，即 当前系统时间 + delta ，可以使用 xwtm_ft(delta) 表示；
- 如果 to 是过去的时间点，将直接返回 -ETIMEDOUT 。

<No error

在文件 xwcq.c 第 529 行定义.

{
        xwreg_t cpuirq;
        xwssz_t rear;
        xwsz_t bufsz;
        xwsz_t cpsz;
        xwer_t rc;
 
        XWOS_VALIDATE(cq, "nullptr", -EFAULT);
        XWOS_VALIDATE(buf, "nullptr", -EFAULT);
        XWOS_VALIDATE(size, "nullptr", -EFAULT);
 
        bufsz = *size;
        cpsz = (bufsz > cq->slotsize) ? cq->slotsize : bufsz;
        rc = xwos_sem_wait_to(&cq->sem, to);
        if (rc < 0) {
                goto err_sem_wait_to;
        }
        xwos_splk_lock_cpuirqsv(&cq->lock, &cpuirq);
        rear = cq->rear - 1;
        if (rear < 0) {
                rear = (xwssz_t)cq->slotnum - 1;
        }
        // cppcheck-suppress [misra-c2012-17.7]
        memcpy(buf, &cq->q[(xwsz_t)rear * cq->slotsize], cpsz);
        xwos_splk_unlock_cpuirqrs(&cq->lock, cpuirq);
        xwos_sem_post(&cq->sem);
        *size = cpsz;
        return XWOK;
 
err_sem_wait_to:
        return rc;
}

函数调用图:

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

◆ xwcq_prq_unintr()

xwer_t xwcq_prq_unintr	(	struct xwcq *	cq,
		xwu8_t *	data,
		xwsz_t *	size
	)

XWCQ API: 等待从循环队列尾端拷贝数据 (Peek at the Rear of Queue)，并且等待不可被中断

参数

[in]	cq	循环队列对象的指针
[out]	data	指向缓冲区的指针，此缓冲区用于接收数据
[in,out]	size	指向缓冲区的指针，此缓冲区： (I) 作为输入时，表示接收缓冲区的大小 (O) 作为输出时，返回实际接收的数据大小

返回: 错误码

返回值

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

注解

上下文：线程

拷贝数据不会取走数据，也不会释放数据槽，数据可被重复拷贝，也可继续被接收。
若循环队列中数据为空，调用此CAPI的线程会阻塞等待，直到循环队列中有消息可取出。
调用此CAPI的线程的阻塞等待不可被中断。

<No error

在文件 xwcq.c 第 564 行定义.

{
        xwreg_t cpuirq;
        xwssz_t rear;
        xwsz_t bufsz;
        xwsz_t cpsz;
        xwer_t rc;
 
        XWOS_VALIDATE(cq, "nullptr", -EFAULT);
        XWOS_VALIDATE(buf, "nullptr", -EFAULT);
        XWOS_VALIDATE(size, "nullptr", -EFAULT);
 
        bufsz = *size;
        cpsz = (bufsz > cq->slotsize) ? cq->slotsize : bufsz;
        rc = xwos_sem_wait_unintr(&cq->sem);
        if (rc < 0) {
                goto err_sem_wait_unintr;
        }
        xwos_splk_lock_cpuirqsv(&cq->lock, &cpuirq);
        rear = cq->rear - 1;
        if (rear < 0) {
                rear = (xwssz_t)cq->slotnum - 1;
        }
        // cppcheck-suppress [misra-c2012-17.7]
        memcpy(buf, &cq->q[(xwsz_t)rear * cq->slotsize], cpsz);
        xwos_splk_unlock_cpuirqrs(&cq->lock, cpuirq);
        xwos_sem_post(&cq->sem);
        *size = cpsz;
        return XWOK;
 
err_sem_wait_unintr:
        return rc;
}

函数调用图:

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

◆ xwcq_put()

xwer_t xwcq_put ( struct xwcq * cq )

XWCQ API：减少循环队列对象的引用计数

参数

[in] cq 循环队列控制块对象指针

返回: 错误码

返回值

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

注解

上下文：任意

在文件 xwcq.c 第 146 行定义.

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

函数调用图:

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

◆ xwcq_release()

xwer_t xwcq_release ( xwcq_d cqd )

XWCQ API：检查循环队列对象的标签并增加引用计数

参数

[in] cqd 循环队列对象描述符

返回: 错误码

返回值

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

注解

同步/异步：同步
上下文：中断、中断底半部、线程
重入性：可重入

在文件 xwcq.c 第 133 行定义.

{
        return xwos_object_release(&cqd.cq->xwobj, cqd.tik);
}

函数调用图:

◆ xwcq_rq()

xwer_t xwcq_rq	(	struct xwcq *	cq,
		xwu8_t *	data,
		xwsz_t *	size
	)

XWCQ API: 等待从循环队列的尾端接收数据 (反向离队，Reversely deQueue)

参数

[in]	cq	循环队列对象的指针
[out]	data	指向缓冲区的指针，此缓冲区用于接收数据
[in,out]	size	指向缓冲区的指针，此缓冲区： (I) 作为输入时，表示接收缓冲区的大小 (O) 作为输出时，返回实际接收的数据大小

返回: 错误码

返回值

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

注解

上下文：线程

若循环队列中数据为空，调用此CAPI的线程会阻塞等待，直到循环队列中有消息可取出，或等待被中断。
如果等待被中断，此CAPI将返回 -EINTR 。

在文件 xwcq.c 第 322 行定义.

{
        return xwcq_rq_to(cq, buf, size, XWTM_MAX);
}

函数调用图:

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

◆ xwcq_rq_to()

xwer_t xwcq_rq_to	(	struct xwcq *	cq,
		xwu8_t *	data,
		xwsz_t *	size,
		xwtm_t	to
	)

XWCQ API: 限时等待从循环队列的尾端接收数据 (反向离队，Reversely deQueue)

参数

[in]	cq	循环队列对象的指针
[out]	data	指向缓冲区的指针，此缓冲区用于接收数据
[in,out]	size	指向缓冲区的指针，此缓冲区： (I) 作为输入时，表示接收缓冲区的大小 (O) 作为输出时，返回实际接收的数据大小
[in]	to	期望唤醒的时间点

返回: 错误码

返回值

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

注解

上下文：线程

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

<No error

在文件 xwcq.c 第 328 行定义.

{
        xwreg_t cpuirq;
        xwsz_t bufsz;
        xwsz_t cpsz;
        xwer_t rc;
 
        XWOS_VALIDATE(cq, "nullptr", -EFAULT);
        XWOS_VALIDATE(buf, "nullptr", -EFAULT);
        XWOS_VALIDATE(size, "nullptr", -EFAULT);
 
        bufsz = *size;
        cpsz = (bufsz > cq->slotsize) ? cq->slotsize : bufsz;
        rc = xwos_sem_wait_to(&cq->sem, to);
        if (rc < 0) {
                goto err_sem_wait_to;
        }
        xwos_splk_lock_cpuirqsv(&cq->lock, &cpuirq);
        cq->rear--;
        if (cq->rear < 0) {
                cq->rear = (xwssz_t)cq->slotnum - 1;
        }
        // cppcheck-suppress [misra-c2012-17.7]
        memcpy(buf, &cq->q[(xwsz_t)cq->rear * cq->slotsize], cpsz);
        xwos_splk_unlock_cpuirqrs(&cq->lock, cpuirq);
        *size = cpsz;
        return XWOK;
 
err_sem_wait_to:
        return rc;
}

函数调用图:

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

◆ xwcq_rq_unintr()

xwer_t xwcq_rq_unintr	(	struct xwcq *	cq,
		xwu8_t *	data,
		xwsz_t *	size
	)

XWCQ API: 等待从循环队列的尾端接收数据 (反向离队，Reversely deQueue)，并且等待不可被中断

参数

[in]	cq	循环队列对象的指针
[out]	data	指向缓冲区的指针，此缓冲区用于接收数据
[in,out]	size	指向缓冲区的指针，此缓冲区： (I) 作为输入时，表示接收缓冲区的大小 (O) 作为输出时，返回实际接收的数据大小

返回: 错误码

返回值

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

注解

上下文：线程

若循环队列中数据为空，调用此CAPI的线程会阻塞等待，直到循环队列中有消息可取出。
调用此CAPI的线程的阻塞等待不可被中断。

<No error

在文件 xwcq.c 第 361 行定义.

{
        xwreg_t cpuirq;
        xwsz_t bufsz;
        xwsz_t cpsz;
        xwer_t rc;
 
        XWOS_VALIDATE(cq, "nullptr", -EFAULT);
        XWOS_VALIDATE(buf, "nullptr", -EFAULT);
        XWOS_VALIDATE(size, "nullptr", -EFAULT);
 
        bufsz = *size;
        cpsz = (bufsz > cq->slotsize) ? cq->slotsize : bufsz;
        rc = xwos_sem_wait_unintr(&cq->sem);
        if (rc < 0) {
                goto err_sem_wait_unintr;
        }
        xwos_splk_lock_cpuirqsv(&cq->lock, &cpuirq);
        cq->rear--;
        if (cq->rear < 0) {
                cq->rear = (xwssz_t)cq->slotnum - 1;
        }
        // cppcheck-suppress [misra-c2012-17.7]
        memcpy(buf, &cq->q[(xwsz_t)cq->rear * cq->slotsize], cpsz);
        xwos_splk_unlock_cpuirqrs(&cq->lock, cpuirq);
        *size = cpsz;
        return XWOK;
 
err_sem_wait_unintr:
        return rc;
}

函数调用图:

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

◆ xwcq_trydq()

xwer_t xwcq_trydq	(	struct xwcq *	cq,
		xwu8_t *	data,
		xwsz_t *	size
	)

XWCQ API: 尝试从循环队列的首端接收数据 (离队，DeQueue)

参数

[in]	cq	循环队列对象的指针
[out]	data	指向缓冲区的指针，此缓冲区用于接收数据
[in,out]	size	指向缓冲区的指针，此缓冲区： (I) 作为输入时，表示接收缓冲区的大小 (O) 作为输出时，返回实际接收的数据大小

返回: 错误码

返回值

XWOK	没有错误
-EFAULT	空指针
-ENODATA	循环队列为空

注解

上下文：任意

若循环队列中为空，就立即返回 -ENODATA 。
此CAPI可在中断中使用。

<No error

在文件 xwcq.c 第 289 行定义.

{
        xwsz_t bufsz;
        xwsz_t cpsz;
        xwreg_t cpuirq;
        xwer_t rc;
 
        XWOS_VALIDATE(cq, "nullptr", -EFAULT);
        XWOS_VALIDATE(buf, "nullptr", -EFAULT);
        XWOS_VALIDATE(size, "nullptr", -EFAULT);
 
        bufsz = *size;
        cpsz = (bufsz > cq->slotsize) ? cq->slotsize : bufsz;
        rc = xwos_sem_trywait(&cq->sem);
        if (rc < 0) {
                goto err_sem_trywait;
        }
        xwos_splk_lock_cpuirqsv(&cq->lock, &cpuirq);
        // cppcheck-suppress [misra-c2012-17.7]
        memcpy(buf, &cq->q[(xwsz_t)cq->front * cq->slotsize], cpsz);
        cq->front++;
        if (cq->front >= (xwssz_t)cq->slotnum) {
                cq->front = 0;
        }
        xwos_splk_unlock_cpuirqrs(&cq->lock, cpuirq);
        *size = cpsz;
        return XWOK;
 
err_sem_trywait:
        return rc;
}

函数调用图:

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

◆ xwcq_trypfq()

xwer_t xwcq_trypfq	(	struct xwcq *	cq,
		xwu8_t *	data,
		xwsz_t *	size
	)

XWCQ API: 尝试从循环队列头端拷贝数据 (Peek at the Front of Queue)

参数

[in]	cq	循环队列对象的指针
[out]	data	指向缓冲区的指针，此缓冲区用于接收数据
[in,out]	size	指向缓冲区的指针，此缓冲区： (I) 作为输入时，表示接收缓冲区的大小 (O) 作为输出时，返回实际接收的数据大小

返回: 错误码

返回值

XWOK	没有错误
-EFAULT	空指针
-ENODATA	循环队列为空

注解

上下文：任意

拷贝数据不会取走数据，也不会释放数据槽，数据可被重复拷贝，也可继续被接收。
若循环队列中为空，就立即返回 -ENODATA ，此CAPI可在中断中使用。

<No error

在文件 xwcq.c 第 493 行定义.

{
        xwreg_t cpuirq;
        xwsz_t bufsz;
        xwsz_t cpsz;
        xwer_t rc;
 
        XWOS_VALIDATE(cq, "nullptr", -EFAULT);
        XWOS_VALIDATE(buf, "nullptr", -EFAULT);
        XWOS_VALIDATE(size, "nullptr", -EFAULT);
 
        bufsz = *size;
        cpsz = (bufsz > cq->slotsize) ? cq->slotsize : bufsz;
        rc = xwos_sem_trywait(&cq->sem);
        if (rc < 0) {
                goto err_sem_trywait;
        }
        xwos_splk_lock_cpuirqsv(&cq->lock, &cpuirq);
        // cppcheck-suppress [misra-c2012-17.7]
        memcpy(buf, &cq->q[(xwsz_t)cq->front * cq->slotsize], cpsz);
        xwos_splk_unlock_cpuirqrs(&cq->lock, cpuirq);
        xwos_sem_post(&cq->sem);
        *size = cpsz;
        return XWOK;
 
err_sem_trywait:
        return rc;
}

函数调用图:

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

◆ xwcq_tryprq()

xwer_t xwcq_tryprq	(	struct xwcq *	cq,
		xwu8_t *	data,
		xwsz_t *	size
	)

XWCQ API: 尝试从循环队列尾端拷贝数据 (Peek at the Rear of Queue)

参数

[in]	cq	循环队列对象的指针
[out]	data	指向缓冲区的指针，此缓冲区用于接收数据
[in,out]	size	指向缓冲区的指针，此缓冲区： (I) 作为输入时，表示接收缓冲区的大小 (O) 作为输出时，返回实际接收的数据大小

返回: 错误码

返回值

XWOK	没有错误
-EFAULT	空指针
-ENODATA	循环队列为空

注解

上下文：任意

拷贝数据不会取走数据，也不会释放数据槽，数据可被重复拷贝，也可继续被接收。
若循环队列中为空，就立即返回 -ENODATA ，此CAPI可在中断中使用。

<No error

在文件 xwcq.c 第 599 行定义.

{
        xwreg_t cpuirq;
        xwssz_t rear;
        xwsz_t bufsz;
        xwsz_t cpsz;
        xwer_t rc;
 
        XWOS_VALIDATE(cq, "nullptr", -EFAULT);
        XWOS_VALIDATE(buf, "nullptr", -EFAULT);
        XWOS_VALIDATE(size, "nullptr", -EFAULT);
 
        bufsz = *size;
        cpsz = (bufsz > cq->slotsize) ? cq->slotsize : bufsz;
        rc = xwos_sem_trywait(&cq->sem);
        if (rc < 0) {
                goto err_sem_trywait;
        }
        xwos_splk_lock_cpuirqsv(&cq->lock, &cpuirq);
        rear = cq->rear - 1;
        if (rear < 0) {
                rear = (xwssz_t)cq->slotnum - 1;
        }
        // cppcheck-suppress [misra-c2012-17.7]
        memcpy(buf, &cq->q[(xwsz_t)rear * cq->slotsize], cpsz);
        xwos_splk_unlock_cpuirqrs(&cq->lock, cpuirq);
        xwos_sem_post(&cq->sem);
        *size = cpsz;
        return XWOK;
 
err_sem_trywait:
        return rc;
}

函数调用图:

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

◆ xwcq_tryrq()

xwer_t xwcq_tryrq	(	struct xwcq *	cq,
		xwu8_t *	data,
		xwsz_t *	size
	)

XWCQ API: 尝试从循环队列的尾端接收数据 (反向离队，Reversely deQueue)

参数

[in]	cq	循环队列对象的指针
[out]	data	指向缓冲区的指针，此缓冲区用于接收数据
[in,out]	size	指向缓冲区的指针，此缓冲区： (I) 作为输入时，表示接收缓冲区的大小 (O) 作为输出时，返回实际接收的数据大小

返回: 错误码

返回值

XWOK	没有错误
-EFAULT	空指针
-ENODATA	循环队列为空

注解

上下文：任意

若循环队列中为空，就立即返回 -ENODATA ，此CAPI可在中断中使用。

<No error

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

{
        xwreg_t cpuirq;
        xwsz_t bufsz;
        xwsz_t cpsz;
        xwer_t rc;
 
        XWOS_VALIDATE(cq, "nullptr", -EFAULT);
        XWOS_VALIDATE(buf, "nullptr", -EFAULT);
        XWOS_VALIDATE(size, "nullptr", -EFAULT);
 
        bufsz = *size;
        cpsz = (bufsz > cq->slotsize) ? cq->slotsize : bufsz;
        rc = xwos_sem_trywait(&cq->sem);
        if (rc < 0) {
                goto err_sem_trywait;
        }
        xwos_splk_lock_cpuirqsv(&cq->lock, &cpuirq);
        cq->rear--;
        if (cq->rear < 0) {
                cq->rear = (xwssz_t)cq->slotnum - 1;
        }
        // cppcheck-suppress [misra-c2012-17.7]
        memcpy(buf, &cq->q[(xwsz_t)cq->rear * cq->slotsize], cpsz);
        xwos_splk_unlock_cpuirqrs(&cq->lock, cpuirq);
        *size = cpsz;
        return XWOK;
 
err_sem_trywait:
        return rc;
}

函数调用图:

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

◆ xwcq_unbind()

xwer_t xwcq_unbind	(	struct xwcq *	cq,
		struct xwos_sel *	sel
	)

XWOS API：从信号选择器上解绑循环队列对象

参数

[in]	cq	循环队列对象的指针
[in]	sel	信号选择器的指针

返回: 错误码

返回值

XWOK	没有错误
-EFAULT	空指针
-ENOTCONN	同步对象没有绑定到事件对象上

注解

上下文：任意

< 报告BUG

< 当条件x成立时报告BUG

<No error

在文件 xwcq.c 第 689 行定义.

{
        xwer_t rc;
 
        rc = xwos_sem_unbind(&cq->sem, sel);
        if (rc < 0) {
                goto err_unbind;
        }
        rc = xwcq_put(cq);
        XWOS_BUG_ON(rc < 0);
        return XWOK;
 
err_unbind:
        return rc;
}

函数调用图:

模块

结构体

宏定义

函数

详细描述

循环队列的静态初始化、销毁

循环队列的动态创建、删除

发送消息

接收消息

拷贝消息

清空循环队列

获取循环队列容量

获取循环队列单个数据槽的大小

获取循环队列中有效数据槽的数量

循环队列对象的生命周期管理

对象描述符和对象标签

宏定义说明

◆ XWCQ_DEF_MEMPOOL

函数说明

◆ xwcq_acquire()

◆ xwcq_bind()

◆ xwcq_dq()

◆ xwcq_dq_to()

◆ xwcq_dq_unintr()

◆ xwcq_eq()

◆ xwcq_fini()

◆ xwcq_flush()

◆ xwcq_get_availability()

◆ xwcq_get_capacity()

◆ xwcq_get_d()

◆ xwcq_get_size()

◆ xwcq_get_tik()

◆ xwcq_grab()

◆ xwcq_init()

◆ xwcq_jq()

◆ xwcq_pfq()

◆ xwcq_pfq_to()

◆ xwcq_pfq_unintr()

◆ xwcq_prq()

◆ xwcq_prq_to()

◆ xwcq_prq_unintr()

◆ xwcq_put()

◆ xwcq_release()

◆ xwcq_rq()

◆ xwcq_rq_to()

◆ xwcq_rq_unintr()

◆ xwcq_trydq()

◆ xwcq_trypfq()

◆ xwcq_tryprq()

◆ xwcq_tryrq()

◆ xwcq_unbind()