QDeadlineTimer Class | Qt Core (original) (raw)

This class is strongly comparable.

Member Function Documentation

[constexpr noexcept] QDeadlineTimer::QDeadlineTimer()

[explicit constexpr noexcept] QDeadlineTimer::QDeadlineTimer(Qt::TimerType timerType)

Constructs an expired QDeadlineTimer object. For this object, remainingTime() will return 0. If timerType is not set, then the object will use the coarse timer type.

The timer type timerType may be ignored, since the timer is already expired. Similarly, for optimization purposes, this function will not attempt to obtain the current time and will use a value known to be in the past. Therefore, deadline() may return an unexpected value and this object cannot be used in calculation of how long it is overdue. If that functionality is required, use QDeadlineTimer::current().

See also hasExpired(), remainingTime(), Qt::TimerType, and current().

[constexpr noexcept] QDeadlineTimer::QDeadlineTimer(QDeadlineTimer::ForeverConstant, Qt::TimerType timerType = Qt::CoarseTimer)

QDeadlineTimer objects created with ForeverConstant never expire. For such objects, remainingTime() will return -1, deadline() will return the maximum value, and isForever() will return true.

The timer type timerType may be ignored, since the timer will never expire.

See also ForeverConstant, hasExpired(), isForever(), remainingTime(), and timerType().

[explicit noexcept] QDeadlineTimer::QDeadlineTimer(qint64 msecs, Qt::TimerType type = Qt::CoarseTimer)

Constructs a QDeadlineTimer object with an expiry time of msecs msecs from the moment of the creation of this object, if msecs is positive. If msecs is zero, this QDeadlineTimer will be marked as expired, causing remainingTime() to return zero and deadline() to return an indeterminate time point in the past. If msecs is negative, the timer will be set to never expire, causing remainingTime() to return -1 and deadline() to return the maximum value.

The QDeadlineTimer object will be constructed with the specified timer type.

For optimization purposes, if msecs is zero, this function may skip obtaining the current time and may instead use a value known to be in the past. If that happens, deadline() may return an unexpected value and this object cannot be used in calculation of how long it is overdue. If that functionality is required, use QDeadlineTimer::current() and add time to it.

Note: Prior to Qt 6.6, the only value that caused the timer to never expire was -1.

See also hasExpired(), isForever(), remainingTime(), and setRemainingTime().

template <typename Rep, typename Period> QDeadlineTimer::QDeadlineTimer(std::chrono::duration<Rep, Period> remaining, Qt::TimerType type = Qt::CoarseTimer)

Constructs a QDeadlineTimer object with a remaining time of remaining. If remaining is zero or negative, this QDeadlineTimer object will be mark as expired, whereas if remaining is equal to duration::max(), the object will be set to never expire.

The QDeadlineTimer object will be constructed with the specified timer type.

This constructor can be used with C++14's user-defined literals for time, such as in:

For optimization purposes, if remaining is zero or negative, this function may skip obtaining the current time and may instead use a value known to be in the past. If that happens, deadline() may return an unexpected value and this object cannot be used in calculation of how long it is overdue. If that functionality is required, use QDeadlineTimer::current() and add time to it.

See also hasExpired(), isForever(), remainingTime(), and setRemainingTime().

template <typename Clock, typename Duration = typename Clock::duration> QDeadlineTimer::QDeadlineTimer(std::chrono::time_point<Clock, Duration> deadline, Qt::TimerType type = Qt::CoarseTimer)

Constructs a QDeadlineTimer object with a deadline at deadline time point, converting from the clock source Clock to Qt's internal clock source (see QElapsedTimer::clockType()).

If deadline is in the past, this QDeadlineTimer object is set to expired, whereas if deadline is equal to Duration::max(), then this object is set to never expire.

The QDeadlineTimer object will be constructed with the specified timer type.

See also hasExpired(), isForever(), remainingTime(), and setDeadline().

[static noexcept] QDeadlineTimer QDeadlineTimer::addNSecs(QDeadlineTimer dt, qint64 nsecs)

Returns a QDeadlineTimer object whose deadline is extended from dt's deadline by nsecs nanoseconds. If dt was set to never expire, this function returns a QDeadlineTimer that will not expire either.

Note: if dt was created as expired, its deadline is indeterminate and adding an amount of time may or may not cause it to become unexpired.

[static noexcept] QDeadlineTimer QDeadlineTimer::current(Qt::TimerType timerType = Qt::CoarseTimer)

Returns a QDeadlineTimer that is expired but is guaranteed to contain the current time. Objects created by this function can participate in the calculation of how long a timer is overdue, using the deadline() function.

The QDeadlineTimer object will be constructed with the specified timerType.

