信号选择器的协作图:

结构体
struct	xwos_sel
	XWOS API：信号选择器对象更多...

struct	xwos_sel_d
	XWOS API：信号选择器对象描述符更多...

宏定义
#define	XWOS_SEL_NILD ((xwos_sel_d){NULL, 0,})
	XWOS API：空的信号选择器对象描述符

函数
static xwer_t	xwos_sel_init (struct xwos_sel sel, xwsz_t num, xwbmp_t bmp, xwbmp_t *msk)
	XWOS API：静态方式初始化信号选择器

static xwer_t	xwos_sel_fini (struct xwos_sel *sel)
	XWOS API：销毁静态方式初始化的信号选择器

static xwer_t	xwos_sel_grab (struct xwos_sel *sel)
	XWOS API：增加信号选择器对象的引用计数

static xwer_t	xwos_sel_put (struct xwos_sel *sel)
	XWOS API：减少信号选择器对象的引用计数

static xwer_t	xwos_sel_create (xwos_sel_d *seld, xwsz_t num)
	XWOS API：动态方式创建信号选择器

static xwer_t	xwos_sel_delete (xwos_sel_d seld)
	XWOS API：删除动态方式创建的信号选择器

static xwer_t	xwos_sel_acquire (xwos_sel_d seld)
	XWOS API：检查信号选择器对象的标签并增加引用计数

static xwer_t	xwos_sel_release (xwos_sel_d seld)
	XWOS API：检查对象的标签并减少引用计数

static xwsq_t	xwos_sel_get_tik (struct xwos_sel *sel)
	XWOS API：获取信号选择器对象的标签

static xwos_sel_d	xwos_sel_get_d (struct xwos_sel *sel)
	XWOS API：获取信号选择器对象描述符

static xwer_t	xwos_sel_bind (struct xwos_sel src, struct xwos_sel dst, xwsq_t pos)
	XWOS API：绑定源信号选择器到目的信号选择器

static xwer_t	xwos_sel_unbind (struct xwos_sel src, struct xwos_sel dst)
	XWOS API：从目的信号选择器上解绑源信号选择器

static xwer_t	xwos_sel_get_num (struct xwos_sel sel, xwsz_t numbuf)
	XWOS API：获取信号选择器中的信号槽的数量

static xwer_t	xwos_sel_select (struct xwos_sel *sel, xwbmp_t msk[], xwbmp_t trg[])
	XWOS API：等待信号选择器中的选择信号

static xwer_t	xwos_sel_select_to (struct xwos_sel *sel, xwbmp_t msk[], xwbmp_t trg[], xwtm_t to)
	XWOS API：限时等待信号选择器中的选择信号

static xwer_t	xwos_sel_tryselect (struct xwos_sel *sel, xwbmp_t msk[], xwbmp_t trg[])
	XWOS API：检测信号选择器中是否有选择信号

详细描述

技术参考手册：信号选择器

信号选择器的静态初始化、销毁

xwos_sel_init() ：静态初始化
xwos_sel_fini() ：销毁

信号选择器的动态创建、删除

xwos_sel_create() ：动态创建
xwos_sel_delete() ：删除

获取事件的状态

xwos_sel_get_num() ：获取信号选择器中的信号槽的数量，可在任意上下文使用

选择信号

xwos_sel_select() ：等待 选择信号 ，只能在线程上下文使用
xwos_sel_select_to() ：限时等待 选择信号 ，只能在线程上下文使用
xwos_sel_tryselect() ：仅测试是否有 选择信号 ，可在任意上下文使用

使用信号选择器选择信号选择器

xwos_sel_bind() ：将信号选择器绑定到另一个信号选择器上
xwos_sel_unbind() ：从信号选择器上解绑

信号选择器对象的生命周期管理

通过 对象指针 管理生命周期：
- xwos_sel_grab() ：增加引用计数
- xwos_sel_put() ：减少引用计数
通过 对象描述符 管理生命周期：
- xwos_sel_acquire() ：增加引用计数
- xwos_sel_release() ：减少引用计数

对象描述符和对象标签

已知信号选择器对象的指针的情况下，可以通过 xwos_sel_get_d() 获取 xwos_sel_d ，或可以通过 xwos_sel_get_tik() 获取对象标签。

C++

C++头文件： xwos/osal/sync/sel.hxx

宏定义说明

◆ XWOS_SEL_NILD

#define XWOS_SEL_NILD ((xwos_sel_d){NULL, 0,})

XWOS API：空的信号选择器对象描述符

在文件 sel.h 第 96 行定义.

函数说明

◆ xwos_sel_acquire()

static xwer_t xwos_sel_acquire ( xwos_sel_d seld )

inlinestatic

XWOS API：检查信号选择器对象的标签并增加引用计数

参数

[in] seld 信号选择器对象描述符

返回: 错误码

返回值

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

注解

上下文：任意

在文件 sel.h 第 214 行定义.

{
        return xwosdl_sel_acquire(&seld.sel->ossel, seld.tik);
}

◆ xwos_sel_bind()

static xwer_t xwos_sel_bind	(	struct xwos_sel *	src,
		struct xwos_sel *	dst,
		xwsq_t	pos
	)

