Back to Qt.io
Contact Us Blog Download Qt
Sur cette page

QSemaphore Class

La classe QSemaphore fournit un sémaphore de comptage général. En savoir plus...

En-tête : #include <QSemaphore>
CMake : find_package(Qt6 REQUIRED COMPONENTS Core)
target_link_libraries(mytarget PRIVATE Qt6::Core)
qmake : QT += core

Remarque : toutes les fonctions de cette classe sont thread-safe.

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 prennent en charge deux opérations fondamentales : « acquire » () et « release » ():

  • acquire(n) tente d'acquérir n ressources. S'il n'y a pas suffisamment de ressources disponibles, l'appel se bloquera jusqu'à ce que ce soit le cas.
  • release(n) libère n ressources.

Il existe également une fonction tryAcquire() qui renvoie immédiatement un résultat si elle ne parvient pas à acquérir les ressources, et une fonction available() qui renvoie 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 consiste à contrôler l’accès à un tampon circulaire partagé par un thread producteur et un thread consommateur. L’exemple « Producteur et consommateur utilisant des sémaphores » montre comment utiliser QSemaphore pour résoudre ce problème.

Un exemple de sémaphore hors du domaine informatique serait un dîner au restaurant. Un sémaphore est initialisé avec le nombre de chaises disponibles dans le restaurant. À mesure que les clients arrivent, ils souhaitent s’asseoir. À mesure que les places sont occupées, la valeur de ` available()` est décrémentée. À mesure que les clients partent, la valeur de ` available()` est incrémentée, permettant ainsi à d’autres clients d’entrer. Si un groupe de 10 personnes souhaite s'asseoir, mais qu'il n'y a que 9 places disponibles, ces 10 personnes devront attendre, tandis qu'un groupe de 4 personnes pourra s'asseoir (ce qui ramène le nombre de places disponibles à 5 et oblige le groupe de 10 personnes à attendre plus longtemps).

Voir également QSemaphoreReleaser, QMutex, QWaitCondition, QThread, ainsi que « Producteur et consommateur à l'aide de sémaphores ».

Documentation des fonctions membres

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

Crée un nouveau sémaphore et initialise le nombre de ressources qu'il gère à n (par défaut, 0).

Voir également release() et available().

[noexcept] QSemaphore::~QSemaphore()

Détruit le sémaphore.

Avertissement : 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 des ressources n protégées par le sémaphore. Si n > available(), cet appel se bloquera jusqu’à ce que suffisamment de ressources soient disponibles.

Voir également 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 également acquire() et release().

void QSemaphore::release(int n = 1)

Libère les ressources de type « n » protégé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 un wrapper RAII autour de cette fonction.

Voir également acquire(), available() et QSemaphoreReleaser.

bool QSemaphore::tryAcquire(int n = 1)

Tente d'acquérir n les ressources protégées par le sémaphore et renvoie true en cas de réussite. Si available() < n, cet appel renvoie immédiatement false sans acquérir aucune ressource.

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 protégé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 également acquire().

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

Tente d’acquérir les ressources n protégées par le sémaphore et renvoie true en cas de succès. Si available() < n, cet appel attendra au maximum timeout millisecondes que les ressources deviennent disponibles.

Remarque : passer un nombre négatif comme paramètre « timeout » revient à appeler acquire(), c'est-à-dire que cette fonction attendra indéfiniment que les 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 à l'appel de ` tryAcquire(1)`, où la fonction renvoie ` true ` si la ressource a été acquise avec succès.

Cette fonction a été introduite dans Qt 6.3.

Voir également 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 équivaut à l'appel de ` tryAcquire(1, timeout)`, où l'appel expire au bout du délai défini par la valeur ` timeout `. La fonction renvoie ` true ` si l'acquisition de la ressource a réussi.

Cette fonction a été introduite dans Qt 6.3.

Voir également 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 à l’appel de ` tryAcquire(1, tp - Clock::now())`, ce qui signifie que l’ tp (instant) est enregistrée, sans tenir compte des ajustements apportés à ` Clock ` pendant l’attente. La fonction renvoie ` true ` si la ressource est acquise avec succès.

Cette fonction a été introduite dans Qt 6.3.

Voir également 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.