QLockFile 类提供在进程之间使用文件的锁。 更多...
| 头： | #include <QLockFile> |
| CMake: |
find_package(Qt6 REQUIRED COMPONENTS Core)
target_link_libraries(mytarget PRIVATE Qt6::Core) |
| qmake: | QT += core |
| enum | LockError { NoError, LockFailedError, PermissionError, UnknownError } |
| 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 ) |
| void | setStaleLockTime (std::chrono::milliseconds value ) |
| int | staleLockTime () const |
| std::chrono::milliseconds | staleLockTimeAsDuration () const |
| bool | tryLock (int timeout = 0) |
| bool | tryLock (std::chrono::milliseconds timeout ) |
| void | unlock () |
锁定文件可以用于阻止多个进程并发性访问同一资源。例如，在磁盘上的配置文件或套接字、端口、共享内存区域 ...
序列化才有保证，若访问共享资源的的所有进程使用 QLockFile，采用相同文件路径。
QLockFile 支持 2 用例：为短期操作保护资源 (如，验证配置文件是否已改变在保存新设置之前)，和为无限长期存活保护资源 (如，用户在编辑器中打开文档)。
当保护短期操作时，可以调用 lock () 并等待直到任何正在运行的操作完成为止。当长时间保护资源时，不管怎样，应用程序应该始终调用 setStaleLockTime (0) 然后 tryLock () 采用短超时，以警告用户资源被锁定。
若持有锁的进程崩溃，锁文件留在磁盘且可以阻止任何其它进程访问共享资源。由于此原因，QLockFile 会试着基于写入文件的进程 ID 检测这种 "陈旧" 锁定文件。为控制进程 ID 同时被重用的状况，会比较当前进程名称与对应锁文件进程 ID 的进程名称。若进程名称不同，认为锁文件陈旧。此外，会考虑锁文件的最后修改时间 (默认 30 秒，对于短期存活操作用例)。若发现锁文件陈旧，会删除它。
因此，对于长时间保护资源的用例，应该调用 setStaleLockTime (0)，和当 tryLock () 返回 LockFailedError ，通报用户文档被锁定，可能使用 getLockInfo () 了解更多细节。
注意： 在 Windows，此类检测陈旧锁时会遇到问题，若机器主机名包含 US-ASCII 字符集外的字符。
此枚举描述最后结果为调用 lock () 或 tryLock ().
| 常量 | 值 | 描述 |
|---|---|---|
QLockFile::NoError
|
0
|
成功获取锁。 |
QLockFile::LockFailedError
|
1
|
无法获取锁由于被另一进程持有。 |
QLockFile::PermissionError
|
2
|
无法创建锁定文件由于父级目录缺乏权限。 |
QLockFile::UnknownError
|
3
|
发生其它错误，例如：完整分区阻止写出锁定文件。 |
构造新锁定文件对象。对象被创建在解锁状态下。当调用 lock () 或 tryLock ()，锁定文件 fileName 将被创建，若它尚不存在。
销毁锁定文件对象。若获得锁，这将释放锁通过删除锁定文件。
返回锁定文件错误状态。
若
tryLock
() 返回
false
，此函数可以被调用以找出锁定失败的原因。
Returns the file name of the lock file
检索锁定文件当前所有者的有关信息。
若
tryLock
() 返回
false
，和
error
() 返回
LockFailedError
，此函数可以被调用以找出有关现有锁定文件的更多信息：
注意， tryLock () automatically deleted the file if there is no running application with this PID, so LockFailedError can only happen if there is an application with this PID (it could be unrelated though).
This can be used to inform users about the existing lock file and give them the choice to delete it. After removing the file using removeStaleLockFile ()，应用程序可以调用 tryLock () 再次。
此函数返回
true
if the information could be successfully retrieved, false if the lock file doesn't exist or doesn't contain the expected data. This can happen if the lock file was deleted between the time where
tryLock
() failed and the call to this function. Simply call
tryLock
() again if this happens.
返回
true
若获得锁通过此
QLockFile
实例，否则返回
false
.
另请参阅 lock (), unlock ()，和 tryLock ().
创建锁定文件。
若另一进程 (或另一线程) 已经创建锁定文件，此函数将阻塞直到进程 (或线程) 释放它为止。
不允许在未先解锁的情况下从同一线程同一锁上多次调用此函数。此函数将 dead-lock 当递归锁定文件时。
返回
true
若获得锁，false 若由于不可恢复的错误 (如：父目录没有权限) 而无法获得锁。
试图强行移除现有锁定文件。
不推荐调用此当保护短期活着操作时： QLockFile 已负责移除锁定文件，当它们早于 staleLockTime ().
此方法才应该被调用当保护长时间资源时，即：采用 staleLockTime (0)，和之后 tryLock () 返回 LockFailedError ，且用户同意移除锁定文件。
返回
true
当成功时，false 若锁定文件无法被移除。这发生在 Windows，当拥有锁的应用程序仍在运行时。
设置 staleLockTime to be the time in milliseconds after which a lock file is considered stale. The default value is 30000, i.e. 30 seconds. If your application typically keeps the file locked for more than 30 seconds (for instance while saving megabytes of data for 2 minutes), you should set a bigger value using setStaleLockTime().
值 staleLockTime 用于 lock () 和 tryLock () in order to determine when an existing lock file is considered stale, i.e. left over by a crashed process. This is useful for the case where the PID got reused meanwhile, so one way to detect a stale lock file is by the fact that it has been around for a long time.
另请参阅 staleLockTime ().
[since 6.2]
void
QLockFile::
setStaleLockTime
(
std::chrono::milliseconds
value
)
这是重载函数。
Sets the interval after which a lock file is considered stale to value . The default value is 30 seconds. If your application typically keeps the file locked for more than 30 seconds (for instance while saving megabytes of data for 2 minutes), you should set a bigger value using setStaleLockTime().
值 staleLockTime () is used by lock () 和 tryLock () in order to determine when an existing lock file is considered stale, i.e. left over by a crashed process. This is useful for the case where the PID got reused meanwhile, so one way to detect a stale lock file is by the fact that it has been around for a long time.
该函数在 Qt 6.2 引入。
另请参阅 staleLockTime ().
返回时间 (以毫秒为单位)，在此时间之后锁定文件被认为陈旧。
另请参阅 setStaleLockTime ().
[since 6.2]
std::chrono::milliseconds
QLockFile::
staleLockTimeAsDuration
() const
这是重载函数。
Returns a std::chrono::milliseconds object which denotes the time after which a lock file is considered stale.
该函数在 Qt 6.2 引入。
另请参阅 setStaleLockTime ().
试图创建锁定文件。此函数返回
true
若获得锁；否则，返回
false
。若另一进程 (或另一线程) 已经创建锁文件，此函数将等待最多
timeout
毫秒为使锁文件变为可用。
注意：传递负数作为 timeout 相当于调用 lock ()，即：此函数将永远等待，直到锁文件可以被锁定若 timeout 为负。
若有获得，必须释放锁采用 unlock () 在另一进程 (或线程) 可以成功锁定它之前。
在不首先解锁的情况下，对来自同一线程的相同锁多次调用此函数是不允许的。此函数将 always 返回 false 当试图递归锁定文件时。
[since 6.2]
bool
QLockFile::
tryLock
(
std::chrono::milliseconds
timeout
)
这是重载函数。
试图创建锁定文件。此函数返回
true
若获得锁；否则，返回
false
。若另一进程 (或另一线程) 已经创建锁文件，此函数将等待最多
timeout
for the lock file to become available.
若有获得，必须释放锁采用 unlock () 在另一进程 (或线程) 可以成功锁定它之前。
在不首先解锁的情况下，对来自同一线程的相同锁多次调用此函数是不允许的。此函数将 always 返回 false 当试图递归锁定文件时。
该函数在 Qt 6.2 引入。
释放锁，通过删除锁定文件。
调用 unlock() 在首先未锁定文件的情况下，什么都不做。