inlinestatic

XWOS API：绑定源信号选择器到目的信号选择器

参数

[in]	src	源信号选择器对象的指针
[in]	dst	目的信号选择器对象的指针
[in]	pos	同步对象映射到位图中的位置

返回: 错误码

返回值

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

注解

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

多个信号选择器可以依次绑定，形成信号传递链。但不可循环绑定，否则会造成无限循环传递。

在文件 sel.h 第 284 行定义.

{
        return xwosdl_sel_bind(&src->ossel, &dst->ossel, pos);
}

◆ xwos_sel_create()

static xwer_t xwos_sel_create	(	xwos_sel_d *	seld,
		xwsz_t	num
	)

inlinestatic

XWOS API：动态方式创建信号选择器

参数

[out]	seld	指向缓冲区的指针，通过此缓冲区返回信号选择器对象描述符
[in]	num	信号选择器中信号的数量

返回: 错误码

返回值

XWOK	没有错误
-EFAULT	空指针
-ENOMEM	内存不足

注解

上下文：任意

在文件 sel.h 第 182 行定义.

{
        return xwosdl_sel_create((xwosdl_sel_d *)seld, num);
}

◆ xwos_sel_delete()

static xwer_t xwos_sel_delete ( xwos_sel_d seld )

inlinestatic

XWOS API：删除动态方式创建的信号选择器

参数

[in] seld 信号选择器对象描述符

返回: 错误码

返回值

XWOK	没有错误
-EFAULT	空指针

注解

上下文：任意

在文件 sel.h 第 197 行定义.

{
        return xwosdl_sel_delete(&seld.sel->ossel, seld.tik);
}

◆ xwos_sel_fini()

static xwer_t xwos_sel_fini ( struct xwos_sel * sel )

inlinestatic

XWOS API：销毁静态方式初始化的信号选择器

参数

[in] sel 信号选择器对象的指针

返回: 错误码

返回值

XWOK	没有错误
-EFAULT	空指针

注解

上下文：任意

在文件 sel.h 第 127 行定义.

{
        return xwosdl_sel_fini(&sel->ossel);
}

◆ xwos_sel_get_d()

static xwos_sel_d xwos_sel_get_d ( struct xwos_sel * sel )

inlinestatic

XWOS API：获取信号选择器对象描述符

参数

[in] sel 信号选择器对象的指针

返回: 信号选择器对象描述符

注解

上下文：任意

在文件 sel.h 第 257 行定义.

{
        xwos_sel_d seld;
 
        seld.sel = sel;
        seld.tik = xwosdl_sel_get_tik(&sel->ossel);
        return seld;
}

◆ xwos_sel_get_num()

static xwer_t xwos_sel_get_num	(	struct xwos_sel *	sel,
		xwsz_t *	numbuf
	)

inlinestatic

XWOS API：获取信号选择器中的信号槽的数量

参数

[in]	sel	信号选择器对象的指针
[out]	numbuf	指向缓冲区的指针，通过此缓冲区返回信号槽的数量

返回: 错误码

返回值

XWOK	没有错误
-EFAULT	空指针

注解

上下文：任意

在文件 sel.h 第 317 行定义.

{
        return xwosdl_sel_get_num(&sel->ossel, numbuf);
}

◆ xwos_sel_get_tik()

static xwsq_t xwos_sel_get_tik ( struct xwos_sel * sel )

inlinestatic

XWOS API：获取信号选择器对象的标签

参数

[in] sel 信号选择器对象的指针

返回: 信号选择器对象的标签

注解

上下文：任意

在文件 sel.h 第 244 行定义.

{
        return xwosdl_sel_get_tik(&sel->ossel);
}

◆ xwos_sel_grab()

static xwer_t xwos_sel_grab ( struct xwos_sel * sel )

inlinestatic

XWOS API：增加信号选择器对象的引用计数

参数

[in] sel 信号选择器对象的指针

返回: 错误码

返回值

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

注解

上下文：任意

此函数主要用于管理 静态对象 的引用计数。若用于 动态对象 ，需要确保对象的指针一定不是野指针。

在文件 sel.h 第 146 行定义.

{
        return xwosdl_sel_grab(&sel->ossel);
}

◆ xwos_sel_init()

static xwer_t xwos_sel_init	(	struct xwos_sel *	sel,
		xwsz_t	num,
		xwbmp_t *	bmp,
		xwbmp_t *	msk
	)

inlinestatic

XWOS API：静态方式初始化信号选择器

参数

[in]	sel	信号选择器对象的指针
[in]	num	信号选择器中信号的数量
[in]	bmp	信号选择器用来记录信号状态的位图缓冲区
[in]	msk	信号选择器用来记录掩码状态的位图缓冲区

返回: 错误码

返回值

XWOK	没有错误
-EFAULT	空指针

注解

上下文：任意

在文件 sel.h 第 111 行定义.

{
        return xwosdl_sel_init(&sel->ossel, num, bmp, msk);
}

◆ xwos_sel_put()

static xwer_t xwos_sel_put ( struct xwos_sel * sel )

inlinestatic

