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

#include <DMtx.hxx>

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

[图例]

Public 成员函数
	Grd ()=delete

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

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

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

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

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 属性
DMtx *	mMtx

xwer_t	mRc

enum LockMode	mLockMode

详细描述

动态互斥锁的RAII机制守卫

在文件 DMtx.hxx 第 92 行定义.

构造及析构函数说明

◆ Grd() [1/3]

xwos::lock::DMtx::Grd::Grd ( )

delete

◆ Grd() [2/3]

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

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

参数

[in]	mtx	动态互斥锁对象指针
[in]	mode	锁模式，取值 DMtx::LockMode DMtx::LockMode::DMtxLock DMtx::LockMode::DMtxLockTimed DMtx::LockMode::DMtxLockUninterruptable DMtx::LockMode::DMtxLockTry
[in]	to	期望唤醒的时间点，仅当 `mode == DMtx::LockMode::DMtxLockTimed` 时有效。

注解

上下文：线程

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

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

    : mMtx(mtx)
    , mLockMode(mode)
{
    if (nullptr != mMtx) {
        switch (mode) {
            case DMtx::LockMode::DMtxLock:
                mRc = xwos_mtx_lock(mMtx->mMtxDesc.mtx);
                break;
            case DMtx::LockMode::DMtxLockTimed:
                mRc = xwos_mtx_lock_to(mMtx->mMtxDesc.mtx, to);
                break;
            case DMtx::LockMode::DMtxLockUninterruptable:
                mRc = xwos_mtx_lock_unintr(mMtx->mMtxDesc.mtx);
                break;
            case DMtx::LockMode::DMtxLockTry:
                mRc = xwos_mtx_trylock(mMtx->mMtxDesc.mtx);
                break;
            case DMtx::LockMode::DMtxUnlock:
                mRc = XWOK;
                break;
            default:
                mLockMode = DMtx::LockMode::DMtxUnlock;
                mRc = XWOK;
                break;
        }
    }
}

函数调用图:

◆ Grd() [3/3]

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

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

参数

[in]	mode	锁模式，取值 DMtx::LockMode DMtx::LockMode::DMtxLock DMtx::LockMode::DMtxLockTimed DMtx::LockMode::DMtxLockUninterruptable DMtx::LockMode::DMtxLockTry
[in]	to	期望唤醒的时间点，仅当 `mode == DMtx::LockMode::DMtxLockTimed` 时有效。

◆ ~Grd()

xwos::lock::DMtx::Grd::~Grd ( )

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

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

{
    if (nullptr != mMtx) {
        if (DMtx::LockMode::DMtxUnlock != mLockMode) {
            xwos_mtx_unlock(mMtx->mMtxDesc.mtx);
        }
    }
}

函数调用图:

成员函数说明

◆ getRc()

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

inline

获取上锁结果错误码

返回: 错误码

返回值

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

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

170{ return mRc; }

◆ wait() [1/4]

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

inline

等待条件量

参数

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

返回: 错误码

注解

上下文：线程

同 wait(sync::Cond * cond) 。

在文件 DMtx.hxx 第 208 行定义.

208{ return wait(&cond); }

xwos::lock::DMtx::Grd::wait

xwer_t wait(sync::Cond *cond)

等待条件量

Definition DMtx.cxx:57

函数调用图:

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

◆ wait() [2/4]

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

inline

限时等待条件量

参数

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

返回: 错误码

注解

上下文：线程

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

在文件 DMtx.hxx 第 254 行定义.

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

函数调用图:

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

◆ wait() [3/4]

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

等待条件量

参数

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

返回: 错误码

返回值

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

注解

上下文：线程

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

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

{
    xwer_t rc;
    if (nullptr != mMtx) {
        union xwos_ulock lock;
        xwsq_t lkst;
 
        lock.osal.mtx = mMtx->mMtxDesc.mtx;
        if (DMtx::LockMode::DMtxLockUninterruptable == 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 = DMtx::LockMode::DMtxUnlock;
            }
        }
    } else {
        rc = -EFAULT;
    }
    return rc;
}

函数调用图:

◆ wait() [4/4]

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

限时等待条件量

参数

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

返回: 错误码

返回值

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

注解

上下文：线程

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

在文件 DMtx.cxx 第 81 行定义.

{
    xwer_t rc;
    if (nullptr != mMtx) {
        union xwos_ulock lock;
        xwsq_t lkst;
        lock.osal.mtx = mMtx->mMtxDesc.mtx;
        if (DMtx::LockMode::DMtxLockUninterruptable == 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 = DMtx::LockMode::DMtxUnlock;
            }
        }
    } else {
        rc = -EFAULT;
    }
    return rc;
}

函数调用图:

结构体成员变量说明

◆ mLockMode

enum LockMode xwos::lock::DMtx::Grd::mLockMode

private

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

◆ mMtx

DMtx* xwos::lock::DMtx::Grd::mMtx

private

在文件 DMtx.hxx 第 95 行定义.

◆ mRc

xwer_t xwos::lock::DMtx::Grd::mRc

private

内部上锁CAPI的返回值

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

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

xwos/cxx/lock/DMtx.hxx
xwos/cxx/lock/DMtx.cxx

Public 成员函数

Private 属性

详细描述

构造及析构函数说明

◆ Grd() [1/3]

◆ Grd() [2/3]

◆ Grd() [3/3]

◆ ~Grd()

成员函数说明

◆ getRc()

◆ wait() [1/4]

◆ wait() [2/4]

◆ wait() [3/4]

◆ wait() [4/4]

结构体成员变量说明

◆ mLockMode

◆ mMtx

◆ mRc