Revision control
Copy as Markdown
// Copyright (C) 2022 The Qt Company Ltd.
// Copyright (C) 2016 Intel Corporation.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR LGPL-3.0-only OR GPL-2.0-only OR GPL-3.0-only
// Qt-Security score:significant reason:default
#include "qchronotimer.h"
#include "qtimer_p.h"
#include "qsingleshottimer_p.h"
#include "qabstracteventdispatcher.h"
#include "qcoreapplication.h"
#include "qcoreapplication_p.h"
#include "qdeadlinetimer.h"
#include "qmetaobject_p.h"
#include "qobject_p.h"
#include "qproperty_p.h"
#include "qthread.h"
using namespace std::chrono_literals;
QT_BEGIN_NAMESPACE
/*!
\class QChronoTimer
\inmodule QtCore
\since 6.8
\ingroup events
\brief The QChronoTimer class provides repetitive and single-shot timers.
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:
\snippet timers/timers.cpp qchronotimer-interval-in-ctor
\snippet timers/timers.cpp qchronotimer-setinterval
You can set a timer to time out only once by calling setSingleShot(true).
\note QChronoTimer has no singleShot() static methods, as the ones on
QTimer already work with chrono types and nanoseconds resolution.
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
\l{QObject::thread()}{thread affinity} to determine which thread
will emit the \l{QChronoTimer::}{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 \c 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:
\snippet timers/timers.cpp zero-timer
From then on, \c 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.
\section1 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 \c nanosleep), though the accuracy of the
timer will not equal this resolution in many real-world situations.
You can set the \l{Qt::TimerType}{timer type} to tell QChronoTimer which
precision to request from the system.
For Qt::PreciseTimer, QChronoTimer will try to keep the precision at
\c 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:
\list
\li 5% of the interval for Qt::CoarseTimer
\li \c 500ms for Qt::VeryCoarseTimer
\endlist
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.
\section1 Alternatives to QChronoTimer
QChronoTimer provides nanosecond resolution and a ±292 years range
(less chances of integer overflow if the interval is longer than \c
std::numeric_limits<int>::max()). If you only need millisecond resolution
and ±24 days range, you can continue to use the classical QTimer class
\include timers-common.qdocinc q-chrono-timer-alternatives
Some operating systems limit the number of timers that may be used;
Qt does its best to work around these limitations.
\sa QBasicTimer, QTimerEvent, QObject::timerEvent(), Timers,
{Analog Clock}
*/
/*!
Constructs a timer with the given \a parent, using the default interval,
\c 0ns.
*/
QChronoTimer::QChronoTimer(QObject *parent)
: QChronoTimer(0ns, parent)
{
}
/*!
Constructs a timer with the given \a parent, using an interval of \a nsec.
*/
QChronoTimer::QChronoTimer(std::chrono::nanoseconds nsec, QObject *parent)
: QObject(*new QTimerPrivate(nsec, this), parent)
{
Q_ASSERT(!d_func()->isQTimer);
}
/*!
Destroys the timer.
*/
QChronoTimer::~QChronoTimer()
{
if (d_func()->isActive()) // stop running timer
stop();
}
/*!
\fn void QChronoTimer::timeout()
This signal is emitted when the timer times out.
\sa interval, start(), stop()
*/
/*!
\property QChronoTimer::active
This boolean property is \c true if the timer is running; otherwise
\c false.
*/
/*!
Returns \c true if the timer is running; otherwise returns \c false.
*/
bool QChronoTimer::isActive() const
{
return d_func()->isActiveData.value();
}
QBindable<bool> QChronoTimer::bindableActive()
{
return QBindable<bool>(&d_func()->isActiveData);
}
/*!
Returns a Qt::TimerId representing the timer ID if the timer is running;
otherwise returns \c Qt::TimerId::Invalid.
\sa Qt::TimerId
*/
Qt::TimerId QChronoTimer::id() const
{
return d_func()->id;
}
/*! \overload start()
Starts or restarts the timer with the timeout specified in \l interval.
//! [stop-restart-timer]
If the timer is already running, it will be
\l{QChronoTimer::stop()}{stopped} and restarted. This will also change its
id().
//! [stop-restart-timer]
If \l singleShot is true, the timer will be activated only once.
*/
void QChronoTimer::start()
{
auto *d = d_func();
if (d->isActive()) // stop running timer
stop();
const auto id = Qt::TimerId{QObject::startTimer(d->intervalDuration, d->type)};
if (id != Qt::TimerId::Invalid) {
d->id = id;
d->isActiveData.notify();
}
}
/*!
Stops the timer.
\sa start()
*/
void QChronoTimer::stop()
{
auto *d = d_func();
if (d->isActive()) {
QObject::killTimer(d->id);
d->id = Qt::TimerId::Invalid;
d->isActiveData.notify();
}
}
/*!
\reimp
*/
void QChronoTimer::timerEvent(QTimerEvent *e)
{
auto *d = d_func();
if (e->id() == d->id) {
if (d->single)
stop();
Q_EMIT timeout(QPrivateSignal());
}
}
/*!
\fn template <typename Functor> QMetaObject::Connection QChronoTimer::callOnTimeout(const QObject *context, Functor &&slot, Qt::ConnectionType connectionType = Qt::AutoConnection)
\overload callOnTimeout()
Creates a connection from the timeout() signal to \a slot to be placed in a
specific event loop of \a context, with connection type \a connectionType,
and returns a handle to the connection.
This method is provided as a convenience. It's equivalent to calling:
\code
QObject::connect(timer, &QChronoTimer::timeout, context, slot, connectionType);
\endcode
\sa QObject::connect(), timeout()
*/
/*!
\property QChronoTimer::singleShot
\brief Whether the timer is a single-shot timer
A single-shot timer fires only once, non-single-shot timers fire every
\l interval.
The default value for this property is \c false.
\sa interval
*/
void QChronoTimer::setSingleShot(bool singleShot)
{
d_func()->single = singleShot;
}
bool QChronoTimer::isSingleShot() const
{
return d_func()->single;
}
QBindable<bool> QChronoTimer::bindableSingleShot()
{
return QBindable<bool>(&d_func()->single);
}
/*!
\property QChronoTimer::interval
\brief The timeout interval
The default value for this property is \c 0ns.
A QChronoTimer with a timeout of \c 0ns will time out as soon as
possible, though the ordering between zero timers and other sources of
events is unspecified.
Setting the interval of a running timer will change the interval,
stop() and then start() the timer, and acquire a new id().
If the timer is not running, only the interval is changed.
\include timers-common.qdocinc negative-intervals-not-allowed
\sa singleShot
*/
void QChronoTimer::setInterval(std::chrono::nanoseconds nsec)
{
if (nsec < 0ns) {
qWarning("QChronoTimer::setInterval: negative intervals aren't allowed; the "
"interval will be set to 1ms.");
nsec = 1ms;
}
auto *d = d_func();
d->intervalDuration.removeBindingUnlessInWrapper();
const bool intervalChanged = nsec != d->intervalDuration.valueBypassingBindings();
d->intervalDuration.setValueBypassingBindings(nsec);
if (d->isActive()) { // Create new timer
QObject::killTimer(d->id); // Restart timer
const auto newId = Qt::TimerId{QObject::startTimer(nsec, d->type)};
if (newId != Qt::TimerId::Invalid) {
// Restarted successfully. No need to update the active state.
d->id = newId;
} else {
// Failed to start the timer.
// Need to notify about active state change.
d->id = Qt::TimerId::Invalid;
d->isActiveData.notify();
}
}
if (intervalChanged)
d->intervalDuration.notify();
}
std::chrono::nanoseconds QChronoTimer::interval() const
{
return d_func()->intervalDuration.value();
}
QBindable<std::chrono::nanoseconds> QChronoTimer::bindableInterval()
{
return {&d_func()->intervalDuration};
}
/*!
\property QChronoTimer::remainingTime
\brief The remaining time
Returns the remaining duration until the timeout.
If the timer is inactive, the returned duration will be negative.
If the timer is overdue, the returned duration will be \c 0ns.
\sa interval
*/
std::chrono::nanoseconds QChronoTimer::remainingTime() const
{
if (isActive())
return QAbstractEventDispatcher::instance()->remainingTime(d_func()->id);
return std::chrono::nanoseconds::min();
}
/*!
\property QChronoTimer::timerType
\brief Controls the accuracy of the timer
The default value for this property is \c Qt::CoarseTimer.
\sa Qt::TimerType
*/
void QChronoTimer::setTimerType(Qt::TimerType atype)
{
d_func()->type = atype;
}
Qt::TimerType QChronoTimer::timerType() const
{
return d_func()->type;
}
QBindable<Qt::TimerType> QChronoTimer::bindableTimerType()
{
return {&d_func()->type};
}
QT_END_NAMESPACE
#include "moc_qchronotimer.cpp"