QSemaphore Class
La classe QSemaphore fournit un sémaphore de comptage général. Plus d'informations...
| En-tête : | #include <QSemaphore> |
| CMake : | find_package(Qt6 REQUIRED COMPONENTS Core)target_link_libraries(mytarget PRIVATE Qt6::Core) |
| qmake : | QT += core |
- Liste de tous les membres, y compris les membres hérités
- QSemaphore fait partie de Threading Classes.
Remarque : toutes les fonctions de cette classe sont sûres pour les threads.
Fonctions publiques
| 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) |
Description détaillée
Un sémaphore est une généralisation d'un mutex. Alors qu'un mutex ne peut être verrouillé qu'une seule fois, il est possible d'acquérir un sémaphore plusieurs fois. Les sémaphores sont généralement utilisés pour protéger un certain nombre de ressources identiques.
Les sémaphores supportent deux opérations fondamentales, acquire() et release() :
- acquire(n) tente d'acquérir n ressources. S'il n'y a pas autant de ressources disponibles, l'appel se bloque jusqu'à ce que ce soit le cas.
- release(n) libère n ressources.
Il existe également une fonction tryAcquire() qui retourne immédiatement si elle ne peut pas acquérir les ressources, et une fonction available() qui retourne le nombre de ressources disponibles à tout moment.
Exemple :
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
Une application typique des sémaphores est le contrôle de l'accès à un tampon circulaire partagé par un thread producteur et un thread consommateur. L'exemple Producer and Consumer using Semaphores montre comment utiliser QSemaphore pour résoudre ce problème.
Un exemple non informatique de sémaphore serait celui d'un repas au restaurant. Un sémaphore est initialisé avec le nombre de chaises dans le restaurant. Au fur et à mesure que les gens arrivent, ils veulent une place. Au fur et à mesure que les places sont occupées, available() est décrémenté. Lorsque les gens partent, available() est incrémenté, ce qui permet à d'autres personnes d'entrer. Si un groupe de 10 personnes souhaite s'asseoir, mais qu'il n'y a que 9 sièges, ces 10 personnes attendront, mais un groupe de 4 personnes sera assis (ce qui portera le nombre de sièges disponibles à 5 et fera attendre le groupe de 10 personnes plus longtemps).
Voir aussi QSemaphoreReleaser, QMutex, QWaitCondition, QThread, et Producer and Consumer using Semaphores.
Documentation sur les fonctions membres
[explicit] QSemaphore::QSemaphore(int n = 0)
Crée un nouveau sémaphore et initialise le nombre de ressources qu'il garde à n (par défaut, 0).
Voir aussi release() et available().
[noexcept] QSemaphore::~QSemaphore()
Détruit le sémaphore.
Attention : La destruction d'un sémaphore en cours d'utilisation peut entraîner un comportement indéfini.
void QSemaphore::acquire(int n = 1)
Tente d'acquérir les ressources n gardées par le sémaphore. Si n > available(), cet appel se bloquera jusqu'à ce que suffisamment de ressources soient disponibles.
Voir aussi release(), available() et tryAcquire().
int QSemaphore::available() const
Renvoie le nombre de ressources actuellement disponibles pour le sémaphore. Ce nombre ne peut jamais être négatif.
Voir aussi acquire() et release().
void QSemaphore::release(int n = 1)
Libère n les ressources gardées par le sémaphore.
Cette fonction peut également être utilisée pour "créer" des ressources. Par exemple :
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 est une enveloppe RAII autour de cette fonction.
Voir aussi acquire(), available() et QSemaphoreReleaser.
bool QSemaphore::tryAcquire(int n = 1)
Tente d'acquérir les ressources n gardées par le sémaphore et renvoie true en cas de succès. Si available() < n, cet appel renvoie immédiatement false sans acquérir de ressources.
Exemple :
QSemaphore sem(5); // sem.available() == 5 sem.tryAcquire(250); // sem.available() == 5, returns false sem.tryAcquire(3); // sem.available() == 2, returns true
Voir aussi acquire().
[since 6.6] bool QSemaphore::tryAcquire(int n, QDeadlineTimer timer)
Tente d'acquérir n les ressources gardées par le sémaphore et renvoie true en cas de succès. Si available() < n, cet appel attendra que timer expire pour que les ressources deviennent disponibles.
Exemple :
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
Cette fonction a été introduite dans Qt 6.6.
Voir aussi acquire().
bool QSemaphore::tryAcquire(int n, int timeout)
Tente d'acquérir n les ressources gardées par le sémaphore et renvoie true en cas de succès. Si available() < n, cet appel attendra au maximum timeout millisecondes pour que les ressources deviennent disponibles.
Remarque : le fait de transmettre un nombre négatif comme timeout équivaut à appeler acquire(), c'est-à-dire que cette fonction attendra indéfiniment que des ressources soient disponibles si timeout est négatif.
Exemple :
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
Voir aussi acquire().
[since 6.3] template <typename Rep, typename Period> bool QSemaphore::tryAcquire(int n, std::chrono::duration<Rep, Period> timeout)
Il s'agit d'une fonction surchargée.
Cette fonction a été introduite dans Qt 6.3.
[noexcept, since 6.3] bool QSemaphore::try_acquire()
Cette fonction est fournie à des fins de compatibilité avec std::counting_semaphore.
Elle équivaut à appeler tryAcquire(1), la fonction renvoyant true lorsque la ressource a été acquise avec succès.
Cette fonction a été introduite dans Qt 6.3.
Voir aussi tryAcquire(), try_acquire_for() et try_acquire_until().
[since 6.3] template <typename Rep, typename Period> bool QSemaphore::try_acquire_for(const std::chrono::duration<Rep, Period> &timeout)
Cette fonction est fournie à des fins de compatibilité avec std::counting_semaphore.
Elle est équivalente à l'appel de tryAcquire(1, timeout), où l'appel s'arrête à la valeur donnée de timeout. La fonction renvoie true si l'acquisition de la ressource est réussie.
Cette fonction a été introduite dans Qt 6.3.
Voir aussi tryAcquire(), try_acquire(), et try_acquire_until().
[since 6.3] template <typename Clock, typename Duration> bool QSemaphore::try_acquire_until(const std::chrono::time_point<Clock, Duration> &tp)
Cette fonction est fournie à des fins de compatibilité avec std::counting_semaphore.
Elle équivaut à appeler tryAcquire(1, tp - Clock::now()), ce qui signifie que le tp (point temporel) est enregistré, en ignorant les ajustements à Clock pendant l'attente. La fonction renvoie true lorsque l'acquisition de la ressource a réussi.
Cette fonction a été introduite dans Qt 6.3.
Voir aussi tryAcquire(), try_acquire() et 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.
