条件量的协作图:

结构体
struct	xwos_cond
	XWOS API：条件量对象更多...

struct	xwos_cond_d
	XWOS API：条件量对象描述符更多...

宏定义
#define	XWOS_COND_NILD ((xwos_cond_d){NULL, 0,})
	XWOS API：空的条件量对象描述符

函数
static xwer_t	xwos_cond_init (struct xwos_cond *cond)
	XWOS API：静态方式初始化条件量对象

static xwer_t	xwos_cond_fini (struct xwos_cond *cond)
	XWOS API：销毁静态方式初始化的条件量对象

static xwer_t	xwos_cond_grab (struct xwos_cond *cond)
	XWOS API：增加条件量对象的引用计数

static xwer_t	xwos_cond_put (struct xwos_cond *cond)
	XWOS API：减少条件量对象的引用计数

static xwer_t	xwos_cond_create (xwos_cond_d *condd)
	XWOS API：动态方式创建条件量对象

static xwer_t	xwos_cond_delete (xwos_cond_d condd)
	XWOS API：删除动态方式创建的条件量对象

static xwer_t	xwos_cond_acquire (xwos_cond_d condd)
	XWOS API：检查条件量对象的标签并增加引用计数

static xwer_t	xwos_cond_release (xwos_cond_d condd)
	XWOS API：检查对象的标签并减少引用计数

static xwsq_t	xwos_cond_get_tik (struct xwos_cond *cond)
	XWOS API：获取条件量对象的标签

static xwos_cond_d	xwos_cond_get_d (struct xwos_cond *cond)
	XWOS API：获取条件量对象描述符

static xwer_t	xwos_cond_bind (struct xwos_cond cond, struct xwos_sel sel, xwsq_t pos)
	XWOS API：绑定条件量对象到信号选择器

static xwer_t	xwos_cond_unbind (struct xwos_cond cond, struct xwos_sel sel)
	XWOS API：从信号选择器上解绑条件量对象

static xwer_t	xwos_cond_freeze (struct xwos_cond *cond)
	XWOS API：冻结条件量对象

static xwer_t	xwos_cond_thaw (struct xwos_cond *cond)
	XWOS API：解冻条件量对象

static xwer_t	xwos_cond_broadcast (struct xwos_cond *cond)
	XWOS API：广播条件量对象

static xwer_t	xwos_cond_unicast (struct xwos_cond *cond)
	XWOS API：单播条件量对象

static xwer_t	xwos_cond_wait (struct xwos_cond cond, union xwos_ulock lock, xwsq_t lktype, void lkdata, xwsq_t *lkst)
	XWOS API：等待条件量

static xwer_t	xwos_cond_wait_to (struct xwos_cond cond, union xwos_ulock lock, xwsq_t lktype, void lkdata, xwtm_t to, xwsq_t *lkst)
	XWOS API：限时等待条件量

static xwer_t	xwos_cond_wait_unintr (struct xwos_cond cond, union xwos_ulock lock, xwsq_t lktype, void lkdata, xwsq_t *lkst)
	XWOS API：不可中断地等待条件量

详细描述

技术参考手册：条件量

条件量的静态初始化、销毁

xwos_cond_init() ：静态初始化
xwos_cond_fini() ：销毁

条件量的动态创建、删除

xwos_cond_create() ：动态创建
xwos_cond_delete() ：删除

触发条件量

xwos_cond_unicast() ：单播条件量，可在任意上下文使用
xwos_cond_broadcast() ：广播条件量，可在任意上下文使用

等待条件量

xwos_cond_wait() ：等待条件量，只能在线程上下文使用
xwos_cond_wait_to() ：限时等待条件量，只能在线程上下文使用
xwos_cond_wait_unintr() ：不可中断地等待条件量，只能在线程上下文使用

冻结与解冻条件量

xwos_cond_freeze() ：冻结，可在任意上下文使用
xwos_cond_thaw() ：解冻，可在任意上下文使用

