信号量的协作图:

结构体
struct	xwos_sem
	XWOS API：信号量对象更多...

struct	xwos_sem_d
	XWOS API：信号量对象描述符更多...

宏定义
#define	XWOS_SEM_NILD ((xwos_sem_d){NULL, 0,})
	XWOS API：空的信号量对象描述符

函数
static xwer_t	xwos_sem_init (struct xwos_sem *sem, xwssq_t val, xwssq_t max)
	XWOS API：静态方式初始化信号量对象

static xwer_t	xwos_sem_fini (struct xwos_sem *sem)
	XWOS API：销毁静态方式初始化的信号量对象

static xwer_t	xwos_sem_grab (struct xwos_sem *sem)
	XWOS API：增加信号量对象的引用计数

static xwer_t	xwos_sem_put (struct xwos_sem *sem)
	XWOS API：减少信号量对象的引用计数

static xwer_t	xwos_sem_create (xwos_sem_d *semd, xwssq_t val, xwssq_t max)
	XWOS API：动态方式创建信号量对象

static xwer_t	xwos_sem_delete (xwos_sem_d semd)
	XWOS API：删除动态方式创建的信号量对象

static xwer_t	xwos_sem_acquire (xwos_sem_d semd)
	XWOS API：检查信号量对象的标签并增加引用计数

static xwer_t	xwos_sem_release (xwos_sem_d semd)
	XWOS API：检查对象的标签并减少引用计数

static xwsq_t	xwos_sem_get_tik (struct xwos_sem *sem)
	XWOS API：获取信号量对象的标签

static xwos_sem_d	xwos_sem_get_d (struct xwos_sem *sem)
	XWOS API：获取信号量对象描述符

static xwer_t	xwos_sem_bind (struct xwos_sem sem, struct xwos_sel sel, xwsq_t pos)
	XWOS API：绑定信号量对象到信号选择器

static xwer_t	xwos_sem_unbind (struct xwos_sem sem, struct xwos_sel sel)
	XWOS API：从信号选择器上解绑信号量对象

static xwer_t	xwos_sem_freeze (struct xwos_sem *sem)
	XWOS API：冻结信号量对象

static xwer_t	xwos_sem_thaw (struct xwos_sem *sem)
	XWOS API：解冻信号量对象

static xwer_t	xwos_sem_post (struct xwos_sem *sem)
	XWOS API：发布信号量

static xwer_t	xwos_sem_wait (struct xwos_sem *sem)
	XWOS API：等待并获取信号量

static xwer_t	xwos_sem_wait_to (struct xwos_sem *sem, xwtm_t to)
	XWOS API：限时等待并获取信号量

static xwer_t	xwos_sem_wait_unintr (struct xwos_sem *sem)
	XWOS API：等待并获取信号量，且等待不可被中断

static xwer_t	xwos_sem_trywait (struct xwos_sem *sem)
	XWOS API：尝试获取信号量

static xwer_t	xwos_sem_get_max (struct xwos_sem sem, xwssq_t max)
	XWOS API：获取信号量对象计数器的最大值

static xwer_t	xwos_sem_get_value (struct xwos_sem sem, xwssq_t val)
	XWOS API：获取信号量对象计数器的值

详细描述

技术参考手册：信号量

信号量的静态初始化、销毁

xwos_sem_init() ：静态初始化
xwos_sem_fini() ：销毁

信号量的动态创建、删除

xwos_sem_create() ：动态创建
xwos_sem_delete() ：删除

发布信号量

xwos_sem_post() ：发布信号量，可在任意上下文使用

等待信号量

xwos_sem_wait() ：等待信号量，只能在线程上下文使用
xwos_sem_wait_to() ：限时等待信号量，只能在线程上下文使用
xwos_sem_wait_unintr() ：不可中断地等待信号量，只能在线程上下文使用
xwos_sem_trywait() ：仅测试信号量，可在任意上下文使用

获取信号量的状态

xwos_sem_get_max() ：获取信号量中计数器的最大值，可在任意上下文使用
xwos_sem_get_value() ：获取信号量中计数器的值，可在任意上下文使用

