QSystemSemaphore Class
La clase QSystemSemaphore proporciona un semáforo de sistema de recuento general. Más...
| Cabecera: | #include <QSystemSemaphore> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS Core)target_link_libraries(mytarget PRIVATE Qt6::Core) |
| qmake: | QT += core |
Tipos Públicos
| enum | AccessMode { Open, Create } |
| enum | SystemSemaphoreError { NoError, PermissionDenied, KeyError, AlreadyExists, NotFound, …, UnknownError } |
Funciones Públicas
| QSystemSemaphore(const QNativeIpcKey &key, int initialValue = 0, QSystemSemaphore::AccessMode mode = Open) | |
| QSystemSemaphore(const QString &key, int initialValue = 0, QSystemSemaphore::AccessMode mode = Open) | |
| ~QSystemSemaphore() | |
| bool | acquire() |
| QSystemSemaphore::SystemSemaphoreError | error() const |
| QString | errorString() const |
| QString | key() const |
| QNativeIpcKey | nativeIpcKey() const |
| bool | release(int n = 1) |
| void | setKey(const QString &key, int initialValue = 0, QSystemSemaphore::AccessMode mode = Open) |
| void | setNativeKey(const QNativeIpcKey &key, int initialValue = 0, QSystemSemaphore::AccessMode mode = Open) |
Descripción detallada
Un semáforo de sistema es una generalización de QSemaphore. Típicamente, un semáforo se utiliza para proteger un cierto número de recursos idénticos.
Al igual que su homólogo más ligero, se puede acceder a un QSystemSemaphore desde múltiples threads. A diferencia de QSemaphore, también se puede acceder a un QSystemSemaphore desde múltiples processes. Esto significa que QSystemSemaphore es una clase mucho más pesada, así que si tu aplicación no necesita acceder a tus semáforos a través de múltiples procesos, probablemente querrás usar QSemaphore.
Los semáforos soportan dos operaciones fundamentales, acquire() y release():
acquire() intenta adquirir un recurso. Si no hay un recurso disponible, la llamada se bloquea hasta que haya un recurso disponible. Entonces se adquiere el recurso y la llamada regresa.
release() libera un recurso para que pueda ser adquirido por otro proceso. La función también puede llamarse con un parámetro n > 1, que libera n recursos.
Los semáforos del sistema se identifican mediante una clave, representada por QNativeIpcKey. Una clave puede crearse de forma multiplataforma utilizando platformSafeKey(). Un semáforo de sistema es creado por el constructor QSystemSemaphore cuando se le pasa un parámetro de modo de acceso de AccessMode::Create. Una vez creado, otros procesos pueden adjuntarse al mismo semáforo utilizando la misma clave y un parámetro de modo de acceso de AccessMode::Open.
Ejemplo: Crear un semáforo del sistema
QSystemSemaphore sem(QSystemSemaphore::platformSafeKey("market"), 3, QSystemSemaphore::Create); // resources available == 3 sem.acquire(); // resources available == 2 sem.acquire(); // resources available == 1 sem.acquire(); // resources available == 0 sem.release(); // resources available == 1 sem.release(2); // resources available == 3
Para obtener más información sobre los tipos de claves, las limitaciones específicas de la plataforma y la interoperabilidad con aplicaciones antiguas o que no sean Qt, consulte la documentación Claves IPC nativas. Eso incluye información importante para aplicaciones sandboxed en plataformas Apple, incluyendo todas las aplicaciones obtenidas a través de la Apple App Store.
Ver también Comunicación entre Procesos, QSharedMemory, y QSemaphore.
Documentación de tipos de miembros
enum QSystemSemaphore::AccessMode
Este enum es utilizado por el constructor y setKey(). Su propósito es permitir el manejo del problema en implementaciones Unix de semáforos que sobreviven a una caída. En Unix, cuando un semáforo sobrevive a una caída, necesitamos una forma de forzarlo a reiniciar su cuenta de recursos, cuando el sistema reutiliza el semáforo. En Windows, donde los semáforos no pueden sobrevivir a una caída, este enum no tiene efecto.
| Constante | Valor | Descripción |
|---|---|---|
QSystemSemaphore::Open | 0 | Si el semáforo ya existe, su recuento inicial de recursos no se reinicia. Si el semáforo aún no existe, se crea y se establece su recuento inicial de recursos. |
QSystemSemaphore::Create | 1 | QSystemSemaphore toma posesión del semáforo y establece su recuento de recursos al valor solicitado, independientemente de si el semáforo ya existe por haber sobrevivido a un fallo. Este valor debe pasarse al constructor, cuando se construye el primer semáforo para una clave concreta y se sabe que si el semáforo ya existe sólo puede ser debido a un fallo. En Windows, donde un semáforo no puede sobrevivir a una caída, Crear y Abrir tienen el mismo comportamiento. |
enum QSystemSemaphore::SystemSemaphoreError
| Constante | Valor | Descripción |
|---|---|---|
QSystemSemaphore::NoError | 0 | No se ha producido ningún error. |
QSystemSemaphore::PermissionDenied | 1 | La operación falló porque la persona que llamó no tenía los permisos requeridos. |
QSystemSemaphore::KeyError | 2 | La operación ha fallado porque la clave no es válida. |
QSystemSemaphore::AlreadyExists | 3 | La operación falló porque ya existía un semáforo del sistema con la clave especificada. |
QSystemSemaphore::NotFound | 4 | La operación falló porque no se pudo encontrar un semáforo del sistema con la clave especificada. |
QSystemSemaphore::OutOfResources | 5 | La operación falló porque no había suficiente memoria disponible para completar la petición. |
QSystemSemaphore::UnknownError | 6 | Algo más ocurrió y fue malo. |
Documentación de las funciones miembro
QSystemSemaphore::QSystemSemaphore(const QNativeIpcKey &key, int initialValue = 0, QSystemSemaphore::AccessMode mode = Open)
Solicita un semáforo del sistema para el key especificado. Los parámetros initialValue y mode se utilizan de acuerdo con las siguientes reglas, que dependen del sistema.
En Unix, si mode es Open y el sistema ya tiene un semáforo identificado por key, se utiliza ese semáforo y no se modifica el recuento de recursos del semáforo, es decir, se ignora initialValue. Pero si el sistema aún no tiene un semáforo identificado por key, crea un nuevo semáforo para esa clave y establece su recuento de recursos en initialValue.
En Unix, si mode es Create y el sistema ya tiene un semáforo identificado por key, se utiliza ese semáforo y su recuento de recursos se establece en initialValue. Si el sistema no tiene ya un semáforo identificado por key, crea un nuevo semáforo para esa clave y establece su recuento de recursos en initialValue.
En Windows, se ignora mode y el sistema siempre intenta crear un semáforo para la clave especificada key. Si el sistema aún no tiene un semáforo identificado como key, crea el semáforo y establece su recuento de recursos en initialValue. Pero si el sistema ya tiene un semáforo identificado como key, utiliza ese semáforo e ignora initialValue.
El parámetro mode sólo se utiliza en sistemas Unix para manejar el caso en el que un semáforo sobrevive a la caída de un proceso. En ese caso, el siguiente proceso que asigne un semáforo con el mismo key obtendrá el semáforo que sobrevivió a la caída, y a menos que mode sea Create, el recuento de recursos no se restablecerá a initialValue sino que mantendrá el valor inicial que le había dado el proceso caído.
Véase también acquire() y key().
QSystemSemaphore::QSystemSemaphore(const QString &key, int initialValue = 0, QSystemSemaphore::AccessMode mode = Open)
Solicita un semáforo del sistema identificado por la clave heredada key.
[noexcept] QSystemSemaphore::~QSystemSemaphore()
El destructor destruye el objeto QSystemSemaphore, pero el semáforo del sistema subyacente no se elimina del sistema a menos que esta instancia de QSystemSemaphore sea la última existente para ese semáforo del sistema.
Dos efectos secundarios importantes del destructor dependen del sistema. En Windows, si acquire() ha sido llamado para este semáforo pero no release(), release() no será llamado por el destructor, ni el recurso será liberado cuando el proceso salga normalmente. Esto sería un error de programa que podría ser la causa de un bloqueo en otro proceso que intente adquirir el mismo recurso. En Unix, los recursos adquiridos que no se liberan antes de llamar al destructor se liberan automáticamente cuando el proceso sale.
bool QSystemSemaphore::acquire()
Adquiere uno de los recursos custodiados por este semáforo, si hay alguno disponible, y devuelve true. Si todos los recursos custodiados por este semáforo ya han sido adquiridos, la llamada se bloquea hasta que uno de ellos sea liberado por otro proceso o hilo que tenga un semáforo con la misma clave.
Si se devuelve false, se ha producido un error del sistema. Llame a error() para obtener un valor de QSystemSemaphore::SystemSemaphoreError que indique qué error se ha producido.
Véase también release().
QSystemSemaphore::SystemSemaphoreError QSystemSemaphore::error() const
Devuelve un valor que indica si se ha producido un error y, en caso afirmativo, de qué error se trata.
Véase también errorString().
QString QSystemSemaphore::errorString() const
Devuelve una descripción de texto del último error que se ha producido. Si error() devuelve un error value, llame a esta función para obtener una cadena de texto que describa el error.
Véase también error().
QString QSystemSemaphore::key() const
Devuelve la clave heredada asignada a este semáforo del sistema. La clave es el nombre por el que se puede acceder al semáforo desde otros procesos.
Véase también setKey().
QNativeIpcKey QSystemSemaphore::nativeIpcKey() const
Devuelve la clave asignada a este semáforo del sistema. La clave es el nombre por el que se puede acceder al semáforo desde otros procesos.
Puede utilizar la clave nativa para acceder a semáforos del sistema que no hayan sido creados por Qt, o para conceder acceso a aplicaciones que no sean Qt. Ver Native IPC Ke ys para más información.
Véase también setNativeKey().
bool QSystemSemaphore::release(int n = 1)
Libera n recursos custodiados por el semáforo. Devuelve true salvo error del sistema.
Ejemplo: Crear un semáforo del sistema que tenga cinco recursos; adquirirlos todos y luego liberarlos todos.
QSystemSemaphore sem(QSystemSemaphore::platformSafeKey("market"), 5, QSystemSemaphore::Create); for (int i = 0; i < 5; ++i) // acquire all 5 resources sem.acquire(); sem.release(5); // release the 5 resources
Esta función también puede "crear" recursos. Por ejemplo, inmediatamente después de la secuencia de sentencias anterior, supongamos que añadimos la sentencia
sem.release(10); // "create" 10 new resources
El semáforo vigila ahora diez nuevos recursos, además de los cinco que ya existían. Normalmente no se utilizaría esta función para crear más recursos.
Véase también acquire().
void QSystemSemaphore::setKey(const QString &key, int initialValue = 0, QSystemSemaphore::AccessMode mode = Open)
Esta función funciona igual que el constructor. Reconstruye este objeto QSystemSemaphore. Si el nuevo key es diferente de la clave antigua, llamar a esta función es como llamar al destructor del semáforo con la clave antigua, y luego llamar al constructor para crear un nuevo semáforo con el nuevo key. Los parámetros initialValue y mode son los definidos para el constructor.
Véase también QSystemSemaphore() y key().
void QSystemSemaphore::setNativeKey(const QNativeIpcKey &key, int initialValue = 0, QSystemSemaphore::AccessMode mode = Open)
Esta función funciona igual que el constructor. Reconstruye este objeto QSystemSemaphore. Si el nuevo key es diferente de la clave antigua, llamar a esta función es como llamar al destructor del semáforo con la clave antigua, y luego llamar al constructor para crear un nuevo semáforo con el nuevo key. Los parámetros initialValue y mode son los definidos para el constructor.
Esta función es útil si la clave nativa fue compartida desde otro proceso. Ver Claves IPC nativas para más información.
Véase también QSystemSemaphore() y nativeIpcKey().
© 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.