使用信号选择器选择条件量

xwos_cond_bind() ：绑定条件量到信号选择器
xwos_cond_unbind() ：从信号选择器上解绑条件量

条件量对象的生命周期管理

通过 对象指针 管理生命周期：
- xwos_cond_grab() ：增加引用计数
- xwos_cond_put() ：减少引用计数
通过 对象描述符 管理生命周期：
- xwos_cond_acquire() ：增加引用计数
- xwos_cond_release() ：减少引用计数

对象描述符和对象标签

已知条件量对象指针的情况下，可以通过 xwos_cond_get_d() 获取 xwos_cond_d ，或可以通过 xwos_cond_get_tik() 获取对象标签。

C++

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

宏定义说明

◆ XWOS_COND_NILD

#define XWOS_COND_NILD ((xwos_cond_d){NULL, 0,})

XWOS API：空的条件量对象描述符

在文件 cond.h 第 106 行定义.

函数说明

◆ xwos_cond_acquire()

static xwer_t xwos_cond_acquire ( xwos_cond_d condd )

inlinestatic

XWOS API：检查条件量对象的标签并增加引用计数

参数

[in] condd 条件量对象描述符

返回: 错误码

返回值

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

注解

上下文：任意

在文件 cond.h 第 218 行定义.

{
        return xwosdl_cond_acquire(&condd.cond->oscond, condd.tik);
}

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

◆ xwos_cond_bind()

static xwer_t xwos_cond_bind	(	struct xwos_cond *	cond,
		struct xwos_sel *	sel,
		xwsq_t	pos
	)

inlinestatic

XWOS API：绑定条件量对象到信号选择器

参数

[in]	cond	条件量对象的指针
[in]	sel	信号选择器的指针
[in]	pos	条件量对象映射到位图中的位置

返回: 错误码

返回值

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

注解

上下文：任意
绑定方式：非独占绑定
绑定了信号选择器的条件量对象，只有广播才会向信号选择器发送信号。

在文件 cond.h 第 287 行定义.

{
        return xwosdl_cond_bind(&cond->oscond, &sel->ossel, pos);
}

◆ xwos_cond_broadcast()

static xwer_t xwos_cond_broadcast ( struct xwos_cond * cond )

inlinestatic

XWOS API：广播条件量对象

参数

[in] cond 条件量对象的指针

返回: 错误码

返回值

XWOK	没有错误
-EFAULT	无效的指针或空指针
-ENEGATIVE	条件量对象已被冻结

注解

上下文：任意

广播条件量会唤醒所有等待的线程。
此CAPI只对未冻结的条件量对象起作用，已冻结的条件量对象将返回错误码 -ENEGATIVE 。

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

{
        return xwosdl_cond_broadcast(&cond->oscond);
}

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

◆ xwos_cond_create()

static xwer_t xwos_cond_create ( xwos_cond_d * condd )

inlinestatic

XWOS API：动态方式创建条件量对象

参数

[out] condd 指向缓冲区的指针，通过此缓冲区返回条件量对象描述符

返回: 错误码

返回值

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

注解

上下文：任意

在文件 cond.h 第 186 行定义.

{
        return xwosdl_cond_create((xwosdl_cond_d *)condd);
}

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

◆ xwos_cond_delete()

static xwer_t xwos_cond_delete ( xwos_cond_d condd )

inlinestatic

XWOS API：删除动态方式创建的条件量对象

参数

[in] condd 条件量对象描述符

返回: 错误码

返回值

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

注解

上下文：任意

在文件 cond.h 第 201 行定义.

{
        return xwosdl_cond_delete(&condd.cond->oscond, condd.tik);
}

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

◆ xwos_cond_fini()

static xwer_t xwos_cond_fini ( struct xwos_cond * cond )

inlinestatic

XWOS API：销毁静态方式初始化的条件量对象

参数

[in] cond 条件量对象的指针

返回: 错误码

返回值

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

注解

上下文：任意