冻结与解冻信号量

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

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

xwos_sem_bind() ：将信号量绑定到信号选择器上
xwos_sem_unbind() ：从信号选择器上解绑

信号量对象的生命周期管理

通过 对象指针 管理生命周期：
- xwos_sem_grab() ：增加引用计数
- xwos_sem_put() ：减少引用计数
通过 对象描述符 管理生命周期：
- xwos_sem_acquire() ：增加引用计数
- xwos_sem_release() ：减少引用计数

对象描述符和对象标签

已知信号量对象的指针的情况下，可以通过 xwos_sem_get_d() 获取 xwos_sem_d ，或可以通过 xwos_sem_get_tik() 获取对象标签。

C++

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

宏定义说明

◆ XWOS_SEM_NILD

#define XWOS_SEM_NILD ((xwos_sem_d){NULL, 0,})

XWOS API：空的信号量对象描述符

在文件 sem.h 第 110 行定义.

函数说明

◆ xwos_sem_acquire()

static xwer_t xwos_sem_acquire ( xwos_sem_d semd )

inlinestatic

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

参数

[in] semd 信号量对象描述符

返回: 错误码

返回值

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

注解

上下文：任意

在文件 sem.h 第 229 行定义.

{
        return xwosdl_sem_acquire(&semd.sem->ossem, semd.tik);
}

◆ xwos_sem_bind()

static xwer_t xwos_sem_bind	(	struct xwos_sem *	sem,
		struct xwos_sel *	sel,
		xwsq_t	pos
	)

inlinestatic

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

参数

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

返回: 错误码

返回值

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

注解

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

在文件 sem.h 第 297 行定义.

{
        return xwosdl_sem_bind(&sem->ossem, &sel->ossel, pos);
}

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

◆ xwos_sem_create()

static xwer_t xwos_sem_create	(	xwos_sem_d *	semd,
		xwssq_t	val,
		xwssq_t	max
	)

inlinestatic

XWOS API：动态方式创建信号量对象

参数

[out]	semd	指向缓冲区的指针，通过此缓冲区返回信号量对象描述符
[in]	val	信号量的初始值
[in]	max	信号量的最大值

返回: 错误码

返回值

XWOK	没有错误
-EFAULT	空指针
-EINVAL	无效参数
-ENOMEM	内存不足

注解

上下文：任意

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

{
        return xwosdl_sem_create((xwosdl_sem_d *)semd, val, max);
}

◆ xwos_sem_delete()

static xwer_t xwos_sem_delete ( xwos_sem_d semd )

inlinestatic

XWOS API：删除动态方式创建的信号量对象

参数

[in] semd 信号量对象描述符

返回: 错误码

返回值

XWOK	没有错误
-EFAULT	空指针

注解

上下文：任意

在文件 sem.h 第 212 行定义.

{
        return xwosdl_sem_delete(&semd.sem->ossem, semd.tik);
}

◆ xwos_sem_fini()

static xwer_t xwos_sem_fini ( struct xwos_sem * sem )

inlinestatic

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

参数

[in] sem 信号量对象的指针

返回: 错误码

返回值

XWOK	没有错误
-EFAULT	空指针

注解

上下文：任意

在文件 sem.h 第 140 行定义.

{
        return xwosdl_sem_fini(&sem->ossem);
}

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

◆ xwos_sem_freeze()

static xwer_t xwos_sem_freeze ( struct xwos_sem * sem )

inlinestatic

XWOS API：冻结信号量对象

参数

[in] sem 信号量对象的指针

返回: 错误码

返回值

XWOK	没有错误
-EFAULT	空指针
-EALREADY	信号量对象已被冻结

注解

上下文：任意

被冻结的信号量对象不允许增加(V操作)，但可以被测试(P操作)。测试信号量对象的线程会被加入到信号量对象的等待队列。

对已经冻结的信号量再次冻结，将返回 -EALREADY 。

在文件 sem.h 第 335 行定义.

{
        return xwosdl_sem_freeze(&sem->ossem);
}

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

◆ xwos_sem_get_d()

static xwos_sem_d xwos_sem_get_d ( struct xwos_sem * sem )

