Back to Qt.io
Contact Us Blog Download Qt

QMutexLocker Class

template <typename Mutex> class QMutexLocker

QMutexLocker 类是一个方便的类，可简化对互斥的锁定和解锁。更多

Header： #include <QMutexLocker>
CMake： find_package(Qt6 REQUIRED COMPONENTS Core)
target_link_libraries(mytarget PRIVATE Qt6::Core)
qmake： QT += core

注意：该类中的所有函数都是线程安全的。

公共函数

QMutexLocker(Mutex *mutex)
(since 6.4) QMutexLocker(QMutexLocker<Mutex> &&other)
~QMutexLocker()
(since 6.4) bool isLocked() const
Mutex *mutex() const
void relock()
(since 6.4) void swap(QMutexLocker<Mutex> &other)
void unlock()
(since 6.4) QMutexLocker<Mutex> &operator=(QMutexLocker<Mutex> &&other)

详细说明

在复杂函数、语句或异常处理代码中锁定和解锁QMutex 或QRecursiveMutex 容易出错且难以调试。在这种情况下，可以使用 QMutexLocker 来确保互斥体的状态始终定义明确。

QMutexLocker 应在需要锁定QMutex 的函数中创建。创建 QMutexLocker 时，静态项已被锁定。您可以通过unlock() 和relock() 来解锁和重新锁定该互斥体。如果锁定了互斥体，则在销毁 QMutexLocker 时将其解锁。

例如，这个复杂函数在进入函数时锁定QMutex ，并在所有退出点解锁互斥体：

int complexFunction(int flag)
{
    mutex.lock();

    int retVal = 0;

    switch (flag) {
    case 0:
    case 1:
        retVal = moreComplexFunction(flag);
        break;
    case 2:
        {
            int status = anotherFunction();
            if (status < 0) {
                mutex.unlock();
                return -2;
            }
            retVal = status + flag;
        }
        break;
    default:
        if (flag > 10) {
            mutex.unlock();
            return -1;
        }
        break;
    }

    mutex.unlock();
    return retVal;
}

这个示例函数在开发过程中会变得越来越复杂，从而增加出错的可能性。

使用 QMutexLocker 大大简化了代码，并使其更具可读性：

int complexFunction(int flag)
{
    QMutexLocker locker(&mutex);

    int retVal = 0;

    switch (flag) {
    case 0:
    case 1:
        return moreComplexFunction(flag);
    case 2:
        {
            int status = anotherFunction();
            if (status < 0)
                return -2;
            retVal = status + flag;
        }
        break;
    default:
        if (flag > 10)
            return -1;
        break;
    }

    return retVal;
}

现在，当 QMutexLocker 对象被销毁时（当函数返回时，因为locker 是一个自变量），mutex 将始终被解锁。

同样的原则也适用于抛出和捕获异常的代码。如果异常没有在锁定互斥项的函数中捕获，那么在异常上传到调用函数的堆栈之前，就无法解锁互斥项。

QMutexLocker 还提供了一个mutex() 成员函数，用于返回 QMutexLocker 正在运行的 mutex。这对需要访问静态项的代码（如QWaitCondition::wait() ）非常有用。例如

class SignalWaiter
{
private:
    QMutexLocker<QMutex> locker;

public:
    SignalWaiter(QMutex *mutex)
        : locker(mutex)
    {
    }

    void waitForSignal()
    {
        ...
        while (!signalled)
            waitCondition.wait(locker.mutex());
        ...
    }
};

另请参见 QReadLocker,QWriteLocker, 和QMutex 。

成员函数文档

[explicit noexcept(...)] QMutexLocker::QMutexLocker(Mutex *mutex)

构造一个 QMutexLocker 并锁定mutex 。当 QMutexLocker 被销毁时，互斥将被解锁。如果mutex 是nullptr ，QMutexLocker 不会执行任何操作。

注意： 当LockIsNoexcept 为true 时，此函数为 noexcept。

另请参阅 QMutex::lock() 。

[noexcept, since 6.4] QMutexLocker::QMutexLocker(QMutexLocker<Mutex> &&other)

Move-construct a QMutexLocker fromother 。互斥和other 的状态将转移到新构建的实例中。移动后，other 将不再管理任何 mutex。

此函数在 Qt 6.4 中引入。

另请参阅 QMutex::lock()。

QMutexLocker::~QMutexLocker()

销毁QMutexLocker 并解锁在构造函数中锁定的互斥。

另请参见 QMutex::unlock().

[noexcept, since 6.4] bool QMutexLocker::isLocked() const

如果QMutexLocker 当前正在锁定其关联的 mutex，则返回 true，否则返回 false。

此函数在 Qt 6.4 中引入。

Mutex *QMutexLocker::mutex() const

返回QMutexLocker 正在运行的互斥项。

[noexcept(...)] void QMutexLocker::relock()

重新锁定已解锁的互斥锁。

注： 当LockIsNoexcept 为true 时，此函数为 noexcept。

另请参阅 unlock() 。

[noexcept, since 6.4] void QMutexLocker::swap(QMutexLocker<Mutex> &other)

将该QMutexLocker 的互斥和状态与other 互换。该操作速度非常快，而且不会失败。

此函数在 Qt 6.4 中引入。

另请参见 QMutex::lock()。

[noexcept] void QMutexLocker::unlock()

解锁此互斥锁。您可以使用relock() 再次锁定它。销毁时无需锁定。

另请参阅 relock().

[noexcept, since 6.4] QMutexLocker<Mutex> &QMutexLocker::operator=(QMutexLocker<Mutex> &&other)

移动将other 赋值给QMutexLocker 。如果QMutexLocker 在赋值前持有锁定的互斥项，则互斥项将被解锁。然后，该互斥项和other 的状态将转移到QMutexLocker 上。转移后，other 将不再管理任何互斥。

此函数在 Qt 6.4 中引入。

另请参阅 QMutex::lock()。

© 2025 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.