在文件 cond.h 第 133 行定义.

{
        return xwosdl_cond_fini(&cond->oscond);
}

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

◆ xwos_cond_freeze()

static xwer_t xwos_cond_freeze ( struct xwos_cond * cond )

inlinestatic

XWOS API：冻结条件量对象

参数

[in] cond 条件量对象的指针

返回: 错误码

返回值

XWOK	没有错误
-EFAULT	无效的指针或空指针
-EALREADY	条件量对象已被冻结

注解

上下文：任意

已冻结的条件量不允许单播或广播，但可以被线程等待。
对已经冻结的条件量再次冻结，将返回 -EALREADY 。

在文件 cond.h 第 323 行定义.

{
        return xwosdl_cond_freeze(&cond->oscond);
}

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

◆ xwos_cond_get_d()

static xwos_cond_d xwos_cond_get_d ( struct xwos_cond * cond )

inlinestatic

XWOS API：获取条件量对象描述符

参数

[in] cond 条件量对象的指针

返回: 条件量对象描述符

注解

上下文：任意

在文件 cond.h 第 261 行定义.

{
        xwos_cond_d condd;
 
        condd.cond = cond;
        condd.tik = xwosdl_cond_get_tik(&cond->oscond);
        return condd;
}

◆ xwos_cond_get_tik()

static xwsq_t xwos_cond_get_tik ( struct xwos_cond * cond )

inlinestatic

XWOS API：获取条件量对象的标签

参数

[in] cond 条件量对象的指针

返回: 条件量对象的标签

注解

上下文：任意

在文件 cond.h 第 248 行定义.

{
        return xwosdl_cond_get_tik(&cond->oscond);
}

◆ xwos_cond_grab()

static xwer_t xwos_cond_grab ( struct xwos_cond * cond )

inlinestatic

XWOS API：增加条件量对象的引用计数

参数

[in] cond 条件量对象的指针

返回: 错误码

返回值

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

注解

上下文：任意

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

在文件 cond.h 第 152 行定义.

{
        return xwosdl_cond_grab(&cond->oscond);
}

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

◆ xwos_cond_init()

static xwer_t xwos_cond_init ( struct xwos_cond * cond )

inlinestatic

XWOS API：静态方式初始化条件量对象

参数

[in] cond 条件量对象的指针

返回: 错误码

返回值

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

注解

上下文：任意

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

{
        return xwosdl_cond_init(&cond->oscond);
}

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

◆ xwos_cond_put()

static xwer_t xwos_cond_put ( struct xwos_cond * cond )

inlinestatic

XWOS API：减少条件量对象的引用计数

参数

[in] cond 条件量对象的指针

返回: 错误码

返回值

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

注解

上下文：任意

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

在文件 cond.h 第 171 行定义.

{
        return xwosdl_cond_put(&cond->oscond);
}

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

◆ xwos_cond_release()

static xwer_t xwos_cond_release ( xwos_cond_d condd )

inlinestatic

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

参数

[in] condd 条件量对象描述符

返回: 错误码

返回值

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

注解

上下文：任意

在文件 cond.h 第 235 行定义.

{
        return xwosdl_cond_release(&condd.cond->oscond, condd.tik);
}

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

◆ xwos_cond_thaw()

static xwer_t xwos_cond_thaw ( struct xwos_cond * cond )

inlinestatic

XWOS API：解冻条件量对象

参数

[in] cond 条件量对象的指针

返回: 错误码

返回值

XWOK	没有错误
-EFAULT	无效的指针或空指针
-EALREADY	条件量对象未被冻结

注解

上下文：任意

此函数只对已冻结的条件量对象起作用，对未冻结的条件量对象调用此函数将返回错误码 -EALREADY 。

在文件 cond.h 第 342 行定义.

{
        return xwosdl_cond_thaw(&cond->oscond);
}

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

◆ xwos_cond_unbind()

static xwer_t xwos_cond_unbind	(	struct xwos_cond *	cond,
		struct xwos_sel *	sel
	)

