QLockFile Class

Documentación de las funciones miembro

[explicit] QLockFile::QLockFile(const QString &fileName)

Construye 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 no existe ya.

Véase también lock() y unlock().

[noexcept] QLockFile::~QLockFile()

Destruye el objeto archivo de bloqueo. Si el bloqueo fue adquirido, esto liberará el bloqueo, borrando 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 la razón por la que falló 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 caso de sistemas de archivos en red),
• el nombre de la aplicación que lo creó (devuelto en appname),

Tenga en cuenta que tryLock() borra automáticamente el archivo si no hay ninguna aplicación en ejecución con este PID, por lo que LockFailedError sólo puede ocurrir si hay una aplicación con este PID (aunque podría no estar relacionada).

Esto se puede utilizar para informar a los usuarios sobre el archivo de bloqueo existente y darles la opción de eliminarlo. Después de eliminar el fichero utilizando removeStaleLockFile(), la aplicación puede llamar de nuevo a tryLock().

Esta función devuelve true si la información pudo ser recuperada con éxito, false si el fichero de bloqueo no existe o no contiene los datos esperados. Esto puede ocurrir si el archivo de bloqueo fue borrado entre el momento en que tryLock() falló y la llamada a esta función. Simplemente llame a tryLock() de nuevo si esto sucede.

bool QLockFile::isLocked() const

Devuelve true si el bloqueo fue adquirido por esta instancia QLockFile, en caso contrario devuelve false.

Véase también lock(), unlock(), y tryLock().

bool QLockFile::lock()

Crea el fichero de bloqueo.

Si otro proceso (u otro hilo) ya ha creado el archivo de bloqueo, esta función se bloqueará hasta que ese proceso (o hilo) lo libere.

No está permitido llamar a esta función varias veces sobre el mismo bloqueo desde el mismo hilo sin desbloquear primero. Esta función se bloqueará cuando el archivo se bloquee recursivamente.

Devuelve true si el bloqueo fue adquirido, false si no pudo ser adquirido debido a un error irrecuperable, como la falta de permisos en el directorio padre.

Véase también unlock() y tryLock().

bool QLockFile::removeStaleLockFile()

Intenta eliminar por la fuerza un archivo de bloqueo existente.

No se recomienda llamar a este método cuando se protege una operación de corta duración: QLockFile ya se encarga de eliminar los archivos de bloqueo después de que sean más antiguos que staleLockTime().

Este método sólo debería llamarse cuando se protege un recurso durante mucho tiempo, es decir, con staleLockTime(0), y después de que tryLock() devolviera LockFailedError, y el usuario estuviera de acuerdo en eliminar el archivo de bloqueo.

Devuelve true en caso de éxito, false si el archivo de bloqueo no pudo ser eliminado. Esto ocurre en Windows, cuando la aplicación propietaria del 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 30000, 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), debes establecer un valor mayor utilizando setStaleLockTime().

El valor de staleLockTime es utilizado por lock() y tryLock() para determinar cuándo un fichero de bloqueo existente se considera obsoleto, es decir, dejado por un proceso que se ha bloqueado. Esto es útil para el caso en que el PID se reutilizó mientras tanto, por lo que una forma de detectar un archivo de bloqueo antiguo es por el hecho de que ha existido durante mucho tiempo.

Esta es 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 bloqueado se considera obsoleto en staleLockTime. El valor por defecto es 30s.

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), debes establecer un valor mayor mediante setStaleLockTime().

El valor de staleLockTime() es utilizado por lock() y tryLock() para determinar cuándo un fichero de bloqueo existente se considera obsoleto, es decir, dejado por un proceso bloqueado. Esto es útil para el caso en que el PID se reutilizó mientras tanto, por lo que una forma de detectar un archivo de bloqueo rancio es por el hecho de que ha existido durante mucho tiempo.

Esta función fue introducida 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 denota el tiempo 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 fichero de bloqueo, esta función esperará como máximo timeout milisegundos a que el fichero de bloqueo esté disponible.

Nota: Pasar un número negativo como timeout es equivalente a llamar a lock(), es decir, esta función esperará eternamente hasta que el fichero de bloqueo pueda ser bloqueado si timeout es negativo.

Si el bloqueo fue obtenido, debe ser liberado 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 desbloquear primero, esta función siempre devolverá false cuando se intente bloquear el fichero recursivamente.

Véase 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 fichero de bloqueo, esta función esperará como máximo timeout a que el fichero de bloqueo esté disponible.

Si se obtuvo el bloqueo, debe liberarse con unlock() antes de que otro proceso (o hilo) pueda bloquearlo con éxito.

No se permite llamar a esta función múltiples veces sobre el mismo bloqueo desde el mismo hilo sin desbloquear primero, esta función siempre devolverá false cuando se intente bloquear el fichero recursivamente.

Esta función se introdujo en Qt 6.2.

Véase también lock() y unlock().

void QLockFile::unlock()

Libera el bloqueo, borrando el archivo bloqueado.

Llamar a unlock() sin bloquear primero el fichero, no hace nada.

Véase también lock() y tryLock().