互斥锁

互斥锁 的协作图:

结构体
struct	xwos_mtx
	XWOS API：互斥锁 更多...
struct	xwos_mtx_d
	XWOS API：互斥锁对象描述符 更多...

宏定义
#define	XWOS_MTX_NILD   ((xwos_mtx_d){NULL, 0,})
	XWOS API：空的互斥锁对象描述符

函数
static xwer_t	xwos_mtx_init (struct xwos_mtx *mtx, xwpr_t sprio)
	XWOS API：静态方式初始化互斥锁
static xwer_t	xwos_mtx_fini (struct xwos_mtx *mtx)
	XWOS API：销毁静态方式初始化的互斥锁
static xwer_t	xwos_mtx_grab (struct xwos_mtx *mtx)
	XWOS API：增加互斥锁对象的引用计数
static xwer_t	xwos_mtx_put (struct xwos_mtx *mtx)
	XWOS API：减少互斥锁对象的引用计数
static xwer_t	xwos_mtx_create (xwos_mtx_d *mtxd, xwpr_t sprio)
	XWOS API：动态方式创建互斥锁
static xwer_t	xwos_mtx_delete (xwos_mtx_d mtxd)
	XWOS API：删除动态方式创建的互斥锁
static xwer_t	xwos_mtx_acquire (xwos_mtx_d mtxd)
	XWOS API：检查互斥锁对象的标签并增加引用计数
static xwer_t	xwos_mtx_release (xwos_mtx_d mtxd)
	XWOS API：检查对象的标签并减少引用计数
static xwsq_t	xwos_mtx_get_tik (struct xwos_mtx *mtx)
	XWOS API：获取互斥锁对象的标签
static xwos_mtx_d	xwos_mtx_get_d (struct xwos_mtx *mtx)
	XWOS API：获取互斥锁对象的描述符
static xwer_t	xwos_mtx_unlock (struct xwos_mtx *mtx)
	XWOS API：解锁互斥锁
static xwer_t	xwos_mtx_lock (struct xwos_mtx *mtx)
	XWOS API：等待并上锁互斥锁
static xwer_t	xwos_mtx_lock_to (struct xwos_mtx *mtx, xwtm_t to)
	XWOS API：限时等待上锁互斥锁
static xwer_t	xwos_mtx_lock_unintr (struct xwos_mtx *mtx)
	XWOS API：等待并上锁互斥锁，且等待不可被中断
static xwer_t	xwos_mtx_trylock (struct xwos_mtx *mtx)
	XWOS API：尝试上锁互斥锁，不会阻塞调用线程
static xwer_t	xwos_mtx_get_status (struct xwos_mtx *mtx, xwsq_t *lkst)
	XWOS API：获取锁的状态

详细描述

技术参考手册： 互斥锁

互斥锁的静态初始化、销毁

• xwos_mtx_init() ：静态初始化
• xwos_mtx_fini() ：销毁

互斥锁的动态创建、删除

• xwos_mtx_create() ：动态创建
• xwos_mtx_delete() ：删除

解锁

• xwos_mtx_unlock() ：解锁互斥锁，只能在 线程 上下文使用

上锁

• xwos_mtx_lock() ：等待并上锁互斥锁，只能在 线程 上下文使用
• xwos_mtx_lock_to() ：限时等待并上锁互斥锁，只能在 线程 上下文使用
• xwos_mtx_lock_unintr() ：不可中断地等待并上锁互斥锁，只能在 线程 上下文使用
• xwos_mtx_trylock() ：尝试上锁互斥锁，只能在 线程 上下文使用

获取锁状态

• xwos_mtx_get_status() ：获取锁的状态，可在 任意 上下文使用

互斥锁对象的生命周期管理

• 通过 对象指针 管理生命周期：
  • xwos_mtx_grab() ：增加引用计数
  • xwos_mtx_put() ：减少引用计数
• 通过 对象描述符 管理生命周期：
  • xwos_mtx_acquire() ：增加引用计数
  • xwos_mtx_release() ：减少引用计数

对象描述符和对象标签

已知互斥锁对象的指针的情况下，可以通过 xwos_mtx_get_d() 获取 xwos_mtx_d ， 或可以通过 xwos_mtx_get_tik() 获取对象标签。

C++

C++头文件： xwos/osal/lock/mtx.hxx

宏定义说明

XWOS_MTX_NILD

#define XWOS_MTX_NILD   ((xwos_mtx_d){NULL, 0,})

XWOS API：空的互斥锁对象描述符

在文件 mtx.h 第 97 行定义.