inlinestatic

XWOS API：从信号选择器上解绑条件量对象

参数

[in]	cond	条件量对象的指针
[in]	sel	信号选择器的指针

返回: 错误码

返回值

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

注解

上下文：任意

在文件 cond.h 第 304 行定义.

{
        return xwosdl_cond_unbind(&cond->oscond, &sel->ossel);
}

◆ xwos_cond_unicast()

static xwer_t xwos_cond_unicast ( struct xwos_cond * cond )

inlinestatic

XWOS API：单播条件量对象

参数

[in] cond 条件量对象的指针

返回: 错误码

返回值

XWOK	没有错误
-EFAULT	无效的指针或空指针
-ENEGATIVE	条件量对象已被冻结

注解

上下文：任意

单播条件量会唤醒第一个等待的线程。
此CAPI只对未冻结的条件量对象起作用，已冻结的条件量对象将返回错误码 -ENEGATIVE 。

在文件 cond.h 第 382 行定义.

{
        return xwosdl_cond_unicast(&cond->oscond);
}

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

◆ xwos_cond_wait()

static xwer_t xwos_cond_wait	(	struct xwos_cond *	cond,
		union xwos_ulock	lock,
		xwsq_t	lktype,
		void *	lkdata,
		xwsq_t *	lkst
	)

inlinestatic

XWOS API：等待条件量

参数

[in]	cond	条件量对象的指针
[in]	lock	锁
[in]	lktype	锁的类型，取值：xwos_lock_type_em
[in]	lkdata	锁的数据
[out]	lkst	指向缓冲区的指针，通过此缓冲区返回锁的状态 `XWOS_LKST_LOCKED` ：已上锁 `XWOS_LKST_UNLOCKED` ：未上锁

返回: 错误码

返回值

XWOK	没有错误
-EFAULT	无效的指针或空指针
-EINVAL	参数无效
-EINTR	等待被中断
-ENOTTHDCTX	不在线程上下文中

注解

上下文：线程

调用此CAPI的线程会阻塞等待条件量，等待的同时会解锁一个锁。
条件量被单播 xwos_cond_unicast() 或广播 xwos_cond_broadcast() 时，会唤醒正在等待的线程，线程会重新对锁进行上锁，上锁成功此CAPI返回 XWOK 。
重新上锁时，当锁类型是互斥锁时，若互斥锁被其他线程占用，将继续阻塞等待互斥锁。
所有类型的锁统一使用 union xwlk_ulock 指代，此联合中包含所有锁的定义，实际是一个指针，有些锁还需要伴生数据 lkdata ：
- XWOS_LK_MTX ：互斥锁
  - lock ：代表互斥锁（访问方式： lock.osal.mtx ）；
  - lockdata ：无作用，设置为 NULL 即可；
- XWOS_LK_SPLK ：自旋锁
  - lock ：代表自旋锁的指针（访问方式： lock.osal.splk ）；
  - lockdata ：无作用，设置为 NULL 即可；
- XWOS_LK_SQLK_WR ：顺序写锁
  - lock ：代表顺序锁的指针（访问方式： lock.osal.sqlk ）；
  - lockdata ：无作用，设置为 NULL 即可；
- XWOS_LK_SQLK_RDEX ：顺序独占读锁
  - lock ：代表顺序锁的指针（访问方式： lock.osal.sqlk ）；
  - lockdata ：无作用，设置为 NULL 即可；
- XWOS_LK_CALLBACK ：自定义的加锁与解锁函数
  - lock ：代表指向 struct xwlk_cblk 的指针（访问方式： lock.cb ）；
  - lockdata ：传递给 struct xwlk_cblk 中的 lock 与 unlock 函数的参数；
lkst 用于返回锁的状态。
- 此CAPI返回 XWOK 时，锁状态一定是 已上锁( XWOS_LKST_LOCKED ) 。
- 此CAPI返回其他错误码时，锁的状态不确定，需要通过返回值 lkst 查询。
线程的等待被中断后，此CAPI返回 -EINTR 。

