Back to Qt.io
Contact Us Blog Download Qt
En esta página

QMutexLocker Class

template <typename Mutex> class QMutexLocker

La clase QMutexLocker es una clase de conveniencia que simplifica el bloqueo y desbloqueo de mutexes. Más...

Cabecera: #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 thread-safe.

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

Bloquear y desbloquear un QMutex o QRecursiveMutex en funciones y sentencias complejas o en código de manejo de excepciones es propenso a errores y difícil de depurar. QMutexLocker puede ser usado en tales situaciones para asegurar que el estado del mutex este siempre bien definido.

QMutexLocker debe ser creado dentro de una función donde un QMutex necesita ser bloqueado. El mutex es bloqueado cuando QMutexLocker es creado. 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 compleja función 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.

Usar 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 será desbloqueado cuando el objeto QMutexLocker es destruido (cuando la función retorna ya que locker es una variable automática).

El mismo principio se aplica al código que lanza y atrapa excepciones. Una excepción que no es capturada en la función que ha bloqueado el mutex no tiene forma de desbloquear el mutex antes de que la excepción sea pasada por la pila a la función que la llama.

QMutexLocker tambien provee una funcion miembro mutex() que retorna el mutex sobre el cual QMutexLocker esta operando. Esto es útil para código que necesita acceso 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());
        //...
    }
};

Ver también QReadLocker, QWriteLocker, y QMutex.

Documentación de funciones miembro

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

Construye un QMutexLocker y bloquea mutex. El mutex será desbloqueado cuando el QMutexLocker sea destruido. Si mutex es nullptr, QMutexLocker no hace nada.

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

Ver también QMutex::lock().

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

Move-construye un QMutexLocker a partir de other. El mutex y el estado de other se transfieren a la nueva instancia construida. Después del movimiento, 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 QMutexLocker y desbloquea el mutex que fue bloqueado 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, o false en caso contrario.

Esta función se introdujo en Qt 6.4.

Mutex *QMutexLocker::mutex() const

Devuelve el mutex sobre el que está operando QMutexLocker.

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

Vuelve a bloquear un mutex locker 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 armario mutex. Puedes usar relock() para bloquearlo de nuevo. No es necesario bloquearlo cuando se destruye.

Véase también relock().

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

Mueve-asigna other a este QMutexLocker. Si este QMutexLocker estaba manteniendo un mutex bloqueado antes de la asignación, el mutex será desbloqueado. El mutex y el estado de other se transfieren entonces a este QMutexLocker. Después del 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.