QSystemSemaphore Class
La clase `QSystemSemaphore` proporciona un semáforo de sistema de conteo general. Más información...
| Encabezado: | #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 del sistema es una generalización de QSemaphore. Normalmente, un semáforo se utiliza para proteger un número determinado de recursos idénticos.
Al igual que su equivalente más ligero, se puede acceder a un `QSystemSemaphore` desde varios ` threads`. A diferencia de ` QSemaphore`, también se puede acceder a un `QSystemSemaphore` desde varios ` processes`. Esto significa que `QSystemSemaphore` es una clase mucho más pesada, por lo que, si tu aplicación no necesita acceder a los semáforos desde varios procesos, probablemente te convenga utilizar ` QSemaphore`.
Los semáforos admiten dos operaciones fundamentales: « acquire()» y « release()»:
acquire() intenta adquirir un recurso. Si no hay ningún recurso disponible, la llamada se bloquea hasta que haya uno disponible. A continuación, se adquiere el recurso y la llamada devuelve un valor.
release() libera un recurso para que pueda ser adquirido por otro proceso. La función también puede invocarse con un parámetro n > 1, lo que libera n recursos.
Los semáforos del sistema se identifican mediante una clave, representada por QNativeIpcKey. Se puede crear una clave de forma multiplataforma utilizando platformSafeKey(). Un semáforo del sistema se crea mediante el constructor QSystemSemaphore cuando se le pasa un parámetro de modo de acceso de tipo « AccessMode::Create ». Una vez creado, otros procesos pueden conectarse al mismo semáforo utilizando la misma clave y un parámetro de modo de acceso de tipo « 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 == 3Para obtener más detalles sobre los tipos de clave, las limitaciones específicas de cada plataforma y la interoperabilidad con aplicaciones más antiguas o ajenas a Qt, consulte la documentación sobre claves IPC nativas. Esta incluye información importante para aplicaciones en entorno aislado (sandbox) en plataformas de Apple, incluidas todas las aplicaciones obtenidas a través de la App Store de Apple.
Véase también Comunicación entre procesos, QSharedMemory y QSemaphore.
Documentación sobre tipos de miembros
enum QSystemSemaphore::AccessMode
Esta enumeración la utilizan el constructor y la función ` setKey()`. Su finalidad es permitir gestionar el problema que se produce en las implementaciones de semáforos de Unix que sobreviven a un fallo del sistema. En Unix, cuando un semáforo sobrevive a un fallo del sistema, necesitamos una forma de forzar que se reinicie su recuento de recursos, cuando el sistema vuelve a utilizar el semáforo. En Windows, donde los semáforos no pueden sobrevivir a un fallo del sistema, esta enumeración no tiene ningún efecto.
| Constante | Valor | Descripción |
|---|---|---|
QSystemSemaphore::Open | 0 | Si el semáforo ya existe, su recuento de recursos inicial no se restablece. Si el semáforo aún no existe, se crea y se establece su recuento de recursos inicial. |
QSystemSemaphore::Create | 1 | QSystemSemaphore toma posesión del semáforo y establece su recuento de recursos en el valor solicitado, independientemente de si el semáforo ya existe por haber sobrevivido a un fallo del sistema. Este valor debe pasarse al constructor, cuando se crea el primer semáforo para una clave concreta y se sabe que, si el semáforo ya existe, solo puede deberse a un fallo del sistema. En Windows, donde un semáforo no puede sobrevivir a un fallo del sistema, las funciones Create y Open 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 ha fallado porque el usuario que la ha iniciado no tenía los permisos necesarios. |
QSystemSemaphore::KeyError | 2 | La operación ha fallado debido a una clave no válida. |
QSystemSemaphore::AlreadyExists | 3 | La operación ha fallado porque ya existía un semáforo del sistema con la clave especificada. |
QSystemSemaphore::NotFound | 4 | La operación ha fallado porque no se ha podido encontrar un semáforo del sistema con la clave especificada. |
QSystemSemaphore::OutOfResources | 5 | La operación ha fallado porque no había memoria suficiente disponible para satisfacer la solicitud. |
QSystemSemaphore::UnknownError | 6 | Ha ocurrido algo más y ha sido un error. |
Documentación de funciones de 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 según las siguientes reglas, que dependen del sistema.
En Unix, si el mode es Open y el sistema ya dispone de un semáforo identificado por key, se utiliza ese semáforo y no se modifica el recuento de recursos del mismo; es decir, se ignora initialValue. Sin embargo, si el sistema aún no dispone de 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 dispone de un semáforo identificado por key, se utiliza ese semáforo y su recuento de recursos se establece en initialValue. Si el sistema aún no dispone de 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 el ` key` especificado. Si el sistema aún no dispone de un semáforo identificado como ` key`, crea el semáforo y establece su recuento de recursos en ` initialValue`. Sin embargo, si el sistema ya dispone de un semáforo identificado como ` key `, utiliza ese semáforo e ignora ` initialValue`.
El parámetro mode solo se utiliza en sistemas Unix para gestionar el caso en el que un semáforo sobrevive a un fallo del proceso. En ese caso, el siguiente proceso que asigne un semáforo con el mismo key obtendrá el semáforo que sobrevivió al fallo y, a menos que mode sea Create, el recuento de recursos no se restablecerá a initialValue, sino que conservará el valor inicial que le había asignado el proceso que falló.
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 que exista para ese semáforo del sistema.
Hay dos efectos secundarios importantes del destructor que dependen del sistema. En Windows, si se ha llamado a ` acquire()` para este semáforo pero no a ` release()`, el destructor no llamará a ` release()`, ni se liberará el recurso cuando el proceso finalice normalmente. Esto constituiría un error de programación que podría provocar un interbloqueo en otro proceso que intentara adquirir el mismo recurso. En Unix, los recursos adquiridos que no se liberen antes de que se llame al destructor se liberan automáticamente cuando el proceso finaliza.
bool QSystemSemaphore::acquire()
Adquiere uno de los recursos protegidos por este semáforo, si hay alguno disponible, y devuelve ` true`. Si todos los recursos protegidos por este semáforo ya han sido adquiridos, la llamada se bloquea hasta que otro proceso o hilo que tenga un semáforo con la misma clave libere uno de ellos.
Si se devuelve «false», se ha producido un error del sistema. Llama 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 textual del último error que se ha producido. Si error() devuelve un objeto de tipo « error value », llama 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 mediante el cual 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 mediante el cual se puede acceder al semáforo desde otros procesos.
Puedes utilizar la clave nativa para acceder a semáforos del sistema que no hayan sido creados por Qt, o para conceder acceso a aplicaciones ajenas a Qt. Consulta «Claves IPC nativas» para obtener más información.
Véase también ` setNativeKey()`.
bool QSystemSemaphore::release(int n = 1)
Libera los recursos n protegidos por el semáforo. Devuelve true, salvo que se produzca un error del sistema.
Ejemplo: Crear un semáforo del sistema con cinco recursos; adquirirlos todos y, a continuación, 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 resourcesEsta 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 resourcesAhora hay diez recursos nuevos protegidos por el semáforo, 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 la nueva key es diferente de la clave anterior, llamar a esta función equivale a llamar al destructor del semáforo con la clave anterior y, a continuación, llamar al constructor para crear un nuevo semáforo con la nueva key. Los parámetros initialValue y mode se definen igual que en el constructor.
Véanse 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 la nueva key es diferente de la clave anterior, llamar a esta función equivale a llamar al destructor del semáforo con la clave anterior y, a continuación, llamar al constructor para crear un nuevo semáforo con la nueva key. Los parámetros initialValue y mode se definen igual que en el constructor.
Esta función resulta útil si la clave nativa se compartía con otro proceso. Consulta «Claves IPC nativas » para obtener más información.
Véanse 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.