QSemaphore Class
La clase QSemaphore proporciona un semáforo de recuento general. Más...
| Cabecera: | #include <QSemaphore> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS Core)target_link_libraries(mytarget PRIVATE Qt6::Core) |
| qmake: | QT += core |
- Lista de todos los miembros, incluyendo los heredados
- QSemaphore es parte de la clase Threading Classes.
Nota: Todas las funciones de esta clase son thread-safe.
Funciones Públicas
| 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) |
Descripción Detallada
Un semáforo es una generalización de un mutex. Mientras que un mutex sólo puede ser bloqueado una vez, es posible adquirir un semáforo múltiples veces. Los semáforos se utilizan normalmente para proteger un cierto número de recursos idénticos.
Los semáforos soportan dos operaciones fundamentales, acquire() y release():
- acquire(n) intenta adquirir n recursos. Si no hay tantos recursos disponibles, la llamada se bloqueará hasta que así sea.
- release(n) libera n recursos.
También hay una función tryAcquire() que devuelve inmediatamente si no puede adquirir los recursos, y una función available() que devuelve el número de recursos disponibles en cualquier momento.
Ejemplo:
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
Una aplicación típica de los semáforos es para controlar el acceso a un buffer circular compartido por un hilo productor y un hilo consumidor. El ejemplo Producer and Consumer using Semaphores muestra cómo utilizar QSemaphore para resolver ese problema.
Un ejemplo no informático de un semáforo sería cenar en un restaurante. Se inicializa un semáforo con el número de sillas del restaurante. A medida que la gente llega, quiere un asiento. A medida que se llenan los asientos, se decrementa available(). A medida que la gente se va, available() se incrementa, permitiendo que entre más gente. Si un grupo de 10 personas quiere sentarse, pero sólo hay 9 asientos, esas 10 personas esperarán, pero un grupo de 4 personas se sentará (llevando los asientos disponibles a 5, haciendo que el grupo de 10 personas espere más).
Vea también QSemaphoreReleaser, QMutex, QWaitCondition, QThread, y Productor y Consumidor usando Semáforos.
Documentación de funciones miembro
[explicit] QSemaphore::QSemaphore(int n = 0)
Crea un nuevo semáforo e inicializa el número de recursos que guarda en n (por defecto, 0).
Véase también release() y available().
[noexcept] QSemaphore::~QSemaphore()
Destruye el semáforo.
Advertencia: Destruir un semáforo que está en uso puede provocar un comportamiento indefinido.
void QSemaphore::acquire(int n = 1)
Intenta adquirir n recursos custodiados por el semáforo. Si n > available(), esta llamada se bloqueará hasta que haya suficientes recursos disponibles.
Véase también release(), available(), y tryAcquire().
int QSemaphore::available() const
Devuelve el número de recursos actualmente disponibles para el semáforo. Este número nunca puede ser negativo.
Véase también acquire() y release().
void QSemaphore::release(int n = 1)
Libera n recursos custodiados por el semáforo.
Esta función también puede utilizarse para "crear" recursos. Por ejemplo:
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 es una envoltura RAII alrededor de esta función.
Ver también acquire(), available(), y QSemaphoreReleaser.
bool QSemaphore::tryAcquire(int n = 1)
Intenta adquirir n recursos custodiados por el semáforo y devuelve true en caso de éxito. Si available() < n, esta llamada devuelve inmediatamente false sin adquirir ningún recurso.
Ejemplo:
QSemaphore sem(5); // sem.available() == 5 sem.tryAcquire(250); // sem.available() == 5, returns false sem.tryAcquire(3); // sem.available() == 2, returns true
Véase también acquire().
[since 6.6] bool QSemaphore::tryAcquire(int n, QDeadlineTimer timer)
Intenta adquirir n recursos custodiados por el semáforo y devuelve true en caso de éxito. Si available() < n, esta llamada esperará hasta que timer expire para que los recursos estén disponibles.
Ejemplo:
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
Esta función se introdujo en Qt 6.6.
Véase también acquire().
bool QSemaphore::tryAcquire(int n, int timeout)
Intenta adquirir n recursos custodiados por el semáforo y devuelve true en caso de éxito. Si available() < n, esta llamada esperará como máximo timeout milisegundos a que los recursos estén disponibles.
Nota: Pasar un número negativo como timeout es equivalente a llamar a acquire(), es decir, esta función esperará eternamente a que los recursos estén disponibles si timeout es negativo.
Ejemplo:
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
Véase también acquire().
[since 6.3] template <typename Rep, typename Period> bool QSemaphore::tryAcquire(int n, std::chrono::duration<Rep, Period> timeout)
Esta es una función sobrecargada.
Esta función se introdujo en Qt 6.3.
[noexcept, since 6.3] bool QSemaphore::try_acquire()
Esta función se proporciona por compatibilidad con std::counting_semaphore.
Es equivalente a llamar a tryAcquire(1), donde la función devuelve true al adquirir el recurso con éxito.
Esta función se introdujo en Qt 6.3.
Véase también tryAcquire(), try_acquire_for(), y try_acquire_until().
[since 6.3] template <typename Rep, typename Period> bool QSemaphore::try_acquire_for(const std::chrono::duration<Rep, Period> &timeout)
Esta función se proporciona por compatibilidad con std::counting_semaphore.
Es equivalente a llamar a tryAcquire(1, timeout), donde la llamada se agota en el valor timeout dado. La función devuelve true al adquirir el recurso con éxito.
Esta función se introdujo en Qt 6.3.
Véase también tryAcquire(), try_acquire() y try_acquire_until().
[since 6.3] template <typename Clock, typename Duration> bool QSemaphore::try_acquire_until(const std::chrono::time_point<Clock, Duration> &tp)
Esta función se proporciona por compatibilidad con std::counting_semaphore.
Es equivalente a llamar a tryAcquire(1, tp - Clock::now()), lo que significa que se registra el tp (punto de tiempo), ignorando los ajustes a Clock mientras se espera. La función devuelve true al adquirir el recurso con éxito.
Esta función se introdujo en Qt 6.3.
Véase también tryAcquire(), try_acquire(), y 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.
