QLockFile¶
Synopsis¶
Functions¶
def
error
()def
getLockInfo
(pid, hostname, appname)def
isLocked
()def
lock
()def
removeStaleLockFile
()def
setStaleLockTime
(arg__1)def
staleLockTime
()def
tryLock
([timeout=0])def
unlock
()
Detailed Description¶
A lock file can be used to prevent multiple processes from accessing concurrently the same resource. For instance, a configuration file on disk, or a socket, a port, a region of shared memory…
Serialization is only guaranteed if all processes that access the shared resource use
QLockFile
, with the same file path.
QLockFile
supports two use cases: to protect a resource for a short-term operation (e.g. verifying if a configuration file has changed before saving new settings), and for long-lived protection of a resource (e.g. a document opened by a user in an editor) for an indefinite amount of time.When protecting for a short-term operation, it is acceptable to call
lock()
and wait until any running operation finishes. When protecting a resource over a long time, however, the application should always callsetStaleLockTime
(0) and thentryLock()
with a short timeout, in order to warn the user that the resource is locked.If the process holding the lock crashes, the lock file stays on disk and can prevent any other process from accessing the shared resource, ever. For this reason,
QLockFile
tries to detect such a “stale” lock file, based on the process ID written into the file. To cover the situation that the process ID got reused meanwhile, the current process name is compared to the name of the process that corresponds to the process ID from the lock file. If the process names differ, the lock file is considered stale. Additionally, the last modification time of the lock file (30s by default, for the use case of a short-lived operation) is taken into account. If the lock file is found to be stale, it will be deleted.For the use case of protecting a resource over a long time, you should therefore call
setStaleLockTime
(0), and whentryLock()
returnsLockFailedError
, inform the user that the document is locked, possibly usinggetLockInfo()
for more details.Note
On Windows, this class has problems detecting a stale lock if the machine’s hostname contains characters outside the US-ASCII character set.
- class PySide2.QtCore.QLockFile(fileName)¶
- Parameters:
fileName – str
- PySide2.QtCore.QLockFile.LockError¶
This enum describes the result of the last call to
lock()
ortryLock()
.Constant
Description
QLockFile.NoError
The lock was acquired successfully.
QLockFile.LockFailedError
The lock could not be acquired because another process holds it.
QLockFile.PermissionError
The lock file could not be created, for lack of permissions in the parent directory.
QLockFile.UnknownError
Another error happened, for instance a full partition prevented writing out the lock file.
- PySide2.QtCore.QLockFile.error()¶
- Return type:
Returns the lock file error status.
If
tryLock()
returnsfalse
, this function can be called to find out the reason why the locking failed.
- PySide2.QtCore.QLockFile.getLockInfo(pid, hostname, appname)¶
- Parameters:
pid – int
hostname – str
appname – str
- Return type:
bool
Retrieves information about the current owner of the lock file.
If
tryLock()
returnsfalse
, anderror()
returnsLockFailedError
, this function can be called to find out more information about the existing lock file:the PID of the application (returned in
pid
)the
hostname
it’s running on (useful in case of networked filesystems),the name of the application which created it (returned in
appname
),
Note that
tryLock()
automatically deleted the file if there is no running application with this PID, soLockFailedError
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()
, the application can calltryLock()
again.This function returns
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 wheretryLock()
failed and the call to this function. Simply calltryLock()
again if this happens.
- PySide2.QtCore.QLockFile.isLocked()¶
- Return type:
bool
Returns
true
if the lock was acquired by thisQLockFile
instance, otherwise returnsfalse
.
- PySide2.QtCore.QLockFile.lock()¶
- Return type:
bool
Creates the lock file.
If another process (or another thread) has created the lock file already, this function will block until that process (or thread) releases it.
Calling this function multiple times on the same lock from the same thread without unlocking first is not allowed. This function will dead-lock when the file is locked recursively.
Returns
true
if the lock was acquired, false if it could not be acquired due to an unrecoverable error, such as no permissions in the parent directory.
- PySide2.QtCore.QLockFile.removeStaleLockFile()¶
- Return type:
bool
Attempts to forcefully remove an existing lock file.
Calling this is not recommended when protecting a short-lived operation:
QLockFile
already takes care of removing lock files after they are older thanstaleLockTime()
.This method should only be called when protecting a resource for a long time, i.e. with
staleLockTime
(0), and aftertryLock()
returnedLockFailedError
, and the user agreed on removing the lock file.Returns
true
on success, false if the lock file couldn’t be removed. This happens on Windows, when the application owning the lock is still running.
- PySide2.QtCore.QLockFile.setStaleLockTime(arg__1)¶
- Parameters:
arg__1 – int
Sets
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 .The value of
staleLockTime
is used bylock()
andtryLock()
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.See also
- PySide2.QtCore.QLockFile.staleLockTime()¶
- Return type:
int
Returns the time in milliseconds after which a lock file is considered stale.
See also
- PySide2.QtCore.QLockFile.tryLock([timeout=0])¶
- Parameters:
timeout – int
- Return type:
bool
Attempts to create the lock file. This function returns
true
if the lock was obtained; otherwise it returnsfalse
. If another process (or another thread) has created the lock file already, this function will wait for at mosttimeout
milliseconds for the lock file to become available.Note: Passing a negative number as the
timeout
is equivalent to callinglock()
, i.e. this function will wait forever until the lock file can be locked iftimeout
is negative.If the lock was obtained, it must be released with
unlock()
before another process (or thread) can successfully lock it.Calling this function multiple times on the same lock from the same thread without unlocking first is not allowed, this function will always return false when attempting to lock the file recursively.
- PySide2.QtCore.QLockFile.unlock()¶
Releases the lock, by deleting the lock file.
Calling without locking the file first, does nothing.
© 2022 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.