QWaitCondition Class
QWaitCondition 类提供了一个用于线程同步的条件变量。更多内容...
| 头文件： | #include <QWaitCondition> |
| CMake： | find_package(Qt6 REQUIRED COMPONENTS Core) target_link_libraries(mytarget PRIVATE Qt6::Core) |
| qmake： | QT += core |
- 所有成员的列表，包括继承的成员
- QWaitCondition 属于多线程类。
注意：该类中的所有函数均是线程安全的。
公共函数
| 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() |
详细说明
QWaitCondition 允许一个线程通知其他线程某项条件已满足。一个或多个线程可以阻塞，等待 QWaitCondition 使用wakeOne() 或wakeAll() 设置条件。使用wakeOne() 唤醒一个随机选择的线程，或使用wakeAll() 唤醒所有线程。
例如，假设我们有三个任务，这些任务应在用户按下任意键时执行。每个任务都可以拆分为一个线程，每个线程的run() 函数体如下所示：
forever {
mutex.lock();
keyPressed.wait(&mutex);
do_something();
mutex.unlock();
}这里，keyPressed 变量是一个类型为QWaitCondition的全局变量。
第四个线程将负责读取按键事件，并在每次接收到按键时唤醒其他三个线程，如下所示：
forever {
getchar();
keyPressed.wakeAll();
}这三个线程被唤醒的顺序是未定义的。此外，如果按下按键时部分线程仍处于do_something() 状态，它们将不会被唤醒（因为它们没有在等待条件变量），因此该按键对应的任务将不会被执行。 这个问题可以通过使用一个计数器和一个用于保护它的QMutex 来解决。例如，以下是工作线程的新代码：
forever {
mutex.lock();
keyPressed.wait(&mutex);
++count;
mutex.unlock();
do_something();
mutex.lock();
--count;
mutex.unlock();
}以下是第四个线程的代码：
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();
}互斥锁是必要的，因为两个线程同时尝试修改同一变量的值会导致不可预测的结果。
等待条件是一种强大的线程同步原语。“使用等待条件的生成者与消费者”示例展示了如何将 QWaitCondition 作为QSemaphore 的替代方案，用于控制对生成者线程和消费者线程共享的环形缓冲区的访问。
另请参阅 QMutex 、QSemaphore 、QThread以及“使用等待条件的生成者与消费者”。
成员函数文档
QWaitCondition::QWaitCondition()
创建一个新的等待条件对象。
[noexcept] QWaitCondition::~QWaitCondition()
销毁等待条件对象。
void QWaitCondition::notify_all()
提供此函数是为了兼容 STL。它等同于 `wakeAll()`。
void QWaitCondition::notify_one()
提供此函数是为了兼容 STL。它等同于 `wakeOne()`。
bool QWaitCondition::wait(QMutex *lockedMutex, QDeadlineTimer deadline = QDeadlineTimer(QDeadlineTimer::Forever))
释放lockedMutex 并等待满足等待条件。lockedMutex 必须由调用线程先锁定。如果lockedMutex 未处于锁定状态，则行为未定义。如果lockedMutex 是递归互斥锁，则该函数立即返回。lockedMutex 将被解锁，调用线程将阻塞，直到满足以下任一条件：
- 另一个线程通过wakeOne() 或wakeAll() 向其发送信号。在此情况下，该函数将返回 true。
- deadline 指定的截止时间已到。如果deadline 的值为
QDeadlineTimer::Forever（默认值），则等待将永远不会超时（必须由事件发出信号）。如果等待超时，该函数将返回 false。
lockedMutex 将被恢复到相同的“锁定”状态。提供此函数是为了允许从“锁定”状态原子地过渡到“等待”状态。
bool QWaitCondition::wait(QReadWriteLock *lockedReadWriteLock, QDeadlineTimer deadline = QDeadlineTimer(QDeadlineTimer::Forever))
释放lockedReadWriteLock 并等待满足等待条件。lockedReadWriteLock 必须由调用线程最初锁定。如果lockedReadWriteLock 未处于锁定状态，则该函数立即返回。lockedReadWriteLock 不得被递归锁定，否则该函数将无法正确释放锁。lockedReadWriteLock 将被解锁，调用线程将阻塞，直到满足以下任一条件：
- 另一个线程通过wakeOne() 或wakeAll() 向其发送信号。在此情况下，该函数将返回 true。
- 达到由deadline 指定的截止时间。如果deadline 的值为
QDeadlineTimer::Forever（默认值），则等待将永远不会超时（必须由事件发出信号）。如果等待超时，该函数将返回 false。
lockedReadWriteLock 将被恢复到相同的“锁定”状态。提供此函数是为了允许从“锁定”状态原子地过渡到“等待”状态。
bool QWaitCondition::wait(QMutex *lockedMutex, unsigned long time)
释放lockedMutex ，并在等待条件上等待time 毫秒。
这是一个重载函数。
bool QWaitCondition::wait(QReadWriteLock *lockedReadWriteLock, unsigned long time)
释放lockedReadWriteLock ，并在等待条件上等待time 毫秒。
这是一个重载函数。
void QWaitCondition::wakeAll()
唤醒所有正在等待该等待条件的线程。线程被唤醒的顺序取决于操作系统的调度策略，无法控制或预测。
另请参阅 wakeOne()。
void QWaitCondition::wakeOne()
唤醒一个正在等待该等待条件的线程。被唤醒的线程取决于操作系统的调度策略，无法被控制或预测。
若要唤醒特定线程，通常的解决方案是使用不同的等待条件，并让不同的线程分别等待不同的条件。
另请参阅 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.
