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).

QChronoTimer also has singleShot() static methods:

        MyWidget widget;
        QChronoTimer::singleShot(200ms, &widget, &MyWidget::updateCaption);

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

An alternative to using QChronoTimer is to call QObject::startTimer() for your object and reimplement the QObject::timerEvent() event handler in your class (which must be a sub-class of QObject). The disadvantage is that timerEvent() does not support such high-level features as single-shot timers or signals.

Another alternative is QBasicTimer. It is typically less cumbersome than using QObject::startTimer() directly. See Timers for an overview of all three approaches.

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