Add QChronoTimer, a timer with nanoseconds precision

The interval in QTimer is a QProperty of type int, which means it's
limited to the number of milliseconds that would fit in an int (~24
days), this could cause overflow if a user constructs a QTimer with an
interval > INT_MAX milliseconds. And it can't be easily changed to use
qint64/std::chrono::nanoseconds:
  - changing the getters to return qint64 means user code would have
    narrowing conversions
  - the bindable QProperty interval can't be changed to qint64 during
    Qt6's lifetime without the risk of breaking user code
  - adding a new bindable QProperty that is qint64/nanoseconds is an
    option, but it has the complication of what to do with the int
    interval; set it when setInterval(milliseconds) is used by using
    saturation arithmetic? and what about notifying observers of the
    changed interval?

Thus the idea of creating a new stop-gap class, QChronoTimer, as a
cleaner solution. Both classes use QTimerPrivate.

During the lifetime of Qt6, QTimer's interval range is about 24 days,
whereas QChronoTimer's interval range is about 292 years
(duration_cast<years>nanoseconds::max()).

Currently the plan is to fold QChronotTimer back into QTimer in Qt7.

Mark all QPropertyS in the new class as FINAL since they aren't
intended to be overridden; this offers a performance boost for QML[1].

[1] https://lists.qt-project.org/pipermail/development/2024-February/044977.html

[ChangeLog][QtCore] Added QChronoTimer, which uses a
std::chrono::nanoseconds intervals, as a replacement for QTimer.

Fixes: QTBUG-113544
Change-Id: I71697f4a8b35452c6b5604b1322ee7f0b4453f04
Reviewed-by: Thiago Macieira <thiago.macieira@intel.com>
Reviewed-by: Qt CI Bot <qt_ci_bot@qt-project.org>

1 files changed, 43 insertions, 1 deletions

diff --git a/src/corelib/doc/snippets/timers/timers.cpp b/src/corelib/doc/snippets/timers/timers.cpp
index c89db6890c..84618adb81 100644
--- a/src/corelib/doc/snippets/timers/timers.cpp
+++ b/src/corelib/doc/snippets/timers/timers.cpp
@@ -1,8 +1,12 @@
 // Copyright (C) 2016 The Qt Company Ltd.
 // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause
 
+#include <QChronoTimer>
+#include <QObject>
 #include <QTimer>
 
+using namespace std::chrono;
+
 class Foo : public QObject
 {
 public:
@@ -35,7 +39,45 @@ Foo::Foo()
     }
 }
 
-int main()
+// QChronoTimer
+class MyWidget : QObject
 {
+    MyWidget()
+    {
+//! [qchronotimer-singleshot]
+        MyWidget widget;
+        QChronoTimer::singleShot(100ms, &widget, &MyWidget::processOneThing);
+//! [qchronotimer-singleshot]
 
+//! [zero-timer]
+        // The default interval is 0ns
+        QChronoTimer *timer = new QChronoTimer(this);
+        connect(timer, &QChronoTimer::timeout, this, &MyWidget::processOneThing);
+        timer->start();
+//! [zero-timer]
+
+        {
+//! [timer-interval-in-ctor]
+        QChronoTimer *timer = new QChronoTimer(1s, this);
+        connect(timer, &QChronoTimer::timeout, this, &MyWidget::processOneThing);
+        timer->start();
+//! [timer-interval-in-ctor]
+        }
+
+        {
+//! [timer-setinterval]
+        QChronoTimer *timer = new QChronoTimer(this);
+        connect(timer, &QChronoTimer::timeout, this, &MyWidget::processOneThing);
+        timer->setInterval(1s);
+        timer->start();
+//! [timer-setinterval]
+        }
+    }
+
+public Q_SLOTS:
+    void processOneThing();
+};
+
+int main()
+{
 }