函数说明

xwos_mtx_acquire()

static xwer_t xwos_mtx_acquire ( xwos_mtx_d  mtxd )

inlinestatic

XWOS API：检查互斥锁对象的标签并增加引用计数

参数

[in]

mtxd

互斥锁对象描述符

返回

错误码

返回值

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

注解

• 上下文：任意

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

{
        return xwosdl_mtx_acquire(&mtxd.mtx->osmtx, mtxd.tik);
}

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

xwos_mtx_create()

static xwer_t xwos_mtx_create ( xwos_mtx_d *  mtxd, xwpr_t  sprio  )

inlinestatic

XWOS API：动态方式创建互斥锁

参数

[out]	mtxd	指向缓冲区的指针，通过此缓冲区返回互斥锁对象描述符
[in]	sprio	互斥锁的静态优先级

返回

错误码

返回值

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

注解

• 上下文：任意

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

{
        return xwosdl_mtx_create((xwosdl_mtx_d *)mtxd, sprio);
}

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

xwos_mtx_delete()

static xwer_t xwos_mtx_delete ( xwos_mtx_d  mtxd )

inlinestatic

XWOS API：删除动态方式创建的互斥锁

参数

[in]

mtxd

互斥锁对象描述符

返回

错误码

返回值

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

注解

• 上下文：任意

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

{
        return xwosdl_mtx_delete(&mtxd.mtx->osmtx, mtxd.tik);
}

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

xwos_mtx_fini()

static xwer_t xwos_mtx_fini ( struct xwos_mtx *  mtx )

inlinestatic

XWOS API：销毁静态方式初始化的互斥锁

参数

[in]

mtx

互斥锁的指针

返回

错误码

返回值

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

注解

• 上下文：任意

在文件 mtx.h 第 126 行定义.

{
        return xwosdl_mtx_fini(&mtx->osmtx);
}

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

xwos_mtx_get_d()

static xwos_mtx_d xwos_mtx_get_d ( struct xwos_mtx *  mtx )

inlinestatic

XWOS API：获取互斥锁对象的描述符

参数

[in]

mtx

互斥锁对象的指针

返回

互斥锁对象的描述符

注解

• 上下文：任意

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

{
        xwos_mtx_d mtxd;
 
        mtxd.mtx = mtx;
        mtxd.tik = xwosdl_mtx_get_tik(&mtx->osmtx);
        return mtxd;
}

xwos_mtx_get_status()

static xwer_t xwos_mtx_get_status ( struct xwos_mtx *  mtx, xwsq_t *  lkst  )

inlinestatic

XWOS API：获取锁的状态

参数

[in]	mtx	互斥锁对象的指针
[out]	status	指向缓冲区的指针，通过此缓冲区返回锁的状态

返回

错误码

返回值

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

注解

• 上下文：任意

在文件 mtx.h 第 387 行定义.

{
        return xwosdl_mtx_get_status(&mtx->osmtx, lkst);
}

xwos_mtx_get_tik()

static xwsq_t xwos_mtx_get_tik ( struct xwos_mtx *  mtx )

inlinestatic

XWOS API：获取互斥锁对象的标签

参数

[in]

mtx

互斥锁对象的指针

返回

互斥锁对象的标签

注解

• 上下文：任意

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

{
        return xwosdl_mtx_get_tik(&mtx->osmtx);
}

xwos_mtx_grab()

static xwer_t xwos_mtx_grab ( struct xwos_mtx *  mtx )

inlinestatic

XWOS API：增加互斥锁对象的引用计数

参数

[in]

mtx

互斥锁对象的指针

返回

错误码

返回值

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

注解

• 上下文：任意

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

在文件 mtx.h 第 145 行定义.

{
        return xwosdl_mtx_grab(&mtx->osmtx);
}

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

xwos_mtx_init()

static xwer_t xwos_mtx_init ( struct xwos_mtx *  mtx, xwpr_t  sprio  )

inlinestatic

XWOS API：静态方式初始化互斥锁

参数

[in]	mtx	互斥锁的指针
[in]	sprio	互斥锁的静态优先级

返回

错误码

返回值

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

注解

• 上下文：任意

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

{
        return xwosdl_mtx_init(&mtx->osmtx, sprio);
}

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

xwos_mtx_lock()

static xwer_t xwos_mtx_lock ( struct xwos_mtx *  mtx )

inlinestatic

XWOS API：等待并上锁互斥锁

参数

[in]

mtx

互斥锁对象的指针

返回

错误码

返回值

