QLockFile 类

成员函数文档

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，则此函数可以用来查找关于现有锁定文件更多的信息。

• 应用程序的进程ID（在pid中返回）
• 它运行的hostname（在网络文件系统中很有用），
• 创建它的应用程序的名称（在appname中返回），

请注意，如果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 秒（例如，在两分钟内保存几兆字节数据），则应使用 setStaleLockTime() 设置一个更大的值。

staleLockTime 的值被 lock() 和 tryLock() 使用，以确定现有锁文件何时被视为过时，即由崩溃的进程留下的。这在 PID 同时被重新使用的场合很有用，因此检测过时锁文件的一种方法是根据其存在时间过长这一事实。

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

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

另请参阅 staleLockTime().

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

设置认为锁文件过时的间隔到 staleLockTime。默认值是 30 秒。

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

staleLockTime() 的值被 lock() 和 tryLock() 使用，以确定现有锁文件何时被视为过时，即由崩溃的进程留下的。这在 PID 同时被重新使用的场合很有用，因此检测过时锁文件的一种方法是根据其存在时间过长这一事实。

此函数自 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()。

[自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()。