Back to Qt.io
Contact Us Blog Download Qt
本页内容

QMutexLocker Class

template <typename Mutex> class QMutexLocker

QMutexLocker 类是一个便利类，用于简化互斥锁的加锁和解锁操作。更多内容...

头文件： #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)

详细说明

QMutexLocker 是一个模板类，其中模板参数Mutex 指定了要锁定和解锁的互斥锁类型（例如QMutex 或QRecursiveMutex ）。

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

应在需要锁定QMutex 的函数内部创建QMutexLocker。创建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 是自动变量，因此函数返回时），互斥锁将始终被解锁。

同样的原理也适用于抛出和捕获异常的代码。如果锁定互斥量的函数中未捕获异常，那么在异常沿调用栈向上传递至调用函数之前，将无法解锁互斥量。

QMutexLocker 还提供了一个名为 `mutex() ` 的成员函数，该函数返回 QMutexLocker 正在操作的互斥锁。这对于需要访问互斥锁的代码（例如 `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)

从other 移动构造一个QMutexLocker。互斥锁以及other 的状态将转移到新构造的实例中。移动操作完成后，other 将不再管理任何互斥锁。

该函数在 Qt 6.4 中引入。

另请参阅 QMutex::lock()。

QMutexLocker::~QMutexLocker()

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

另请参阅 QMutex::unlock()。

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

如果该QMutexLocker 当前正在锁定其关联的互斥锁，则返回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)

使用 `other` 与该 `QMutexLocker ` 的互斥锁及其状态进行交换。此操作速度极快，且绝不会失败。

该函数在 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()。

© 2026 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.