Doc: document QElapsedTimer

Task-Number: QT-2965

4 files changed, 382 insertions, 0 deletions

diff --git a/doc/src/snippets/qelapsedtimer/main.cpp b/doc/src/snippets/qelapsedtimer/main.cpp
new file mode 100644
index 0000000..9d0421f
--- /dev/null
+++ b/doc/src/snippets/qelapsedtimer/main.cpp
@@ -0,0 +1,112 @@
+/****************************************************************************
+**
+** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).
+** All rights reserved.
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the QtNetwork module of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL$
+** No Commercial Usage
+** This file contains pre-release code and may not be distributed.
+** You may use this file in accordance with the terms and conditions
+** contained in the Technology Preview License Agreement accompanying
+** this package.
+**
+** GNU Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 2.1 as published by the Free Software
+** Foundation and appearing in the file LICENSE.LGPL included in the
+** packaging of this file.  Please review the following information to
+** ensure the GNU Lesser General Public License version 2.1 requirements
+** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
+**
+** In addition, as a special exception, Nokia gives you certain additional
+** rights.  These rights are described in the Nokia Qt LGPL Exception
+** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
+**
+** If you have questions regarding the use of this file, please contact
+** Nokia at qt-info@nokia.com.
+**
+**
+**
+**
+**
+**
+**
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+#include <QtCore>
+
+void slowOperation1()
+{
+    static char buf[256];
+    for (int i = 0; i < (1<<20); ++i)
+        buf[i % sizeof buf] = i;
+}
+
+void slowOperation2(int) { slowOperation1(); }
+
+void startExample()
+{
+//![0]
+    QElapsedTimer timer;
+    timer.start();
+
+    slowOperation1();
+
+    qDebug() << "The slow operation took" << timer.elapsed() << "milliseconds";
+//![0]
+}
+
+//![1]
+void executeSlowOperations(int timeout)
+{
+    QElapsedTimer timer;
+    timer.start();
+    slowOperation1();
+
+    int remainingTime = timeout - timer.elapsed();
+    if (remainingTime > 0)
+        slowOperation2(remainingTime);
+}
+//![1]
+
+//![2]
+void executeOperationsForTime(int ms)
+{
+    QElapsedTimer timer;
+    timer.start();
+
+    while (!timer.hasExpired(ms))
+        slowOperation1();
+}
+//![2]
+
+int restartExample()
+{
+//![3]
+    QElapsedTimer timer;
+
+    int count = 1;
+    timer.start();
+    do {
+        count *= 2;
+        slowOperation2(count);
+    } while (timer.restart() < 250);
+
+    return count;
+//![3]
+}
+
+int main(int argc, char **argv)
+{
+    QCoreApplication app(argc, argv);
+
+    startExample();
+    restartExample();
+    executeSlowOperations(5);
+    executeOperationsForTime(5);
+}
diff --git a/doc/src/snippets/qelapsedtimer/qelapsedtimer.pro b/doc/src/snippets/qelapsedtimer/qelapsedtimer.pro
new file mode 100644
index 0000000..b0a8f66
--- /dev/null
+++ b/doc/src/snippets/qelapsedtimer/qelapsedtimer.pro
@@ -0,0 +1,2 @@
+SOURCES = main.cpp
+QT -= gui
diff --git a/src/corelib/tools/qelapsedtimer.cpp b/src/corelib/tools/qelapsedtimer.cpp
index 220b108..28dfc23 100644
--- a/src/corelib/tools/qelapsedtimer.cpp
+++ b/src/corelib/tools/qelapsedtimer.cpp
@@ -43,18 +43,204 @@
 
 QT_BEGIN_NAMESPACE
 
+/*!
+    \class QElapsedTimer
+    \brief The QElapsedTimer class provides a fast way to calculate elapsed times.
+    \since 4.7
+
+    \reentrant
+    \ingroup tools
+    \inmodule QtCore
+
+    The QElapsedTimer class is usually used to quickly calculate how much
+    time has elapsed between two events. Its API is similar to that of QTime,
+    so code that was using that can be ported quickly to the new class.
+
+    However, unlike QTime, QElapsedTimer tries to use monotonic clocks if
+    possible. This means it's not possible to convert QElapsedTimer objects
+    to a human-readable time.
+
+    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:
+
+    \snippet doc/src/snippets/qelapsedtimer/main.cpp 0
+
+    In this example, the timer is started by a call to start() and the
+    elapsed timer is calculated by the elapsed() function.
+
+    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}-type functions in QIODevice and its
+    subclasses are good examples of such need. In that case, the code could
+    be as follows:
+
+    \snippet doc/src/snippets/qelapsedtimer/main.cpp 1
+
+    Another use-case is to execute a certain operation for a specific
+    timeslice. For this, QElapsedTimer provides the hasExpired() convenience
+    function, which can be used to determine if a certain number of
+    milliseconds has already elapsed:
+
+    \snippet doc/src/snippets/qelapsedtimer/main.cpp 1
+
+    \section1 Reference clocks
+
+    QElapsedTimer will use the platform's monotonic reference clock in all
+    platforms that support it (see QElapsedTimer::isMonotonic()). This has
+    the added benefit that QElapsedTimer is immune to time adjustments, such
+    as the user correcting the time. Also unlike QTime, QElapsedTimer is
+    immune to changes in the timezone settings, such as daylight savings
+    periods.
+
+    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
+    (QElapsedTimer::msecsSinceReference()) 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.
+
+    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
+    QElapsedTimer::clockType()).
+
+    \section2 32-bit overflows
+
+    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.
+
+    The information on which clocks types may overflow and how to remedy that
+    issue is documented along with the clock types.
+
+    \sa QTime, QTimer
+*/
+
+/*!
+    \enum QElapsedTimer::ClockType
+
+    This enum contains the different clock types that QElapsedTimer may use.
+
+    QElapsedTimer 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 QElapsedTimer can be used with other non-Qt
+    implementations, to guarantee that the same reference clock is being
+    used.
+
+    \value SystemTime       The human-readable system time. This clock is not monotonic.
+    \value MonotonicClock   The system's monotonic clock, usually found in Unix systems. This clock is not monotonic and does not overflow.
+    \value TickCounter      The system's tick counter, used on Windows and Symbian systems. This clock may overflow.
+    \value MachAbsoluteTime The Mach kernel's absolute time (Mac OS X). This clock is monotonic and does not overflow.
+
+    \section2 SystemTime
+
+    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} function, with the milliseconds added. This
+    clock type is currently only used on Unix systems that do not support
+    monotonic clocks (see below).
+
+    This is the only non-monotonic clock that QElapsedTimer may use.
+
+    \section2 MonotonicClock
+
+    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}).
+
+    This clock does not overflow.
+
+    \section2 TickCounter
+
+    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.
+
+    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.
+
+    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.
+
+    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.
+
+    \section2 MachAbsoluteTime
+
+    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.
+
+    This clock is monotonic and does not overflow.
+
+    \sa clockType(), isMonotonic()
+*/
+
+/*!
+    \fn bool QElapsedTimer::operator ==(const QElapsedTimer &other) const
+
+    Returns true if this object and \a other contain the same time.
+*/
+
+/*!
+    \fn bool QElapsedTimer::operator !=(const QElapsedTimer &other) const
+
+    Returns true if this object and \a other contain different times.
+*/
+
 static const qint64 invalidData = Q_INT64_C(0x8000000000000000);
 
