Back to Qt.io
Contact Us Blog Download Qt

QSemaphore Class

QSemaphore 类提供了一种通用计数信号。更多

头文件： #include <QSemaphore>
CMake： find_package(Qt6 REQUIRED COMPONENTS Core)
target_link_libraries(mytarget PRIVATE Qt6::Core)
qmake： QT += core

注意：该类中的所有函数都是线程安全的。

公共函数

QSemaphore(int n = 0)
~QSemaphore()
void acquire(int n = 1)
int available() const
void release(int n = 1)
bool tryAcquire(int n = 1)
(since 6.6) bool tryAcquire(int n, QDeadlineTimer timer)
bool tryAcquire(int n, int timeout)
(since 6.3) bool tryAcquire(int n, std::chrono::duration<Rep, Period> timeout)
(since 6.3) bool try_acquire()
(since 6.3) bool try_acquire_for(const std::chrono::duration<Rep, Period> &timeout)
(since 6.3) bool try_acquire_until(const std::chrono::time_point<Clock, Duration> &tp)

详细说明

寄存器是对互斥的一种概括。虽然互斥只能锁定一次，但却可以多次获取一个 Semaphore。Semaphores 通常用于保护一定数量的相同资源。

Semaphores 支持两个基本操作：acquire() 和release() ：

  • acquire(n) 尝试获取n 个资源。如果没有那么多可用资源，调用将阻塞，直到出现这种情况。
  • release(n) 释放n 个资源。

还有一个tryAcquire() 函数，如果无法获取资源，则立即返回；还有一个available() 函数，可随时返回可用资源的数量。

举例说明：

QSemaphore sem(5);      // sem.available() == 5

sem.acquire(3);         // sem.available() == 2
sem.acquire(2);         // sem.available() == 0
sem.release(5);         // sem.available() == 5
sem.release(5);         // sem.available() == 10

sem.tryAcquire(1);      // sem.available() == 9, returns true
sem.tryAcquire(250);    // sem.available() == 9, returns false

生产者线程和消费者线程共享的循环缓冲区的访问控制是 Semaphores 的典型应用。使用 Semaphores 的生产者和消费者示例展示了如何使用 QSemaphore 解决这一问题。

在餐厅用餐是一个非计算类的 Semaphore 示例。用餐厅的椅子数量对一个信号进行初始化。当人们到达时，他们想要一个座位。当座位坐满时，available() 就会递减。当有人离开时，available() 就会递增，允许更多的人进入。如果一行 10 人想入座，但只有 9 个座位，那么这 10 人将等待，但一行 4 人将入座（将可用座位减至 5 个，使一行 10 人等待的时间更长）。

另请参阅 QSemaphoreReleaser,QMutex,QWaitCondition,QThread 以及使用 Semaphores 的生产者和消费者。

成员函数文档

[explicit] QSemaphore::QSemaphore(int n = 0)

创建一个新的 semaphore，并将其守护的资源数初始化为n （默认为 0）。

另请参阅 release() 和available()。

[noexcept] QSemaphore::~QSemaphore()

销毁信号灯。

警告 销毁正在使用的信号传递器可能会导致未定义的行为。

void QSemaphore::acquire(int n = 1)

尝试获取由 semaphore 保护的n 资源。如果n >available() ，该调用将阻塞，直到有足够的资源可用。

另请参阅 release()、available() 和tryAcquire()。

int QSemaphore::available() const

返回 semaphore 当前可用资源的数量。该数字永远不会为负数。

另请参阅 acquire() 和release()。

void QSemaphore::release(int n = 1)

释放由 semaphore 保护的n 资源。

该函数也可用于 "创建 "资源。例如

QSemaphore sem(5);      // a semaphore that guards 5 resources
sem.acquire(5);         // acquire all 5 resources
sem.release(5);         // release the 5 resources
sem.release(10);        // "create" 10 new resources

QSemaphoreReleaser 是该函数的 RAII封装函数。

另请参阅 acquire(),available() 和QSemaphoreReleaser 。

bool QSemaphore::tryAcquire(int n = 1)

尝试获取由 semaphore 保护的n 资源，成功后返回true 。如果available() <n ，该调用将立即返回false ，而不会获取任何资源。

示例：

QSemaphore sem(5);      // sem.available() == 5
sem.tryAcquire(250);    // sem.available() == 5, returns false
sem.tryAcquire(3);      // sem.available() == 2, returns true

另请参见 acquire()。

[since 6.6] bool QSemaphore::tryAcquire(int n, QDeadlineTimer timer)

尝试获取由 semaphore 保护的n 资源，成功后返回true 。如果available() <n ，则该调用将等待timer 过期，资源才会可用。

示例：

QSemaphore sem(5);                          // sem.available() == 5
sem.tryAcquire(250, QDeadlineTimer(1000));  // sem.available() == 5, waits 1000 milliseconds and returns false
sem.tryAcquire(3, QDeadlineTimer(30s));     // sem.available() == 2, returns true without waiting

此函数在 Qt 6.6 中引入。

另请参阅 acquire()。

bool QSemaphore::tryAcquire(int n, int timeout)

尝试获取由 semaphore 保护的n 资源，成功后返回true 。如果available() <n ，则此调用将最多等待timeout 毫秒，直到资源可用。

注意：传递负数作为timeout 相当于调用acquire()，也就是说，如果timeout 为负数，则此函数将永远等待资源可用。

示例

QSemaphore sem(5);            // sem.available() == 5
sem.tryAcquire(250, 1000);    // sem.available() == 5, waits 1000 milliseconds and returns false
sem.tryAcquire(3, 30000);     // sem.available() == 2, returns true without waiting

另请参见 acquire()。

[since 6.3] template <typename Rep, typename Period> bool QSemaphore::tryAcquire(int n, std::chrono::duration<Rep, Period> timeout)

这是一个重载函数。

该函数在 Qt 6.3 中引入。

[noexcept, since 6.3] bool QSemaphore::try_acquire()

该函数与std::counting_semaphore 兼容。

它等同于调用tryAcquire(1) ，其中函数在成功获取资源后返回true 。

此函数在 Qt 6.3 中引入。

另请参阅 tryAcquire()、try_acquire_for() 和try_acquire_until()。

[since 6.3] template <typename Rep, typename Period> bool QSemaphore::try_acquire_for(const std::chrono::duration<Rep, Period> &timeout)

该函数与std::counting_semaphore 兼容。

它等同于调用tryAcquire(1, timeout) ，其中，调用时间超出给定的timeout 值。该函数在成功获取资源后返回true 。

该函数在 Qt 6.3 中引入。

另请参阅 tryAcquire()、try_acquire() 和try_acquire_until()。

[since 6.3] template <typename Clock, typename Duration> bool QSemaphore::try_acquire_until(const std::chrono::time_point<Clock, Duration> &tp)

提供此函数是为了与std::counting_semaphore 兼容。

它等同于调用tryAcquire(1, tp - Clock::now()) ，即记录tp （时间点），忽略等待期间对Clock 的调整。该函数在成功获取资源后返回true 。

该函数在 Qt 6.3 中引入。

另请参阅 tryAcquire()、try_acquire() 和try_acquire_for()。

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