静态互斥锁的RAII机制守卫更多...

#include <SMtx.hxx>

xwos::lock::SMtx::Grd 的协作图:

[图例]

Public 成员函数
	Grd ()=delete

	Grd (SMtx *mtx, enum LockMode mode=LockMode::SMtxLock, xwtm_t to=XWTM_MAX)
	构造静态互斥锁的RAII机制守卫并上锁互斥锁

	Grd (SMtx &mtx, enum LockMode mode=LockMode::SMtxLock, xwtm_t to=XWTM_MAX)
	构造静态互斥锁的RAII机制守卫并上锁互斥锁

	~Grd ()
	析构静态互斥锁的RAII机制守卫并解锁互斥锁

xwer_t	getRc ()
	获取上锁结果错误码

enum LockMode	getLockMode ()
	获取上锁模式

xwer_t	wait (sync::Cond *cond)
	等待条件量

xwer_t	wait (sync::Cond &cond)
	等待条件量

xwer_t	wait (sync::Cond *cond, xwtm_t to)
	限时等待条件量

xwer_t	wait (sync::Cond &cond, xwtm_t to)
	限时等待条件量

Private 属性
SMtx *	mMtx

xwer_t	mRc

enum LockMode	mLockMode

详细描述

静态互斥锁的RAII机制守卫

在文件 SMtx.hxx 第 93 行定义.

构造及析构函数说明

◆ Grd() [1/3]

xwos::lock::SMtx::Grd::Grd ( )

delete

◆ Grd() [2/3]

xwos::lock::SMtx::Grd::Grd	(	SMtx *	mtx,
		enum LockMode	mode = `LockMode::SMtxLock`,
		xwtm_t	to = `XWTM_MAX`
	)

构造静态互斥锁的RAII机制守卫并上锁互斥锁

参数

[in]	mtx	静态互斥锁对象指针
[in]	mode	锁模式，取值 SMtx::LockMode SMtx::LockMode::SMtxLock SMtx::LockMode::SMtxLockTimed SMtx::LockMode::SMtxLockUninterruptable SMtx::LockMode::SMtxLockTry
[in]	to	期望唤醒的时间点，仅当 `mode == SMtx::LockMode::SMtxLockTimed` 时有效。

注解

上下文：线程

上锁分为下列几种模式：
- SMtx::LockMode::SMtxunLock 未上锁。
- SMtx::LockMode::SMtxLock 如果无法上锁，调用线程会阻塞等待上锁。
- SMtx::LockMode::SMtxLockTimed 定时等待模式，如果无法上锁，调用线程会定时阻塞等待上锁。
- SMtx::LockMode::SMtxLockUninterruptable 不可中断等待模式，如果无法上锁，调用线程会阻塞等待上锁，且不可被中断。
- SMtx::LockMode::SMtxLockTry 尝试上锁模式，如果无法上锁，调用线程不会阻塞等待，尝试失败立即返回。
此C++API返回的是 SMtx::Grd 的对象。 SMtx::Grd 是静态互斥锁的RAII机制守卫。
如果上锁成功( SMtx::Grd 内部的 mRc == XWOK )， SMtx::Grd 对象析构时会自动解锁互斥锁。
如果上锁失败，错误码存放在 SMtx::Grd 内部的 mRc ，可通过 SMtx::Grd::getRc() 获取。此时 SMtx::Grd 析构时不会解锁互斥锁。
当 mode 为 SMtx::LockMode::SMtxLock 或 SMtx::LockMode::SMtxLockTimed ,等待被中断时， mRc == -EINTR 。
当 mode 为 SMtx::LockMode::SMtxLockTimed ,等待超时时， mRc == -ETIMEDOUT 。
当 mode 为 SMtx::LockMode::SMtxLockTry ,上锁失败时， mRc == -EWOULDBLOCK 。

在文件 SMtx.cxx 第 19 行定义.

    : mMtx(mtx)
    , mLockMode(mode)
{
    if (nullptr != mMtx) {
        switch (mode) {
            case SMtx::LockMode::SMtxLock:
                mRc = xwos_mtx_lock(&mMtx->mLock);
                break;
            case SMtx::LockMode::SMtxLockTimed:
                mRc = xwos_mtx_lock_to(&mMtx->mLock, to);
                break;
            case SMtx::LockMode::SMtxLockUninterruptable:
                mRc = xwos_mtx_lock_unintr(&mMtx->mLock);
                break;
            case SMtx::LockMode::SMtxLockTry:
                mRc = xwos_mtx_trylock(&mMtx->mLock);
                break;
            case SMtx::LockMode::SMtxUnlock:
                mRc = XWOK;
                break;
            default:
                mLockMode = SMtx::LockMode::SMtxUnlock;
                mRc = XWOK;
                break;
        }
    }
}