[noexcept] qint64 QDeadlineTimer::deadline() const

Returns the absolute time point for the deadline stored in QDeadlineTimer object, calculated in milliseconds relative to the reference clock, the same as QElapsedTimer::msecsSinceReference(). The value will be in the past if this QDeadlineTimer has expired.

If this QDeadlineTimer never expires, this function returns std::numeric_limits<qint64>::max().

This function can be used to calculate the amount of time a timer is overdue, by subtracting QDeadlineTimer::current() or QElapsedTimer::msecsSinceReference(), as in the following example:

[qint64](qttypes.html#qint64-typedef) realTimeLeft = deadline.deadline();
if (realTimeLeft != (std::numeric_limits<[qint64](qttypes.html#qint64-typedef)>::max)()) {
    realTimeLeft -= [QDeadlineTimer](qdeadlinetimer.html#QDeadlineTimer)::current().deadline();
    // or:
    //QElapsedTimer timer;
    //timer.start();
    //realTimeLeft -= timer.msecsSinceReference();
}

Note: Timers that were created as expired have an indetermine time point in the past as their deadline, so the above calculation may not work.

See also remainingTime(), deadlineNSecs(), and setDeadline().

[noexcept] qint64 QDeadlineTimer::deadlineNSecs() const

Returns the absolute time point for the deadline stored in QDeadlineTimer object, calculated in nanoseconds relative to the reference clock, the same as QElapsedTimer::msecsSinceReference(). The value will be in the past if this QDeadlineTimer has expired.

If this QDeadlineTimer never expires or the number of nanoseconds until the deadline can't be accommodated in the return type, this function returns std::numeric_limits<qint64>::max().

This function can be used to calculate the amount of time a timer is overdue, by subtracting QDeadlineTimer::current(), as in the following example:

[qint64](qttypes.html#qint64-typedef) realTimeLeft = deadline.deadlineNSecs();
if (realTimeLeft != std::numeric_limits<[qint64](qttypes.html#qint64-typedef)>::max())
    realTimeLeft -= [QDeadlineTimer](qdeadlinetimer.html#QDeadlineTimer)::current().deadlineNSecs();

Note: Timers that were created as expired have an indetermine time point in the past as their deadline, so the above calculation may not work.

See also remainingTime() and deadlineNSecs().

[noexcept] bool QDeadlineTimer::hasExpired() const

Returns true if this QDeadlineTimer object has expired, false if there remains time left. For objects that have expired, remainingTime() will return zero and deadline() will return a time point in the past.

QDeadlineTimer objects created with the ForeverConstant never expire and this function always returns false for them.

See also isForever() and remainingTime().

[constexpr noexcept] bool QDeadlineTimer::isForever() const

Returns true if this QDeadlineTimer object never expires, false otherwise. For timers that never expire, remainingTime() always returns -1 and deadline() returns the maximum value.

See also ForeverConstant, hasExpired(), and remainingTime().

[noexcept] qint64 QDeadlineTimer::remainingTime() const

Returns the remaining time in this QDeadlineTimer object in milliseconds. If the timer has already expired, this function will return zero and it is not possible to obtain the amount of time overdue with this function (to do that, see deadline()). If the timer was set to never expire, this function returns -1.

This function is suitable for use in Qt APIs that take a millisecond timeout, such as the many QIODevice waitFor functions or the timed lock functions in QMutex, QWaitCondition, QSemaphore, or QReadWriteLock. For example:

mutex.tryLock(deadline.remainingTime());

See also setRemainingTime(), remainingTimeNSecs(), isForever(), and hasExpired().

[noexcept] std::chrono::nanoseconds QDeadlineTimer::remainingTimeAsDuration() const

Returns the time remaining before the deadline.

[noexcept] qint64 QDeadlineTimer::remainingTimeNSecs() const

Returns the remaining time in this QDeadlineTimer object in nanoseconds. If the timer has already expired, this function will return zero and it is not possible to obtain the amount of time overdue with this function. If the timer was set to never expire, this function returns -1.

See also remainingTime(), isForever(), and hasExpired().

[noexcept] void QDeadlineTimer::setDeadline(qint64 msecs, Qt::TimerType timerType = Qt::CoarseTimer)

Sets the deadline for this QDeadlineTimer object to be the msecs absolute time point, counted in milliseconds since the reference clock (the same as QElapsedTimer::msecsSinceReference()), and the timer type to timerType. If the value is in the past, this QDeadlineTimer will be marked as expired.

If msecs is std::numeric_limits<qint64>::max() or the deadline is beyond a representable point in the future, this QDeadlineTimer will be set to never expire.

See also setPreciseDeadline(), deadline(), deadlineNSecs(), and setRemainingTime().

template <typename Clock, typename Duration = typename Clock::duration> void QDeadlineTimer::setDeadline(std::chrono::time_point<Clock, Duration> deadline, Qt::TimerType type = Qt::CoarseTimer)

Sets this QDeadlineTimer to the deadline marked by deadline time point, converting from the clock source Clock to Qt's internal clock source (see QElapsedTimer::clockType()).

If deadline is in the past, this QDeadlineTimer object is set to expired, whereas if deadline is equal to Duration::max(), then this object is set to never expire.

The timer type for this QDeadlineTimer object will be set to the specified type.

See also hasExpired(), isForever(), and remainingTime().

[noexcept] void QDeadlineTimer::setPreciseDeadline(qint64 secs, qint64 nsecs = 0, Qt::TimerType timerType = Qt::CoarseTimer)

Sets the deadline for this QDeadlineTimer object to be secs seconds and nsecs nanoseconds since the reference clock epoch (the same as QElapsedTimer::msecsSinceReference()), and the timer type to timerType. If the value is in the past, this QDeadlineTimer will be marked as expired.

If secs or nsecs is std::numeric_limits<qint64>::max(), this QDeadlineTimer will be set to never expire. If nsecs is more than 1 billion nanoseconds (1 second), then secs will be adjusted accordingly.

See also setDeadline(), deadline(), deadlineNSecs(), and setRemainingTime().

[noexcept] void QDeadlineTimer::setPreciseRemainingTime(qint64 secs, qint64 nsecs = 0, Qt::TimerType timerType = Qt::CoarseTimer)

Sets the remaining time for this QDeadlineTimer object to secs seconds plus nsecs nanoseconds from now, if secs has a positive value. If secs is negative, this QDeadlineTimer will be set it to never expire (this behavior does not apply to nsecs). If both parameters are zero, this QDeadlineTimer will be marked as expired.

For optimization purposes, if both secs and nsecs are zero, this function may skip obtaining the current time and may instead use a value known to be in the past. If that happens, deadline() may return an unexpected value and this object cannot be used in calculation of how long it is overdue. If that functionality is required, use QDeadlineTimer::current() and add time to it.

The timer type for this QDeadlineTimer object will be set to the specified timerType.

Note: Prior to Qt 6.6, the only condition that caused the timer to never expire was when secs was -1.

See also setRemainingTime(), hasExpired(), isForever(), and remainingTime().

[noexcept] void QDeadlineTimer::setRemainingTime(qint64 msecs, Qt::TimerType timerType = Qt::CoarseTimer)

Sets the remaining time for this QDeadlineTimer object to msecs milliseconds from now, if msecs has a positive value. If msecs is zero, this QDeadlineTimer object will be marked as expired, whereas a negative value will set it to never expire.

For optimization purposes, if msecs is zero, this function may skip obtaining the current time and may instead use a value known to be in the past. If that happens, deadline() may return an unexpected value and this object cannot be used in calculation of how long it is overdue. If that functionality is required, use QDeadlineTimer::current() and add time to it.

The timer type for this QDeadlineTimer object will be set to the specified timerType.

Note: Prior to Qt 6.6, the only value that caused the timer to never expire was -1.

See also setPreciseRemainingTime(), hasExpired(), isForever(), and remainingTime().

template <typename Rep, typename Period> void QDeadlineTimer::setRemainingTime(std::chrono::duration<Rep, Period> remaining, Qt::TimerType type = Qt::CoarseTimer)

This is an overloaded function.

Sets the remaining time for this QDeadlineTimer object to remaining. If remaining is zero or negative, this QDeadlineTimer object will be mark as expired, whereas if remaining is equal to duration::max(), the object will be set to never expire.

The timer type for this QDeadlineTimer object will be set to the specified type.

This function can be used with C++14's user-defined literals for time, such as in:

using namespace std::chrono_literals;
deadline.setRemainingTime(250ms);

See also setDeadline(), remainingTime(), hasExpired(), and isForever().

void QDeadlineTimer::setTimerType(Qt::TimerType timerType)

Changes the timer type for this object to timerType.

The behavior for each possible value of timerType is operating-system dependent. Qt::PreciseTimer will use the most precise timer that Qt can find, with resolution of 1 millisecond or better, whereas QDeadlineTimer will try to use a more coarse timer for Qt::CoarseTimer and Qt::VeryCoarseTimer.

See also timerType() and Qt::TimerType.

[noexcept] void QDeadlineTimer::swap(QDeadlineTimer &other)

Swaps this deadline timer with other. This operation is very fast and never fails.

[noexcept] Qt::TimerType QDeadlineTimer::timerType() const

Returns the timer type is active for this object.

See also setTimerType().

QDeadlineTimer &QDeadlineTimer::operator+=(qint64 msecs)

Extends this QDeadlineTimer object by msecs milliseconds and returns itself. If this object is set to never expire, this function does nothing.

To add times of precision greater than 1 millisecond, use addNSecs().

QDeadlineTimer &QDeadlineTimer::operator-=(qint64 msecs)

Shortens this QDeadlineTimer object by msecs milliseconds and returns itself. If this object is set to never expire, this function does nothing.

To subtract times of precision greater than 1 millisecond, use addNSecs().

template <typename Rep, typename Period> QDeadlineTimer &QDeadlineTimer::operator=(std::chrono::duration<Rep, Period> remaining)

Sets this deadline timer to the remaining time.

template <typename Clock, typename Duration = typename Clock::duration> QDeadlineTimer &QDeadlineTimer::operator=(std::chrono::time_point<Clock, Duration> deadline_)

Assigns deadline_ to this deadline timer.

Related Non-Members

[noexcept] bool operator!=(const QDeadlineTimer &lhs, const QDeadlineTimer &rhs)

Returns true if the deadline on lhs and the deadline in rhs are different, false otherwise. The timer type used to create the two deadlines is ignored. This function is equivalent to:

return lhs.deadlineNSecs() != rhs.deadlineNSecs();

Note: comparing QDeadlineTimer objects with different timer types is not supported and may result in unpredictable behavior.

QDeadlineTimer operator+(QDeadlineTimer dt, qint64 msecs)

Returns a QDeadlineTimer object whose deadline is msecs later than the deadline stored in dt. If dt is set to never expire, this function returns a QDeadlineTimer that does not expire either.

To add times of precision greater than 1 millisecond, use addNSecs().

QDeadlineTimer operator+(qint64 msecs, QDeadlineTimer dt)

Returns a QDeadlineTimer object whose deadline is msecs later than the deadline stored in dt. If dt is set to never expire, this function returns a QDeadlineTimer that does not expire either.

To add times of precision greater than 1 millisecond, use addNSecs().

QDeadlineTimer operator-(QDeadlineTimer dt, qint64 msecs)

Returns a QDeadlineTimer object whose deadline is msecs before the deadline stored in dt. If dt is set to never expire, this function returns a QDeadlineTimer that does not expire either.

To subtract times of precision greater than 1 millisecond, use addNSecs().

[noexcept] bool operator<(const QDeadlineTimer &lhs, const QDeadlineTimer &rhs)

Returns true if the deadline on lhs is earlier than the deadline in rhs, false otherwise. The timer type used to create the two deadlines is ignored. This function is equivalent to:

return lhs.deadlineNSecs() < rhs.deadlineNSecs();

Note: comparing QDeadlineTimer objects with different timer types is not supported and may result in unpredictable behavior.

[noexcept] bool operator<=(const QDeadlineTimer &lhs, const QDeadlineTimer &rhs)

Returns true if the deadline on lhs is earlier than or the same as the deadline in rhs, false otherwise. The timer type used to create the two deadlines is ignored. This function is equivalent to:

return lhs.deadlineNSecs() <= rhs.deadlineNSecs();

Note: comparing QDeadlineTimer objects with different timer types is not supported and may result in unpredictable behavior.

[noexcept] bool operator==(const QDeadlineTimer &lhs, const QDeadlineTimer &rhs)

Returns true if the deadline on lhs and the deadline in rhs are the same, false otherwise. The timer type used to create the two deadlines is ignored. This function is equivalent to:

return lhs.deadlineNSecs() == rhs.deadlineNSecs();

Note: comparing QDeadlineTimer objects with different timer types is not supported and may result in unpredictable behavior.

[noexcept] bool operator>(const QDeadlineTimer &lhs, const QDeadlineTimer &rhs)

Returns true if the deadline on lhs is later than the deadline in rhs, false otherwise. The timer type used to create the two deadlines is ignored. This function is equivalent to:

return lhs.deadlineNSecs() > rhs.deadlineNSecs();

Note: comparing QDeadlineTimer objects with different timer types is not supported and may result in unpredictable behavior.

[noexcept] bool operator>=(const QDeadlineTimer &lhs, const QDeadlineTimer &rhs)

Returns true if the deadline on lhs is later than or the same as the deadline in rhs, false otherwise. The timer type used to create the two deadlines is ignored. This function is equivalent to:

return lhs.deadlineNSecs() >= rhs.deadlineNSecs();

Note: comparing QDeadlineTimer objects with different timer types is not supported and may result in unpredictable behavior.