QDeadlineTimer Class

Detailed Description

The QDeadlineTimer class marks a deadline in the future.

The QDeadlineTimer class is usually used to calculate future deadlines and verify whether the deadline has expired. QDeadlineTimer can also be used for deadlines without expiration ("forever"). It forms a counterpart to QElapsedTimer, which calculates how much time has elapsed since QElapsedTimer::start() was called.

QDeadlineTimer provides a more convenient API compared to QElapsedTimer::hasExpired().

The typical use-case for the class is to create a QDeadlineTimer before the operation in question is started, and then use remainingTime() or hasExpired() to determine whether to continue trying the operation. QDeadlineTimer objects can be passed to functions being called to execute this operation so they know how long to still operate.

     void executeOperation(int msecs)
     {
         QDeadlineTimer deadline(msecs);
         do {
             if (readFromDevice(deadline.remainingTime())
                 break;
             waitForReadyRead(deadline);
         } while (!deadline.hasExpired());
     }

Many QDeadlineTimer functions deal with time out values, which all are measured in milliseconds. There are two special values, the same as many other Qt functions named waitFor or similar:

• 0: no time left, expired
• -1: infinite time left, timer never expires

Reference Clocks

QDeadlineTimer will use the same clock as QElapsedTimer (see QElapsedTimer::clockType() and QElapsedTimer::isMonotonic()).

Timer types

Like QTimer, QDeadlineTimer can select among different levels of coarseness on the timers. You can select precise timing by passing Qt::PreciseTimer to the functions that set of change the timer, or you can select coarse timing by passing Qt::CoarseTimer. Qt::VeryCoarseTimer is currently interpreted the same way as Qt::CoarseTimer.

This feature is dependent on support from the operating system: if the OS does not support a coarse timer functionality, then QDeadlineTimer will behave like Qt::PreciseTimer was passed.

QDeadlineTimer defaults to Qt::CoarseTimer because on operating systems that do support coarse timing, making timing calls to that clock source is often much more efficient. The level of coarseness depends on the operating system, but should be in the order of a couple of milliseconds.

std::chrono Compatibility

QDeadlineTimer is compatible with the std::chrono API from C++11 and can be constructed from or compared to both std::chrono::duration and std::chrono::time_point objects. In addition, it is fully compatible with the time literals from C++14, which allow one to write code as:

     using namespace std::chrono;
     using namespace std::chrono_literals;

     QDeadlineTimer deadline(30s);
     device->waitForReadyRead(deadline);
     if (deadline.remainingTime<nanoseconds>() > 300ms)
         cleanup();

As can be seen in the example above, QDeadlineTimer offers a templated version of remainingTime() and deadline() that can be used to return std::chrono objects.

Note that comparing to time_point is not as efficient as comparing to duration, since QDeadlineTimer may need to convert from its own internal clock source to the clock source used by the time_point object. Also note that, due to this conversion, the deadlines will not be precise, so the following code is not expected to compare equally:

     using namespace std::chrono;
     using namespace std::chrono_literals;
     auto now = steady_clock::now();
     QDeadlineTimer deadline(now + 1s);
     Q_ASSERT(deadline == now + 1s);