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

QWaitCondition Class

La clase QWaitCondition proporciona una variable de condición para sincronizar hilos. Más...

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

QWaitCondition()
~QWaitCondition()
void notify_all()
void notify_one()
bool wait(QMutex *lockedMutex, QDeadlineTimer deadline = QDeadlineTimer(QDeadlineTimer::Forever))
bool wait(QReadWriteLock *lockedReadWriteLock, QDeadlineTimer deadline = QDeadlineTimer(QDeadlineTimer::Forever))
bool wait(QMutex *lockedMutex, unsigned long time)
bool wait(QReadWriteLock *lockedReadWriteLock, unsigned long time)
void wakeAll()
void wakeOne()

Descripción Detallada

QWaitCondition permite a un thread indicar a otros threads que se ha cumplido algún tipo de condición. Uno o muchos hilos pueden bloquearse esperando que un QWaitCondition establezca una condición con wakeOne() o wakeAll(). Usa wakeOne() para despertar un hilo seleccionado al azar o wakeAll() para despertarlos a todos.

Por ejemplo, supongamos que tenemos tres tareas que deben realizarse cada vez que el usuario pulsa una tecla. Cada tarea podría dividirse en un hilo, cada uno de los cuales tendría un cuerpo run() como este:

forever {
    mutex.lock();
    keyPressed.wait(&mutex);
    do_something();
    mutex.unlock();
}

Aquí, la variable keyPressed es una variable global de tipo QWaitCondition.

Un cuarto hilo leería las pulsaciones de teclas y despertaría a los otros tres hilos cada vez que recibiera una, así:

forever {
    getchar();
    keyPressed.wakeAll();
}

El orden en que los tres hilos son despertados es indefinido. Además, si algunos de los hilos están todavía en do_something() cuando se pulsa la tecla, no serán despertados (ya que no están esperando en la variable de condición) y por lo tanto la tarea no se realizará para esa pulsación de tecla. Este problema se puede resolver utilizando un contador y un QMutex para guardarlo. Por ejemplo, aquí está el nuevo código para los hilos trabajadores:

forever {
    mutex.lock();
    keyPressed.wait(&mutex);
    ++count;
    mutex.unlock();

    do_something();

    mutex.lock();
    --count;
    mutex.unlock();
}

Aquí está el código para el cuarto hilo:

forever {
    getchar();

    mutex.lock();
    // Sleep until there are no busy worker threads
    while (count > 0) {
        mutex.unlock();
        sleep(1);
        mutex.lock();
    }
    keyPressed.wakeAll();
    mutex.unlock();
}

El mutex es necesario porque los resultados de dos hilos intentando cambiar el valor de la misma variable simultáneamente son impredecibles.

Las condiciones de espera son una potente primitiva de sincronización de hilos. El ejemplo Producer and Consumer using Wait Conditions muestra cómo utilizar QWaitCondition como alternativa a QSemaphore para controlar el acceso a un buffer circular compartido por un hilo productor y un hilo consumidor.

Consulte también QMutex, QSemaphore, QThread, y Productor y consumidor utilizando condiciones de espera.

Documentación de funciones miembro

QWaitCondition::QWaitCondition()

Construye un nuevo objeto de condición de espera.

[noexcept] QWaitCondition::~QWaitCondition()

Destruye el objeto de condición de espera.

void QWaitCondition::notify_all()

Esta función se proporciona por compatibilidad con STL. Es equivalente a wakeAll().

void QWaitCondition::notify_one()

Esta función se proporciona por compatibilidad con STL. Es equivalente a wakeOne().

bool QWaitCondition::wait(QMutex *lockedMutex, QDeadlineTimer deadline = QDeadlineTimer(QDeadlineTimer::Forever))

Libera el lockedMutex y espera en la condición de espera. lockedMutex debe estar bloqueado inicialmente por el subproceso que realiza la llamada. Si lockedMutex no está en un estado bloqueado, el comportamiento es indefinido. Si lockedMutex es un mutex recursivo, esta función retorna inmediatamente. El lockedMutex se desbloqueará, y el hilo llamador se bloqueará hasta que se cumpla cualquiera de estas condiciones:

  • Otro subproceso le envía una señal utilizando wakeOne() o wakeAll(). Esta función devolverá true en este caso.
  • se alcance el plazo dado por deadline. Si deadline es QDeadlineTimer::Forever (por defecto), entonces la espera nunca expirará (el evento debe ser señalado). Esta función devolverá false si se agota el tiempo de espera.

lockedMutex volverá al mismo estado de bloqueo. Esta función se proporciona para permitir la transición atómica del estado bloqueado al estado de espera.

Véase también wakeOne() y wakeAll().

bool QWaitCondition::wait(QReadWriteLock *lockedReadWriteLock, QDeadlineTimer deadline = QDeadlineTimer(QDeadlineTimer::Forever))

Libera el lockedReadWriteLock y espera en la condición de espera. lockedReadWriteLock debe estar bloqueado inicialmente por el subproceso que realiza la llamada. Si lockedReadWriteLock no está en un estado bloqueado, esta función retorna inmediatamente. El lockedReadWriteLock no debe ser bloqueado recursivamente, de lo contrario esta función no liberará el bloqueo correctamente. lockedReadWriteLock se desbloqueará, y el subproceso llamante se bloqueará hasta que se cumpla alguna de estas condiciones:

  • Otra hebra lo señala usando wakeOne() o wakeAll(). Esta función devolverá true en este caso.
  • se alcance el plazo dado por deadline. Si deadline es QDeadlineTimer::Forever (por defecto), entonces la espera nunca expirará (el evento debe ser señalado). Esta función devolverá false si se agota el tiempo de espera.

lockedReadWriteLock volverá al mismo estado de bloqueo. Esta función se proporciona para permitir la transición atómica del estado bloqueado al estado de espera.

Véase también wakeOne() y wakeAll().

bool QWaitCondition::wait(QMutex *lockedMutex, unsigned long time)

Libera el lockedMutex y espera en la condición de espera durante time milisegundos.

Se trata de una función sobrecargada.

bool QWaitCondition::wait(QReadWriteLock *lockedReadWriteLock, unsigned long time)

Libera el lockedReadWriteLock y espera en la condición de espera durante time milisegundos.

Se trata de una función sobrecargada.

void QWaitCondition::wakeAll()

Despierta todos los hilos que esperan en la condición de espera. El orden en el que se despiertan los hilos depende de las políticas de programación del sistema operativo y no se puede controlar ni predecir.

Véase también wakeOne().

void QWaitCondition::wakeOne()

Despierta una hebra que espera en la condición de espera. La hebra que se despierta depende de las políticas de programación del sistema operativo, y no se puede controlar o predecir.

Si quieres activar un proceso específico, la solución es utilizar diferentes condiciones de espera y hacer que diferentes procesos esperen en diferentes condiciones.

Véase también wakeAll().

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