QLockFile Class

成员函数文档

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() 会自动删除文件，因此LockFailedError 只能在具有此 PID 的应用程序存在时才会发生（但也可能与此无关）。

这可以用来通知用户现有的锁文件，并让他们选择删除。使用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 被重复使用的情况下非常有用，因此检测过期锁文件的一种方法就是看它是否存在了很长时间。

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