QDeadlineTimer¶
The
QDeadlineTimer
class marks a deadline in the future. More…
New in version 5.8.
Synopsis¶
Functions¶
def
__iadd__
(msecs)def
__isub__
(msecs)def
_q_data
()def
deadline
()def
deadlineNSecs
()def
hasExpired
()def
isForever
()def
remainingTime
()def
remainingTimeNSecs
()def
setDeadline
(msecs[, timerType=Qt.CoarseTimer])def
setPreciseDeadline
(secs[, nsecs=0[, type=Qt.CoarseTimer]])def
setPreciseRemainingTime
(secs[, nsecs=0[, type=Qt.CoarseTimer]])def
setRemainingTime
(msecs[, type=Qt.CoarseTimer])def
setTimerType
(type)def
swap
(other)def
timerType
()
Static functions¶
Detailed Description¶
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 toQElapsedTimer
, which calculates how much time has elapsed sincestart()
was called.
QDeadlineTimer
provides a more convenient API compared tohasExpired()
.The typical use-case for the class is to create a
QDeadlineTimer
before the operation in question is started, and then useremainingTime()
orhasExpired()
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 namedwaitFor
or similar:
0: no time left, expired
-1: infinite time left, timer never expires
Reference Clocks¶
QDeadlineTimer
will use the same clock asQElapsedTimer
(seeclockType()
andisMonotonic()
).
Timer types¶
Like
QTimer
,QDeadlineTimer
can select among different levels of coarseness on the timers. You can select precise timing by passingPreciseTimer
to the functions that set of change the timer, or you can select coarse timing by passingCoarseTimer
.VeryCoarseTimer
is currently interpreted the same way asCoarseTimer
.This feature is dependent on support from the operating system: if the OS does not support a coarse timer functionality, then
QDeadlineTimer
will behave likePreciseTimer
was passed.
QDeadlineTimer
defaults toCoarseTimer
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 thestd::chrono
API from C++11 and can be constructed from or compared to bothstd::chrono::duration
andstd::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 ofremainingTime()
anddeadline()
that can be used to returnstd::chrono
objects.Note that comparing to
time_point
is not as efficient as comparing toduration
, sinceQDeadlineTimer
may need to convert from its own internal clock source to the clock source used by thetime_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);See also
QTime
QTimer
QDeadlineTimer
TimerType
- class PySide2.QtCore.QDeadlineTimer(arg__1[, type_=Qt.CoarseTimer])¶
PySide2.QtCore.QDeadlineTimer([type_=Qt.CoarseTimer])
PySide2.QtCore.QDeadlineTimer(QDeadlineTimer)
PySide2.QtCore.QDeadlineTimer(msecs[, type=Qt.CoarseTimer])
- param type:
- param arg__1:
- param msecs:
int
- param type_:
- param QDeadlineTimer:
QDeadlineTimer
objects created withForeverConstant
never expire. For such objects,remainingTime()
will return -1,deadline()
will return the maximum value, andisForever()
will return true.The timer type
timerType
may be ignored, since the timer will never expire.See also
ForeverConstant
hasExpired()
isForever()
remainingTime()
timerType()
Constructs an expired
QDeadlineTimer
object. For this object,remainingTime()
will return 0.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, usecurrent()
.See also
hasExpired()
remainingTime()
TimerType
current()
Constructs a
QDeadlineTimer
object with an expiry time ofmsecs
msecs from the moment of the creation of this object, if msecs is positive. Ifmsecs
is zero, thisQDeadlineTimer
will be marked as expired, causingremainingTime()
to return zero anddeadline()
to return an indeterminate time point in the past. Ifmsecs
is -1, the timer will be set to never expire, causingremainingTime()
to return -1 anddeadline()
to return the maximum value.The
QDeadlineTimer
object will be constructed with the specified timertype
.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, usecurrent()
and add time to it.
- PySide2.QtCore.QDeadlineTimer.ForeverConstant¶
Constant
Description
QDeadlineTimer.Forever
Used when creating a
QDeadlineTimer
to indicate the deadline should not expire
- PySide2.QtCore.QDeadlineTimer._q_data()¶
- Return type:
- static PySide2.QtCore.QDeadlineTimer.addNSecs(dt, nsecs)¶
- Parameters:
nsecs – int
- Return type:
Returns a
QDeadlineTimer
object whose deadline is extended fromdt
‘s deadline bynsecs
nanoseconds. Ifdt
was set to never expire, this function returns aQDeadlineTimer
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 PySide2.QtCore.QDeadlineTimer.current([timerType=Qt.CoarseTimer])¶
- Parameters:
timerType –
TimerType
- Return type:
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 thedeadline()
function.The
QDeadlineTimer
object will be constructed with the specifiedtimerType
.
- PySide2.QtCore.QDeadlineTimer.deadline()¶
- Return type:
int
Returns the absolute time point for the deadline stored in
QDeadlineTimer
object, calculated in milliseconds relative to the reference clock, the same asmsecsSinceReference()
. The value will be in the past if thisQDeadlineTimer
has expired.If this
QDeadlineTimer
never expires, this function returnsstd::numeric_limits<qint64>::max()
.This function can be used to calculate the amount of time a timer is overdue, by subtracting
current()
ormsecsSinceReference()
, as in the following example:qint64 realTimeLeft = deadline.deadline(); if (realTimeLeft != (std::numeric_limits<qint64>::max)()) { realTimeLeft -= 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
- PySide2.QtCore.QDeadlineTimer.deadlineNSecs()¶
- Return type:
int
Returns the absolute time point for the deadline stored in
QDeadlineTimer
object, calculated in nanoseconds relative to the reference clock, the same asmsecsSinceReference()
. The value will be in the past if thisQDeadlineTimer
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 returnsstd::numeric_limits<qint64>::max()
.This function can be used to calculate the amount of time a timer is overdue, by subtracting
current()
, as in the following example:qint64 realTimeLeft = deadline.deadlineNSecs(); if (realTimeLeft != std::numeric_limits<qint64>::max()) realTimeLeft -= 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
- PySide2.QtCore.QDeadlineTimer.hasExpired()¶
- Return type:
bool
Returns true if this
QDeadlineTimer
object has expired, false if there remains time left. For objects that have expired,remainingTime()
will return zero anddeadline()
will return a time point in the past.QDeadlineTimer
objects created with theForeverConstant
never expire and this function always returns false for them.See also
- PySide2.QtCore.QDeadlineTimer.isForever()¶
- Return type:
bool
Returns true if this
QDeadlineTimer
object never expires, false otherwise. For timers that never expire,remainingTime()
always returns -1 anddeadline()
returns the maximum value.See also
ForeverConstant
hasExpired()
remainingTime()
- PySide2.QtCore.QDeadlineTimer.__iadd__(msecs)¶
- Parameters:
msecs – int
- Return type:
Extends this
QDeadlineTimer
object bymsecs
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()
.
- PySide2.QtCore.QDeadlineTimer.__isub__(msecs)¶
- Parameters:
msecs – int
- Return type:
Shortens this
QDeadlineTimer
object bymsecs
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()
.
- PySide2.QtCore.QDeadlineTimer.remainingTime()¶
- Return type:
int
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, seedeadline()
). 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 inQMutex
,QWaitCondition
,QSemaphore
, orQReadWriteLock
. For example:mutex.tryLock(deadline.remainingTime());
- PySide2.QtCore.QDeadlineTimer.remainingTimeNSecs()¶
- Return type:
int
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
- PySide2.QtCore.QDeadlineTimer.setDeadline(msecs[, timerType=Qt.CoarseTimer])¶
- Parameters:
msecs – int
timerType –
TimerType
Sets the deadline for this
QDeadlineTimer
object to be themsecs
absolute time point, counted in milliseconds since the reference clock (the same asmsecsSinceReference()
), and the timer type totimerType
. If the value is in the past, thisQDeadlineTimer
will be marked as expired.If
msecs
isstd::numeric_limits<qint64>::max()
or the deadline is beyond a representable point in the future, thisQDeadlineTimer
will be set to never expire.
- PySide2.QtCore.QDeadlineTimer.setPreciseDeadline(secs[, nsecs=0[, type=Qt.CoarseTimer]])¶
- Parameters:
secs – int
nsecs – int
type –
TimerType
Sets the deadline for this
QDeadlineTimer
object to besecs
seconds andnsecs
nanoseconds since the reference clock epoch (the same asmsecsSinceReference()
), and the timer type totimerType
. If the value is in the past, thisQDeadlineTimer
will be marked as expired.If
secs
ornsecs
isstd::numeric_limits<qint64>::max()
, thisQDeadlineTimer
will be set to never expire. Ifnsecs
is more than 1 billion nanoseconds (1 second), thensecs
will be adjusted accordingly.
- PySide2.QtCore.QDeadlineTimer.setPreciseRemainingTime(secs[, nsecs=0[, type=Qt.CoarseTimer]])¶
- Parameters:
secs – int
nsecs – int
type –
TimerType
Sets the remaining time for this
QDeadlineTimer
object tosecs
seconds plusnsecs
nanoseconds from now, ifsecs
has a positive value. Ifsecs
is -1, thisQDeadlineTimer
will be set it to never expire. If both parameters are zero, thisQDeadlineTimer
will be marked as expired.The timer type for this
QDeadlineTimer
object will be set to the specifiedtimerType
.
- PySide2.QtCore.QDeadlineTimer.setRemainingTime(msecs[, type=Qt.CoarseTimer])¶
- Parameters:
msecs – int
type –
TimerType
Sets the remaining time for this
QDeadlineTimer
object tomsecs
milliseconds from now, ifmsecs
has a positive value. Ifmsecs
is zero, thisQDeadlineTimer
object will be marked as expired, whereas a value of -1 will set it to never expire.The timer type for this
QDeadlineTimer
object will be set to the specifiedtimerType
.
- PySide2.QtCore.QDeadlineTimer.setTimerType(type)¶
- Parameters:
type –
TimerType
Changes the timer type for this object to
timerType
.The behavior for each possible value of
timerType
is operating-system dependent.PreciseTimer
will use the most precise timer that Qt can find, with resolution of 1 millisecond or better, whereasQDeadlineTimer
will try to use a more coarse timer forCoarseTimer
andVeryCoarseTimer
.See also
timerType()
TimerType
- PySide2.QtCore.QDeadlineTimer.swap(other)¶
- Parameters:
other –
PySide2.QtCore.QDeadlineTimer
Swaps this deadline timer with the
other
deadline timer.
- PySide2.QtCore.QDeadlineTimer.timerType()¶
- Return type:
Returns the timer type is active for this object.
See also
© 2022 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.