+/*!
+    Marks this QElapsedTimer object as invalid.
+
+    An invalid object can be checked with isValid(). Calculations of timer
+    elapsed since invalid data are undefined and will likely produce bizarre
+    results.
+
+    \sa isValid(), start(), restart()
+*/
 void QElapsedTimer::invalidate()
 {
      t1 = t2 = invalidData;
 }
 
+/*!
+    Returns true if this object was invalidated by a call to invalidate() and
+    has not been restarted since.
+
+    \sa invalidate(), start(), restart()
+*/
 bool QElapsedTimer::isValid() const
 {
     return t1 != invalidData && t2 != invalidData;
 }
 
+/*!
+    Returns true if this QElapsedTimer has already expired by \a timeout
+    milliseconds (that is, more than \a timeout milliseconds have elapsed).
+    The value of \a timeout can be -1 to indicate that this timer does not
+    expire, in which case this function will always return false.
+
+    \sa elapsed()
+*/
 bool QElapsedTimer::hasExpired(qint64 timeout) const
 {
     // if timeout is -1, quint64(timeout) is LLINT_MAX, so this will be
diff --git a/src/corelib/tools/qelapsedtimer_generic.cpp b/src/corelib/tools/qelapsedtimer_generic.cpp
index 3feecd6..9b589c1 100644
--- a/src/corelib/tools/qelapsedtimer_generic.cpp
+++ b/src/corelib/tools/qelapsedtimer_generic.cpp
@@ -44,21 +44,57 @@
 
 QT_BEGIN_NAMESPACE
 
+/*!
+    Returns the clock type that this QElapsedTimer implementation uses.
+
+    \sa isMonotonic()
+*/
 QElapsedTimer::ClockType QElapsedTimer::clockType()
 {
     return SystemTime;
 }
 
+/*!
+    Returns true if this is a monotonic clock, false otherwise. See the
+    information on the different clock types to understand which ones are
+    monotonic.
+
+    \sa clockType(), QElapsedTimer::ClockType
+*/
 bool QElapsedTimer::isMonotonic()
 {
     return false;
 }
 
+/*!
+    Starts this timer. Once started, a timer value can be checked with elapsed() or msecsSinceReference().
+
+    Normally, a timer is started just before a lengthy operation, such as:
+    \snippet doc/src/snippets/qelapsedtimer/main.cpp 0
+
+    Also, starting a timer makes it valid again.
+
+    \sa restart(), invalidate(), elapsed()
+*/
 void QElapsedTimer::start()
 {
     restart();
 }
 
+/*!
+    Restarts the timer and returns the time elapsed since the previous start.
+    This function is equivalent to obtaining the elapsed time with elapsed()
+    and then starting the timer again with restart(), but it does so in one
+    single operation, avoiding the need to obtain the clock value twice.
+
+    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:
+
+    \snippet doc/src/snippets/qelapsedtimer/main.cpp 3
+
+    \sa start(), invalidate(), elapsed()
+*/
 qint64 QElapsedTimer::restart()
 {
     qint64 old = t1;
@@ -67,27 +103,73 @@ qint64 QElapsedTimer::restart()
     return t1 - old;
 }
 
+/*!
+    Returns the number of milliseconds since this QElapsedTimer was last
+    started. Calling this function in a QElapsedTimer that was invalidated
+    will result in undefined results.
+
+    \sa start(), restart(), hasExpired(), invalidate()
+*/
 qint64 QElapsedTimer::elapsed() const
 {
     return QDateTime::currentMsecsSinceEpoch() - t1;
 }
 
+/*!
+    Returns the number of milliseconds between last time this QElapsedTimer
+    object was started and its reference clock's start.
+
+    This number is usually arbitrary for all clocks except the
+    QElapsedTimer::SystemTime 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).
+
+    \sa clockType(), elapsed()
+*/
 qint64 QElapsedTimer::msecsSinceReference() const
 {
     return t1;
 }
 
+/*!
+    Returns the number of milliseconds between this QElapsedTimer and \a
+    other. If \a other was started before this object, the returned value
+    will be positive. If it was started later, the returned value will be
+    negative.
+
+    The return value is undefined if this object or \a other were invalidated.
+
+    \sa secsTo(), elapsed()
+*/
 qint64 QElapsedTimer::msecsTo(const QElapsedTimer &other) const
 {
     qint64 diff = other.t1 - t1;
     return diff;
 }
 
+/*!
+    Returns the number of seconds between this QElapsedTimer and \a other. If
+    \a other was started before this object, the returned value will be
+    positive. If it was started later, the returned value will be negative.
+
+    The return value is undefined if this object or \a other were invalidated.
+
+    \sa msecsTo(), elapsed()
+*/
 qint64 QElapsedTimer::secsTo(const QElapsedTimer &other) const
 {
     return msecsTo(other) / 1000;
 }
 
+/*!
+    \relates QElapsedTimer
+
+    Returns true if \a v1 was started before \a v2, false otherwise.
+
+    The returned value is undefined if one of the two parameters is invalid
+    and the other isn't. However, two invalid timers are equal and thus this
+    function will return false.
+*/
 bool operator<(const QElapsedTimer &v1, const QElapsedTimer &v2)
 {
     return v1.t1 < v2.t1;