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

QMutex Class

La clase QMutex proporciona serialización de acceso entre hilos. Más...

Cabecera: #include <QMutex>
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

QMutex()
~QMutex()
void lock()
(since 6.6) bool tryLock(QDeadlineTimer timer)
bool tryLock(int timeout)
bool tryLock()
bool try_lock()
bool try_lock_for(std::chrono::duration<Rep, Period> duration)
bool try_lock_until(std::chrono::time_point<Clock, Duration> timePoint)
void unlock()

Descripción Detallada

El propósito de un QMutex es proteger un objeto, estructura de datos o sección de código para que sólo un hilo pueda acceder a él a la vez (esto es similar a la palabra clave de Java synchronized ). Usualmente es mejor usar un mutex con QMutexLocker ya que esto facilita asegurar que el bloqueo y desbloqueo se realicen de manera consistente.

Por ejemplo, digamos que hay un método que imprime un mensaje al usuario en dos líneas:

int number = 6;

void method1()
{
    number *= 5;
    number /= 4;
}

void method2()
{
    number *= 3;
    number /= 2;
}

Si estos dos métodos son llamados sucesivamente, ocurre lo siguiente:

// method1()
number *= 5;        // number is now 30
number /= 4;        // number is now 7

// method2()
number *= 3;        // number is now 21
number /= 2;        // number is now 10

Si estos dos métodos se llaman simultáneamente desde dos hilos, podría producirse la siguiente secuencia:

// Thread 1 calls method1()
number *= 5;        // number is now 30

// Thread 2 calls method2().
//
// Most likely Thread 1 has been put to sleep by the operating
// system to allow Thread 2 to run.
number *= 3;        // number is now 90
number /= 2;        // number is now 45

// Thread 1 finishes executing.
number /= 4;        // number is now 11, instead of 10

Si añadimos un mutex, deberíamos obtener el resultado que deseamos:

QMutex mutex;
int number = 6;

void method1()
{
    mutex.lock();
    number *= 5;
    number /= 4;
    mutex.unlock();
}

void method2()
{
    mutex.lock();
    number *= 3;
    number /= 2;
    mutex.unlock();
}

Entonces sólo un hilo puede modificar number en un momento dado y el resultado es correcto. Este es un ejemplo trivial, por supuesto, pero es aplicable a cualquier otro caso en el que las cosas deban suceder en una secuencia determinada.

Cuando se llama a lock() en un hilo, otros hilos que intenten llamar a lock() en el mismo lugar se bloquearán hasta que el hilo que obtuvo el bloqueo llame a unlock(). Una alternativa sin bloqueo a lock() es tryLock().

QMutex está optimizado para ser rápido en el caso no-contenido. No asignará memoria si no hay contención en ese mutex. Se construye y destruye casi sin sobrecarga, lo que significa que está bien tener muchos mutexes como parte de otras clases.

Ver también QRecursiveMutex, QMutexLocker, QReadWriteLock, QSemaphore, y QWaitCondition.

Documentación de Funciones Miembro

[constexpr noexcept] QMutex::QMutex()

Construye un nuevo mutex. El mutex se crea en un estado desbloqueado.

[noexcept] QMutex::~QMutex()

Destruye el mutex.

Advertencia: Destruir un mutex bloqueado puede resultar en un comportamiento indefinido.

[noexcept(...)] void QMutex::lock()

Bloquea el mutex. Si otro hilo ha bloqueado el mutex entonces esta llamada se bloqueará hasta que ese hilo lo haya desbloqueado.

Si el mutex ya estaba bloqueado por la hebra actual, esta llamada nunca regresará, causando un dead-lock.

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

Véase también unlock().

[noexcept(...), since 6.6] bool QMutex::tryLock(QDeadlineTimer timer)

Intenta bloquear el mutex. Esta función devuelve true si se ha obtenido el bloqueo; en caso contrario, devuelve false. Si otro hilo ha bloqueado el mutex, esta función esperará hasta que timer expire para que el mutex esté disponible.

Si el bloqueo fue obtenido, el mutex debe ser desbloqueado con unlock() antes de que otro thread pueda bloquearlo exitosamente.

Esta función se introdujo en Qt 6.6.

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

Véase también lock() y unlock().

[noexcept(...)] bool QMutex::tryLock(int timeout)

Intenta bloquear el mutex. Esta función devuelve true si se ha obtenido el bloqueo; en caso contrario, devuelve false. Si otro hilo ha bloqueado el mutex, esta función esperará como máximo timeout milisegundos a que el mutex esté disponible.

Nota: Pasar un número negativo como timeout es equivalente a llamar a lock(), es decir, esta función esperará eternamente hasta que el mutex pueda ser bloqueado si timeout es negativo.

Si se obtuvo el bloqueo, el mutex debe ser desbloqueado con unlock() antes de que otro hilo pueda bloquearlo con éxito.

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

Véase también lock() y unlock().

[noexcept] bool QMutex::tryLock()

Intenta bloquear el mutex. Esta función devuelve true si se obtuvo el bloqueo; en caso contrario devuelve false.

Si el bloqueo fue obtenido, el mutex debe ser desbloqueado con unlock() antes de que otro hilo pueda bloquearlo con éxito.

Esta es una función sobrecargada.

Véase también lock() y unlock().

[noexcept] bool QMutex::try_lock()

Intenta bloquear el mutex. Esta función devuelve true si se ha obtenido el bloqueo; en caso contrario devuelve false.

Esta función se proporciona por compatibilidad con el concepto de la biblioteca estándar Lockable. Es equivalente a tryLock().

template <typename Rep, typename Period> bool QMutex::try_lock_for(std::chrono::duration<Rep, Period> duration)

Intenta bloquear el mutex. Esta función devuelve true si se ha obtenido el bloqueo; en caso contrario, devuelve false. Si otro hilo ha bloqueado el mutex, esta función esperará al menos duration para que el mutex esté disponible.

Nota: Pasar una duración negativa como duration es equivalente a llamar a try_lock(). Este comportamiento difiere de tryLock().

Si el bloqueo fue obtenido, el mutex debe ser desbloqueado con unlock() antes de que otro thread pueda bloquearlo exitosamente.

Véase también lock() y unlock().

template <typename Clock, typename Duration> bool QMutex::try_lock_until(std::chrono::time_point<Clock, Duration> timePoint)

Intenta bloquear el mutex. Esta función devuelve true si se ha obtenido el bloqueo; en caso contrario, devuelve false. Si otro hilo ha bloqueado el mutex, esta función esperará al menos hasta timePoint para que el mutex esté disponible.

Nota: Pasar un timePoint que ya ha pasado equivale a llamar a try_lock(). Este comportamiento difiere de tryLock().

Si el bloqueo fue obtenido, el mutex debe ser desbloqueado con unlock() antes de que otro thread pueda bloquearlo exitosamente.

Véase también lock() y unlock().

[noexcept] void QMutex::unlock()

Desbloquea el mutex. Intentar desbloquear un mutex en un hilo diferente al que lo bloqueó resulta en un error. Desbloquear un mutex que no está bloqueado produce un comportamiento indefinido.

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