<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html>
<html lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<!-- qlockfile.cpp -->
<title>QLockFile Class | Qt Core 5.9</title>
<link rel="stylesheet" type="text/css" href="style/offline-simple.css" />
<script type="text/javascript">
document.getElementsByTagName("link").item(0).setAttribute("href", "style/offline.css");
// loading style sheet breaks anchors that were jumped to before
// so force jumping to anchor again
setTimeout(function() {
var anchor = location.hash;
// need to jump to different anchor first (e.g. none)
location.hash = "#";
setTimeout(function() {
location.hash = anchor;
}, 0);
}, 0);
</script>
</head>
<body>
<div class="header" id="qtdocheader">
<div class="main">
<div class="main-rounded">
<div class="navigationbar">
<table><tr>
<td >Qt 5.9</td><td ><a href="qtcore-index.html">Qt Core</a></td><td ><a href="qtcore-module.html">C++ Classes</a></td><td >QLockFile</td></tr></table><table class="buildversion"><tr>
<td id="buildversion" width="100%" align="right">Qt 5.9.4 Reference Documentation</td>
</tr></table>
</div>
</div>
<div class="content">
<div class="line">
<div class="content mainContent">
<div class="sidebar">
<div class="toc">
<h3><a name="toc">Contents</a></h3>
<ul>
<li class="level1"><a href="#public-types">Public Types</a></li>
<li class="level1"><a href="#public-functions">Public Functions</a></li>
<li class="level1"><a href="#details">Detailed Description</a></li>
</ul>
</div>
<div class="sidebar-content" id="sidebar-content"></div></div>
<h1 class="title">QLockFile Class</h1>
<!-- $$$QLockFile-brief -->
<p>The <a href="qlockfile.html">QLockFile</a> class provides locking between processes using a file. <a href="#details">More...</a></p>
<!-- @@@QLockFile -->
<div class="table"><table class="alignedsummary">
<tr><td class="memItemLeft rightAlign topAlign"> Header:</td><td class="memItemRight bottomAlign"> <span class="preprocessor">#include <QLockFile></span>
</td></tr><tr><td class="memItemLeft rightAlign topAlign"> qmake:</td><td class="memItemRight bottomAlign"> QT += core</td></tr><tr><td class="memItemLeft rightAlign topAlign"> Since:</td><td class="memItemRight bottomAlign"> Qt 5.1</td></tr></table></div><ul>
<li><a href="qlockfile-members.html">List of all members, including inherited members</a></li>
</ul>
<a name="public-types"></a>
<h2 id="public-types">Public Types</h2>
<div class="table"><table class="alignedsummary">
<tr><td class="memItemLeft rightAlign topAlign"> enum </td><td class="memItemRight bottomAlign"><b><a href="qlockfile.html#LockError-enum">LockError</a></b> { NoError, LockFailedError, PermissionError, UnknownError }</td></tr>
</table></div>
<a name="public-functions"></a>
<h2 id="public-functions">Public Functions</h2>
<div class="table"><table class="alignedsummary">
<tr><td class="memItemLeft rightAlign topAlign"> </td><td class="memItemRight bottomAlign"><b><a href="qlockfile.html#QLockFile">QLockFile</a></b>(const QString &<i>fileName</i>)</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> </td><td class="memItemRight bottomAlign"><b><a href="qlockfile.html#dtor.QLockFile">~QLockFile</a></b>()</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> LockError </td><td class="memItemRight bottomAlign"><b><a href="qlockfile.html#error">error</a></b>() const</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> bool </td><td class="memItemRight bottomAlign"><b><a href="qlockfile.html#getLockInfo">getLockInfo</a></b>(qint64 *<i>pid</i>, QString *<i>hostname</i>, QString *<i>appname</i>) const</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> bool </td><td class="memItemRight bottomAlign"><b><a href="qlockfile.html#isLocked">isLocked</a></b>() const</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> bool </td><td class="memItemRight bottomAlign"><b><a href="qlockfile.html#lock">lock</a></b>()</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> bool </td><td class="memItemRight bottomAlign"><b><a href="qlockfile.html#removeStaleLockFile">removeStaleLockFile</a></b>()</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> void </td><td class="memItemRight bottomAlign"><b><a href="qlockfile.html#setStaleLockTime">setStaleLockTime</a></b>(int <i>staleLockTime</i>)</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> int </td><td class="memItemRight bottomAlign"><b><a href="qlockfile.html#staleLockTime">staleLockTime</a></b>() const</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> bool </td><td class="memItemRight bottomAlign"><b><a href="qlockfile.html#tryLock">tryLock</a></b>(int <i>timeout</i> = 0)</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> void </td><td class="memItemRight bottomAlign"><b><a href="qlockfile.html#unlock">unlock</a></b>()</td></tr>
</table></div>
<a name="details"></a>
<!-- $$$QLockFile-description -->
<div class="descr">
<h2 id="details">Detailed Description</h2>
<p>The <a href="qlockfile.html">QLockFile</a> class provides locking between processes using a file.</p>
<p>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...</p>
<p>Serialization is only guaranteed if all processes that access the shared resource use <a href="qlockfile.html">QLockFile</a>, with the same file path.</p>
<p><a href="qlockfile.html">QLockFile</a> 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.</p>
<p>When protecting for a short-term operation, it is acceptable to call <a href="qlockfile.html#lock">lock</a>() and wait until any running operation finishes. When protecting a resource over a long time, however, the application should always call <a href="qlockfile.html#setStaleLockTime">setStaleLockTime</a>(0) and then <a href="qlockfile.html#tryLock">tryLock</a>() with a short timeout, in order to warn the user that the resource is locked.</p>
<p>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, <a href="qlockfile.html">QLockFile</a> 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.</p>
<p>For the use case of protecting a resource over a long time, you should therefore call <a href="qlockfile.html#setStaleLockTime">setStaleLockTime</a>(0), and when <a href="qlockfile.html#tryLock">tryLock</a>() returns <a href="qlockfile.html#LockError-enum">LockFailedError</a>, inform the user that the document is locked, possibly using <a href="qlockfile.html#getLockInfo">getLockInfo</a>() for more details.</p>
<p><b>Note: </b>On Windows, this class has problems detecting a stale lock if the machine's hostname contains characters outside the US-ASCII character set.</p></div>
<!-- @@@QLockFile -->
<div class="types">
<h2>Member Type Documentation</h2>
<!-- $$$LockError$$$NoError$$$LockFailedError$$$PermissionError$$$UnknownError -->
<h3 class="fn" id="LockError-enum"><a name="LockError-enum"></a>enum QLockFile::<span class="name">LockError</span></h3>
<p>This enum describes the result of the last call to <a href="qlockfile.html#lock">lock</a>() or <a href="qlockfile.html#tryLock">tryLock</a>().</p>
<div class="table"><table class="valuelist"><tr valign="top" class="odd"><th class="tblConst">Constant</th><th class="tblval">Value</th><th class="tbldscr">Description</th></tr>
<tr><td class="topAlign"><code>QLockFile::NoError</code></td><td class="topAlign tblval"><code>0</code></td><td class="topAlign">The lock was acquired successfully.</td></tr>
<tr><td class="topAlign"><code>QLockFile::LockFailedError</code></td><td class="topAlign tblval"><code>1</code></td><td class="topAlign">The lock could not be acquired because another process holds it.</td></tr>
<tr><td class="topAlign"><code>QLockFile::PermissionError</code></td><td class="topAlign tblval"><code>2</code></td><td class="topAlign">The lock file could not be created, for lack of permissions in the parent directory.</td></tr>
<tr><td class="topAlign"><code>QLockFile::UnknownError</code></td><td class="topAlign tblval"><code>3</code></td><td class="topAlign">Another error happened, for instance a full partition prevented writing out the lock file.</td></tr>
</table></div>
<!-- @@@LockError -->
</div>
<div class="func">
<h2>Member Function Documentation</h2>
<!-- $$$QLockFile[overload1]$$$QLockFileconstQString& -->
<h3 class="fn" id="QLockFile"><a name="QLockFile"></a>QLockFile::<span class="name">QLockFile</span>(const <span class="type"><a href="qstring.html">QString</a></span> &<i>fileName</i>)</h3>
<p>Constructs a new lock file object. The object is created in an unlocked state. When calling <a href="qlockfile.html#lock">lock</a>() or <a href="qlockfile.html#tryLock">tryLock</a>(), a lock file named <i>fileName</i> will be created, if it doesn't already exist.</p>
<p><b>See also </b><a href="qlockfile.html#lock">lock</a>() and <a href="qlockfile.html#unlock">unlock</a>().</p>
<!-- @@@QLockFile -->
<!-- $$$~QLockFile[overload1]$$$~QLockFile -->
<h3 class="fn" id="dtor.QLockFile"><a name="dtor.QLockFile"></a>QLockFile::<span class="name">~QLockFile</span>()</h3>
<p>Destroys the lock file object. If the lock was acquired, this will release the lock, by deleting the lock file.</p>
<!-- @@@~QLockFile -->
<!-- $$$error[overload1]$$$error -->
<h3 class="fn" id="error"><a name="error"></a><span class="type"><a href="qlockfile.html#LockError-enum">LockError</a></span> QLockFile::<span class="name">error</span>() const</h3>
<p>Returns the lock file error status.</p>
<p>If <a href="qlockfile.html#tryLock">tryLock</a>() returns <code>false</code>, this function can be called to find out the reason why the locking failed.</p>
<!-- @@@error -->
<!-- $$$getLockInfo[overload1]$$$getLockInfoqint64*QString*QString* -->
<h3 class="fn" id="getLockInfo"><a name="getLockInfo"></a><span class="type">bool</span> QLockFile::<span class="name">getLockInfo</span>(<span class="type"><a href="qtglobal.html#qint64-typedef">qint64</a></span> *<i>pid</i>, <span class="type"><a href="qstring.html">QString</a></span> *<i>hostname</i>, <span class="type"><a href="qstring.html">QString</a></span> *<i>appname</i>) const</h3>
<p>Retrieves information about the current owner of the lock file.</p>
<p>If <a href="qlockfile.html#tryLock">tryLock</a>() returns <code>false</code>, and <a href="qlockfile.html#error">error</a>() returns <a href="qlockfile.html#LockError-enum">LockFailedError</a>, this function can be called to find out more information about the existing lock file:</p>
<ul>
<li>the PID of the application (returned in <i>pid</i>)</li>
<li>the <i>hostname</i> it's running on (useful in case of networked filesystems),</li>
<li>the name of the application which created it (returned in <i>appname</i>),</li>
</ul>
<p>Note that <a href="qlockfile.html#tryLock">tryLock</a>() automatically deleted the file if there is no running application with this PID, so <a href="qlockfile.html#LockError-enum">LockFailedError</a> can only happen if there is an application with this PID (it could be unrelated though).</p>
<p>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 <a href="qlockfile.html#removeStaleLockFile">removeStaleLockFile</a>(), the application can call <a href="qlockfile.html#tryLock">tryLock</a>() again.</p>
<p>This function returns <code>true</code> 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 <a href="qlockfile.html#tryLock">tryLock</a>() failed and the call to this function. Simply call <a href="qlockfile.html#tryLock">tryLock</a>() again if this happens.</p>
<!-- @@@getLockInfo -->
<!-- $$$isLocked[overload1]$$$isLocked -->
<h3 class="fn" id="isLocked"><a name="isLocked"></a><span class="type">bool</span> QLockFile::<span class="name">isLocked</span>() const</h3>
<p>Returns <code>true</code> if the lock was acquired by this <a href="qlockfile.html">QLockFile</a> instance, otherwise returns <code>false</code>.</p>
<p><b>See also </b><a href="qlockfile.html#lock">lock</a>(), <a href="qlockfile.html#unlock">unlock</a>(), and <a href="qlockfile.html#tryLock">tryLock</a>().</p>
<!-- @@@isLocked -->
<!-- $$$lock[overload1]$$$lock -->
<h3 class="fn" id="lock"><a name="lock"></a><span class="type">bool</span> QLockFile::<span class="name">lock</span>()</h3>
<p>Creates the lock file.</p>
<p>If another process (or another thread) has created the lock file already, this function will block until that process (or thread) releases it.</p>
<p>Calling this function multiple times on the same lock from the same thread without unlocking first is not allowed. This function will <i>dead-lock</i> when the file is locked recursively.</p>
<p>Returns <code>true</code> 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.</p>
<p><b>See also </b><a href="qlockfile.html#unlock">unlock</a>() and <a href="qlockfile.html#tryLock">tryLock</a>().</p>
<!-- @@@lock -->
<!-- $$$removeStaleLockFile[overload1]$$$removeStaleLockFile -->
<h3 class="fn" id="removeStaleLockFile"><a name="removeStaleLockFile"></a><span class="type">bool</span> QLockFile::<span class="name">removeStaleLockFile</span>()</h3>
<p>Attempts to forcefully remove an existing lock file.</p>
<p>Calling this is not recommended when protecting a short-lived operation: <a href="qlockfile.html">QLockFile</a> already takes care of removing lock files after they are older than <a href="qlockfile.html#staleLockTime">staleLockTime</a>().</p>
<p>This method should only be called when protecting a resource for a long time, i.e. with <a href="qlockfile.html#staleLockTime">staleLockTime</a>(0), and after <a href="qlockfile.html#tryLock">tryLock</a>() returned <a href="qlockfile.html#LockError-enum">LockFailedError</a>, and the user agreed on removing the lock file.</p>
<p>Returns <code>true</code> on success, false if the lock file couldn't be removed. This happens on Windows, when the application owning the lock is still running.</p>
<!-- @@@removeStaleLockFile -->
<!-- $$$setStaleLockTime[overload1]$$$setStaleLockTimeint -->
<h3 class="fn" id="setStaleLockTime"><a name="setStaleLockTime"></a><span class="type">void</span> QLockFile::<span class="name">setStaleLockTime</span>(<span class="type">int</span> <i>staleLockTime</i>)</h3>
<p>Sets <i>staleLockTime</i> 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().</p>
<p>The value of <i>staleLockTime</i> is used by <a href="qlockfile.html#lock">lock</a>() and <a href="qlockfile.html#tryLock">tryLock</a>() 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.</p>
<p><b>See also </b><a href="qlockfile.html#staleLockTime">staleLockTime</a>().</p>
<!-- @@@setStaleLockTime -->
<!-- $$$staleLockTime[overload1]$$$staleLockTime -->
<h3 class="fn" id="staleLockTime"><a name="staleLockTime"></a><span class="type">int</span> QLockFile::<span class="name">staleLockTime</span>() const</h3>
<p>Returns the time in milliseconds after which a lock file is considered stale.</p>
<p><b>See also </b><a href="qlockfile.html#setStaleLockTime">setStaleLockTime</a>().</p>
<!-- @@@staleLockTime -->
<!-- $$$tryLock[overload1]$$$tryLockint -->
<h3 class="fn" id="tryLock"><a name="tryLock"></a><span class="type">bool</span> QLockFile::<span class="name">tryLock</span>(<span class="type">int</span> <i>timeout</i> = 0)</h3>
<p>Attempts to create the lock file. This function returns <code>true</code> if the lock was obtained; otherwise it returns <code>false</code>. If another process (or another thread) has created the lock file already, this function will wait for at most <i>timeout</i> milliseconds for the lock file to become available.</p>
<p>Note: Passing a negative number as the <i>timeout</i> is equivalent to calling <a href="qlockfile.html#lock">lock</a>(), i.e. this function will wait forever until the lock file can be locked if <i>timeout</i> is negative.</p>
<p>If the lock was obtained, it must be released with <a href="qlockfile.html#unlock">unlock</a>() before another process (or thread) can successfully lock it.</p>
<p>Calling this function multiple times on the same lock from the same thread without unlocking first is not allowed, this function will <i>always</i> return false when attempting to lock the file recursively.</p>
<p><b>See also </b><a href="qlockfile.html#lock">lock</a>() and <a href="qlockfile.html#unlock">unlock</a>().</p>
<!-- @@@tryLock -->
<!-- $$$unlock[overload1]$$$unlock -->
<h3 class="fn" id="unlock"><a name="unlock"></a><span class="type">void</span> QLockFile::<span class="name">unlock</span>()</h3>
<p>Releases the lock, by deleting the lock file.</p>
<p>Calling unlock() without locking the file first, does nothing.</p>
<p><b>See also </b><a href="qlockfile.html#lock">lock</a>() and <a href="qlockfile.html#tryLock">tryLock</a>().</p>
<!-- @@@unlock -->
</div>
</div>
</div>
</div>
</div>
</div>
<div class="footer">
<p>
<acronym title="Copyright">©</acronym> 2017 The Qt Company Ltd.
Documentation contributions included herein are the copyrights of
their respective owners.<br> The documentation provided herein is licensed under the terms of the <a href="http://www.gnu.org/licenses/fdl.html">GNU Free Documentation License version 1.3</a> as published by the Free Software Foundation.<br> 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. </p>
</div>
</body>
</html>
distrib
>
Mageia
>
6
>
armv5tl
>
media
>
core-updates
>
by-pkgid
>
768f7d9f703884aa2562bf0a651086df
>
files
>
484