inlinestatic

XWOS API：获取信号量对象描述符

参数

[in] sem 信号量对象的指针

返回: 信号量对象描述符

注解

上下文：任意

在文件 sem.h 第 272 行定义.

{
        xwos_sem_d semd;
 
        semd.sem = sem;
        semd.tik = xwosdl_sem_get_tik(&sem->ossem);
        return semd;
}

◆ xwos_sem_get_max()

static xwer_t xwos_sem_get_max	(	struct xwos_sem *	sem,
		xwssq_t *	max
	)

inlinestatic

XWOS API：获取信号量对象计数器的最大值

参数

[in]	sem	信号量对象的指针
[out]	max	指向缓冲区的指针，通过此缓冲区返回信号量对象计数器的最大值

返回: 错误码

返回值

XWOK	没有错误
-EFAULT	空指针

注解

上下文：任意

在文件 sem.h 第 470 行定义.

{
        return xwosdl_sem_get_max(&sem->ossem, max);
}

◆ xwos_sem_get_tik()

static xwsq_t xwos_sem_get_tik ( struct xwos_sem * sem )

inlinestatic

XWOS API：获取信号量对象的标签

参数

[in] sem 信号量对象的指针

返回: 信号量对象的标签

注解

上下文：任意

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

{
        return xwosdl_sem_get_tik(&sem->ossem);
}

◆ xwos_sem_get_value()

static xwer_t xwos_sem_get_value	(	struct xwos_sem *	sem,
		xwssq_t *	val
	)

inlinestatic

XWOS API：获取信号量对象计数器的值

参数

[in]	sem	信号量对象的指针
[out]	val	指向缓冲区的指针，通过此缓冲区返回信号量对象计数器的值

返回: 错误码

返回值

XWOK	没有错误
-EFAULT	空指针

注解

上下文：任意

在文件 sem.h 第 486 行定义.

{
        return xwosdl_sem_get_value(&sem->ossem, val);
}

◆ xwos_sem_grab()

static xwer_t xwos_sem_grab ( struct xwos_sem * sem )

inlinestatic

XWOS API：增加信号量对象的引用计数

参数

[in] sem 信号量对象的指针

返回: 错误码

返回值

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

注解

上下文：任意

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

在文件 sem.h 第 159 行定义.

{
        return xwosdl_sem_grab(&sem->ossem);
}

◆ xwos_sem_init()

static xwer_t xwos_sem_init	(	struct xwos_sem *	sem,
		xwssq_t	val,
		xwssq_t	max
	)

inlinestatic

XWOS API：静态方式初始化信号量对象

参数

[in]	sem	信号量对象的指针
[in]	val	信号量的初始值
[in]	max	信号量的最大值

返回: 错误码

返回值

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

注解

上下文：任意

在文件 sem.h 第 125 行定义.

{
        return xwosdl_sem_init(&sem->ossem, val, max);
}

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

◆ xwos_sem_post()

static xwer_t xwos_sem_post ( struct xwos_sem * sem )

inlinestatic

XWOS API：发布信号量

参数

[in] sem 信号量对象的指针

返回: 错误码

返回值

XWOK	没有错误
-EFAULT	空指针
-ENEGATIVE	信号量对象已被冻结
-ERANGE	信号量对象的值已经最大

注解

上下文：任意

此函数只对未冻结的信号量对象起作用，已冻结的信号量对象将得到错误码 -ENEGATIVE 。

在文件 sem.h 第 373 行定义.

{
        return xwosdl_sem_post(&sem->ossem);
}

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

◆ xwos_sem_put()

static xwer_t xwos_sem_put ( struct xwos_sem * sem )

inlinestatic

XWOS API：减少信号量对象的引用计数

参数

[in] sem 信号量对象的指针

返回: 错误码

返回值

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

注解

上下文：任意

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

在文件 sem.h 第 178 行定义.

{
        return xwosdl_sem_put(&sem->ossem);
}

◆ xwos_sem_release()

static xwer_t xwos_sem_release ( xwos_sem_d semd )

inlinestatic

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

参数

[in] semd 信号量对象描述符

