| Line | Source Code | Coverage |
|---|
| 1 | /**************************************************************************** | - |
| 2 | ** | - |
| 3 | ** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies). | - |
| 4 | ** Contact: http://www.qt-project.org/legal | - |
| 5 | ** | - |
| 6 | ** This file is part of the QtCore module of the Qt Toolkit. | - |
| 7 | ** | - |
| 8 | ** $QT_BEGIN_LICENSE:LGPL$ | - |
| 9 | ** Commercial License Usage | - |
| 10 | ** Licensees holding valid commercial Qt licenses may use this file in | - |
| 11 | ** accordance with the commercial license agreement provided with the | - |
| 12 | ** Software or, alternatively, in accordance with the terms contained in | - |
| 13 | ** a written agreement between you and Digia. For licensing terms and | - |
| 14 | ** conditions see http://qt.digia.com/licensing. For further information | - |
| 15 | ** use the contact form at http://qt.digia.com/contact-us. | - |
| 16 | ** | - |
| 17 | ** GNU Lesser General Public License Usage | - |
| 18 | ** Alternatively, this file may be used under the terms of the GNU Lesser | - |
| 19 | ** General Public License version 2.1 as published by the Free Software | - |
| 20 | ** Foundation and appearing in the file LICENSE.LGPL included in the | - |
| 21 | ** packaging of this file. Please review the following information to | - |
| 22 | ** ensure the GNU Lesser General Public License version 2.1 requirements | - |
| 23 | ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. | - |
| 24 | ** | - |
| 25 | ** In addition, as a special exception, Digia gives you certain additional | - |
| 26 | ** rights. These rights are described in the Digia Qt LGPL Exception | - |
| 27 | ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. | - |
| 28 | ** | - |
| 29 | ** GNU General Public License Usage | - |
| 30 | ** Alternatively, this file may be used under the terms of the GNU | - |
| 31 | ** General Public License version 3.0 as published by the Free Software | - |
| 32 | ** Foundation and appearing in the file LICENSE.GPL included in the | - |
| 33 | ** packaging of this file. Please review the following information to | - |
| 34 | ** ensure the GNU General Public License version 3.0 requirements will be | - |
| 35 | ** met: http://www.gnu.org/copyleft/gpl.html. | - |
| 36 | ** | - |
| 37 | ** | - |
| 38 | ** $QT_END_LICENSE$ | - |
| 39 | ** | - |
| 40 | ****************************************************************************/ | - |
| 41 | | - |
| 42 | #include "qelapsedtimer.h" | - |
| 43 | | - |
| 44 | QT_BEGIN_NAMESPACE | - |
| 45 | | - |
| 46 | /*! | - |
| 47 | \class QElapsedTimer | - |
| 48 | \inmodule QtCore | - |
| 49 | \brief The QElapsedTimer class provides a fast way to calculate elapsed times. | - |
| 50 | \since 4.7 | - |
| 51 | | - |
| 52 | \reentrant | - |
| 53 | \ingroup tools | - |
| 54 | | - |
| 55 | The QElapsedTimer class is usually used to quickly calculate how much | - |
| 56 | time has elapsed between two events. Its API is similar to that of QTime, | - |
| 57 | so code that was using that can be ported quickly to the new class. | - |
| 58 | | - |
| 59 | However, unlike QTime, QElapsedTimer tries to use monotonic clocks if | - |
| 60 | possible. This means it's not possible to convert QElapsedTimer objects | - |
| 61 | to a human-readable time. | - |
| 62 | | - |
| 63 | The typical use-case for the class is to determine how much time was | - |
| 64 | spent in a slow operation. The simplest example of such a case is for | - |
| 65 | debugging purposes, as in the following example: | - |
| 66 | | - |
| 67 | \snippet qelapsedtimer/main.cpp 0 | - |
| 68 | | - |
| 69 | In this example, the timer is started by a call to start() and the | - |
| 70 | elapsed timer is calculated by the elapsed() function. | - |
| 71 | | - |
| 72 | The time elapsed can also be used to recalculate the time available for | - |
| 73 | another operation, after the first one is complete. This is useful when | - |
| 74 | the execution must complete within a certain time period, but several | - |
| 75 | steps are needed. The \tt{waitFor}-type functions in QIODevice and its | - |
| 76 | subclasses are good examples of such need. In that case, the code could | - |
| 77 | be as follows: | - |
| 78 | | - |
| 79 | \snippet qelapsedtimer/main.cpp 1 | - |
| 80 | | - |
| 81 | Another use-case is to execute a certain operation for a specific | - |
| 82 | timeslice. For this, QElapsedTimer provides the hasExpired() convenience | - |
| 83 | function, which can be used to determine if a certain number of | - |
| 84 | milliseconds has already elapsed: | - |
| 85 | | - |
| 86 | \snippet qelapsedtimer/main.cpp 2 | - |
| 87 | | - |
| 88 | \section1 Reference clocks | - |
| 89 | | - |
| 90 | QElapsedTimer will use the platform's monotonic reference clock in all | - |
| 91 | platforms that support it (see QElapsedTimer::isMonotonic()). This has | - |
| 92 | the added benefit that QElapsedTimer is immune to time adjustments, such | - |
| 93 | as the user correcting the time. Also unlike QTime, QElapsedTimer is | - |
| 94 | immune to changes in the timezone settings, such as daylight saving | - |
| 95 | periods. | - |
| 96 | | - |
| 97 | On the other hand, this means QElapsedTimer values can only be compared | - |
| 98 | with other values that use the same reference. This is especially true if | - |
| 99 | the time since the reference is extracted from the QElapsedTimer object | - |
| 100 | (QElapsedTimer::msecsSinceReference()) and serialised. These values | - |
| 101 | should never be exchanged across the network or saved to disk, since | - |
| 102 | there's no telling whether the computer node receiving the data is the | - |
| 103 | same as the one originating it or if it has rebooted since. | - |
| 104 | | - |
| 105 | It is, however, possible to exchange the value with other processes | - |
| 106 | running on the same machine, provided that they also use the same | - |
| 107 | reference clock. QElapsedTimer will always use the same clock, so it's | - |
| 108 | safe to compare with the value coming from another process in the same | - |
| 109 | machine. If comparing to values produced by other APIs, you should check | - |
| 110 | that the clock used is the same as QElapsedTimer (see | - |
| 111 | QElapsedTimer::clockType()). | - |
| 112 | | - |
| 113 | \section2 32-bit overflows | - |
| 114 | | - |
| 115 | Some of the clocks used by QElapsedTimer have a limited range and may | - |
| 116 | overflow after hitting the upper limit (usually 32-bit). QElapsedTimer | - |
| 117 | deals with this overflow issue and presents a consistent timing. However, | - |
| 118 | when extracting the time since reference from QElapsedTimer, two | - |
| 119 | different processes in the same machine may have different understanding | - |
| 120 | of how much time has actually elapsed. | - |
| 121 | | - |
| 122 | The information on which clocks types may overflow and how to remedy that | - |
| 123 | issue is documented along with the clock types. | - |
| 124 | | - |
| 125 | \sa QTime, QTimer | - |
| 126 | */ | - |
| 127 | | - |
| 128 | /*! | - |
| 129 | \enum QElapsedTimer::ClockType | - |
| 130 | | - |
| 131 | This enum contains the different clock types that QElapsedTimer may use. | - |
| 132 | | - |
| 133 | QElapsedTimer will always use the same clock type in a particular | - |
| 134 | machine, so this value will not change during the lifetime of a program. | - |
| 135 | It is provided so that QElapsedTimer can be used with other non-Qt | - |
| 136 | implementations, to guarantee that the same reference clock is being | - |
| 137 | used. | - |
| 138 | | - |
| 139 | \value SystemTime The human-readable system time. This clock is not monotonic. | - |
| 140 | \value MonotonicClock The system's monotonic clock, usually found in Unix systems. This clock is monotonic and does not overflow. | - |
| 141 | \value TickCounter The system's tick counter, used on Windows systems. This clock may overflow. | - |
| 142 | \value MachAbsoluteTime The Mach kernel's absolute time (Mac OS X). This clock is monotonic and does not overflow. | - |
| 143 | \value PerformanceCounter The high-resolution performance counter provided by Windows. This clock is monotonic and does not overflow. | - |
| 144 | | - |
| 145 | \section2 SystemTime | - |
| 146 | | - |
| 147 | The system time clock is purely the real time, expressed in milliseconds | - |
| 148 | since Jan 1, 1970 at 0:00 UTC. It's equivalent to the value returned by | - |
| 149 | the C and POSIX \tt{time} function, with the milliseconds added. This | - |
| 150 | clock type is currently only used on Unix systems that do not support | - |
| 151 | monotonic clocks (see below). | - |
| 152 | | - |
| 153 | This is the only non-monotonic clock that QElapsedTimer may use. | - |
| 154 | | - |
| 155 | \section2 MonotonicClock | - |
| 156 | | - |
| 157 | This is the system's monotonic clock, expressed in milliseconds since an | - |
| 158 | arbitrary point in the past. This clock type is used on Unix systems | - |
| 159 | which support POSIX monotonic clocks (\tt{_POSIX_MONOTONIC_CLOCK}). | - |
| 160 | | - |
| 161 | This clock does not overflow. | - |
| 162 | | - |
| 163 | \section2 TickCounter | - |
| 164 | | - |
| 165 | The tick counter clock type is based on the system's or the processor's | - |
| 166 | tick counter, multiplied by the duration of a tick. This clock type is | - |
| 167 | used on Windows platforms. If the high-precision performance | - |
| 168 | counter is available on Windows, the \tt{PerformanceCounter} clock type | - |
| 169 | is used instead. | - |
| 170 | | - |
| 171 | The TickCounter clock type is the only clock type that may overflow. | - |
| 172 | Windows Vista and Windows Server 2008 support the extended 64-bit tick | - |
| 173 | counter, which allows avoiding the overflow. | - |
| 174 | | - |
| 175 | On Windows systems, the clock overflows after 2^32 milliseconds, which | - |
| 176 | corresponds to roughly 49.7 days. This means two processes' reckoning of | - |
| 177 | the time since the reference may be different by multiples of 2^32 | - |
| 178 | milliseconds. When comparing such values, it's recommended that the high | - |
| 179 | 32 bits of the millisecond count be masked off. | - |
| 180 | | - |
| 181 | \section2 MachAbsoluteTime | - |
| 182 | | - |
| 183 | This clock type is based on the absolute time presented by Mach kernels, | - |
| 184 | such as that found on Mac OS X. This clock type is presented separately | - |
| 185 | from MonotonicClock since Mac OS X is also a Unix system and may support | - |
| 186 | a POSIX monotonic clock with values differing from the Mach absolute | - |
| 187 | time. | - |
| 188 | | - |
| 189 | This clock is monotonic and does not overflow. | - |
| 190 | | - |
| 191 | \section2 PerformanceCounter | - |
| 192 | | - |
| 193 | This clock uses the Windows functions \tt{QueryPerformanceCounter} and | - |
| 194 | \tt{QueryPerformanceFrequency} to access the system's high-precision | - |
| 195 | performance counter. Since this counter may not be available on all | - |
| 196 | systems, QElapsedTimer will fall back to the \tt{TickCounter} clock | - |
| 197 | automatically, if this clock cannot be used. | - |
| 198 | | - |
| 199 | This clock is monotonic and does not overflow. | - |
| 200 | | - |
| 201 | \sa clockType(), isMonotonic() | - |
| 202 | */ | - |
| 203 | | - |
| 204 | /*! | - |
| 205 | \fn bool QElapsedTimer::operator ==(const QElapsedTimer &other) const | - |
| 206 | | - |
| 207 | Returns true if this object and \a other contain the same time. | - |
| 208 | */ | - |
| 209 | | - |
| 210 | /*! | - |
| 211 | \fn bool QElapsedTimer::operator !=(const QElapsedTimer &other) const | - |
| 212 | | - |
| 213 | Returns true if this object and \a other contain different times. | - |
| 214 | */ | - |
| 215 | | - |
| 216 | static const qint64 invalidData = Q_INT64_C(0x8000000000000000); | - |
| 217 | | - |
| 218 | /*! | - |
| 219 | Marks this QElapsedTimer object as invalid. | - |
| 220 | | - |
| 221 | An invalid object can be checked with isValid(). Calculations of timer | - |
| 222 | elapsed since invalid data are undefined and will likely produce bizarre | - |
| 223 | results. | - |
| 224 | | - |
| 225 | \sa isValid(), start(), restart() | - |
| 226 | */ | - |
| 227 | void QElapsedTimer::invalidate() Q_DECL_NOTHROW | - |
| 228 | { | - |
| 229 | t1 = t2 = invalidData; executed (the execution status of this line is deduced): t1 = t2 = invalidData; | - |
| 230 | } executed: }Execution Count:590148 | 590148 |
| 231 | | - |
| 232 | /*! | - |
| 233 | Returns false if this object was invalidated by a call to invalidate() and | - |
| 234 | has not been restarted since. | - |
| 235 | | - |
| 236 | \sa invalidate(), start(), restart() | - |
| 237 | */ | - |
| 238 | bool QElapsedTimer::isValid() const Q_DECL_NOTHROW | - |
| 239 | { | - |
| 240 | return t1 != invalidData && t2 != invalidData; executed: return t1 != invalidData && t2 != invalidData;Execution Count:381183 | 381183 |
| 241 | } | - |
| 242 | | - |
| 243 | /*! | - |
| 244 | Returns true if this QElapsedTimer has already expired by \a timeout | - |
| 245 | milliseconds (that is, more than \a timeout milliseconds have elapsed). | - |
| 246 | The value of \a timeout can be -1 to indicate that this timer does not | - |
| 247 | expire, in which case this function will always return false. | - |
| 248 | | - |
| 249 | \sa elapsed() | - |
| 250 | */ | - |
| 251 | bool QElapsedTimer::hasExpired(qint64 timeout) const Q_DECL_NOTHROW | - |
| 252 | { | - |
| 253 | // if timeout is -1, quint64(timeout) is LLINT_MAX, so this will be | - |
| 254 | // considered as never expired | - |
| 255 | return quint64(elapsed()) > quint64(timeout); executed: return quint64(elapsed()) > quint64(timeout);Execution Count:77961 | 77961 |
| 256 | } | - |
| 257 | | - |
| 258 | QT_END_NAMESPACE | - |
| 259 | | - |
| | |