QLockFile Class
La classe QLockFile permet de verrouiller un fichier entre plusieurs processus. En savoir plus...
| En-tête : | #include <QLockFile> |
| CMake : | find_package(Qt6 REQUIRED COMPONENTS Core) target_link_libraries(mytarget PRIVATE Qt6::Core) |
| qmake : | QT += core |
- Liste de tous les membres, y compris les membres hérités
- QLockFile fait partie de la catégorie « Entrée/Sortie et réseau ».
Types publics
| enum | LockError { NoError, LockFailedError, PermissionError, UnknownError } |
Fonctions publiques
| 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() |
Description détaillée
Un fichier de verrouillage peut être utilisé pour empêcher plusieurs processus d’accéder simultanément à la même ressource. Par exemple, un fichier de configuration sur le disque, ou un socket, un port, une région de mémoire partagée…
La sérialisation n’est garantie que si tous les processus accédant à la ressource partagée utilisent QLockFile, avec le même chemin d’accès au fichier.
QLockFile prend en charge deux cas d’utilisation : la protection d’une ressource pour une opération de courte durée (par exemple, vérifier si un fichier de configuration a été modifié avant d’enregistrer de nouveaux paramètres) et la protection à long terme d’une ressource (par exemple, un document ouvert par un utilisateur dans un éditeur) pour une durée indéterminée.
Lorsqu’il s’agit de protéger une ressource pour une opération de courte durée, il est acceptable d’appeler ` lock()` et d’attendre que toute opération en cours se termine. En revanche, lorsqu’il s’agit de protéger une ressource sur une longue durée, l’application doit toujours appeler ` setStaleLockTime(0 ms)`, puis ` tryLock()` avec un délai d’expiration court, afin d’avertir l’utilisateur que la ressource est verrouillée.
Si le processus détenant le verrou se bloque, le fichier de verrouillage reste sur le disque et peut empêcher tout autre processus d’accéder à la ressource partagée, et ce de manière définitive. C’est pourquoi QLockFile tente de détecter un tel fichier de verrouillage « périmé », en se basant sur l’ID du processus inscrit dans le fichier. Pour pallier le cas où l’ID de processus aurait été réutilisé entre-temps, le nom du processus actuel est comparé au nom du processus correspondant à l’ID de processus figurant dans le fichier de verrouillage. Si les noms de processus diffèrent, le fichier de verrouillage est considéré comme obsolète. De plus, la date et l’heure de la dernière modification du fichier de verrouillage (30 secondes par défaut, pour le cas d’utilisation d’une opération de courte durée) sont prises en compte. Si le fichier de verrouillage est jugé obsolète, il sera supprimé.
Dans le cas d’une protection de ressource à long terme, vous devez donc appeler ` setStaleLockTime(0)`, et lorsque ` tryLock()` renvoie ` LockFailedError`, informer l’utilisateur que le document est verrouillé, éventuellement en utilisant ` getLockInfo()` pour plus de détails.
Limites
L’implémentation de QLockFile est généralement sûre, pour la plupart des environnements et des systèmes de fichiers. Il existe toutefois quelques situations dans lesquelles elle peut conclure à tort qu’un fichier de verrouillage est obsolète alors qu’il ne l’est pas, ne pas détecter un fichier obsolète, ou rencontrer des conflits lors du verrouillage. Cette section documente ces problèmes.
Il existe deux stratégies principales pour atténuer ces risques : choisir une valeur appropriée et non nulle pour ` staleLockTime()` et choisir un système de fichiers local standard pour stocker les fichiers de verrouillage (tel que ` /var/lock ` si l'exécution se fait en tant que root sur des systèmes Unix ou le répertoire ` runtime location`). Cela peut s’avérer impossible dans certains cas d’utilisation de QLockFile, par exemple lorsque QLockFile est utilisé pour indiquer qu’un chemin de fichier fourni par l’utilisateur est en cours d’édition.
Identifiants de machine non persistants
QLockFile utilise l’identifiant unique de la machine pour distinguer un verrou associé à la machine actuelle de celui associé à un processus s’exécutant sur un autre hôte. Si l’identifiant de la machine change au fil du temps (comme sur les systèmes dotés d’un stockage éphémère, qui doivent générer un nouvel identifiant à chaque démarrage), QLockFile sera incapable de détecter qu’un fichier de verrouillage est obsolète après un redémarrage.
À l’inverse, si deux machines différentes ont des identifiants de machine en conflit (par exemple, une image système clonée ou une restauration à partir de sauvegardes) et fournissent un chemin d’accès réseau à QLockFile, la classe peut conclure que le verrou est obsolète alors qu’il ne l’est pas en réalité.
Absence de verrouillage natif
QLockFile utilise des appels spécifiques au système d’exploitation pour indiquer aux autres processus et threads que le verrou est actif (et non périmé), même au-delà du paramètre ` staleLockTime()`. Cette fonctionnalité peut faire défaut pour les fichiers situés sur certains systèmes de fichiers en réseau ou virtuels (tels que FUSE sous Linux et macOS), lors de l’utilisation de différents systèmes de fichiers pour accéder au même fichier si le verrou natif n’est pas transféré, ou dans certains environnements qui bloquent les appels système nécessaires.
Si la prise en charge native du verrouillage fait défaut, QLockFile s’appuiera uniquement sur l’existence, la date de modification et le contenu du fichier de verrouillage lui-même. Dans ce cas, si le processus verrouillant actuellement la ressource la conserve au-delà de la valeur définie par ` staleLockTime()`, QLockFile s’appropriera le verrou.
Systèmes de fichiers en réseau
Il n’est pas précisé si le verrouillage natif des fichiers est pris en charge dans les environnements en réseau : dans certaines implémentations, il est pris en charge pour tous les clients accédant au système de fichiers ; dans d’autres, le système local peut prendre en charge le verrouillage pour ses propres processus mais ne le partagera pas sur le réseau ; et dans d’autres encore, il n’y a pas de verrouillage natif, même au sein d’un même hôte. De plus, il est possible que certains clients participent au verrouillage en réseau et d’autres non, pour un même fichier. Si le verrouillage n’est pas pris en charge sur le réseau, QLockFile respectera les limitations décrites ci-dessus concernant l’absence de verrouillage natif.
Par ailleurs, si le fichier de verrouillage contient l’identifiant d’un autre hôte, QLockFile ne pourra pas confirmer que le processus détenant un verrou est toujours en cours d’exécution et devra attendre que la fonction ` staleLockTime()` se remette d’une sortie non correcte.
Accès à des fichiers réels différents via le même chemin
Il est possible que deux processus aient des vues différentes du système de fichiers, ce qui fait qu’un même chemin d’accès corresponde à des fichiers différents dans le système de fichiers. Dans ce cas, les deux objets QLockFile parviendront probablement à créer le verrou, mais ne seront pas mutuellement exclusifs. Cela peut entraîner des conflits si la ressource protégée par le fichier de verrouillage est toujours partagée entre eux.
Cette situation se rencontre le plus souvent avec les conteneurs (voir ci-dessous), mais ne leur est pas exclusive.
Fichiers partagés avec des conteneurs
Avec certaines implémentations de conteneurs, il est possible de masquer l’existence de certains processus (par exemple, la fonctionnalité « PID namespace » de Linux). Si un processus s’exécute à l’intérieur d’un tel conteneur mais partage l’identifiant machine du système hôte ou d’un autre conteneur, deux processus situés dans des conteneurs différents (ou sur l’hôte) détermineront de manière erronée si le processus de verrouillage est toujours en cours d’exécution. De plus, certains contrôleurs de conteneurs peuvent remplacer l’ID de démarrage à l’intérieur du conteneur, ce qui conduit les processus lancés à conclure que le fichier de verrouillage est toujours obsolète, quelle que soit la fraîcheur de son horodatage.
Dans certaines autres implémentations, les conteneurs peuvent disposer d’un stockage éphémère ou créer intentionnellement un nouvel identifiant de machine pour éviter les collisions. Dans ce cas, l’application rencontrera les problèmes décrits ci-dessus pour les identifiants de machine non persistants.
Cependant, le verrouillage natif des fichiers fonctionne généralement (sous réserve des limitations du système de fichiers et de l’environnement évoquées plus haut) ; ainsi, même si QLockFile conclut que le fichier est apparemment obsolète, il ne s’emparera pas d’un fichier de verrouillage verrouillé en natif.
Accès n’utilisant pas le même protocole
QLockFile ne peut pas gérer les modifications apportées au fichier de verrouillage en dehors du protocole implémenté par cette classe. Cela inclut la suppression du fichier de verrouillage par d’autres outils, tels que tmpwatch et ses équivalents, mais aussi certains antivirus ou outils similaires.
Décalage d’horloge
QLockFile repose sur l’exactitude de l’horodatage du fichier de verrouillage. Si l’horloge avance brusquement, QLockFile peut conclure qu’un fichier de verrouillage est devenu obsolète alors qu’il ne l’est pas, et inversement en cas de retard brusque.
C’est pourquoi il est recommandé que tous les systèmes utilisent une heure synchronisée sur le réseau et effectuent cette synchronisation dès le début de leur processus de démarrage. Ceci est particulièrement important pour les systèmes de fichiers en réseau.
Documentation sur les types de membres
enum QLockFile::LockError
Cette énumération décrit le résultat du dernier appel à la méthode ` lock()` ou ` tryLock()`.
| Constante | Valeur | Description |
|---|---|---|
QLockFile::NoError | 0 | Le verrou a été acquis avec succès. |
QLockFile::LockFailedError | 1 | Le verrou n’a pas pu être acquis car un autre processus le détient. |
QLockFile::PermissionError | 2 | Le fichier de verrouillage n’a pas pu être créé, faute d’autorisations dans le répertoire parent. |
QLockFile::UnknownError | 3 | Une autre erreur s’est produite, par exemple une partition pleine a empêché l’écriture du fichier de verrouillage. |
Documentation des fonctions membres
[explicit] QLockFile::QLockFile(const QString &fileName)
Crée un nouvel objet de fichier de verrouillage. L'objet est créé dans un état déverrouillé. Lors de l'appel de ` lock()` ou ` tryLock()`, un fichier de verrouillage nommé ` fileName ` sera créé s'il n'existe pas encore.
Voir également lock() et unlock().
[noexcept] QLockFile::~QLockFile()
Supprime l'objet du 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 le statut d'erreur du fichier de verrouillage.
Si la fonction ` tryLock()` renvoie ` false`, cette fonction peut être appelée pour déterminer 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 la fonction ` tryLock()` renvoie ` false` et que la fonction ` 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é par pid)
- l'hostname sur lequel 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é par ` appname`),
Notez que la fonction tryLock() supprime automatiquement le fichier s’il n’y a aucune application en cours d’exécution avec ce PID ; par conséquent, l’appel à LockFailedError ne peut avoir lieu que s’il existe une application avec ce PID (même si celle-ci n’est pas nécessairement liée au fichier).
Cette fonction peut être utilisée pour informer les utilisateurs de l’existence du 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, et `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 de 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 de ` QLockFile `, sinon renvoie « false ».
Voir également 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 bloquera jusqu'à ce que ce processus (ou thread) le libère.
Il n’est pas autorisé d’appeler cette fonction plusieurs fois sur le même verrou à partir du même thread sans l’avoir d’abord déverrouillé. Cette fonction provoquera un blocage mortel (deadlock) si le fichier est verrouillé de manière récursive.
Renvoie ` true ` si le verrou a été acquis, `false` s’il n’a pas pu l’être en raison d’une erreur irrémédiable, telle que l’absence de droits d’accès dans le répertoire parent.
Voir également ` unlock()` et ` tryLock()`.
bool QLockFile::removeStaleLockFile()
Tentative de suppression forcée d'un fichier de verrouillage existant.
Il n’est pas recommandé d’appeler cette fonction pour protéger une opération de courte durée : la fonction ` QLockFile ` se charge déjà de supprimer les fichiers de verrouillage dès qu’ils dépassent la durée spécifiée par ` staleLockTime()`.
Cette méthode ne doit être appelée que pour protéger une ressource sur une longue durée, c'est-à-dire avec ` staleLockTime(0)`, et après que ` tryLock()` a renvoyé ` LockFailedError`, et que l'utilisateur a accepté la suppression du fichier de verrouillage.
Renvoie true en cas de succès, false si le fichier de verrouillage n’a pas pu être supprimé. Cela se produit sous Windows lorsque l’application détentrice du verrou est toujours en cours d’exécution.
void QLockFile::setStaleLockTime(int staleLockTime)
Définit la valeur de ` staleLockTime ` sur le délai, en millisecondes, au terme duquel un fichier de verrouillage est considéré comme obsolète. La valeur par défaut est 30 000, soit 30 secondes. Si votre application maintient généralement le fichier verrouillé pendant plus de 30 secondes (par exemple, lors de l'enregistrement de plusieurs mégaoctets de données pendant 2 minutes), vous devez définir une valeur plus élevée à l'aide de la méthode `setStaleLockTime()`.
La valeur de ` staleLockTime ` est utilisée par les fonctions ` lock()` et ` tryLock()` afin de déterminer à quel moment un fichier de verrouillage existant est considéré comme obsolète, c'est-à-dire abandonné par un processus qui s'est bloqué. Cela s'avère utile dans le cas où le PID aurait été réutilisé entre-temps ; ainsi, l'un des moyens de détecter un fichier de verrouillage obsolète consiste à vérifier s'il est présent depuis longtemps.
Il s'agit d'une fonction surchargée, équivalente à l'appel suivant :
setStaleLockTime(std::chrono::milliseconds{staleLockTime});Voir également staleLockTime().
[since 6.2] void QLockFile::setStaleLockTime(std::chrono::milliseconds staleLockTime)
Définit l'intervalle au terme duquel un fichier de verrouillage est considéré comme périmé à staleLockTime. La valeur par défaut est de 30 s.
Si votre application maintient généralement le fichier verrouillé pendant plus de 30 secondes (par exemple, lors de l'enregistrement de plusieurs mégaoctets de données pendant 2 minutes), vous devez définir une valeur plus élevée à l'aide de la fonction `setStaleLockTime()`.
La valeur de ` staleLockTime()` est utilisée par ` lock()` et ` tryLock()` afin de déterminer à quel moment un fichier de verrouillage existant est considéré comme obsolète, c'est-à-dire abandonné par un processus qui s'est bloqué. Cela s'avère utile dans le cas où le PID a été réutilisé entre-temps ; ainsi, l'un des moyens de détecter un fichier de verrouillage obsolète consiste à vérifier s'il est présent depuis longtemps.
Définir cette valeur sur 0 ou un nombre négatif désactivera la vérification des horodatages sur les fichiers de verrouillage. La fonction ` QLockFile ` continuera toutefois à détecter un fichier de verrouillage obsolète si son contenu indique que le processus de verrouillage n’est plus en cours d’exécution.
Cette fonction a été introduite dans Qt 6.2.
Voir également staleLockTime().
int QLockFile::staleLockTime() const
Renvoie le délai, en millisecondes, au terme duquel un fichier de verrouillage est considéré comme obsolète.
Voir aussi setStaleLockTime().
[since 6.2] std::chrono::milliseconds QLockFile::staleLockTimeAsDuration() const
Renvoie un objet std::chrono::milliseconds indiquant le délai au terme duquel un fichier de verrouillage est considéré comme obsolète.
Cette fonction a été introduite dans Qt 6.2.
Voir également 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 que le fichier de verrouillage devienne disponible.
Remarque : passer un nombre négatif comme paramètre à timeout revient à 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é à l’aide de ` unlock()` avant qu’un autre processus (ou thread) ne puisse le verrouiller avec succès.
Il n’est pas autorisé d’appeler cette fonction plusieurs fois sur le même verrou à partir du même thread sans l’avoir d’abord déverrouillé ; cette fonction renverra toujours « false » en cas de tentative de verrouillage récursif du fichier.
Voir également 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 soit disponible.
Si le verrou a été obtenu, il doit être libéré à l’aide de ` unlock()` avant qu’un autre processus (ou thread) puisse le verrouiller avec succès.
Il n’est pas autorisé d’appeler cette fonction plusieurs fois sur le même verrou à partir du même thread sans l’avoir d’abord déverrouillé ; cette fonction renverra toujours « false » en cas de tentative de verrouillage récursif du fichier.
Il s'agit d'une fonction surchargée.
Cette fonction a été introduite dans Qt 6.2.
Voir également ` lock()` et ` unlock()`.
void QLockFile::unlock()
Libère le verrou en supprimant le fichier de verrouillage.
Appeler la fonction unlock() sans avoir préalablement verrouillé le fichier n'a aucun effet.
© 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.
