线程栅栏的协作图:

结构体
struct	xwos_br
	XWOS API：线程栅栏更多...

struct	xwos_br_d
	XWOS API：线程栅栏对象描述符更多...

宏定义
#define	XWOS_BR_NILD ((xwos_br_d){NULL, 0,})
	XWOS API：空的线程栅栏对象描述符

函数
static xwer_t	xwos_br_init (struct xwos_br br, xwsz_t num, xwbmp_t bmp, xwbmp_t *msk)
	XWOS API：静态方式初始化线程栅栏

static xwer_t	xwos_br_fini (struct xwos_br *br)
	XWOS API：销毁静态方式初始化的线程栅栏

static xwer_t	xwos_br_grab (struct xwos_br *br)
	XWOS API：增加线程栅栏对象的引用计数

static xwer_t	xwos_br_put (struct xwos_br *br)
	XWOS API：减少线程栅栏对象的引用计数

static xwer_t	xwos_br_create (xwos_br_d *brd, xwsz_t num)
	XWOS API：动态方式创建线程栅栏

static xwer_t	xwos_br_delete (xwos_br_d brd)
	XWOS API：删除动态方式创建的线程栅栏

static xwer_t	xwos_br_acquire (xwos_br_d brd)
	XWOS API：检查线程栅栏对象的标签并增加引用计数

static xwer_t	xwos_br_release (xwos_br_d brd)
	XWOS API：检查对象的标签并减少引用计数

static xwsq_t	xwos_br_get_tik (struct xwos_br *br)
	XWOS API：获取线程栅栏对象的标签

static xwos_br_d	xwos_br_get_d (struct xwos_br *br)
	XWOS API：获取线程栅栏对象描述符

static xwer_t	xwos_br_bind (struct xwos_br br, struct xwos_sel sel, xwsq_t pos)
	XWOS API：绑定线程栅栏到信号选择器

static xwer_t	xwos_br_unbind (struct xwos_br br, struct xwos_sel sel)
	XWOS API：从信号选择器上解绑线程栅栏

static xwer_t	xwos_br_get_num (struct xwos_br br, xwsz_t numbuf)
	XWOS API：获取线程栅栏中线程槽数量

static xwer_t	xwos_br_wait (struct xwos_br *br)
	XWOS API：等待所有线程到达栅栏

static xwer_t	xwos_br_wait_to (struct xwos_br *br, xwtm_t to)
	XWOS API：限时等待所有线程到达栅栏

static xwer_t	xwos_br_wait_unintr (struct xwos_br *br)
	XWOS API：等待所有线程到达栅栏，且等待不可被中断

详细描述

技术参考手册：线程栅栏

线程栅栏的静态初始化、销毁

xwos_br_init() ：静态初始化
xwos_br_fini() ：销毁

线程栅栏的动态创建、删除

xwos_br_create() ：动态创建
xwos_br_delete() ：删除

获取事件的状态

xwos_br_get_num() ：获取线程栅栏中线程槽数量，可在任意上下文使用

同步线程

xwos_br_wait() ：等待所有线程到达栅栏，只能在线程上下文使用
xwos_br_wait_to() ：限时等待所有线程到达栅栏，只能在线程上下文使用
xwos_br_wait_unintr() ：等待所有线程到达栅栏，且等待不可被中断，只能在线程上下文使用

使用信号选择器选择线程栅栏

xwos_br_bind() ：将线程栅栏绑定到信号选择器上
xwos_br_unbind() ：从信号选择器上解绑

线程栅栏对象的生命周期管理

通过 对象指针 管理生命周期：
- xwos_br_grab() ：增加引用计数
- xwos_br_put() ：减少引用计数
通过 对象描述符 管理生命周期：
- xwos_br_acquire() ：增加引用计数
- xwos_br_release() ：减少引用计数

对象描述符和对象标签

已知线程栅栏对象的指针的情况下，可以通过 xwos_br_get_d() 获取 xwos_br_d ，或可以通过 xwos_br_get_tik() 获取对象标签。

C++

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

宏定义说明

◆ XWOS_BR_NILD

#define XWOS_BR_NILD ((xwos_br_d){NULL, 0,})

XWOS API：空的线程栅栏对象描述符

在文件 br.h 第 98 行定义.

函数说明

◆ xwos_br_init()

static xwer_t xwos_br_init	(	struct xwos_br *	br,
		xwsz_t	num,
		xwbmp_t *	bmp,
		xwbmp_t *	msk
	)

inlinestatic

XWOS API：静态方式初始化线程栅栏

参数