函数调用图:

◆ Grd() [3/3]

xwos::lock::SMtx::Grd::Grd	(	SMtx &	mtx,
		enum LockMode	mode = `LockMode::SMtxLock`,
		xwtm_t	to = `XWTM_MAX`
	)

构造静态互斥锁的RAII机制守卫并上锁互斥锁

参数

[in]	mode	锁模式，取值 SMtx::LockMode SMtx::LockMode::SMtxLock SMtx::LockMode::SMtxLockTimed SMtx::LockMode::SMtxLockUninterruptable SMtx::LockMode::SMtxLockTry
[in]	to	期望唤醒的时间点，仅当 `mode == SMtx::LockMode::SMtxLockTimed` 时有效。

◆ ~Grd()

xwos::lock::SMtx::Grd::~Grd ( )

析构静态互斥锁的RAII机制守卫并解锁互斥锁

在文件 SMtx.cxx 第 48 行定义.

{
    if (nullptr != mMtx) {
        if (SMtx::LockMode::SMtxUnlock != mLockMode) {
            xwos_mtx_unlock(&mMtx->mLock);
        }
    }
}

函数调用图:

成员函数说明

◆ getLockMode()

enum LockMode xwos::lock::SMtx::Grd::getLockMode ( )

inline

获取上锁模式

在文件 SMtx.hxx 第 175 行定义.

175{ return mLockMode; }

◆ getRc()

xwer_t xwos::lock::SMtx::Grd::getRc ( )

inline

获取上锁结果错误码

返回: 错误码

返回值

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

在文件 SMtx.hxx 第 170 行定义.

170{ return mRc; }

◆ wait() [1/4]

xwer_t xwos::lock::SMtx::Grd::wait ( sync::Cond & cond )

inline

等待条件量

参数

[in] cond 条件量对象的引用

返回: 错误码

注解

上下文：线程

同 wait(sync::Cond * cond) 。

在文件 SMtx.hxx 第 213 行定义.

213{ return wait(&cond); }

xwos::lock::SMtx::Grd::wait

xwer_t wait(sync::Cond *cond)

等待条件量

Definition SMtx.cxx:57

函数调用图:

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

◆ wait() [2/4]

xwer_t xwos::lock::SMtx::Grd::wait	(	sync::Cond &	cond,
		xwtm_t	to
	)

inline

限时等待条件量

参数

[in]	cond	条件量对象的引用
[in]	to	期望唤醒的时间点

返回: 错误码

注解

上下文：线程

同 wait(sync::Cond * cond, xwtm_t to) 。

在文件 SMtx.hxx 第 259 行定义.

259{ return wait(&cond, to); }

函数调用图:

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

◆ wait() [3/4]

xwer_t xwos::lock::SMtx::Grd::wait ( sync::Cond * cond )

等待条件量

参数

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

返回: 错误码

返回值

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

注解

上下文：线程

调用此C++API的线程会阻塞等待条件量，等待的同时会解锁互斥锁。
如果构造 SMtx::Grd 时使用的模式是 SMtx::LockMode::SMtxLockUninterruptable ，那么等待模式也是不可中断的。
条件量被单播 sync::Cond::unicast() 或广播 sync::Cond::broadcast() 时，会唤醒正在等待的线程。
线程被唤醒后，会重新上锁互斥锁，如果构造 SMtx::Grd 时使用的模式是 SMtx::LockMode::SMtxLockUninterruptable ，那么重新上锁的模式也是 SMtx::LockMode::SMtxLockUninterruptable 。
重新上锁成功后将返回 XWOK 。
线程的等待被中断后，此C++API返回 -EINTR 。
如果此C++API返回非 XWOK 的错误码，应该使用 SMtx::Grd::getLockMode() 确认是否上锁成功。

在文件 SMtx.cxx 第 57 行定义.

