PySide6.QtCore.QLockFile

class QLockFile

QLockFile 类使用文件在进程之间提供锁定。更多…

概要

方法

注意

本文档可能包含从C++自动翻译到Python的代码片段。我们始终欢迎对代码片段翻译的贡献。如果您发现翻译问题，您也可以通过在我们的https:/bugreports.qt.io/projects/PYSIDE上创建工单来告知我们。

详细描述

锁文件可用于防止多个进程同时访问同一资源。例如，磁盘上的配置文件、套接字、端口、共享内存区域等。

只有在所有访问共享资源的进程都使用QLockFile，并且使用相同的文件路径时，序列化才能得到保证。

QLockFile 支持两种使用场景：短期操作保护资源（例如在保存新设置之前验证配置文件是否已更改），以及长期保护资源（例如用户在编辑器中打开的文档）无限期的时间。

在保护短期操作时，可以调用lock()并等待任何正在运行的操作完成。然而，在长时间保护资源时，应用程序应始终调用setStaleLockTime（0ms），然后使用短超时调用tryLock()，以警告用户资源已被锁定。

如果持有锁的进程崩溃，锁文件会留在磁盘上，并且可能阻止任何其他进程访问共享资源。因此，QLockFile 尝试基于写入文件的进程ID检测这种“陈旧”的锁文件。为了覆盖进程ID在此期间被重用的情形，当前进程名称将与锁文件中对应的进程ID的进程名称进行比较。如果进程名称不同，锁文件将被视为陈旧。此外，锁文件的最后修改时间（默认为30秒，适用于短期操作的使用场景）也会被考虑。如果发现锁文件是陈旧的，它将被删除。

对于长时间保护资源的使用场景，因此你应该调用setStaleLockTime (0)，当tryLock()返回LockFailedError时，通知用户文档已被锁定，可能使用getLockInfo()获取更多详细信息。

注意

在Windows上，如果机器的主机名包含US-ASCII字符集之外的字符，此类在检测陈旧锁时会出现问题。

class LockError

此枚举描述了最后一次调用lock()或tryLock()的结果。

常量

描述

QLockFile.NoError

锁已成功获取。

QLockFile.LockFailedError

无法获取锁，因为另一个进程持有它。

QLockFile.PermissionError

由于父目录权限不足，无法创建锁定文件。

QLockFile.UnknownError

发生了另一个错误，例如分区已满，导致无法写入锁定文件。
__init__(fileName)
Parameters:

fileName – str

构造一个新的锁文件对象。该对象在创建时处于未锁定状态。当调用lock()或tryLock()时，如果不存在名为fileName的锁文件，将会创建一个。

另请参阅

lock() unlock()

error()
Return type:

LockError

返回锁文件错误状态。

如果 tryLock() 返回 false，可以调用此函数来找出锁定失败的原因。

fileName()
Return type:

字符串

返回锁定文件的文件名

getLockInfo()
Return type:

(int, str, str)

检索有关锁文件当前所有者的信息。

如果 tryLock() 返回 false，并且 error() 返回 LockFailedError，则可以调用此函数以获取有关现有锁定文件的更多信息：

  • 应用程序的PID（在pid中返回）

  • 它运行的hostname（在网络文件系统的情况下很有用），

  • 创建它的应用程序名称（在appname中返回），

请注意，tryLock() 如果没有运行具有此 PID 的应用程序，则会自动删除文件，因此 LockFailedError 只有在存在具有此 PID 的应用程序时才会发生（尽管可能无关）。

这可以用来通知用户有关现有锁定文件的信息，并让他们选择删除它。在使用removeStaleLockFile()删除文件后，应用程序可以再次调用tryLock()。

如果信息能够成功检索，此函数返回true，如果锁定文件不存在或不包含预期数据，则返回false。如果在tryLock()失败和调用此函数之间删除了锁定文件，则可能发生这种情况。如果发生这种情况，只需再次调用tryLock()。

isLocked()
Return type:

布尔

如果锁被此QLockFile实例获取，则返回true，否则返回false。

另请参阅

lock() unlock() tryLock()

lock()
Return type:

布尔

创建锁文件。

如果另一个进程（或另一个线程）已经创建了锁文件，此函数将阻塞，直到该进程（或线程）释放它。

不允许在同一线程中多次调用此函数而不先解锁。当文件被递归锁定时，此函数将死锁。

如果锁被获取，则返回true，如果由于不可恢复的错误（例如父目录没有权限）而无法获取锁，则返回false。

另请参阅

unlock() tryLock()

removeStaleLockFile()
Return type:

布尔

尝试强制删除现有的锁文件。

不建议在保护短期操作时调用此方法：QLockFile 已经负责在锁文件超过 staleLockTime() 后删除它们。

此方法仅应在长时间保护资源时调用，即使用staleLockTime（0），并且在tryLock()返回LockFailedError后，用户同意删除锁文件。

成功时返回 true，如果无法删除锁定文件则返回 false。这种情况在 Windows 上发生，当拥有锁定的应用程序仍在运行时。

setStaleLockTime(staleLockTime)
Parameters:

staleLockTime – int

设置staleLockTime为锁文件被认为过时的时间（以毫秒为单位）。默认值为30000，即30秒。如果你的应用程序通常会将文件锁定超过30秒（例如在保存大量数据时可能需要2分钟），你应该使用setStaleLockTime()设置一个更大的值。

staleLockTime 的值被 lock() 和 tryLock() 使用，以确定现有的锁文件何时被视为过时，即由崩溃的进程遗留下来的。这对于 PID 在此期间被重用的情况非常有用，因此检测过时锁文件的一种方法是它已经存在了很长时间。

这是一个重载函数，等同于调用：

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

另请参阅

staleLockTime()

staleLockTime()
Return type:

整数

返回以毫秒为单位的时间，超过该时间后锁定文件将被视为过时。

另请参阅

setStaleLockTime()

tryLock(timeout)
Parameters:

timeout – int

Return type:

布尔

尝试创建锁文件。如果成功获取锁，此函数将返回true；否则返回false。如果另一个进程（或另一个线程）已经创建了锁文件，此函数将最多等待timeout毫秒，直到锁文件可用。

注意：将负数作为timeout传递等同于调用lock()，即如果timeout为负数，此函数将永远等待，直到锁定文件可以被锁定。

如果锁被获取，必须在另一个进程（或线程）成功锁定它之前使用unlock()释放它。

不允许在未解锁的情况下从同一线程多次调用此函数，当尝试递归锁定文件时，此函数将始终返回false。

另请参阅

lock() unlock()

unlock()

通过删除锁文件来释放锁。

在没有先锁定文件的情况下调用unlock()，不会执行任何操作。

另请参阅

lock() tryLock()