QChronoTimer Class

Detailed Description

The QChronoTimer class provides a high-level programming interface for timers. To use it, create a QChronoTimer, either passing the interval to the constructor, or setting it after construction using setInterval(), connect its timeout() signal to the appropriate slots, and call start(). From then on, it will emit the timeout() signal at constant intervals. For example:

        QChronoTimer *timer = new QChronoTimer(1s, this);
        connect(timer, &QChronoTimer::timeout, this, &MyWidget::processOneThing);
        timer->start();
        QChronoTimer *timer = new QChronoTimer(this);
        connect(timer, &QChronoTimer::timeout, this, &MyWidget::processOneThing);
        timer->setInterval(1s);
        timer->start();

You can set a timer to time out only once by calling setSingleShot(true).

In multithreaded applications, you can use QChronoTimer in any thread that has an event loop. To start an event loop from a non-GUI thread, use QThread::exec(). Qt uses the timer's thread affinity to determine which thread will emit the timeout() signal. Because of this, you must start and stop the timer in its thread; it is not possible to start a timer from another thread.

As a special case, a QChronoTimer with a timeout of 0ns will time out as soon as possible, though the ordering between zero timers and other sources of events is unspecified. Zero timers can be used to do some work while still providing a responsive user interface:

        // The default interval is 0ns
        QChronoTimer *timer = new QChronoTimer(this);
        connect(timer, &QChronoTimer::timeout, this, &MyWidget::processOneThing);
        timer->start();

From then on, processOneThing() will be called repeatedly. It should be written in such a way that it always returns quickly (for example, after processing one data item) so that Qt can deliver events to the user interface and stop the timer as soon as it has done all its work. This is the traditional way of implementing heavy work in GUI applications, but as multithreading is becoming available on more platforms, a modern alternative is doing the heavy work in a thread other than the GUI (main) thread. Qt has the QThread class, which can be used to achieve that.

Accuracy and Timer Resolution

The accuracy of timers depends on the underlying operating system and hardware. Most platforms support requesting nano-second precision for timers (for example, libc's nanosleep), though the accuracy of the timer will not equal this resolution in many real-world situations.

You can set the timer type to tell QChronoTimer which precision to request from the system.

For Qt::PreciseTimer, QChronoTimer will try to keep the precision at 1ns. Precise timers will never time out earlier than expected.

For Qt::CoarseTimer and Qt::VeryCoarseTimer types, QChronoTimer may wake up earlier than expected, within the margins for those types:

• 5% of the interval for Qt::CoarseTimer
• 500ms for Qt::VeryCoarseTimer

All timer types may time out later than expected if the system is busy or unable to provide the requested accuracy. In such a case of timeout overrun, Qt will emit timeout() only once, even if multiple timeouts have expired, and then will resume the original interval.

Alternatives to QChronoTimer

QChronoTimer provides nanosecond resolution and a ±292 years range (less chances of integer overflow if the interval is longer than std::numeric_limits<int>::max()). If you only need millisecond resolution and ±24 days range, you can continue to use the classical QTimer class

Another alternative is reimplementing the QObject::timerEvent() method in your class (which must be a sub-class of QObject), and using one of the following approaches:

• Using QBasicTimer, a lightweight value-class wrapping a timer ID. You can start the timer with QBasicTimer::start() and stop it with QBasicTimer::stop(). You can handle the event in your reimplemneted timerEvent().
• A more low-level method is manipulating the timer IDs directly. To start the timer call QObject::startTimer(), storing the returned ID. To stop the timer call QObject::killTimer(). You can handle the event in your reimplemented timerEvent(). This approach is typically more cumbersome than using QBasicTimer.

A disadvantage of using timerEvent() is that some high-level features, such as single-shot timers and signals, aren't supported.

Some operating systems limit the number of timers that may be used; Qt does its best to work around these limitations.