CopperSpice API  1.9.1
QLockFile Class Reference

The QLockFile class provides locking between processes using a file. More...

Public Types

enum  LockError

Public Methods

 QLockFile (const QString &fileName)
 ~QLockFile ()
LockError error () const
bool getLockInfo (qint64 *pid, QString *hostname, QString *appname) const
bool isLocked () const
bool lock ()
bool removeStaleLockFile ()
void setStaleLockTime (int staleLockTime)
int staleLockTime () const
bool tryLock (int timeout=0)
void unlock ()

Detailed Description

This class can be used to prevent multiple processes from accessing the same resource concurrently. An example of a resource is a configuration file on disk, a socket, a port, or a region of shared memory. Concurrent access is only blocked if all processes which access the shared resource use QLockFile and have the same file path.

QLockFile supports two use cases.

To protect a resource for a short term operation
Call lock() and wait until any running operation finishes.
For a long term lock of a resource
Call setStaleLockTime(0) and then tryLock() 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 when tryLock() returns LockFailedError, inform the user that the document is locked, possibly using getLockInfo() for more details.

Member Enumeration Documentation

This enum describes the result of the last call to lock() or tryLock().

Constant Value Description
QLockFile::NoError 0 Lock was acquired successfully
QLockFile::LockFailedError 1 Lock could not be acquired because another process holds it
QLockFile::PermissionError 2 lock file could not be created, for lack of permissions in the parent directory
QLockFile::UnknownError 3 Another error happened, for instance a full partition prevented writing out the lock file

Constructor & Destructor Documentation

QLockFile::QLockFile ( const QString fileName)

Constructs a new lock file object. The object is created in an unlocked state. When calling lock() or tryLock() a lock file named fileName will be created, if it does not already exist.

See also
lock(), unlock()
QLockFile::~QLockFile ( )

Destroys the lock file object. If the lock was acquired, this will release the lock, by deleting the lock file.

Method Documentation

QLockFile::LockError QLockFile::error ( ) const

Returns the lock file error status. If tryLock() returns false this method can be called to find out the reason why the locking failed.

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

This method retrieves information about the current owner of the lock file. The method will return true if the information was successfully retrieved and false if the lock file does not exist or contains invalid data.

Call this method when tryLock() returns false and error() returns LockFailedError.

  • PID of the application placed in the parameter pid
  • The hostname the application is running on
  • The name of the application which created the lock file is placed in the parameter appname),

If this method returns false the lock file may have been deleted between the time tryLock() failed and the call to this method. Call tryLock() again if this happens.

The tryLock() method automatically deletes the file if there is no running application with this PID, so LockFailedError can only happen if there is an application with this PID.

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 call tryLock() again.

bool QLockFile::isLocked ( ) const

Returns true if the lock was acquired by this QLockFile instance, otherwise returns false.

See also
lock(), tryLock(), unlock()
bool QLockFile::lock ( )

Creates the lock file. 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.

If another process (or another thread) has created the lock file already, this method will block until that process (or thread) releases it. Calling this method multiple times on the same lock from the same thread without unlocking first is not allowed. This method will dead lock when the file is locked recursively.

See also
tryLock(), unlock()
bool QLockFile::removeStaleLockFile ( )

Attempts to force the removal of an existing lock file. Returns true on success and false if the lock file could not be removed.

Calling this method is not recommended when protecting a short lived operation. QLockFile already takes care of removing lock files after they are older than staleLockTime(). This method should only be called when protecting a resource for a long time and after tryLock() returned LockFailedError, and the user agreed on removing the lock file.

void QLockFile::setStaleLockTime ( int  staleLockTime)

Sets staleLockTime to be the time in milliseconds after which a lock file is considered stale. The default value is 30000 which is 30 seconds. If your application typically keeps the file locked for more than 30 seconds, set a bigger value using setStaleLockTime().

The value of staleLockTime is used by lock() and 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.

See also
int QLockFile::staleLockTime ( ) const

Returns the time in milliseconds after which a lock file is considered stale.

See also
bool QLockFile::tryLock ( int  timeout = 0)

Attempts to create the lock file. This method returns true if the lock was obtained, otherwise it returns false. If another process (or another thread) has created the lock file already this method will wait for at most timeout milliseconds for the lock file to become available. If the lock was obtained it must be released with unlock() before another process (or thread) can successfully lock it.

Passing a negative number as the timeout is equivalent to calling lock(). This method will wait forever until the lock file can be locked if timeout is negative.

Calling this method multiple times on the same lock from the same thread without unlocking first is not allowed, this method will always return false when attempting to lock the file recursively.

See also
lock(), unlock()
void QLockFile::unlock ( )

Releases the lock, by deleting the lock file. Calling unlock() without locking the file first, does nothing.

See also
lock(), tryLock()