[in]	br	线程栅栏对象的指针
[in]	num	线程栅栏中的线程数量
[in]	bmp	线程栅栏用来记录线程抵达事件的位图缓冲区
[in]	msk	线程栅栏用来记录线程掩码状态的位图缓冲区，长度应与bmp一致

返回: 错误码

返回值

XWOK	没有错误
-EFAULT	无效的指针或空指针

注解

上下文：任意

在文件 br.h 第 113 行定义.

{
        return xwosdl_br_init(&br->osbr, num, bmp, msk);
}

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

◆ xwos_br_fini()

static xwer_t xwos_br_fini ( struct xwos_br * br )

inlinestatic

XWOS API：销毁静态方式初始化的线程栅栏

参数

[in] br 线程栅栏对象的指针

返回: 错误码

返回值

XWOK	没有错误
-EFAULT	无效的指针或空指针

注解

上下文：任意

在文件 br.h 第 129 行定义.

{
        return xwosdl_br_fini(&br->osbr);
}

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

◆ xwos_br_grab()

static xwer_t xwos_br_grab ( struct xwos_br * br )

inlinestatic

XWOS API：增加线程栅栏对象的引用计数

参数

[in] br 线程栅栏对象的指针

返回: 错误码

返回值

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

注解

上下文：任意

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

在文件 br.h 第 148 行定义.

{
        return xwosdl_br_grab(&br->osbr);
}

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

◆ xwos_br_put()

static xwer_t xwos_br_put ( struct xwos_br * br )

inlinestatic

XWOS API：减少线程栅栏对象的引用计数

参数

[in] br 线程栅栏对象的指针

返回: 错误码

返回值

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

注解

上下文：任意

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

在文件 br.h 第 167 行定义.

{
        return xwosdl_br_put(&br->osbr);
}

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

◆ xwos_br_create()

static xwer_t xwos_br_create	(	xwos_br_d *	brd,
		xwsz_t	num
	)

inlinestatic

XWOS API：动态方式创建线程栅栏

参数

[out]	brd	指向缓冲区的指针，通过此缓冲区返回线程栅栏对象描述符
[in]	num	线程栅栏中的线程数量

返回: 错误码

返回值

XWOK	没有错误
-EFAULT	无效的指针或空指针
-ENOMEM	内存不足

注解

上下文：任意

在文件 br.h 第 184 行定义.

{
        return xwosdl_br_create((xwosdl_br_d *)brd, num);
}

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

◆ xwos_br_delete()

static xwer_t xwos_br_delete ( xwos_br_d brd )

inlinestatic

XWOS API：删除动态方式创建的线程栅栏

参数

[in] brd 线程栅栏对象描述符

返回: 错误码

返回值

XWOK	没有错误
-EFAULT	无效的指针或空指针

注解

上下文：任意

在文件 br.h 第 199 行定义.

{
        return xwosdl_br_delete(&brd.br->osbr, brd.tik);
}

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

◆ xwos_br_acquire()

static xwer_t xwos_br_acquire ( xwos_br_d brd )

inlinestatic

XWOS API：检查线程栅栏对象的标签并增加引用计数

参数

[in] brd 线程栅栏对象描述符

返回: 错误码

返回值

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

注解

上下文：任意

在文件 br.h 第 216 行定义.

{
        return xwosdl_br_acquire(&brd.br->osbr, brd.tik);
}

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

◆ xwos_br_release()

static xwer_t xwos_br_release ( xwos_br_d brd )

inlinestatic

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

参数

[in] brd 线程栅栏对象描述符

返回: 错误码

返回值

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

注解

上下文：任意

在文件 br.h 第 233 行定义.

{
        return xwosdl_br_release(&brd.br->osbr, brd.tik);
}

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

◆ xwos_br_get_tik()

static xwsq_t xwos_br_get_tik ( struct xwos_br * br )

inlinestatic

XWOS API：获取线程栅栏对象的标签

参数

[in] br 线程栅栏对象的指针

返回: 线程栅栏对象的标签

注解

上下文：任意

在文件 br.h 第 246 行定义.

{
        return xwosdl_br_get_tik(&br->osbr);
}

◆ xwos_br_get_d()

static xwos_br_d xwos_br_get_d ( struct xwos_br * br )

inlinestatic

XWOS API：获取线程栅栏对象描述符

参数

[in] br 线程栅栏对象的指针

返回: 线程栅栏对象描述符

注解

上下文：任意

在文件 br.h 第 259 行定义.

{
        xwos_br_d brd;
 
        brd.br = br;
        brd.tik = xwosdl_br_get_tik(&br->osbr);
        return brd;
}

