src/corelib/tools/qelapsedtimer.cpp

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
   4 ** Contact: http://www.qt-project.org/
   5 **
   6 ** This file is part of the QtCore module of the Qt Toolkit.
   7 **
   8 ** $QT_BEGIN_LICENSE:LGPL$
   9 ** GNU Lesser General Public License Usage
  10 ** This file may be used under the terms of the GNU Lesser General Public
  11 ** License version 2.1 as published by the Free Software Foundation and
  12 ** appearing in the file LICENSE.LGPL included in the packaging of this
  13 ** file. Please review the following information to ensure the GNU Lesser
  14 ** General Public License version 2.1 requirements will be met:
  15 ** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
  16 **
  17 ** In addition, as a special exception, Nokia gives you certain additional
  18 ** rights. These rights are described in the Nokia Qt LGPL Exception
  19 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
  20 **
  21 ** GNU General Public License Usage
  22 ** Alternatively, this file may be used under the terms of the GNU General
  23 ** Public License version 3.0 as published by the Free Software Foundation
  24 ** and appearing in the file LICENSE.GPL included in the packaging of this
  25 ** file. Please review the following information to ensure the GNU General
  26 ** Public License version 3.0 requirements will be met:
  27 ** http://www.gnu.org/copyleft/gpl.html.
  28 **
  29 ** Other Usage
  30 ** Alternatively, this file may be used in accordance with the terms and
  31 ** conditions contained in a signed written agreement between you and Nokia.
  32 **
  33 **
  34 **
  35 **
  36 **
  37 **
  38 ** $QT_END_LICENSE$
  39 **
  40 ****************************************************************************/
  41
  42 #include "qelapsedtimer.h"
  43
  44 QT_BEGIN_NAMESPACE
  45
  46 /*!
  47     \class QElapsedTimer
  48     \brief The QElapsedTimer class provides a fast way to calculate elapsed times.
  49     \since 4.7
  50
  51     \reentrant
  52     \ingroup tools
  53     \inmodule QtCore
  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 doc/src/snippets/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 doc/src/snippets/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 doc/src/snippets/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 savings
  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 that 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's 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()
 228 {
 229      t1 = t2 = invalidData;
 230 }
 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
 239 {
 240     return t1 != invalidData && t2 != invalidData;
 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
 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);
 256 }
 257
 258 QT_END_NAMESPACE