在文件 cond.h 第 432 行定义.

{
        return xwosdl_cond_wait(&cond->oscond, lock, lktype, lkdata, lkst);
}

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

◆ xwos_cond_wait_to()

static xwer_t xwos_cond_wait_to	(	struct xwos_cond *	cond,
		union xwos_ulock	lock,
		xwsq_t	lktype,
		void *	lkdata,
		xwtm_t	to,
		xwsq_t *	lkst
	)

inlinestatic

XWOS API：限时等待条件量

参数

[in]	cond	条件量对象的指针
[in]	lock	锁
[in]	lktype	锁的类型，取值：xwos_lock_type_em
[in]	lkdata	锁的数据
[in]	to	期望唤醒的时间点
[out]	lkst	指向缓冲区的指针，通过此缓冲区返回锁的状态 `XWOS_LKST_LOCKED` ：已上锁 `XWOS_LKST_UNLOCKED` ：未上锁

返回: 错误码

返回值

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

注解

上下文：线程

调用此CAPI的线程会阻塞等待条件量，等待的同时会解锁一个锁。
条件量被单播 xwos_cond_unicast() 或广播 xwos_cond_broadcast() 时，会唤醒正在等待的线程，线程会重新对锁进行上锁，上锁成功此CAPI返回 XWOK 。
重新上锁时，当锁类型是互斥锁时，若互斥锁被其他线程占用，将继续阻塞等待互斥锁，直到超时的时间点 to 。
所有类型的锁统一使用 union xwlk_ulock 指代，此联合中包含所有锁的定义，实际是一个指针，有些锁还需要伴生数据 lkdata ：
- XWOS_LK_MTX ：互斥锁
  - lock ：代表互斥锁（访问方式： lock.osal.mtx ）；
  - lockdata ：无作用，设置为 NULL 即可；
- XWOS_LK_SPLK ：自旋锁
  - lock ：代表自旋锁的指针（访问方式： lock.osal.splk ）；
  - lockdata ：无作用，设置为 NULL 即可；
- XWOS_LK_SQLK_WR ：顺序写锁
  - lock ：代表顺序锁的指针（访问方式： lock.osal.sqlk ）；
  - lockdata ：无作用，设置为 NULL 即可；
- XWOS_LK_SQLK_RDEX ：顺序独占读锁
  - lock ：代表顺序锁的指针（访问方式： lock.osal.sqlk ）；
  - lockdata ：无作用，设置为 NULL 即可；
- XWOS_LK_CALLBACK ：自定义的加锁与解锁函数
  - lock ：代表指向 struct xwlk_cblk 的指针（访问方式： lock.cb ）；
  - lockdata ：传递给 struct xwlk_cblk 中的 lock 与 unlock 函数的参数；
to 表示等待超时的时间点：
- to 通常是未来的时间，即 当前系统时间 + delta ，可以使用 xwtm_ft(delta) 表示；
- 如果 to 是过去的时间点，此CAPI将直接返回 -ETIMEDOUT 。
lkst 用于返回锁的状态。
- 此CAPI返回 XWOK 时，锁状态一定是 已上锁( XWOS_LKST_LOCKED ) 。
- 此CAPI返回其他错误码时，锁的状态不确定，需要通过返回值 lkst 查询。
线程的等待被中断后，此CAPI返回 -EINTR 。
线程的等待超时后，此CAPI返回 -ETIMEDOUT 。

在文件 cond.h 第 492 行定义.

{
        return xwosdl_cond_wait_to(&cond->oscond, lock, lktype, lkdata, to, lkst);
}

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

◆ xwos_cond_wait_unintr()

static xwer_t xwos_cond_wait_unintr	(	struct xwos_cond *	cond,
		union xwos_ulock	lock,
		xwsq_t	lktype,
		void *	lkdata,
		xwsq_t *	lkst
	)

