En esta página

QMutexLocker Class

template <typename Mutex> class QMutexLocker

La clase QMutexLocker es una clase de ayuda que simplifica el bloqueo y desbloqueo de mutexes. Más información...

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

Nota: Todas las funciones de esta clase son seguras para subprocesos.

Funciones públicas

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)

Descripción detallada

QMutexLocker es una clase de plantilla en la que el parámetro de plantilla Mutex especifica el tipo de mutex (como QMutex o QRecursiveMutex) que se va a bloquear y desbloquear.

Bloquear y desbloquear un ` QMutex ` o un ` QRecursiveMutex ` en funciones y sentencias complejas o en código de gestión de excepciones es propenso a errores y difícil de depurar. QMutexLocker puede utilizarse en tales situaciones para garantizar que el estado del mutex esté siempre bien definido.

El `QMutexLocker` debe crearse dentro de una función en la que sea necesario bloquear un ` QMutex `. El mutex se bloquea al crear el `QMutexLocker`. Se puede desbloquear y volver a bloquear el mutex con ` unlock() ` y ` relock()`. Si está bloqueado, el mutex se desbloqueará cuando se destruya el `QMutexLocker`.

Por ejemplo, esta función compleja bloquea un ` QMutex ` al entrar en la función y desbloquea el mutex en todos los puntos de salida:

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;
}

Esta función de ejemplo se irá complicando a medida que se desarrolle, lo que aumenta la probabilidad de que se produzcan errores.

El uso de QMutexLocker simplifica enormemente el código y lo hace más legible:

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;
}

Ahora, el mutex siempre se desbloqueará cuando se destruya el objeto `QMutexLocker` (cuando la función devuelva un valor, ya que ` locker ` es una variable `auto`).

El mismo principio se aplica al código que lanza y captura excepciones. Una excepción que no se captura en la función que ha bloqueado el mutex no tiene forma de desbloquearlo antes de que la excepción se transmita por la pila hasta la función que la ha llamado.

QMutexLocker también proporciona una función miembro ` mutex() ` que devuelve el mutex sobre el que está operando el QMutexLocker. Esto resulta útil para el código que necesita acceder al mutex, como ` QWaitCondition::wait()`. Por ejemplo:

class SignalWaiter
{
private:
    QMutexLocker<QMutex> locker;

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

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

Véase también QReadLocker, QWriteLocker y QMutex.

Documentación de las funciones de miembro

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

Crea un objeto `QMutexLocker` y bloquea ` mutex`. El mutex se desbloqueará cuando se destruya el `QMutexLocker`. Si ` mutex ` es ` nullptr`, `QMutexLocker` no realiza ninguna acción.

Nota: Esta función es «noexcept» cuando LockIsNoexcept es true.

Véase también QMutex::lock().

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

Crea mediante «move» un objeto `QMutexLocker` a partir de ` other`. El mutex y el estado de ` other ` se transfieren a la instancia recién creada. Tras la operación «move», ` other ` ya no gestionará ningún mutex.

Esta función se introdujo en Qt 6.4.

Véase también ` QMutex::lock()`.

QMutexLocker::~QMutexLocker()

Destruye el objeto « QMutexLocker » y libera el mutex que se bloqueó en el constructor.

Véase también QMutex::unlock().

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

Devuelve «true» si este ` QMutexLocker ` está bloqueando actualmente su mutex asociado; en caso contrario, devuelve «false».

Esta función se introdujo en Qt 6.4.

Mutex *QMutexLocker::mutex() const

Devuelve el mutex sobre el que está operando el método « QMutexLocker ».

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

Vuelve a bloquear un mutex desbloqueado.

Nota: Esta función es «noexcept» cuando ` LockIsNoexcept ` es ` true`.

Véase también unlock().

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

Intercambia el mutex y el estado de este ` QMutexLocker ` con ` other`. Esta operación es muy rápida y nunca falla.

Esta función se introdujo en Qt 6.4.

Véase también QMutex::lock().

[noexcept] void QMutexLocker::unlock()

Desbloquea este mutex. Puedes utilizar ` relock() ` para volver a bloquearlo. No es necesario bloquearlo cuando se destruya.

Véase también relock().

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

La asignación por traslado asigna other a este QMutexLocker. Si este QMutexLocker mantenía un mutex bloqueado antes de la asignación, el mutex se desbloqueará. A continuación, el mutex y el estado de other se transfieren a este QMutexLocker. Tras el traslado, other ya no gestionará ningún mutex.

Esta función se introdujo en Qt 6.4.

Véase también 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.