XWOS API：减少信号选择器对象的引用计数

参数

[in] sel 信号选择器对象的指针

返回: 错误码

返回值

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

注解

上下文：任意

此函数主要用于管理 静态对象 的引用计数。若用于 动态对象 ，需要确保对象的指针一定不是野指针。

在文件 sel.h 第 165 行定义.

{
        return xwosdl_sel_put(&sel->ossel);
}

◆ xwos_sel_release()

static xwer_t xwos_sel_release ( xwos_sel_d seld )

inlinestatic

XWOS API：检查对象的标签并减少引用计数

参数

[in] seld 信号选择器对象描述符

返回: 错误码

返回值

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

注解

上下文：任意

在文件 sel.h 第 231 行定义.

{
        return xwosdl_sel_release(&seld.sel->ossel, seld.tik);
}

◆ xwos_sel_select()

static xwer_t xwos_sel_select	(	struct xwos_sel *	sel,
		xwbmp_t	msk[],
		xwbmp_t	trg[]
	)

inlinestatic

XWOS API：等待信号选择器中的 选择信号

参数

[in]	sel	信号选择器对象的指针
[in]	msk	同步对象位图掩码，表示只关注掩码内的同步对象
[out]	trg	指向缓冲区的指针，通过此缓冲区返回已触发的同步对象位图掩码

返回: 错误码

返回值

XWOK	没有错误
-EFAULT	空指针
-EINTR	等待被中断
-ENOTTHDCTX	不在线程上下文中

注解

上下文：线程

在文件 sel.h 第 336 行定义.

{
        return xwosdl_sel_select(&sel->ossel, msk, trg);
}

◆ xwos_sel_select_to()

static xwer_t xwos_sel_select_to	(	struct xwos_sel *	sel,
		xwbmp_t	msk[],
		xwbmp_t	trg[],
		xwtm_t	to
	)

inlinestatic

XWOS API：限时等待信号选择器中的 选择信号

参数

[in]	sel	信号选择器对象的指针
[in]	msk	同步对象位图掩码，表示只关注掩码内的同步对象
[out]	trg	指向缓冲区的指针，通过此缓冲区返回已触发的同步对象位图掩码
[in]	to	期望唤醒的时间点

返回: 错误码

返回值

XWOK	没有错误
-EFAULT	空指针
-ETIMEDOUT	超时
-EINTR	等待被中断
-ENOTTHDCTX	不在线程上下文中

注解

上下文：线程

to 表示等待超时的时间点：

to 通常是未来的时间，即 当前系统时间 + delta ，可以使用 xwtm_ft(delta) 表示；
如果 to 是过去的时间点，将直接返回 -ETIMEDOUT 。

在文件 sel.h 第 362 行定义.

{
        return xwosdl_sel_select_to(&sel->ossel, msk, trg, to);
}

◆ xwos_sel_tryselect()

static xwer_t xwos_sel_tryselect	(	struct xwos_sel *	sel,
		xwbmp_t	msk[],
		xwbmp_t	trg[]
	)

inlinestatic

XWOS API：检测信号选择器中是否有 选择信号

参数

[in]	sel	信号选择器对象的指针
[in]	msk	同步对象位图掩码，表示只关注掩码内的同步对象
[out]	trg	指向缓冲区的指针，通过此缓冲区返回已触发的同步对象位图掩码

返回: 错误码

返回值

XWOK	没有错误
-EFAULT	空指针
-ENODATA	没有任何同步对象向信号选择器发送选择信号

注解

上下文：任意

若没有 **选择信号**，立即返回错误码 -ENODATA ，不会等待。

在文件 sel.h 第 384 行定义.

{
        return xwosdl_sel_select(&sel->ossel, msk, trg);
}

◆ xwos_sel_unbind()

static xwer_t xwos_sel_unbind	(	struct xwos_sel *	src,
		struct xwos_sel *	dst
	)

inlinestatic

XWOS API：从目的信号选择器上解绑源信号选择器

参数

[in]	src	源信号选择器对象的指针
[in]	dst	目的信号选择器对象的指针

返回: 错误码

返回值

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

注解

上下文：任意

在文件 sel.h 第 301 行定义.

{
        return xwosdl_sel_unbind(&src->ossel, &dst->ossel);
}

结构体

宏定义

函数

详细描述

信号选择器的静态初始化、销毁

信号选择器的动态创建、删除

获取事件的状态

选择信号

使用信号选择器选择信号选择器

信号选择器对象的生命周期管理

对象描述符和对象标签

C++

宏定义说明

◆ XWOS_SEL_NILD

函数说明

◆ xwos_sel_acquire()

◆ xwos_sel_bind()

◆ xwos_sel_create()

◆ xwos_sel_delete()

◆ xwos_sel_fini()

◆ xwos_sel_get_d()

◆ xwos_sel_get_num()

◆ xwos_sel_get_tik()

◆ xwos_sel_grab()

◆ xwos_sel_init()

◆ xwos_sel_put()

◆ xwos_sel_release()

◆ xwos_sel_select()

◆ xwos_sel_select_to()

◆ xwos_sel_tryselect()

◆ xwos_sel_unbind()