inlinestatic

XWOS API：不可中断地等待条件量

参数

[in]	cond	条件量对象的指针
[in]	lock	锁
[in]	lktype	锁的类型，取值：xwos_lock_type_em
[in]	lkdata	锁的数据
[out]	lkst	指向缓冲区的指针，通过此缓冲区返回锁的状态 `XWOS_LKST_LOCKED` ：已上锁 `XWOS_LKST_UNLOCKED` ：未上锁

返回: 错误码

返回值

XWOK	没有错误
-EFAULT	无效的指针或空指针
-EINVAL	参数无效
-ENOTTHDCTX	不在线程上下文中

注解

上下文：线程

调用此CAPI的线程会阻塞等待条件量，且等待不可被中断，等待的同时会解锁一个锁。
条件量被单播 xwos_cond_unicast() 或广播 xwos_cond_broadcast() 时，会唤醒正在等待的线程，线程会重新对锁进行上锁，上锁成功此CAPI返回 XWOK 。
重新上锁时，当锁类型是互斥锁时，若互斥锁被其他线程占用，将继续阻塞等待互斥锁，且使用CAPI xwos_mtx_lock_unitr() 进行等待。
所有类型的锁统一使用 union xwlk_ulock 指代，此联合中包含所有锁的定义，实际是一个指针，有些锁还需要伴生数据 lkdata ：
- XWOS_LK_MTX ：互斥锁
  - lock ：代表互斥锁（访问方式： lock.osal.mtx ）；
  - lockdata ：无作用，设置为 NULL 即可；
- XWOS_LK_SPLK ：自旋锁
  - lock ：代表自旋锁的指针（访问方式： lock.osal.splk ）；
  - lockdata ：无作用，设置为 NULL 即可；
- XWOS_LK_SQLK_WR ：顺序写锁
  - lock ：代表顺序锁的指针（访问方式： lock.osal.sqlk ）；
  - lockdata ：无作用，设置为 NULL 即可；
- XWOS_LK_SQLK_RDEX ：顺序独占读锁
  - lock ：代表顺序锁的指针（访问方式： lock.osal.sqlk ）；
  - lockdata ：无作用，设置为 NULL 即可；
- XWOS_LK_CALLBACK ：自定义的加锁与解锁函数
  - lock ：代表指向 struct xwlk_cblk 的指针（访问方式： lock.cb ）；
  - lockdata ：传递给 struct xwlk_cblk 中的 lock 与 unlock 函数的参数；
lkst 用于返回锁的状态。
- 此CAPI返回 XWOK 时，锁状态一定是 已上锁( XWOS_LKST_LOCKED ) 。
- 此CAPI返回其他错误码时，锁的状态不确定，需要通过返回值 lkst 查询。

在文件 cond.h 第 543 行定义.

{
        return xwosdl_cond_wait_unintr(&cond->oscond, lock, lktype, lkdata, lkst);
}

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

结构体

宏定义

函数

详细描述

条件量的静态初始化、销毁

条件量的动态创建、删除

触发条件量

等待条件量

冻结与解冻条件量

使用信号选择器选择条件量

条件量对象的生命周期管理

对象描述符和对象标签

C++

宏定义说明

◆ XWOS_COND_NILD

函数说明

◆ xwos_cond_acquire()

◆ xwos_cond_bind()

◆ xwos_cond_broadcast()

◆ xwos_cond_create()

◆ xwos_cond_delete()

◆ xwos_cond_fini()

◆ xwos_cond_freeze()

◆ xwos_cond_get_d()

◆ xwos_cond_get_tik()

◆ xwos_cond_grab()

◆ xwos_cond_init()

◆ xwos_cond_put()

◆ xwos_cond_release()

◆ xwos_cond_thaw()

◆ xwos_cond_unbind()

◆ xwos_cond_unicast()

◆ xwos_cond_wait()

◆ xwos_cond_wait_to()

◆ xwos_cond_wait_unintr()