XWOK	没有错误
-EFAULT	无效的指针或空指针
-EOBJDEAD	互斥锁对象无效
-EINTR	等待被中断
-ENOTTHDCTX	不在线程上下文中
-EDSPMPT	抢占被关闭
-EDSBH	中断底半部被关闭

注解

• 上下文：线程

• 如果无法上锁，调用此CAPI的线程会阻塞等待，直到互斥锁可被上锁，或等待被中断。
• 线程的阻塞等待可能被中断，此时，API返回 -EINTR 。

在文件 mtx.h 第 302 行定义.

{
        return xwosdl_mtx_lock(&mtx->osmtx);
}

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

xwos_mtx_lock_to()

static xwer_t xwos_mtx_lock_to ( struct xwos_mtx *  mtx, xwtm_t  to  )

inlinestatic

XWOS API：限时等待上锁互斥锁

参数

[in]	mtx	互斥锁对象的指针
[in]	to	期望唤醒的时间点

返回

错误码

返回值

XWOK	没有错误
-EFAULT	无效的指针或空指针
-EOBJDEAD	互斥锁对象无效
-EINTR	等待被中断
-ETIMEDOUT	超时
-ENOTTHDCTX	不在线程上下文中
-EDSPMPT	抢占被关闭
-EDSBH	中断底半部被关闭

注解

• 上下文：线程

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

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

在文件 mtx.h 第 329 行定义.

{
        return xwosdl_mtx_lock_to(&mtx->osmtx, to);
}

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

xwos_mtx_lock_unintr()

static xwer_t xwos_mtx_lock_unintr ( struct xwos_mtx *  mtx )

inlinestatic

XWOS API：等待并上锁互斥锁，且等待不可被中断

参数

[in]

mtx

互斥锁对象的指针

返回

错误码

返回值

XWOK	没有错误
-EFAULT	无效的指针或空指针
-EOBJDEAD	互斥锁对象无效
-ENOTTHDCTX	不在线程上下文中
-EDSPMPT	抢占被关闭
-EDSBH	中断底半部被关闭

注解

• 上下文：线程

在文件 mtx.h 第 348 行定义.

{
        return xwosdl_mtx_lock_unintr(&mtx->osmtx);
}

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

xwos_mtx_put()

static xwer_t xwos_mtx_put ( struct xwos_mtx *  mtx )

inlinestatic

XWOS API：减少互斥锁对象的引用计数

参数

[in]

mtx

互斥锁对象的指针

返回

错误码

返回值

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

注解

• 上下文：任意

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

在文件 mtx.h 第 164 行定义.

{
        return xwosdl_mtx_put(&mtx->osmtx);
}

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

xwos_mtx_release()

static xwer_t xwos_mtx_release ( xwos_mtx_d  mtxd )

inlinestatic

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

参数

[in]

mtxd

互斥锁对象描述符

返回

错误码

返回值

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

注解

• 上下文：任意

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

{
        return xwosdl_mtx_release(&mtxd.mtx->osmtx, mtxd.tik);
}

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

xwos_mtx_trylock()

static xwer_t xwos_mtx_trylock ( struct xwos_mtx *  mtx )

inlinestatic

XWOS API：尝试上锁互斥锁，不会阻塞调用线程

参数

[in]

mtx

互斥锁对象的指针

返回

错误码

返回值

XWOK	没有错误
-EFAULT	无效的指针或空指针
-EOBJDEAD	互斥锁对象无效
-EWOULDBLOCK	尝试获取锁失败
-ENOTTHDCTX	不在线程上下文中

注解

• 上下文：线程

此函数虽然不会阻塞调用线程，但也不可在中断上下文中使用， 因为在OS中互斥锁通常需要记录自己的拥有者（一般是线程对象结构体）， 中断上下文不存在对应的线程对象结构体。

在文件 mtx.h 第 370 行定义.

{
        return xwosdl_mtx_trylock(&mtx->osmtx);
}

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

xwos_mtx_unlock()

static xwer_t xwos_mtx_unlock ( struct xwos_mtx *  mtx )

inlinestatic

XWOS API：解锁互斥锁

参数

[in]

mtx

互斥锁对象的指针

返回

错误码

返回值

XWOK	没有错误
-EFAULT	无效的指针或空指针
-EOBJDEAD	互斥锁对象无效
-EOWNER	线程并没有锁定此互斥锁
-ENOTTHDCTX	不在线程上下文中

注解

• 上下文：线程

在文件 mtx.h 第 279 行定义.

{
        return xwosdl_mtx_unlock(&mtx->osmtx);
}

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