QLockFile Class
La clase QLockFile permite bloquear el acceso a un archivo entre procesos. Más información...
| Encabezado: | #include <QLockFile> |
| 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
- QLockFile forma parte de Entrada/Salida y Redes.
Tipos públicos
| enum | LockError { NoError, LockFailedError, PermissionError, UnknownError } |
Funciones públicas
| QLockFile(const QString &fileName) | |
| ~QLockFile() | |
| QLockFile::LockError | error() const |
| QString | fileName() const |
| bool | getLockInfo(qint64 *pid, QString *hostname, QString *appname) const |
| bool | isLocked() const |
| bool | lock() |
| bool | removeStaleLockFile() |
| void | setStaleLockTime(int staleLockTime) |
(since 6.2) void | setStaleLockTime(std::chrono::milliseconds staleLockTime) |
| int | staleLockTime() const |
(since 6.2) std::chrono::milliseconds | staleLockTimeAsDuration() const |
| bool | tryLock(int timeout) |
(since 6.2) bool | tryLock(std::chrono::milliseconds timeout = std::chrono::milliseconds::zero()) |
| void | unlock() |
Descripción detallada
Un archivo de bloqueo se puede utilizar para evitar que varios procesos accedan simultáneamente al mismo recurso. Por ejemplo, un archivo de configuración en disco, un socket, un puerto o una región de memoria compartida...
La serialización solo está garantizada si todos los procesos que acceden al recurso compartido utilizan QLockFile con la misma ruta de archivo.
QLockFile admite dos casos de uso: proteger un recurso para una operación a corto plazo (por ejemplo, comprobar si un archivo de configuración ha cambiado antes de guardar los nuevos ajustes) y proteger un recurso a largo plazo (por ejemplo, un documento abierto por un usuario en un editor) durante un tiempo indefinido.
Al proteger un recurso para una operación a corto plazo, es aceptable llamar a ` lock()` y esperar a que finalice cualquier operación en curso. Sin embargo, al proteger un recurso durante un periodo prolongado, la aplicación siempre debe llamar a ` setStaleLockTime(0 ms)` y, a continuación, a ` tryLock()` con un tiempo de espera breve, con el fin de advertir al usuario de que el recurso está bloqueado.
Si el proceso que mantiene el bloqueo se bloquea, el archivo de bloqueo permanece en el disco y puede impedir que cualquier otro proceso acceda al recurso compartido, para siempre. Por este motivo, QLockFile intenta detectar dichos archivos de bloqueo «caducados», basándose en el ID de proceso escrito en el archivo. Para tener en cuenta la situación en la que el ID de proceso se haya reutilizado entretanto, se compara el nombre del proceso actual con el nombre del proceso que corresponde al ID de proceso del archivo de bloqueo. Si los nombres de los procesos difieren, el archivo de bloqueo se considera obsoleto. Además, se tiene en cuenta la hora de la última modificación del archivo de bloqueo (30 s por defecto, para el caso de uso de una operación de corta duración). Si se determina que el archivo de bloqueo está obsoleto, se eliminará.
Por lo tanto, en el caso de proteger un recurso durante un periodo prolongado, se debe llamar a ` setStaleLockTime(0)`, y cuando ` tryLock()` devuelva ` LockFailedError`, informar al usuario de que el documento está bloqueado, utilizando, si procede, ` getLockInfo()` para obtener más detalles.
Limitaciones
La implementación de QLockFile suele ser segura en la mayoría de entornos y sistemas de archivos. Existen algunas situaciones en las que puede concluir erróneamente que un archivo de bloqueo está obsoleto cuando no lo está, no detectar un archivo obsoleto o producir una carrera de acceso al bloquearlo. En esta sección se documentan estos problemas.
Existen dos estrategias principales de mitigación: elegir un valor adecuado distinto de cero para ` staleLockTime()` y elegir un sistema de archivos local habitual para almacenar los archivos de bloqueo (como ` /var/lock ` si se ejecuta como root en sistemas Unix o ` runtime location`). Esto puede no ser posible en determinados casos de uso de QLockFile, como cuando se utiliza QLockFile para indicar que se está editando una ruta de archivo proporcionada por el usuario.
ID de máquina no persistentes
QLockFile utiliza el identificador único de la máquina para diferenciar un bloqueo de la máquina actual de uno de un proceso que se ejecuta en un host diferente. Si el identificador de máquina cambia con el tiempo (como en sistemas con almacenamiento efímero, que deben generar un nuevo identificador en cada arranque), QLockFile no podrá detectar que un archivo de bloqueo está obsoleto tras un reinicio.
Por el contrario, si dos máquinas diferentes tienen ID de máquina que coinciden (por ejemplo, una imagen del sistema clonada o una restauración a partir de copias de seguridad) y proporcionan una ruta de red a QLockFile, la clase podría concluir que el bloqueo está obsoleto cuando en realidad no lo está.
Ausencia de bloqueo nativo
QLockFile utiliza llamadas específicas del sistema operativo para indicar a otros procesos y subprocesos que el bloqueo está activo (no obsoleto), incluso más allá de la configuración de ` staleLockTime()`. Esta funcionalidad puede no estar disponible para archivos en algunos sistemas de archivos en red o virtuales (como FUSE en Linux y macOS), cuando se utilizan diferentes sistemas de archivos para acceder al mismo archivo si el bloqueo nativo no se transfiere, o en determinados entornos que bloquean las llamadas al sistema necesarias.
Si no hay soporte nativo para el bloqueo, QLockFile se basará únicamente en la existencia, la fecha de modificación y el contenido del propio archivo de bloqueo. En este caso, si el proceso que tiene bloqueado el recurso en ese momento lo mantiene más allá de staleLockTime(), QLockFile le arrebatará el bloqueo.
Sistemas de archivos en red
No se especifica si el bloqueo nativo de archivos es compatible en entornos en red: en algunas implementaciones, es compatible para todos los clientes que acceden al sistema de archivos; en otras, el sistema local puede admitir el bloqueo para sus propios procesos, pero no lo compartirá a través de la red; y en otras más, no existe bloqueo nativo ni siquiera dentro de un mismo host. Además, es posible que algunos clientes participen en el bloqueo en red y otros no, para el mismo archivo. Si el bloqueo no es compatible a través de la red, QLockFile se regirá por las limitaciones descritas anteriormente para la ausencia de bloqueo nativo.
Además, si el archivo de bloqueo contiene la identificación de un host diferente, QLockFile no podrá confirmar que el proceso que mantiene el bloqueo sigue en ejecución, y tendrá que esperar a que staleLockTime() se recupere de una salida anómala.
Acceso a diferentes archivos reales a través de la misma ruta
Es posible que dos procesos tengan visiones diferentes del sistema de archivos, lo que hace que una ruta de archivo idéntica corresponda a archivos distintos en el sistema de archivos. En este caso, es probable que los dos objetos QLockFile consigan crear el bloqueo, pero no serán mutuamente excluyentes. Esto puede provocar conflictos si el recurso que protege el archivo de bloqueo sigue siendo compartido entre ellos.
Esta situación se da con mayor frecuencia con los contenedores (véase más abajo), pero no es exclusiva de ellos.
Archivos compartidos con contenedores
En algunas implementaciones de contenedores, es posible ocultar la existencia de ciertos procesos (por ejemplo, la función «espacio de nombres de PID» de Linux). Si un proceso se está ejecutando dentro de uno de estos contenedores pero comparte el ID de máquina del sistema anfitrión o de otro contenedor, dos procesos en contenedores diferentes (o en el sistema anfitrión) determinarán erróneamente si el proceso que ha aplicado el bloqueo sigue en ejecución. Además, algunos controladores de contenedores pueden sustituir el ID de arranque dentro del contenedor, lo que hace que los procesos iniciados concluyan que el archivo de bloqueo siempre está desactualizado, independientemente de lo reciente que sea su marca de tiempo.
En otras implementaciones, los contenedores pueden disponer de almacenamiento efímero o crear intencionadamente un nuevo ID de máquina para evitar colisiones. En este caso, la aplicación experimentará los problemas descritos anteriormente para los ID de máquina no persistentes.
Sin embargo, el bloqueo nativo de archivos suele funcionar (sujeto a las limitaciones del sistema de archivos y del entorno, tal y como se ha comentado anteriormente), por lo que, aunque QLockFile concluyera que el archivo está aparentemente obsoleto, no «robará» un archivo de bloqueo que esté bloqueado de forma nativa.
Accesos que no utilizan el mismo protocolo
QLockFile no puede interoperar con modificaciones del archivo de bloqueo realizadas fuera del protocolo implementado por esta clase. Esto incluye la eliminación del archivo de bloqueo por parte de otras herramientas, como tmpwatch y similares, pero también algunas herramientas de análisis de virus o similares.
Desfase del reloj
QLockFile se basa en que la marca de tiempo del archivo de bloqueo sea precisa. Si el reloj se adelanta, QLockFile podría concluir que un archivo de bloqueo ha quedado obsoleto cuando no es así, y viceversa si el reloj se retrasa.
Por este motivo, se recomienda que todos los sistemas mantengan la hora sincronizada con la red y realicen esta sincronización al inicio de su proceso de arranque. Esto es especialmente importante para los sistemas de archivos en red.
Documentación sobre tipos de miembros
enum QLockFile::LockError
Esta enumeración describe el resultado de la última llamada a lock() o tryLock().
| Constante | Valor | Descripción |
|---|---|---|
QLockFile::NoError | 0 | El bloqueo se ha adquirido correctamente. |
QLockFile::LockFailedError | 1 | No se ha podido adquirir el bloqueo porque otro proceso lo tiene en su poder. |
QLockFile::PermissionError | 2 | No se ha podido crear el archivo de bloqueo por falta de permisos en el directorio principal. |
QLockFile::UnknownError | 3 | Se ha producido otro error; por ejemplo, una partición llena ha impedido escribir el archivo de bloqueo. |
Documentación de las funciones miembro
[explicit] QLockFile::QLockFile(const QString &fileName)
Crea un nuevo objeto de archivo de bloqueo. El objeto se crea en estado desbloqueado. Al llamar a ` lock()` o ` tryLock()`, se creará un archivo de bloqueo llamado ` fileName `, si aún no existe.
Véanse también lock() y unlock().
[noexcept] QLockFile::~QLockFile()
Elimina el objeto del archivo de bloqueo. Si se había adquirido el bloqueo, esta acción lo liberará al eliminar el archivo de bloqueo.
QLockFile::LockError QLockFile::error() const
Devuelve el estado de error del archivo de bloqueo.
Si ` tryLock()` devuelve ` false`, se puede llamar a esta función para averiguar el motivo por el que ha fallado el bloqueo.
QString QLockFile::fileName() const
Devuelve el nombre del archivo de bloqueo
bool QLockFile::getLockInfo(qint64 *pid, QString *hostname, QString *appname) const
Recupera información sobre el propietario actual del archivo de bloqueo.
Si ` tryLock()` devuelve ` false` y ` error()` devuelve ` LockFailedError`, se puede llamar a esta función para obtener más información sobre el archivo de bloqueo existente:
- el PID de la aplicación (devuelto en ` pid`)
- el hostname en el que se está ejecutando (útil en el caso de sistemas de archivos en red),
- el nombre de la aplicación que lo creó (devuelto en ` appname`),
Ten en cuenta que ` tryLock()` elimina automáticamente el archivo si no hay ninguna aplicación en ejecución con este PID, por lo que ` LockFailedError ` solo puede producirse si hay una aplicación con este PID (aunque podría no estar relacionada).
Esto puede utilizarse para informar a los usuarios sobre la existencia del archivo de bloqueo y darles la opción de eliminarlo. Tras eliminar el archivo mediante ` removeStaleLockFile()`, la aplicación puede volver a llamar a ` tryLock()`.
Esta función devuelve ` true ` si la información se ha podido recuperar correctamente, y `false` si el archivo de bloqueo no existe o no contiene los datos esperados. Esto puede ocurrir si el archivo de bloqueo se ha eliminado entre el momento en que falló ` tryLock()` y la llamada a esta función. Si esto ocurre, basta con volver a llamar a ` tryLock()`.
bool QLockFile::isLocked() const
Devuelve « true » si el bloqueo fue adquirido por esta instancia de « QLockFile »; en caso contrario, devuelve « false ».
Véase también lock(), unlock() y tryLock().
bool QLockFile::lock()
Crea el archivo de bloqueo.
Si otro proceso (u otro hilo) ya ha creado el archivo de bloqueo, esta función se bloqueará hasta que dicho proceso (o hilo) lo libere.
No está permitido llamar a esta función varias veces sobre el mismo bloqueo desde el mismo hilo sin desbloquearlo primero. Esta función provocará un interbloqueo cuando el archivo esté bloqueado de forma recursiva.
Devuelve ` true ` si se ha adquirido el bloqueo, y `false` si no se ha podido adquirir debido a un error irrecuperable, como la falta de permisos en el directorio principal.
Véanse también unlock() y tryLock().
bool QLockFile::removeStaleLockFile()
Intenta eliminar de forma forzada un archivo de bloqueo existente.
No se recomienda llamar a esta función cuando se protege una operación de corta duración: QLockFile ya se encarga de eliminar los archivos de bloqueo una vez que superan el tiempo de vida especificado en staleLockTime().
Este método solo debe llamarse cuando se protege un recurso durante un periodo prolongado, es decir, con ` staleLockTime(0)`, y después de que ` tryLock()` haya devuelto ` LockFailedError`, y el usuario haya aceptado eliminar el archivo de bloqueo.
Devuelve true si se realiza correctamente, y false si no se ha podido eliminar el archivo de bloqueo. Esto ocurre en Windows cuando la aplicación que posee el bloqueo sigue ejecutándose.
void QLockFile::setStaleLockTime(int staleLockTime)
Establece ` staleLockTime ` como el tiempo, en milisegundos, tras el cual un archivo de bloqueo se considera obsoleto. El valor por defecto es 30 000, es decir, 30 segundos. Si tu aplicación suele mantener el archivo bloqueado durante más de 30 segundos (por ejemplo, al guardar megabytes de datos durante 2 minutos), deberías establecer un valor mayor mediante setStaleLockTime().
El valor de ` staleLockTime ` es utilizado por ` lock()` y ` tryLock()` para determinar cuándo se considera obsoleto un archivo de bloqueo existente, es decir, cuando es un residuo de un proceso que se ha bloqueado. Esto resulta útil en los casos en los que el PID se ha reutilizado entretanto, por lo que una forma de detectar un archivo de bloqueo obsoleto es el hecho de que lleve mucho tiempo sin utilizarse.
Se trata de una función sobrecargada, equivalente a llamar a:
setStaleLockTime(std::chrono::milliseconds{staleLockTime});Véase también staleLockTime().
[since 6.2] void QLockFile::setStaleLockTime(std::chrono::milliseconds staleLockTime)
Establece el intervalo tras el cual un archivo de bloqueo se considera obsoleto en staleLockTime. El valor por defecto es 30 s.
Si tu aplicación suele mantener el archivo bloqueado durante más de 30 segundos (por ejemplo, mientras guarda megabytes de datos durante 2 minutos), deberías establecer un valor mayor mediante setStaleLockTime().
El valor de ` staleLockTime()` es utilizado por ` lock()` y ` tryLock()` para determinar cuándo se considera obsoleto un archivo de bloqueo existente, es decir, cuando es un vestigio de un proceso que se ha bloqueado. Esto resulta útil en los casos en los que el PID se ha reutilizado entretanto, por lo que una forma de detectar un archivo de bloqueo obsoleto es el hecho de que lleve mucho tiempo sin modificarse.
Si se establece este valor en 0 o en un número negativo, se desactivará la verificación de las marcas de tiempo en los archivos de bloqueo. QLockFile seguirá detectando un bloqueo obsoleto si su contenido indica que el proceso que lo bloqueó ya no se está ejecutando.
Esta función se introdujo en Qt 6.2.
Véase también staleLockTime().
int QLockFile::staleLockTime() const
Devuelve el tiempo, en milisegundos, tras el cual un archivo de bloqueo se considera obsoleto.
Véase también setStaleLockTime().
[since 6.2] std::chrono::milliseconds QLockFile::staleLockTimeAsDuration() const
Devuelve un objeto std::chrono::milliseconds que indica el tiempo transcurrido tras el cual un archivo de bloqueo se considera obsoleto.
Esta función se introdujo en Qt 6.2.
Véase también ` setStaleLockTime()`.
bool QLockFile::tryLock(int timeout)
Intenta crear el archivo de bloqueo. Esta función devuelve ` true ` si se ha obtenido el bloqueo; en caso contrario, devuelve ` false`. Si otro proceso (u otro hilo) ya ha creado el archivo de bloqueo, esta función esperará como máximo ` timeout ` milisegundos a que el archivo de bloqueo quede disponible.
Nota: Pasar un número negativo como timeout equivale a llamar a lock(), es decir, esta función esperará indefinidamente hasta que el archivo de bloqueo pueda bloquearse si timeout es negativo.
Si se ha obtenido el bloqueo, debe liberarse con unlock() antes de que otro proceso (o hilo) pueda bloquearlo correctamente.
No está permitido llamar a esta función varias veces sobre el mismo bloqueo desde el mismo hilo sin desbloquearlo primero; esta función siempre devolverá «false» al intentar bloquear el archivo de forma recursiva.
Véanse también lock() y unlock().
[since 6.2] bool QLockFile::tryLock(std::chrono::milliseconds timeout = std::chrono::milliseconds::zero())
Intenta crear el archivo de bloqueo. Esta función devuelve ` true ` si se ha obtenido el bloqueo; en caso contrario, devuelve ` false`. Si otro proceso (u otro hilo) ya ha creado el archivo de bloqueo, esta función esperará como máximo ` timeout ` a que el archivo de bloqueo esté disponible.
Si se ha obtenido el bloqueo, este debe liberarse con ` unlock()` antes de que otro proceso (o hilo) pueda bloquearlo con éxito.
No está permitido llamar a esta función varias veces sobre el mismo bloqueo desde el mismo hilo sin desbloquearlo primero; esta función siempre devolverá «false» al intentar bloquear el archivo de forma recursiva.
Esta es una función sobrecargada.
Esta función se introdujo en Qt 6.2.
Véase también lock() y unlock().
void QLockFile::unlock()
Libera el bloqueo eliminando el archivo de bloqueo.
Si se llama a unlock() sin haber bloqueado primero el archivo, no se produce ningún efecto.
© 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.