<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "DTD/xhtml1-strict.dtd">
<html><head><title>QElapsedTimer Class Reference</title><style>h3.fn,span.fn { margin-left: 1cm; text-indent: -1cm }
a:link { color: #004faf; text-decoration: none }
a:visited { color: #672967; text-decoration: none }
td.postheader { font-family: sans-serif }
tr.address { font-family: sans-serif }
body { background: #ffffff; color: black; }
</style></head><body><table border="0" cellpadding="0" cellspacing="0" width="100%"><tr /><td align="left" valign="top" width="32"><img align="left" border="0" height="32" src="images/rb-logo.png" width="32" /></td><td width="1">  </td><td class="postheader" valign="center"><a href="index.html"><font color="#004faf">Home</font></a> · <a href="classes.html"><font color="#004faf">All Classes</font></a> · <a href="modules.html"><font color="#004faf">Modules</font></a></td></table><h1 align="center">QElapsedTimer Class Reference<br /><sup><sup>[<a href="qtcore.html">QtCore</a> module]</sup></sup></h1><p>The QElapsedTimer class provides a fast way to calculate elapsed
times. <a href="#details">More...</a></p>
<h3>Types</h3><ul><li><div class="fn" />enum <b><a href="qelapsedtimer.html#ClockType-enum">ClockType</a></b> { SystemTime, MonotonicClock, TickCounter, MachAbsoluteTime, PerformanceCounter }</li></ul><h3>Methods</h3><ul><li><div class="fn" /><b><a href="qelapsedtimer.html#QElapsedTimer">__init__</a></b> (<i>self</i>)</li><li><div class="fn" /><b><a href="qelapsedtimer.html#QElapsedTimer-2">__init__</a></b> (<i>self</i>, QElapsedTimer)</li><li><div class="fn" />int <b><a href="qelapsedtimer.html#elapsed">elapsed</a></b> (<i>self</i>)</li><li><div class="fn" />bool <b><a href="qelapsedtimer.html#hasExpired">hasExpired</a></b> (<i>self</i>, int <i>timeout</i>)</li><li><div class="fn" /><b><a href="qelapsedtimer.html#invalidate">invalidate</a></b> (<i>self</i>)</li><li><div class="fn" />bool <b><a href="qelapsedtimer.html#isValid">isValid</a></b> (<i>self</i>)</li><li><div class="fn" />int <b><a href="qelapsedtimer.html#msecsSinceReference">msecsSinceReference</a></b> (<i>self</i>)</li><li><div class="fn" />int <b><a href="qelapsedtimer.html#msecsTo">msecsTo</a></b> (<i>self</i>, QElapsedTimer <i>other</i>)</li><li><div class="fn" />int <b><a href="qelapsedtimer.html#nsecsElapsed">nsecsElapsed</a></b> (<i>self</i>)</li><li><div class="fn" />int <b><a href="qelapsedtimer.html#restart">restart</a></b> (<i>self</i>)</li><li><div class="fn" />int <b><a href="qelapsedtimer.html#secsTo">secsTo</a></b> (<i>self</i>, QElapsedTimer <i>other</i>)</li><li><div class="fn" /><b><a href="qelapsedtimer.html#start">start</a></b> (<i>self</i>)</li></ul><h3>Static Methods</h3><ul><li><div class="fn" />ClockType <b><a href="qelapsedtimer.html#clockType">clockType</a></b> ()</li><li><div class="fn" />bool <b><a href="qelapsedtimer.html#isMonotonic">isMonotonic</a></b> ()</li></ul><h3>Special Methods</h3><ul><li><div class="fn" />bool <b><a href="qelapsedtimer.html#__eq__">__eq__</a></b> (<i>self</i>, QElapsedTimer <i>other</i>)</li><li><div class="fn" />bool <b><a href="qelapsedtimer.html#__ge__">__ge__</a></b> (<i>self</i>, QElapsedTimer <i>v2</i>)</li><li><div class="fn" />bool <b><a href="qelapsedtimer.html#__lt__">__lt__</a></b> (<i>self</i>, QElapsedTimer <i>v2</i>)</li><li><div class="fn" />bool <b><a href="qelapsedtimer.html#__ne__">__ne__</a></b> (<i>self</i>, QElapsedTimer <i>other</i>)</li></ul><a name="details" /><hr /><h2>Detailed Description</h2><p>The QElapsedTimer class provides a fast way to calculate elapsed
times.</p>
<p>The QElapsedTimer class is usually used to quickly calculate how
much time has elapsed between two events. Its API is similar to
that of <a href="qtime.html">QTime</a>, so code that was using that
can be ported quickly to the new class.</p>
<p>However, unlike <a href="qtime.html">QTime</a>, QElapsedTimer
tries to use monotonic clocks if possible. This means it's not
possible to convert QElapsedTimer objects to a human-readable
time.</p>
<p>The typical use-case for the class is to determine how much time
was spent in a slow operation. The simplest example of such a case
is for debugging purposes, as in the following example:</p>
<pre class="cpp">
<span class="type">QElapsedTimer</span> timer;
timer<span class="operator">.</span>start();
slowOperation1();
<a href="qtcore.html#qDebug">qDebug</a>() <span class="operator"><</span><span class="operator"><</span> <span class="string">"The slow operation took"</span> <span class="operator"><</span><span class="operator"><</span> timer<span class="operator">.</span>elapsed() <span class="operator"><</span><span class="operator"><</span> <span class="string">"milliseconds"</span>;
</pre>
<p>In this example, the timer is started by a call to <a href="qelapsedtimer.html#start">start</a>() and the elapsed timer is
calculated by the <a href="qelapsedtimer.html#elapsed">elapsed</a>() function.</p>
<p>The time elapsed can also be used to recalculate the time
available for another operation, after the first one is complete.
This is useful when the execution must complete within a certain
time period, but several steps are needed. The
<tt>waitFor</tt>-type functions in <a href="qiodevice.html">QIODevice</a> and its subclasses are good examples
of such need. In that case, the code could be as follows:</p>
<pre class="cpp">
<span class="type">void</span> executeSlowOperations(<span class="type">int</span> timeout)
{
<span class="type">QElapsedTimer</span> timer;
timer<span class="operator">.</span>start();
slowOperation1();
<span class="type">int</span> remainingTime <span class="operator">=</span> timeout <span class="operator">-</span> timer<span class="operator">.</span>elapsed();
<span class="keyword">if</span> (remainingTime <span class="operator">></span> <span class="number">0</span>)
slowOperation2(remainingTime);
}
</pre>
<p>Another use-case is to execute a certain operation for a
specific timeslice. For this, QElapsedTimer provides the <a href="qelapsedtimer.html#hasExpired">hasExpired</a>() convenience
function, which can be used to determine if a certain number of
milliseconds has already elapsed:</p>
<pre class="cpp">
<span class="type">void</span> executeOperationsForTime(<span class="type">int</span> ms)
{
<span class="type">QElapsedTimer</span> timer;
timer<span class="operator">.</span>start();
<span class="keyword">while</span> (<span class="operator">!</span>timer<span class="operator">.</span>hasExpired(ms))
slowOperation1();
}
</pre>
<a id="reference-clocks" name="reference-clocks" />
<h3>Reference clocks</h3>
<p>QElapsedTimer will use the platform's monotonic reference clock
in all platforms that support it (see <a href="qelapsedtimer.html#isMonotonic">QElapsedTimer.isMonotonic</a>()).
This has the added benefit that QElapsedTimer is immune to time
adjustments, such as the user correcting the time. Also unlike
<a href="qtime.html">QTime</a>, QElapsedTimer is immune to changes
in the timezone settings, such as daylight savings periods.</p>
<p>On the other hand, this means QElapsedTimer values can only be
compared with other values that use the same reference. This is
especially true if the time since the reference is extracted from
the QElapsedTimer object (<a href="qelapsedtimer.html#msecsSinceReference">QElapsedTimer.msecsSinceReference</a>())
and serialised. These values should never be exchanged across the
network or saved to disk, since there's no telling whether the
computer node receiving the data is the same as the one originating
it or if it has rebooted since.</p>
<p>It is, however, possible to exchange the value with other
processes running on the same machine, provided that they also use
the same reference clock. QElapsedTimer will always use the same
clock, so it's safe to compare with the value coming from another
process in the same machine. If comparing to values produced by
other APIs, you should check that the clock used is the same as
QElapsedTimer (see <a href="qelapsedtimer.html#clockType">QElapsedTimer.clockType</a>()).</p>
<a name="32-bit-overflows" />
<h4>32-bit overflows</h4>
<p>Some of the clocks that QElapsedTimer have a limited range and
may overflow after hitting the upper limit (usually 32-bit).
QElapsedTimer deals with this overflow issue and presents a
consistent timing. However, when extracting the time since
reference from QElapsedTimer, two different processes in the same
machine may have different understanding of how much time has
actually elapsed.</p>
<p>The information on which clocks types may overflow and how to
remedy that issue is documented along with the clock types.</p>
<hr /><h2>Type Documentation</h2><h3 class="fn"><a name="ClockType-enum" />QElapsedTimer.ClockType</h3><p>This enum contains the different clock types that <a href="qelapsedtimer.html">QElapsedTimer</a> may use.</p>
<p><a href="qelapsedtimer.html">QElapsedTimer</a> will always use
the same clock type in a particular machine, so this value will not
change during the lifetime of a program. It is provided so that
<a href="qelapsedtimer.html">QElapsedTimer</a> can be used with
other non-Qt implementations, to guarantee that the same reference
clock is being used.</p>
<table class="valuelist">
<tr class="odd" valign="top">
<th class="tblConst">Constant</th>
<th class="tblval">Value</th>
<th class="tbldscr">Description</th>
</tr>
<tr>
<td class="topAlign"><tt>QElapsedTimer.SystemTime</tt></td>
<td class="topAlign"><tt>0</tt></td>
<td class="topAlign">The human-readable system time. This clock is
not monotonic.</td>
</tr>
<tr>
<td class="topAlign"><tt>QElapsedTimer.MonotonicClock</tt></td>
<td class="topAlign"><tt>1</tt></td>
<td class="topAlign">The system's monotonic clock, usually found in
Unix systems. This clock is monotonic and does not overflow.</td>
</tr>
<tr>
<td class="topAlign"><tt>QElapsedTimer.TickCounter</tt></td>
<td class="topAlign"><tt>2</tt></td>
<td class="topAlign">The system's tick counter, used on Windows and
Symbian systems. This clock may overflow.</td>
</tr>
<tr>
<td class="topAlign"><tt>QElapsedTimer.MachAbsoluteTime</tt></td>
<td class="topAlign"><tt>3</tt></td>
<td class="topAlign">The Mach kernel's absolute time (Mac OS X).
This clock is monotonic and does not overflow.</td>
</tr>
<tr>
<td class="topAlign">
<tt>QElapsedTimer.PerformanceCounter</tt></td>
<td class="topAlign"><tt>4</tt></td>
<td class="topAlign">The high-resolution performance counter
provided by Windows. This clock is monotonic and does not
overflow.</td>
</tr>
</table>
<a id="systemtime" name="systemtime" />
<h5>SystemTime</h5>
<p>The system time clock is purely the real time, expressed in
milliseconds since Jan 1, 1970 at 0:00 UTC. It's equivalent to the
value returned by the C and POSIX <tt>time</tt> function, with the
milliseconds added. This clock type is currently only used on Unix
systems that do not support monotonic clocks (see below).</p>
<p>This is the only non-monotonic clock that <a href="qelapsedtimer.html">QElapsedTimer</a> may use.</p>
<a id="monotonicclock" name="monotonicclock" />
<h5>MonotonicClock</h5>
<p>This is the system's monotonic clock, expressed in milliseconds
since an arbitrary point in the past. This clock type is used on
Unix systems which support POSIX monotonic clocks
(<tt>_POSIX_MONOTONIC_CLOCK</tt>).</p>
<p>This clock does not overflow.</p>
<a id="tickcounter" name="tickcounter" />
<h5>TickCounter</h5>
<p>The tick counter clock type is based on the system's or the
processor's tick counter, multiplied by the duration of a tick.
This clock type is used on Windows and Symbian platforms. If the
high-precision performance counter is available on Windows, the
<tt>PerformanceCounter</tt> clock type is used instead.</p>
<p>The TickCounter clock type is the only clock type that may
overflow. Windows Vista and Windows Server 2008 support the
extended 64-bit tick counter, which allows avoiding the
overflow.</p>
<p>On Windows systems, the clock overflows after 2^32 milliseconds,
which corresponds to roughly 49.7 days. This means two processes's
reckoning of the time since the reference may be different by
multiples of 2^32 milliseconds. When comparing such values, it's
recommended that the high 32 bits of the millisecond count be
masked off.</p>
<p>On Symbian systems, the overflow happens after 2^32 ticks, the
duration of which can be obtained from the platform HAL using the
constant HAL.ENanoTickPeriod. When comparing values between
processes, it's necessary to divide the value by the tick duration
and mask off the high 32 bits.</p>
<a id="machabsolutetime" name="machabsolutetime" />
<h5>MachAbsoluteTime</h5>
<p>This clock type is based on the absolute time presented by Mach
kernels, such as that found on Mac OS X. This clock type is
presented separately from MonotonicClock since Mac OS X is also a
Unix system and may support a POSIX monotonic clock with values
differing from the Mach absolute time.</p>
<p>This clock is monotonic and does not overflow.</p>
<a id="performancecounter" name="performancecounter" />
<h5>PerformanceCounter</h5>
<p>This clock uses the Windows functions
<tt>QueryPerformanceCounter</tt> and
<tt>QueryPerformanceFrequency</tt> to access the system's
high-precision performance counter. Since this counter may not be
available on all systems, <a href="qelapsedtimer.html">QElapsedTimer</a> will fall back to the
<tt>TickCounter</tt> clock automatically, if this clock cannot be
used.</p>
<p>This clock is monotonic and does not overflow.</p>
<p><b>See also</b> <a href="qelapsedtimer.html#clockType">clockType</a>() and <a href="qelapsedtimer.html#isMonotonic">isMonotonic</a>().</p>
<hr /><h2>Method Documentation</h2><h3 class="fn"><a name="QElapsedTimer" />QElapsedTimer.__init__ (<i>self</i>)</h3><h3 class="fn"><a name="QElapsedTimer-2" />QElapsedTimer.__init__ (<i>self</i>, <a href="qelapsedtimer.html">QElapsedTimer</a>)</h3><h3 class="fn"><a name="clockType" /><a href="qelapsedtimer.html#ClockType-enum">ClockType</a> QElapsedTimer.clockType ()</h3><p>Returns the clock type that this <a href="qelapsedtimer.html">QElapsedTimer</a> implementation uses.</p>
<p><b>See also</b> <a href="qelapsedtimer.html#isMonotonic">isMonotonic</a>().</p>
<h3 class="fn"><a name="elapsed" />int QElapsedTimer.elapsed (<i>self</i>)</h3><p>Returns the number of milliseconds since this <a href="qelapsedtimer.html">QElapsedTimer</a> was last started. Calling
this function in a <a href="qelapsedtimer.html">QElapsedTimer</a>
that was invalidated will result in undefined results.</p>
<p><b>See also</b> <a href="qelapsedtimer.html#start">start</a>(),
<a href="qelapsedtimer.html#restart">restart</a>(), <a href="qelapsedtimer.html#hasExpired">hasExpired</a>(), and <a href="qelapsedtimer.html#invalidate">invalidate</a>().</p>
<h3 class="fn"><a name="hasExpired" />bool QElapsedTimer.hasExpired (<i>self</i>, int <i>timeout</i>)</h3><p>Returns true if this <a href="qelapsedtimer.html">QElapsedTimer</a> has already expired by
<i>timeout</i> milliseconds (that is, more than <i>timeout</i>
milliseconds have elapsed). The value of <i>timeout</i> can be -1
to indicate that this timer does not expire, in which case this
function will always return false.</p>
<p><b>See also</b> <a href="qelapsedtimer.html#elapsed">elapsed</a>().</p>
<h3 class="fn"><a name="invalidate" />QElapsedTimer.invalidate (<i>self</i>)</h3><p>Marks this <a href="qelapsedtimer.html">QElapsedTimer</a> object
as invalid.</p>
<p>An invalid object can be checked with <a href="qelapsedtimer.html#isValid">isValid</a>(). Calculations of timer
elapsed since invalid data are undefined and will likely produce
bizarre results.</p>
<p><b>See also</b> <a href="qelapsedtimer.html#isValid">isValid</a>(), <a href="qelapsedtimer.html#start">start</a>(), and <a href="qelapsedtimer.html#restart">restart</a>().</p>
<h3 class="fn"><a name="isMonotonic" />bool QElapsedTimer.isMonotonic ()</h3><p>Returns true if this is a monotonic clock, false otherwise. See
the information on the different clock types to understand which
ones are monotonic.</p>
<p><b>See also</b> <a href="qelapsedtimer.html#clockType">clockType</a>() and <a href="qelapsedtimer.html#ClockType-enum">QElapsedTimer.ClockType</a>.</p>
<h3 class="fn"><a name="isValid" />bool QElapsedTimer.isValid (<i>self</i>)</h3><p>Returns false if this object was invalidated by a call to
<a href="qelapsedtimer.html#invalidate">invalidate</a>() and has
not been restarted since.</p>
<p><b>See also</b> <a href="qelapsedtimer.html#invalidate">invalidate</a>(), <a href="qelapsedtimer.html#start">start</a>(), and <a href="qelapsedtimer.html#restart">restart</a>().</p>
<h3 class="fn"><a name="msecsSinceReference" />int QElapsedTimer.msecsSinceReference (<i>self</i>)</h3><p>Returns the number of milliseconds between last time this
<a href="qelapsedtimer.html">QElapsedTimer</a> object was started
and its reference clock's start.</p>
<p>This number is usually arbitrary for all clocks except the
<a href="qelapsedtimer.html#ClockType-enum">QElapsedTimer.SystemTime</a>
clock. For that clock type, this number is the number of
milliseconds since January 1st, 1970 at 0:00 UTC (that is, it is
the Unix time expressed in milliseconds).</p>
<p><b>See also</b> <a href="qelapsedtimer.html#clockType">clockType</a>() and <a href="qelapsedtimer.html#elapsed">elapsed</a>().</p>
<h3 class="fn"><a name="msecsTo" />int QElapsedTimer.msecsTo (<i>self</i>, <a href="qelapsedtimer.html">QElapsedTimer</a> <i>other</i>)</h3><p>Returns the number of milliseconds between this <a href="qelapsedtimer.html">QElapsedTimer</a> and <i>other</i>. If
<i>other</i> was started before this object, the returned value
will be positive. If it was started later, the returned value will
be negative.</p>
<p>The return value is undefined if this object or <i>other</i>
were invalidated.</p>
<p><b>See also</b> <a href="qelapsedtimer.html#secsTo">secsTo</a>()
and <a href="qelapsedtimer.html#elapsed">elapsed</a>().</p>
<h3 class="fn"><a name="nsecsElapsed" />int QElapsedTimer.nsecsElapsed (<i>self</i>)</h3><p>Returns the number of nanoseconds since this <a href="qelapsedtimer.html">QElapsedTimer</a> was last started. Calling
this function in a <a href="qelapsedtimer.html">QElapsedTimer</a>
that was invalidated will result in undefined results.</p>
<p>On platforms that do not provide nanosecond resolution, the
value returned will be the best estimate available.</p>
<p>This function was introduced in Qt 4.8.</p>
<p><b>See also</b> <a href="qelapsedtimer.html#start">start</a>(),
<a href="qelapsedtimer.html#restart">restart</a>(), <a href="qelapsedtimer.html#hasExpired">hasExpired</a>(), and <a href="qelapsedtimer.html#invalidate">invalidate</a>().</p>
<h3 class="fn"><a name="restart" />int QElapsedTimer.restart (<i>self</i>)</h3><p>Restarts the timer and returns the time elapsed since the
previous start. This function is equivalent to obtaining the
elapsed time with <a href="qelapsedtimer.html#elapsed">elapsed</a>() and then starting the
timer again with <a href="qelapsedtimer.html#start">start</a>(),
but it does so in one single operation, avoiding the need to obtain
the clock value twice.</p>
<p>The following example illustrates how to use this function to
calibrate a parameter to a slow operation (for example, an
iteration count) so that this operation takes at least 250
milliseconds:</p>
<pre class="cpp">
<span class="type"><a href="qelapsedtimer.html">QElapsedTimer</a></span> timer;
<span class="type">int</span> count <span class="operator">=</span> <span class="number">1</span>;
timer<span class="operator">.</span>start();
<span class="keyword">do</span> {
count <span class="operator">*</span><span class="operator">=</span> <span class="number">2</span>;
slowOperation2(count);
} <span class="keyword">while</span> (timer<span class="operator">.</span>restart() <span class="operator"><</span> <span class="number">250</span>);
<span class="keyword">return</span> count;
</pre>
<p><b>See also</b> <a href="qelapsedtimer.html#start">start</a>(),
<a href="qelapsedtimer.html#invalidate">invalidate</a>(), and
<a href="qelapsedtimer.html#elapsed">elapsed</a>().</p>
<h3 class="fn"><a name="secsTo" />int QElapsedTimer.secsTo (<i>self</i>, <a href="qelapsedtimer.html">QElapsedTimer</a> <i>other</i>)</h3><p>Returns the number of seconds between this <a href="qelapsedtimer.html">QElapsedTimer</a> and <i>other</i>. If
<i>other</i> was started before this object, the returned value
will be positive. If it was started later, the returned value will
be negative.</p>
<p>The return value is undefined if this object or <i>other</i>
were invalidated.</p>
<p><b>See also</b> <a href="qelapsedtimer.html#msecsTo">msecsTo</a>() and <a href="qelapsedtimer.html#elapsed">elapsed</a>().</p>
<h3 class="fn"><a name="start" />QElapsedTimer.start (<i>self</i>)</h3><p>Starts this timer. Once started, a timer value can be checked
with <a href="qelapsedtimer.html#elapsed">elapsed</a>() or <a href="qelapsedtimer.html#msecsSinceReference">msecsSinceReference</a>().</p>
<p>Normally, a timer is started just before a lengthy operation,
such as:</p>
<pre class="cpp">
<span class="type"><a href="qelapsedtimer.html">QElapsedTimer</a></span> timer;
timer<span class="operator">.</span>start();
slowOperation1();
<a href="qtcore.html#qDebug">qDebug</a>() <span class="operator"><</span><span class="operator"><</span> <span class="string">"The slow operation took"</span> <span class="operator"><</span><span class="operator"><</span> timer<span class="operator">.</span>elapsed() <span class="operator"><</span><span class="operator"><</span> <span class="string">"milliseconds"</span>;
</pre>
<p>Also, starting a timer makes it valid again.</p>
<p><b>See also</b> <a href="qelapsedtimer.html#restart">restart</a>(), <a href="qelapsedtimer.html#invalidate">invalidate</a>(), and <a href="qelapsedtimer.html#elapsed">elapsed</a>().</p>
<h3 class="fn"><a name="__eq__" />bool QElapsedTimer.__eq__ (<i>self</i>, <a href="qelapsedtimer.html">QElapsedTimer</a> <i>other</i>)</h3><h3 class="fn"><a name="__ge__" />bool QElapsedTimer.__ge__ (<i>self</i>, <a href="qelapsedtimer.html">QElapsedTimer</a> <i>v2</i>)</h3><h3 class="fn"><a name="__lt__" />bool QElapsedTimer.__lt__ (<i>self</i>, <a href="qelapsedtimer.html">QElapsedTimer</a> <i>v2</i>)</h3><h3 class="fn"><a name="__ne__" />bool QElapsedTimer.__ne__ (<i>self</i>, <a href="qelapsedtimer.html">QElapsedTimer</a> <i>other</i>)</h3><address><hr /><div align="center"><table border="0" cellspacing="0" width="100%"><tr class="address"><td align="left" width="25%">PyQt 4.10.3 for X11</td><td align="center" width="50%">Copyright © <a href="http://www.riverbankcomputing.com">Riverbank Computing Ltd</a> and <a href="http://www.qtsoftware.com">Nokia</a> 2012</td><td align="right" width="25%">Qt 4.8.5</td></tr></table></div></address></body></html>
