QLockFile Class

成员函数文档

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

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

另请参阅 lock() 和unlock()。

[noexcept] QLockFile::~QLockFile()

销毁锁文件对象。如果已获取锁，则通过删除锁文件来释放该锁。

QLockFile::LockError QLockFile::error() const

返回锁定文件的错误状态。

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

QString QLockFile::fileName() const

返回锁定文件的文件名

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

获取锁定文件当前所有者的信息。

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

• 应用程序的 PID（由 `pid` 返回）
• 其运行的hostname （在网络文件系统中很有用），
• 创建该文件的应用程序名称（通过 `appname` 返回），

请注意，如果没有 PID 与该锁文件匹配的正在运行的应用程序，tryLock() 会自动删除该文件，因此只有当存在 PID 与该锁文件匹配的应用程序时（尽管该应用程序可能与此无关），LockFailedError 才会被调用。

这可用于告知用户锁文件的存在，并让用户选择是否删除它。使用removeStaleLockFile() 删除文件后，应用程序可以再次调用tryLock()。

如果信息成功获取，该函数返回true ；如果锁定文件不存在或不包含预期数据，则返回false。这种情况可能发生在tryLock()调用失败与本次函数调用之间，锁定文件已被删除。若发生此情况，只需再次调用tryLock()即可。

bool QLockFile::isLocked() const

如果锁是由此QLockFile 实例获取的，则返回true ；否则返回false 。

另请参阅 lock()、unlock() 和tryLock()。

bool QLockFile::lock()

创建锁文件。

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

不允许在同一线程上对同一锁多次调用此函数，且未先解锁。当文件被递归锁定时，此函数将导致死锁。

如果成功获取锁，则返回true ；如果因不可恢复的错误（例如父目录无权限）而无法获取锁，则返回false。

另请参阅 unlock() 和tryLock()。

bool QLockFile::removeStaleLockFile()

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

在保护短暂操作时，不建议调用此方法：QLockFile 已负责在锁文件存在时间超过staleLockTime() 后将其删除。

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

成功时返回true ；若无法删除锁定文件则返回false。这种情况通常发生在Windows系统中，当拥有该锁的应用程序仍在运行时。

void QLockFile::setStaleLockTime(int staleLockTime)

将 `staleLockTime ` 设置为锁定文件被视为过期的毫秒数。默认值为 30000，即 30 秒。 如果您的应用程序通常会将文件锁定超过 30 秒（例如，在 2 分钟内保存数兆字节的数据），则应使用 setStaleLockTime() 设置一个更大的值。

`staleLockTime ` 的值会被 `lock()` 和 `tryLock()` 调用所使用，以确定何时将现有锁文件视为过期文件，即由崩溃进程遗留的文件。当 PID 在此期间被重用时，此机制非常有用，因此检测过期锁文件的一种方法是根据其存在时间过长这一事实。

这是一个重载函数，相当于调用：

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

另请参阅 staleLockTime()。

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

将锁定文件被视为过期的间隔时间设置为staleLockTime 。默认值为30秒。

如果您的应用程序通常会将文件锁定超过30秒（例如，在2分钟内保存数兆字节的数据），则应使用 setStaleLockTime() 设置一个更大的值。

`staleLockTime()` 的值会被 `lock()` 和 `tryLock()` 调用所使用，以确定何时将现有锁文件视为过期文件（即由崩溃进程遗留的文件）。当 PID 在此期间被重复使用时，此机制非常有用；因此，检测过期锁文件的一种方法是检查该文件是否已存在较长时间。

将此值设置为 0 或负数将禁用对锁文件时间戳的验证。如果锁文件的内容表明加锁进程已不再运行，QLockFile 仍会检测到过期的锁文件。

该函数于 Qt 6.2 中引入。

另请参阅 staleLockTime()。

int QLockFile::staleLockTime() const

返回锁文件被视为过期所需的毫秒数。

另请参阅 setStaleLockTime()。

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

返回一个 std::chrono::milliseconds 对象，该对象表示锁文件被视为过期所需经过的时间。

该函数在 Qt 6.2 中引入。

另请参阅 ` setStaleLockTime()`。

bool QLockFile::tryLock(int timeout)

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

注意：将负数作为timeout 参数传递等同于调用lock()，即如果timeout 为负数，则该函数将无限期等待，直到锁文件可以被锁定为止。

如果已获得锁，则必须先使用unlock() 释放锁，另一个进程（或线程）才能成功锁定该文件。

不允许在同一线程上对同一锁多次调用此函数而未先解锁，当尝试递归锁定文件时，此函数将始终返回 false。

另请参阅 lock() 和unlock()。

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

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

如果成功获取了锁，必须先通过unlock() 释放锁，其他进程（或线程）才能成功锁定该文件。

不允许在同一线程上对同一锁多次调用此函数而未先解锁，当尝试递归锁定文件时，此函数将始终返回 false。

该函数在 Qt 6.2 中引入。

另请参见 lock() 和unlock()。

void QLockFile::unlock()

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

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

另请参阅 lock() 和tryLock()。