QSemaphore Class
La clase QSemaphore proporciona un semáforo de recuento general. Más información...
| Encabezado: | #include <QSemaphore> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS Core) target_link_libraries(mytarget PRIVATE Qt6::Core) |
| qmake: | QT += core |
- Lista de todos los miembros, incluidos los heredados
- QSemaphore forma parte de las clases de subprocesos.
Nota: Todas las funciones de esta clase son seguras para subprocesos.
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 solo se puede bloquear una vez, es posible adquirir un semáforo varias veces. Los semáforos se utilizan normalmente para proteger un número determinado de recursos idénticos.
Los semáforos admiten dos operaciones fundamentales: « acquire()» y « release()»:
- acquire(n) intenta adquirir n recursos. Si no hay tantos recursos disponibles, la llamada se bloqueará hasta que haya suficientes.
- release(n) libera n recursos.
También existe una función tryAcquire() que devuelve un valor 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 falseUna aplicación típica de los semáforos es el control del acceso a un búfer circular compartido por un hilo productor y un hilo consumidor. El ejemplo «Productor y consumidor con semáforos» muestra cómo utilizar QSemaphore para resolver ese problema.
Un ejemplo no informático de un semáforo sería ir a cenar a un restaurante. El semáforo se inicializa con el número de sillas del restaurante. A medida que llega la gente, busca un asiento. A medida que se van ocupando los asientos, se decrementa available(). Cuando la gente se marcha, se incrementa available(), lo que permite que entren más personas. Si un grupo de 10 personas quiere sentarse, pero solo hay 9 asientos, esas 10 personas tendrán que esperar, mientras que un grupo de 4 personas sí podrá sentarse (lo que reduce a 5 el número de asientos disponibles y hace que el grupo de 10 personas tenga que esperar más tiempo).
Véase también QSemaphoreReleaser, QMutex, QWaitCondition, QThread y «Productor y consumidor mediante semáforos».
Documentación de las funciones de miembro
[explicit] QSemaphore::QSemaphore(int n = 0)
Crea un nuevo semáforo e inicializa el número de recursos que protege en n (por defecto, 0).
Véanse también ` release()` y ` available()`.
[noexcept] QSemaphore::~QSemaphore()
Destruye el semáforo.
Advertencia: La destrucción de un semáforo que está en uso puede provocar un comportamiento indefinido.
void QSemaphore::acquire(int n = 1)
Intenta adquirir n recursos protegidos 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 disponibles actualmente 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 los recursos de « n » protegidos por el semáforo.
Esta función también se puede utilizar 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 resourcesQSemaphoreReleaser es un envoltorio RAII de esta función.
Véase también acquire(), available() y QSemaphoreReleaser.
bool QSemaphore::tryAcquire(int n = 1)
Intenta adquirir n los recursos protegidos por el semáforo y devuelve true si la operación se realiza con é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 trueVéase también acquire().
[since 6.6] bool QSemaphore::tryAcquire(int n, QDeadlineTimer timer)
Intenta adquirir un n e de los recursos protegidos por el semáforo y devuelve un true e si la operación se realiza con éxito. Si available() < n, esta llamada esperará hasta que timer expire para que los recursos queden 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 waitingEsta función se introdujo en Qt 6.6.
Véase también acquire().
bool QSemaphore::tryAcquire(int n, int timeout)
Intenta adquirir n los recursos protegidos por el semáforo y devuelve true si la operación se realiza con é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 ` equivale a llamar a ` acquire()`, es decir, esta función esperará indefinidamente 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 waitingVé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 ofrece para garantizar la compatibilidad con std::counting_semaphore.
Equivale a llamar a ` tryAcquire(1)`, donde la función devuelve ` true ` si se obtiene el recurso correctamente.
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 para garantizar la compatibilidad con std::counting_semaphore.
Equivale a llamar a ` tryAcquire(1, timeout)`, donde la llamada caduca según el valor ` timeout ` especificado. La función devuelve ` true ` si se adquiere el recurso correctamente.
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 ofrece para garantizar la compatibilidad con « std::counting_semaphore ».
Es equivalente a llamar a ` tryAcquire(1, tp - Clock::now())`, lo que significa que se registra ` tp ` (el momento en el tiempo), ignorando los ajustes en ` 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.