QMutex Class
La clase QMutex permite la serialización del acceso entre subprocesos. Más información...
| Encabezado: | #include <QMutex> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS Core) target_link_libraries(mytarget PRIVATE Qt6::Core) |
| qmake: | QT += core |
- Lista de todos los miembros, incluidos los miembros heredados
- QMutex forma parte de las clases de subprocesos.
Nota: Todas las funciones de esta clase son seguras para subprocesos.
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 objetivo de un QMutex es proteger un objeto, una estructura de datos o una sección de código para que solo un hilo pueda acceder a él a la vez (esto es similar a la palabra clave « synchronized » de Java). Por lo general, es recomendable utilizar un mutex junto con un « QMutexLocker », ya que así resulta más fácil garantizar que el bloqueo y el desbloqueo se realicen de forma coherente.
Por ejemplo, supongamos que hay un método que muestra 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 se invocan 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 10Si estos dos métodos se invocan simultáneamente desde dos subprocesos, 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 10Si añadimos un mutex, deberíamos obtener el resultado deseado:
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();
}De este modo, solo un hilo puede modificar ` number ` en un momento dado y el resultado es correcto. Se trata, por supuesto, de un ejemplo trivial, pero se aplica a cualquier otro caso en el que las operaciones deban realizarse en una secuencia concreta.
Cuando se invoca a ` lock()` en un hilo, los demás hilos que intenten invocar a ` lock()` en el mismo lugar quedarán bloqueados hasta que el hilo que haya obtenido el bloqueo invoque a ` unlock()`. Una alternativa no bloqueante a ` lock()` es ` tryLock()`.
QMutex está optimizado para ser rápido en casos sin conflicto. No asignará memoria si no hay conflicto en ese mutex. Se crea y se destruye prácticamente sin sobrecarga, lo que significa que no supone ningún problema tener muchos mutexes como parte de otras clases.
Véase también QRecursiveMutex, QMutexLocker, QReadWriteLock, QSemaphore y QWaitCondition.
Documentación de las funciones miembro
[constexpr noexcept default] QMutex::QMutex()
Crea un nuevo mutex. El mutex se crea en estado desbloqueado.
[noexcept] QMutex::~QMutex()
Destruye el mutex.
Advertencia: La destrucción de un mutex bloqueado puede provocar un comportamiento indefinido.
[noexcept(...)] void QMutex::lock()
Bloquea el mutex. Si otro hilo ha bloqueado el mutex, esta llamada se bloqueará hasta que dicho hilo lo haya desbloqueado.
Si el mutex ya estaba bloqueado por el hilo actual, esta llamada nunca retornará, lo que provocará un interbloqueo.
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 expire ` timer ` para que el mutex quede disponible.
Si se ha obtenido el bloqueo, el mutex debe desbloquearse con unlock() antes de que otro hilo pueda bloquearlo correctamente.
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 quede disponible.
Nota: Pasar un número negativo como timeout equivale a llamar a lock(), es decir, esta función esperará indefinidamente hasta que se pueda bloquear el mutex si timeout es negativo.
Si se ha obtenido el bloqueo, el mutex debe desbloquearse con unlock() antes de que otro hilo pueda bloquearlo correctamente.
Nota: Esta función es «noexcept» cuando FutexAlwaysAvailable es true.
Véanse también lock() y unlock().
[noexcept] bool QMutex::tryLock()
Intenta bloquear el mutex. Esta función devuelve ` true ` si se ha obtenido el bloqueo; en caso contrario, devuelve ` false`.
Si se ha obtenido el bloqueo, el mutex debe desbloquearse con ` unlock()` antes de que otro hilo pueda bloquearlo correctamente.
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 para garantizar la 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 ` a que el mutex quede disponible.
Nota: Pasar una duración negativa como duration equivale a llamar a try_lock(). Este comportamiento difiere del de tryLock().
Si se ha obtenido el bloqueo, el mutex debe desbloquearse con unlock() antes de que otro hilo pueda bloquearlo correctamente.
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 que ` timePoint ` para que el mutex quede disponible.
Nota: Pasar un ` timePoint ` que ya ha sido devuelto equivale a llamar a ` try_lock()`. Este comportamiento difiere del de ` tryLock()`.
Si se ha obtenido el bloqueo, el mutex debe desbloquearse con unlock() antes de que otro hilo pueda bloquearlo correctamente.
Véanse también lock() y unlock().
[noexcept] void QMutex::unlock()
Desbloquea el mutex. Si se intenta desbloquear un mutex en un hilo distinto al que lo bloqueó, se produce un error. Desbloquear un mutex que no está bloqueado da lugar a 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.