QLockFile Class

Documentation des fonctions membres

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

Construit un nouvel objet fichier de verrouillage. L'objet est créé dans un état déverrouillé. Lors de l'appel à lock() ou tryLock(), un fichier de verrouillage nommé fileName sera créé, s'il n'existe pas déjà.

Voir aussi lock() et unlock().

[noexcept] QLockFile::~QLockFile()

Détruit l'objet fichier de verrouillage. Si le verrou a été acquis, cette opération le libère en supprimant le fichier de verrouillage.

QLockFile::LockError QLockFile::error() const

Renvoie l'état d'erreur du fichier de verrouillage.

Si tryLock() renvoie false, cette fonction peut être appelée pour connaître la raison de l'échec du verrouillage.

QString QLockFile::fileName() const

Renvoie le nom du fichier de verrouillage

bool QLockFile::getLockInfo(qint64 *pid, QString *hostname, QString *appname) const

Récupère des informations sur le propriétaire actuel du fichier de verrouillage.

Si tryLock() renvoie false, et error() renvoie LockFailedError, cette fonction peut être appelée pour obtenir plus d'informations sur le fichier de verrouillage existant :

• le PID de l'application (renvoyé dans pid)
• l'adresse hostname sur laquelle elle s'exécute (utile dans le cas de systèmes de fichiers en réseau),
• le nom de l'application qui l'a créé (renvoyé dans appname),

Notez que tryLock() a automatiquement supprimé le fichier s'il n'y a pas d'application en cours d'exécution avec ce PID, de sorte que LockFailedError ne peut se produire que s'il y a une application avec ce PID (il peut cependant ne pas y avoir de lien).

Ceci peut être utilisé pour informer les utilisateurs de l'existence d'un fichier de verrouillage et leur donner la possibilité de le supprimer. Après avoir supprimé le fichier à l'aide de removeStaleLockFile(), l'application peut appeler à nouveau tryLock().

Cette fonction renvoie true si les informations ont pu être récupérées avec succès, false si le fichier de verrouillage n'existe pas ou ne contient pas les données attendues. Cela peut se produire si le fichier de verrouillage a été supprimé entre le moment où tryLock() a échoué et l'appel à cette fonction. Dans ce cas, il suffit d'appeler à nouveau tryLock().

bool QLockFile::isLocked() const

Renvoie true si le verrou a été acquis par cette instance QLockFile, sinon renvoie false.

Voir aussi lock(), unlock(), et tryLock().

bool QLockFile::lock()

Crée le fichier de verrouillage.

Si un autre processus (ou un autre thread) a déjà créé le fichier de verrouillage, cette fonction se bloque jusqu'à ce que ce processus (ou thread) le libère.

Il est interdit d'appeler cette fonction plusieurs fois sur le même verrou à partir du même thread sans le déverrouiller d'abord. Cette fonction se bloque lorsque le fichier est verrouillé de manière récursive.

Retourne true si le verrou a été acquis, false s'il n'a pas pu être acquis en raison d'une erreur irrécupérable, telle que l'absence de permissions dans le répertoire parent.

Voir aussi unlock() et tryLock().

bool QLockFile::removeStaleLockFile()

Tente de supprimer de force un fichier de verrouillage existant.

Il n'est pas recommandé d'appeler cette méthode pour protéger une opération de courte durée : QLockFile se charge déjà de supprimer les fichiers de verrouillage lorsqu'ils sont plus anciens que staleLockTime().

Cette méthode ne doit être appelée que pour protéger une ressource pendant une longue période, c'est-à-dire avec staleLockTime(0), et après que tryLock() a renvoyé LockFailedError, et que l'utilisateur a accepté de supprimer le fichier de verrouillage.

Renvoie true en cas de succès, false si le fichier verrouillé n'a pas pu être supprimé. Cela se produit sous Windows, lorsque l'application propriétaire du verrou est toujours en cours d'exécution.

void QLockFile::setStaleLockTime(int staleLockTime)

Définit staleLockTime comme étant le temps en millisecondes après lequel un fichier de verrouillage est considéré comme périmé. La valeur par défaut est 30000, soit 30 secondes. Si votre application garde généralement le fichier verrouillé pendant plus de 30 secondes (par exemple en sauvegardant des mégaoctets de données pendant 2 minutes), vous devriez définir une valeur plus grande en utilisant setStaleLockTime().