◆ xwos_br_bind()

static xwer_t xwos_br_bind	(	struct xwos_br *	br,
		struct xwos_sel *	sel,
		xwsq_t	pos
	)

inlinestatic

XWOS API：绑定线程栅栏到信号选择器

参数

[in]	br	线程栅栏对象的指针
[in]	sel	信号选择器的指针
[in]	pos	线程栅栏对象映射到位图中的位置

返回: 错误码

返回值

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

注解

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

当所有线程到达线程栅栏时，绑定了信号选择器的线程栅栏将向信号选择器发送信号。

在文件 br.h 第 286 行定义.

{
        return xwosdl_br_bind(&br->osbr, &sel->ossel, pos);
}

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

◆ xwos_br_unbind()

static xwer_t xwos_br_unbind	(	struct xwos_br *	br,
		struct xwos_sel *	sel
	)

inlinestatic

XWOS API：从信号选择器上解绑线程栅栏

参数

[in]	br	线程栅栏对象的指针
[in]	sel	信号选择器的指针

返回: 错误码

返回值

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

注解

上下文：任意

在文件 br.h 第 303 行定义.

{
        return xwosdl_br_unbind(&br->osbr, &sel->ossel);
}

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

◆ xwos_br_get_num()

static xwer_t xwos_br_get_num	(	struct xwos_br *	br,
		xwsz_t *	numbuf
	)

inlinestatic

XWOS API：获取线程栅栏中线程槽数量

参数

[in]	br	线程栅栏对象的指针
[out]	numbuf	指向缓冲区的指针，通过此缓冲区返回线程槽数量

返回: 错误码

返回值

XWOK	没有错误
-EFAULT	空指针

注解

上下文：任意

在文件 br.h 第 319 行定义.

{
        return xwosdl_br_get_num(&br->osbr, numbuf);
}

◆ xwos_br_wait()

static xwer_t xwos_br_wait ( struct xwos_br * br )

inlinestatic

XWOS API：等待所有线程到达栅栏

参数

[in] br 线程栅栏对象的指针

返回: 错误码

返回值

XWOK	没有错误
-EFAULT	无效的指针或空指针
-ECHRNG	线程数量超出范围
-EINTR	等待被中断
-ENOTTHDCTX：不在线程上下文中

注解

上下文：线程

在文件 br.h 第 337 行定义.

{
        return xwosdl_br_wait(&br->osbr);
}

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

◆ xwos_br_wait_to()

static xwer_t xwos_br_wait_to	(	struct xwos_br *	br,
		xwtm_t	to
	)

inlinestatic

XWOS API：限时等待所有线程到达栅栏

参数

[in]	br	线程栅栏对象的指针
[in]	to	期望唤醒的时间点

返回: 错误码

返回值

XWOK	没有错误
-EFAULT	无效的指针或空指针
-ECHRNG	线程数量超出范围
-ETIMEDOUT	超时
-EINTR	等待被中断
-ENOTTHDCTX：不在线程上下文中

注解

上下文：线程

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

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

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

{
        return xwosdl_br_wait_to(&br->osbr, to);
}

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

◆ xwos_br_wait_unintr()

static xwer_t xwos_br_wait_unintr ( struct xwos_br * br )

inlinestatic

XWOS API：等待所有线程到达栅栏，且等待不可被中断

参数

[in] br 线程栅栏对象的指针

返回: 错误码

返回值

XWOK	没有错误
-EFAULT	无效的指针或空指针
-ECHRNG	线程数量超出范围
-EINTR	等待被中断
-ENOTTHDCTX：不在线程上下文中

注解

上下文：线程

在文件 br.h 第 380 行定义.

{
        return xwosdl_br_wait_unintr(&br->osbr);
}

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

结构体

宏定义

函数

详细描述

线程栅栏的静态初始化、销毁

线程栅栏的动态创建、删除

获取事件的状态

同步线程

使用信号选择器选择线程栅栏

线程栅栏对象的生命周期管理

对象描述符和对象标签

C++

宏定义说明

◆ XWOS_BR_NILD

函数说明

◆ xwos_br_init()

◆ xwos_br_fini()

◆ xwos_br_grab()

◆ xwos_br_put()

◆ xwos_br_create()

◆ xwos_br_delete()

◆ xwos_br_acquire()

◆ xwos_br_release()

◆ xwos_br_get_tik()

◆ xwos_br_get_d()

◆ xwos_br_bind()

◆ xwos_br_unbind()

◆ xwos_br_get_num()

◆ xwos_br_wait()

◆ xwos_br_wait_to()

◆ xwos_br_wait_unintr()