返回: 错误码

返回值

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

注解

上下文：任意

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

{
        return xwosdl_sem_release(&semd.sem->ossem, semd.tik);
}

◆ xwos_sem_thaw()

static xwer_t xwos_sem_thaw ( struct xwos_sem * sem )

inlinestatic

XWOS API：解冻信号量对象

参数

[in] sem 信号量对象的指针

返回: 错误码

返回值

XWOK	没有错误
-EFAULT	空指针
-EALREADY	信号量对象未被冻结

注解

上下文：任意

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

在文件 sem.h 第 354 行定义.

{
        return xwosdl_sem_thaw(&sem->ossem);
}

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

◆ xwos_sem_trywait()

static xwer_t xwos_sem_trywait ( struct xwos_sem * sem )

inlinestatic

XWOS API：尝试获取信号量

参数

[in] sem 信号量对象的指针

返回: 错误码

返回值

XWOK	没有错误
-EFAULT	空指针
-ENODATA	信号量对象资源不可用（信号量对象无法被获取）

注解

上下文：任意

若没有检测到信号，立即返回错误码 -ENODATA ，不会阻塞。

在文件 sem.h 第 454 行定义.

{
        return xwosdl_sem_trywait(&sem->ossem);
}

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

◆ xwos_sem_unbind()

static xwer_t xwos_sem_unbind	(	struct xwos_sem *	sem,
		struct xwos_sel *	sel
	)

inlinestatic

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

参数

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

返回: 错误码

返回值

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

注解

上下文：任意

在文件 sem.h 第 314 行定义.

{
        return xwosdl_sem_unbind(&sem->ossem, &sel->ossel);
}

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

◆ xwos_sem_wait()

static xwer_t xwos_sem_wait ( struct xwos_sem * sem )

inlinestatic

XWOS API：等待并获取信号量

参数

[in] sem 信号量对象的指针

返回: 错误码

返回值

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

注解

上下文：线程

在文件 sem.h 第 392 行定义.

{
        return xwosdl_sem_wait(&sem->ossem);
}

◆ xwos_sem_wait_to()

static xwer_t xwos_sem_wait_to	(	struct xwos_sem *	sem,
		xwtm_t	to
	)

inlinestatic

XWOS API：限时等待并获取信号量

参数

[in]	sem	信号量对象的指针
[in]	to	期望唤醒的时间点

返回: 错误码

返回值

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

注解

上下文：线程

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

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

在文件 sem.h 第 418 行定义.

{
        return xwosdl_sem_wait_to(&sem->ossem, to);
}

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

◆ xwos_sem_wait_unintr()

static xwer_t xwos_sem_wait_unintr ( struct xwos_sem * sem )

inlinestatic

XWOS API：等待并获取信号量，且等待不可被中断

参数

[in] sem 信号量对象的指针

返回: 错误码

返回值

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

注解

上下文：线程

在文件 sem.h 第 436 行定义.

{
        return xwosdl_sem_wait_unintr(&sem->ossem);
}

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

结构体

宏定义

函数

详细描述

信号量的静态初始化、销毁

信号量的动态创建、删除

发布信号量

等待信号量

获取信号量的状态

冻结与解冻信号量

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

信号量对象的生命周期管理

对象描述符和对象标签

C++

宏定义说明

◆ XWOS_SEM_NILD

函数说明

◆ xwos_sem_acquire()

◆ xwos_sem_bind()

◆ xwos_sem_create()

◆ xwos_sem_delete()

◆ xwos_sem_fini()

◆ xwos_sem_freeze()

◆ xwos_sem_get_d()

◆ xwos_sem_get_max()

◆ xwos_sem_get_tik()

◆ xwos_sem_get_value()

◆ xwos_sem_grab()

◆ xwos_sem_init()

◆ xwos_sem_post()

◆ xwos_sem_put()

◆ xwos_sem_release()

◆ xwos_sem_thaw()

◆ xwos_sem_trywait()

◆ xwos_sem_unbind()

◆ xwos_sem_wait()

◆ xwos_sem_wait_to()

◆ xwos_sem_wait_unintr()