La valeur de staleLockTime est utilisée par lock() et tryLock() afin de déterminer quand un fichier verrouillé existant est considéré comme périmé, c'est-à-dire laissé par un processus qui s'est arrêté. C'est utile dans le cas où le PID a été réutilisé entre-temps, de sorte qu'une façon de détecter un fichier de verrouillage périmé est de s'assurer qu'il existe depuis longtemps.

Il s'agit d'une fonction surchargée, équivalente à l'appel à :

setStaleLockTime(std::chrono::milliseconds{staleLockTime});

Voir aussi staleLockTime().

[since 6.2] void QLockFile::setStaleLockTime(std::chrono::milliseconds staleLockTime)

Définit l'intervalle après lequel un fichier verrouillé est considéré comme périmé à staleLockTime. La valeur par défaut est de 30 secondes.

Si votre application garde généralement le fichier verrouillé pendant plus de 30 secondes (par exemple en sauvegardant des mégaoctets de données pendant 2 minutes), vous devriez définir une valeur plus grande en utilisant setStaleLockTime().

La valeur de staleLockTime() est utilisée par lock() et tryLock() afin de déterminer quand un fichier verrouillé existant est considéré comme périmé, c'est-à-dire laissé par un processus qui s'est arrêté. C'est utile dans le cas où le PID a été réutilisé entre-temps, de sorte qu'un moyen de détecter un fichier de verrouillage périmé est le fait qu'il existe depuis longtemps.

Cette fonction a été introduite dans Qt 6.2.

Voir aussi staleLockTime().

int QLockFile::staleLockTime() const

Renvoie le temps en millisecondes après lequel un fichier de verrouillage est considéré comme périmé.

Voir aussi setStaleLockTime().

[since 6.2] std::chrono::milliseconds QLockFile::staleLockTimeAsDuration() const

Renvoie un objet std::chrono::millisecondes qui indique le temps après lequel un fichier de verrouillage est considéré comme périmé.

Cette fonction a été introduite dans Qt 6.2.

Voir aussi setStaleLockTime().

bool QLockFile::tryLock(int timeout)

Tente de créer le fichier de verrouillage. Cette fonction renvoie true si le verrou a été obtenu, sinon elle renvoie false. Si un autre processus (ou un autre thread) a déjà créé le fichier de verrouillage, cette fonction attendra au maximum timeout millisecondes pour que le fichier de verrouillage devienne disponible.

Remarque : le fait de transmettre un nombre négatif comme timeout équivaut à appeler lock(), c'est-à-dire que cette fonction attendra indéfiniment que le fichier de verrouillage puisse être verrouillé si timeout est négatif.

Si le verrou a été obtenu, il doit être libéré avec unlock() avant qu'un autre processus (ou thread) puisse le verrouiller avec succès.

Il n'est pas permis d'appeler cette fonction plusieurs fois sur le même verrou à partir du même thread sans déverrouiller d'abord, cette fonction renverra toujours false lors d'une tentative de verrouillage récursif du fichier.

Voir aussi lock() et unlock().

[since 6.2] bool QLockFile::tryLock(std::chrono::milliseconds timeout = std::chrono::milliseconds::zero())

Tente de créer le fichier de verrouillage. Cette fonction renvoie true si le verrou a été obtenu ; sinon, elle renvoie false. Si un autre processus (ou un autre thread) a déjà créé le fichier de verrouillage, cette fonction attendra au maximum timeout que le fichier de verrouillage devienne disponible.

Si le verrou a été obtenu, il doit être libéré avec unlock() avant qu'un autre processus (ou thread) puisse le verrouiller avec succès.

Il est interdit d'appeler cette fonction plusieurs fois sur le même verrou à partir du même thread sans déverrouiller d'abord, cette fonction renverra toujours false si elle tente de verrouiller le fichier de manière récursive.

Cette fonction a été introduite dans Qt 6.2.

Voir aussi lock() et unlock().

void QLockFile::unlock()

Libère le verrou en supprimant le fichier verrouillé.

Appeler unlock() sans verrouiller le fichier d'abord ne fait rien.

Voir aussi lock() et tryLock().