QSemaphore Class
Die Klasse QSemaphore bietet eine allgemeine Zählsemaphore. Mehr...
| Kopfzeile: | #include <QSemaphore> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS Core)target_link_libraries(mytarget PRIVATE Qt6::Core) |
| qmake: | QT += core |
- Liste aller Mitglieder, einschließlich geerbter Mitglieder
- QSemaphore ist Teil der Threading-Klassen.
Hinweis: Alle Funktionen in dieser Klasse sind thread-sicher.
Öffentliche Funktionen
| 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) |
Detaillierte Beschreibung
Eine Semaphore ist eine Verallgemeinerung eines Mutex. Während ein Mutex nur einmal gesperrt werden kann, ist es möglich, eine Semaphore mehrfach zu aktivieren. Semaphore werden typischerweise verwendet, um eine bestimmte Anzahl von identischen Ressourcen zu schützen.
Semaphore unterstützen zwei grundlegende Operationen, acquire() und release():
- acquire(n) versucht, n Ressourcen zu erwerben. Wenn nicht so viele Ressourcen verfügbar sind, blockiert der Aufruf, bis dies der Fall ist.
- release(n) gibt n Ressourcen frei.
Es gibt auch eine tryAcquire()-Funktion, die sofort zurückkehrt, wenn sie die Ressourcen nicht erwerben kann, und eine available()-Funktion, die die Anzahl der verfügbaren Ressourcen zu jedem Zeitpunkt zurückgibt.
Beispiel:
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
Eine typische Anwendung von Semaphoren ist die Steuerung des Zugriffs auf einen Ringpuffer, der von einem Producer-Thread und einem Consumer-Thread gemeinsam genutzt wird. Das Beispiel Producer and Consumer using Semaphores zeigt, wie man QSemaphore verwendet, um dieses Problem zu lösen.
Ein nicht rechnergestütztes Beispiel für eine Semaphore wäre das Essen in einem Restaurant. Eine Semaphore wird mit der Anzahl der Stühle im Restaurant initialisiert. Wenn Leute ankommen, wollen sie einen Platz. Wenn die Plätze besetzt sind, wird available() dekrementiert. Wenn die Leute das Restaurant verlassen, wird available() inkrementiert, so dass mehr Leute eintreten können. Wenn eine Gruppe von 10 Personen einen Sitzplatz haben möchte, es aber nur 9 Plätze gibt, warten diese 10 Personen, während eine Gruppe von 4 Personen einen Sitzplatz erhält (was die Anzahl der verfügbaren Plätze auf 5 erhöht und die Gruppe von 10 Personen länger warten lässt).
Siehe auch QSemaphoreReleaser, QMutex, QWaitCondition, QThread und Producer und Consumer using Semaphores.
Dokumentation der Mitgliederfunktionen
[explicit] QSemaphore::QSemaphore(int n = 0)
Erzeugt eine neue Semaphore und initialisiert die Anzahl der Ressourcen, die sie bewacht, auf n (standardmäßig 0).
Siehe auch release() und available().
[noexcept] QSemaphore::~QSemaphore()
Zerstört das Semaphor.
Warnung: Das Zerstören einer Semaphore, die in Gebrauch ist, kann zu undefiniertem Verhalten führen.
void QSemaphore::acquire(int n = 1)
Versucht, die von der Semaphore bewachten n Ressourcen zu erhalten. Wenn n > available() ist, wird dieser Aufruf blockiert, bis genügend Ressourcen verfügbar sind.
Siehe auch release(), available(), und tryAcquire().
int QSemaphore::available() const
Gibt die Anzahl der Ressourcen zurück, die derzeit für die Semaphore verfügbar sind. Diese Zahl kann niemals negativ sein.
Siehe auch acquire() und release().
void QSemaphore::release(int n = 1)
Gibt n Ressourcen frei, die von der Semaphore bewacht werden.
Diese Funktion kann auch zum "Erstellen" von Ressourcen verwendet werden. Zum Beispiel:
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 ist ein RAII-Wrapper um diese Funktion.
Siehe auch acquire(), available(), und QSemaphoreReleaser.
bool QSemaphore::tryAcquire(int n = 1)
Versucht, die von der Semaphore bewachten Ressourcen n zu erwerben und gibt bei Erfolg true zurück. Wenn available() < n, gibt dieser Aufruf sofort false zurück, ohne Ressourcen zu erwerben.
Beispiel:
QSemaphore sem(5); // sem.available() == 5 sem.tryAcquire(250); // sem.available() == 5, returns false sem.tryAcquire(3); // sem.available() == 2, returns true
Siehe auch acquire().
[since 6.6] bool QSemaphore::tryAcquire(int n, QDeadlineTimer timer)
Versucht, die von der Semaphore bewachten Ressourcen n zu erwerben und gibt bei Erfolg true zurück. Wenn available() < n ist, wartet dieser Aufruf, bis timer abläuft, damit die Ressourcen verfügbar werden.
Beispiel:
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
Diese Funktion wurde in Qt 6.6 eingeführt.
Siehe auch acquire().
bool QSemaphore::tryAcquire(int n, int timeout)
Versucht, n von der Semaphore bewachte Ressourcen zu erwerben und gibt bei Erfolg true zurück. Wenn available() < n ist, wartet dieser Aufruf höchstens timeout Millisekunden, bis die Ressourcen verfügbar sind.
Hinweis: Die Übergabe einer negativen Zahl als timeout ist gleichbedeutend mit dem Aufruf von acquire(), d. h. diese Funktion wartet ewig, bis Ressourcen verfügbar werden, wenn timeout negativ ist.
Beispiel:
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
Siehe auch acquire().
[since 6.3] template <typename Rep, typename Period> bool QSemaphore::tryAcquire(int n, std::chrono::duration<Rep, Period> timeout)
Dies ist eine überladene Funktion.
Diese Funktion wurde in Qt 6.3 eingeführt.
[noexcept, since 6.3] bool QSemaphore::try_acquire()
Diese Funktion ist aus Gründen der Kompatibilität mit std::counting_semaphore vorgesehen.
Sie ist äquivalent zum Aufruf von tryAcquire(1), wobei die Funktion bei erfolgreicher Erfassung der Ressource true zurückgibt.
Diese Funktion wurde in Qt 6.3 eingeführt.
Siehe auch tryAcquire(), try_acquire_for(), und try_acquire_until().
[since 6.3] template <typename Rep, typename Period> bool QSemaphore::try_acquire_for(const std::chrono::duration<Rep, Period> &timeout)
Diese Funktion wird aus Gründen der Kompatibilität mit std::counting_semaphore angeboten.
Sie ist gleichbedeutend mit dem Aufruf von tryAcquire(1, timeout), wobei der Aufruf bei dem angegebenen Wert timeout abbricht. Die Funktion gibt true zurück, wenn die Ressource erfolgreich erworben wurde.
Diese Funktion wurde in Qt 6.3 eingeführt.
Siehe auch tryAcquire(), try_acquire(), und try_acquire_until().
[since 6.3] template <typename Clock, typename Duration> bool QSemaphore::try_acquire_until(const std::chrono::time_point<Clock, Duration> &tp)
Diese Funktion wird aus Gründen der Kompatibilität mit std::counting_semaphore angeboten.
Sie ist äquivalent zum Aufruf von tryAcquire(1, tp - Clock::now()), was bedeutet, dass der tp (Zeitpunkt) aufgezeichnet wird und die Anpassungen an Clock während des Wartens ignoriert werden. Die Funktion gibt true zurück, wenn die Ressource erfolgreich erfasst wurde.
Diese Funktion wurde in Qt 6.3 eingeführt.
Siehe auch tryAcquire(), try_acquire(), und 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.