{
    xwer_t rc;
    if (nullptr != mMtx) {
        union xwos_ulock lock;
        xwsq_t lkst;
        lock.osal.mtx = &mMtx->mLock;
        if (SMtx::LockMode::SMtxLockUninterruptable == mLockMode) {
            rc = xwos_cond_wait_unintr(cond->getXwosObj(), lock, XWOS_LK_MTX, nullptr, &lkst);
        } else {
            rc = xwos_cond_wait(cond->getXwosObj(), lock, XWOS_LK_MTX, nullptr, &lkst);
        }
        if (rc < 0) {
            if (XWOS_LKST_UNLOCKED == lkst) {
                mLockMode = SMtx::LockMode::SMtxUnlock;
            }
        }
    } else {
        rc = -EFAULT;
    }
    return rc;
}

函数调用图:

◆ wait() [4/4]

xwer_t xwos::lock::SMtx::Grd::wait	(	sync::Cond *	cond,
		xwtm_t	to
	)

限时等待条件量

参数

[in]	cond	条件量对象的指针
[in]	to	期望唤醒的时间点

返回: 错误码

返回值

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

注解

上下文：线程

调用此C++API的线程会限时阻塞等待条件量，等待的同时会解锁互斥锁。
如果构造 SMtx::Grd 时使用的模式是 SMtx::LockMode::SMtxLockUninterruptable ，那么等待模式也是不可中断的，此时参数 to 无效，等待将不会超时。
条件量被单播 sync::Cond::unicast() 或广播 sync::Cond::broadcast() 时，会唤醒正在等待的线程。
线程被唤醒后，会重新上锁互斥锁，如果构造 SMtx::Grd 时使用的模式是 SMtx::LockMode::SMtxLockUninterruptable ，那么重新上锁的模式也是 SMtx::LockMode::SMtxLockUninterruptable 。
如果构造 SMtx::Grd 时使用的模式不是 SMtx::LockMode::SMtxLockUninterruptable ，线程被唤醒时，若互斥锁被其他线程占用，线程也最多等待互斥锁到时间点 to 。
重新上锁成功后将返回 XWOK 。
线程的等待被中断后，此C++API返回 -EINTR 。
线程的等待超时后，此C++API返回 -ETIMEDOUT 。
如果此C++API返回非 XWOK 的错误码，应该使用 SMtx::Grd::getLockMode() 确认是否上锁成功。

在文件 SMtx.cxx 第 80 行定义.

{
    xwer_t rc;
    if (nullptr != mMtx) {
        union xwos_ulock lock;
        xwsq_t lkst;
 
        lock.osal.mtx = &mMtx->mLock;
        if (SMtx::LockMode::SMtxLockUninterruptable == mLockMode) {
            rc = xwos_cond_wait_unintr(cond->getXwosObj(), lock, XWOS_LK_MTX, nullptr, &lkst);
        } else {
            rc = xwos_cond_wait_to(cond->getXwosObj(), lock, XWOS_LK_MTX, nullptr, to, &lkst);
        }
        if (rc < 0) {
            if (XWOS_LKST_UNLOCKED == lkst) {
                mLockMode = SMtx::LockMode::SMtxUnlock;
            }
        }
    } else {
        rc = -EFAULT;
    }
    return rc;
}

函数调用图:

结构体成员变量说明

◆ mLockMode

enum LockMode xwos::lock::SMtx::Grd::mLockMode

private

在文件 SMtx.hxx 第 98 行定义.

◆ mMtx

SMtx* xwos::lock::SMtx::Grd::mMtx

private

在文件 SMtx.hxx 第 96 行定义.

◆ mRc

xwer_t xwos::lock::SMtx::Grd::mRc

private

内部上锁CAPI的返回值

在文件 SMtx.hxx 第 97 行定义.

该类的文档由以下文件生成:

xwos/cxx/lock/SMtx.hxx
xwos/cxx/lock/SMtx.cxx

Public 成员函数

Private 属性

详细描述

构造及析构函数说明

◆ Grd() [1/3]

◆ Grd() [2/3]

◆ Grd() [3/3]

◆ ~Grd()

成员函数说明

◆ getLockMode()

◆ getRc()

◆ wait() [1/4]

◆ wait() [2/4]

◆ wait() [3/4]

◆ wait() [4/4]

结构体成员变量说明

◆ mLockMode

◆ mMtx

◆ mRc