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)

详细说明

信号量是互斥锁的泛化形式。互斥锁只能被锁定一次，而信号量则可以被多次获取。信号量通常用于保护一定数量的相同资源。

信号量支持两种基本操作：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

信号量的典型应用是控制生产者线程和消费者线程共享的环形缓冲区的访问权限。“使用信号量的生产者与消费者”示例展示了如何使用QSemaphore 解决该问题。

一个非计算领域的信号量示例是餐厅就餐。信号量初始化为餐厅的座椅数量。随着客人到来，他们需要座位。当座位被占用时，available() 会被递减。当客人离开时，available() 会被递增，从而允许更多人进入。 如果有一桌10人想入座，但只有9个座位，这10人将需要等待；而一桌4人则可以入座（使可用座位数变为5，导致那桌10人需要等待更长时间）。

另请参阅 QSemaphoreReleaser 、QMutex 、QWaitCondition 、QThread 以及“使用信号量的生产者与消费者”。

成员函数文档

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

创建一个新的信号量，并将它所保护的资源数量初始化为n （默认值为0）。

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

[noexcept] QSemaphore::~QSemaphore()

销毁该信号量。

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

void QSemaphore::acquire(int n = 1)

尝试获取由信号量保护的n 资源。如果n >available()，则此调用将阻塞，直到有足够的资源可用为止。

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

int QSemaphore::available() const

返回信号量当前可用的资源数量。该数值绝不会为负。

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

void QSemaphore::release(int n = 1)

释放由信号量保护的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)

尝试获取由信号量保护的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)

尝试获取由信号量保护的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)

尝试获取由信号量保护的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()。

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