Класс QDeadlineTimer

Класс QDeadlineTimer отмечает крайний срок в будущем. Подробнее...

• Список всех членов, включая унаследованные

Примечание: Все функции в этом классе являются перевходовыми.

Открытые типы

Открытые функции

Статические открытые члены

Связанные нечлены

Подробное описание

Класс QDeadlineTimer отмечает крайний срок в будущем.

Класс QDeadlineTimer обычно используется для расчета будущих крайних сроков и проверки истечения крайнего срока. QDeadlineTimer также может использоваться для крайних сроков без истечения ("навсегда"). Он представляет собой пару к QElapsedTimer, который вычисляет, сколько времени прошло с момента вызова QElapsedTimer::start().

QDeadlineTimer предоставляет более удобный API по сравнению с QElapsedTimer::hasExpired().

Типичный сценарий использования класса — создание QDeadlineTimer перед запуском операции, а затем использование remainingTime() или hasExpired() для определения того, следует ли продолжать попытку выполнения операции. Объекты QDeadlineTimer могут передаваться функциям, вызываемым для выполнения этой операции, чтобы они знали, сколько времени еще нужно работать.

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

Многие функции QDeadlineTimer работают со значениями таймаутов, все из которых измеряются в миллисекундах. Существуют два специальных значения, аналогично многим другим функциям Qt, которые называются waitFor или подобно этому:

• 0: нет времени, истекло
• -1: бесконечное время, таймер никогда не истекает

Ссылки на часы

QDeadlineTimer будет использовать те же часы, что и QElapsedTimer (см. QElapsedTimer::clockType() и QElapsedTimer::isMonotonic()).

Типы таймеров

Как и QTimer, QDeadlineTimer может выбирать между различными уровнями грубости таймеров. Вы можете выбрать точное время, передав Qt::PreciseTimer функциям, устанавливающим таймер, или выбрать грубое время, передав Qt::CoarseTimer. Qt::VeryCoarseTimer в настоящее время интерпретируется так же, как Qt::CoarseTimer.

Эта функция зависит от поддержки операционной системы: если ОС не поддерживает грубые таймеры, то QDeadlineTimer будет вести себя так, как будто был передан Qt::PreciseTimer.

QDeadlineTimer по умолчанию использует Qt::CoarseTimer, поскольку на операционных системах, поддерживающих грубое время, вызов функций для этого источника времени часто гораздо эффективнее. Уровень грубости зависит от операционной системы, но должен быть порядка нескольких миллисекунд.

std::chrono Совместимость

QDeadlineTimer совместим с API std::chrono из C++11 и может быть создан или сравнен как с std::chrono::duration, так и с std::chrono::time_point объектами. Кроме того, он полностью совместим с литералами времени из C++14, что позволяет писать код, как:

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

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

Как видно из примера выше, QDeadlineTimer предлагает шаблонную версию remainingTime() и deadline(), которые можно использовать для возврата объектов std::chrono.

Обратите внимание, что сравнение с time_point не является таким эффективным, как сравнение с duration, так как QDeadlineTimer может потребоваться преобразовать свой внутренний источник времени в источник времени, используемый объектом time_point. Также обратите внимание, что из-за этого преобразования сроки не будут точными, поэтому ожидается, что следующий код не сравнится:

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

См. также QTime, QTimer, QDeadlineTimer и Qt::TimerType.

Документация по типам членов

enum QDeadlineTimer::ForeverConstant

Документация по функциям-членам

QDeadlineTimer::QDeadlineTimer(Qt::TimerType timerType = Qt::CoarseTimer)

Конструирует объект QDeadlineTimer, который уже истек. Для этого объекта remainingTime() вернёт 0.

Тип таймера timerType может быть проигнорирован, так как таймер уже истек. Аналогично, в целях оптимизации, эта функция не будет пытаться получить текущее время и будет использовать значение, известное как прошедшее. Поэтому, deadline() может вернуть неожиданное значение, и этот объект нельзя использовать для расчёта того, как долго он просрочен. Если требуется эта функциональность, используйте QDeadlineTimer::current().

См. также hasExpired(), remainingTime(), Qt::TimerType и current().

QDeadlineTimer::QDeadlineTimer(QDeadlineTimer::ForeverConstant, Qt::TimerType timerType = Qt::CoarseTimer)

Объекты QDeadlineTimer, созданные с помощью ForeverConstant, никогда не истекают. Для таких объектов remainingTime() вернёт -1, deadline() вернёт максимальное значение, а isForever() вернёт true.

Тип таймера timerType может быть проигнорирован, так как таймер уже истек.

См. также ForeverConstant, hasExpired(), isForever(), remainingTime() и timerType().

QDeadlineTimer::QDeadlineTimer(qint64 msecs, Qt::TimerType type = Qt::CoarseTimer)

Создаёт объект QDeadlineTimer со сроком истечения через msecs мс от момента создания объекта, если msecs положительное. Если msecs равно нулю, этот QDeadlineTimer будет помечен как истекший, что приведет к возврату 0 от remainingTime() и неопределенного значения в прошлом от deadline(). Если msecs равно -1, таймер будет установлен на никогда не истекающий, что приведет к возврату -1 от remainingTime() и максимального значения от deadline().

Объект QDeadlineTimer будет создан с указанным типом таймера type.

В целях оптимизации, если msecs равно нулю, эта функция может пропустить получение текущего времени и вместо этого использовать известное прошедшее значение. Если это произойдёт, deadline() может вернуть неожиданное значение, и этот объект нельзя использовать для расчёта того, как долго он просрочен. Если требуется эта функциональность, используйте QDeadlineTimer::current() и добавьте время к нему.

См. также hasExpired(), isForever(), remainingTime() и setRemainingTime().

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

Создаёт объект QDeadlineTimer со сроком действия в момент времени deadline, преобразуя его из источника времени Clock во внутренний источник времени Qt (см. QElapsedTimer::clockType()).

Если deadline лежит в прошлом, этот объект QDeadlineTimer устанавливается в истекший, а если deadline равно Duration::max(), то этот объект устанавливается на никогда не истекающий.

Объект QDeadlineTimer будет создан с указанным типом таймера type.

См. также hasExpired(), isForever(), remainingTime() и setDeadline().

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

Создаёт объект QDeadlineTimer с оставшимся временем remaining. Если remaining равно нулю или отрицательно, этот объект QDeadlineTimer будет помечен как истекший, а если remaining равно duration::max(), объект будет установлен на никогда не истекающий.

Объект QDeadlineTimer будет создан с указанным типом таймера type.

Этот конструктор может быть использован с пользовательскими литералами времени C++14, например:

using namespace std::chrono_literals;
QDeadlineTimer deadline(250ms);

В целях оптимизации, если remaining равно нулю или отрицательно, эта функция может пропустить получение текущего времени и вместо этого использовать известное прошедшее значение. Если это произойдёт, deadline() может вернуть неожиданное значение, и этот объект нельзя использовать для расчёта того, как долго он просрочен. Если требуется эта функциональность, используйте QDeadlineTimer::current() и добавьте время к нему.

См. также hasExpired(), isForever(), remainingTime() и setRemainingTime().

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

Возвращает объект QDeadlineTimer, срок действия которого продлён от срока действия dt на nsecs наносекунд. Если dt был установлен на никогда не истекающий, эта функция возвращает QDeadlineTimer, который также не будет истекать.

Примечание: если dt был создан как истекший, его срок действия неопределён, и добавление времени может или не может привести к тому, что он станет неистекшим.

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

Возвращает QDeadlineTimer, который истек, но гарантированно содержит текущее время. Объекты, созданные этой функцией, могут участвовать в расчёте того, как долго таймер просрочен, используя функцию deadline().

Объект QDeadlineTimer будет создан с указанным timerType.

qint64 QDeadlineTimer::deadline() const

Возвращает абсолютный момент времени для срока действия, хранящегося в объекте QDeadlineTimer, рассчитанный в миллисекундах относительно эталонных часов, аналогично QElapsedTimer::msecsSinceReference(). Значение будет в прошлом, если у этого QDeadlineTimer истек срок действия.

Если у этого QDeadlineTimer срок действия никогда не истекает, эта функция возвращает std::numeric_limits<qint64>::max().

Эту функцию можно использовать для расчета времени, на которое таймер опоздал, вычитая QDeadlineTimer::current() или QElapsedTimer::msecsSinceReference(), как в приведённом ниже примере:

qint64 realTimeLeft = deadline.deadline();
if (realTimeLeft != (std::numeric_limits<qint64>::max)()) {
    realTimeLeft -= QDeadlineTimer::current().deadline();
    // or:
    //QElapsedTimer timer;
    //timer.start();
    //realTimeLeft -= timer.msecsSinceReference();
}

Примечание: Таймеры, созданные как истекшие, имеют неопределённую точку времени в прошлом как крайний срок, поэтому вышеупомянутое вычисление может не сработать.

См. также remainingTime(), deadlineNSecs() и setDeadline().

qint64 QDeadlineTimer::deadlineNSecs() const

Возвращает абсолютную точку времени крайнего срока, хранящегося в объекте QDeadlineTimer, вычисленную в наносекундах относительно системных часов, как и QElapsedTimer::msecsSinceReference(). Значение будет в прошлом, если этот QDeadlineTimer истек.

Если этот QDeadlineTimer никогда не истечёт, эта функция возвращает std::numeric_limits<qint64>::max().

Эту функцию можно использовать для расчета времени, на которое таймер опоздал, вычитая QDeadlineTimer::current(), как в приведённом ниже примере:

qint64 realTimeLeft = deadline.deadlineNSecs();
if (realTimeLeft != std::numeric_limits<qint64>::max())
    realTimeLeft -= QDeadlineTimer::current().deadlineNSecs();

Примечание: Таймеры, созданные как истекшие, имеют неопределённую точку времени в прошлом как крайний срок, поэтому вышеупомянутое вычисление может не сработать.

См. также remainingTime() и deadlineNSecs().

bool QDeadlineTimer::hasExpired() const

Возвращает true, если этот объект QDeadlineTimer истек, false, если осталось время. Для объектов, истекших, remainingTime() вернёт ноль, а deadline() вернёт точку времени в прошлом.

Объекты QDeadlineTimer, созданные с ForeverConstant, никогда не истекают, и эта функция всегда возвращает false для них.

См. также isForever() и remainingTime().

bool QDeadlineTimer::isForever() const

Возвращает true, если этот объект QDeadlineTimer никогда не истекает, false в противном случае. Для таймеров, которые никогда не истекают, remainingTime() всегда возвращает -1, а deadline() возвращает максимальное значение.

См. также ForeverConstant, hasExpired() и remainingTime().

qint64 QDeadlineTimer::remainingTime() const

Возвращает оставшееся время в объекте QDeadlineTimer в миллисекундах. Если таймер уже истек, эта функция вернёт ноль, и невозможно получить количество времени опоздания с помощью этой функции (для этого см. deadline()). Если таймер был установлен на никогда не истекающий, эта функция возвращает -1.

Эта функция подходит для использования в API Qt, которые принимают таймаут в миллисекундах, например, во многих функциях QIODevice waitFor или функциях блокировки с таймаутом в QMutex, QWaitCondition, QSemaphore или QReadWriteLock. Например:

mutex.tryLock(deadline.remainingTime());

См. также setRemainingTime(), remainingTimeNSecs(), isForever() и hasExpired().

std::chrono::nanoseconds QDeadlineTimer::remainingTimeAsDuration() const

Возвращает время, оставшееся до крайнего срока.

qint64 QDeadlineTimer::remainingTimeNSecs() const

Возвращает оставшееся время в объекте QDeadlineTimer в наносекундах. Если таймер уже истек, эта функция вернёт ноль, и невозможно получить количество времени опоздания с помощью этой функции. Если таймер был установлен на никогда не истекающий, эта функция возвращает -1.

См. также remainingTime(), isForever() и hasExpired().

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

Устанавливает крайний срок для этого объекта QDeadlineTimer на абсолютную точку времени msecs, отсчитываемую в миллисекундах с момента начала отсчёта (так же, как QElapsedTimer::msecsSinceReference()), и тип таймера на timerType. Если значение находится в прошлом, этот QDeadlineTimer будет помечен как истекший.

Если msecs равно std::numeric_limits<qint64>::max(), этот QDeadlineTimer будет установлен на никогда не истекающий.

См. также setPreciseDeadline(), deadline(), deadlineNSecs() и setRemainingTime().

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

Устанавливает этому QDeadlineTimer крайний срок, заданный точкой времени deadline, конвертируя из источника времени Clock во внутренний источник времени Qt (см. QElapsedTimer::clockType()).

Если deadline находится в прошлом, этот QDeadlineTimer устанавливается в истекший, а если deadline равно Duration::max(), то этот объект устанавливается на никогда не истекающий.

Тип таймера для этого объекта QDeadlineTimer будет установлен на указанный type.

См. также hasExpired(), isForever() и remainingTime().

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

Устанавливает крайний срок для этого объекта QDeadlineTimer на secs секунд и nsecs наносекунд с момента начала отсчёта (так же, как QElapsedTimer::msecsSinceReference()), и тип таймера на timerType. Если значение находится в прошлом, этот QDeadlineTimer будет помечен как истекший.

Если secs или nsecs равно std::numeric_limits<qint64>::max(), этот QDeadlineTimer будет установлен на никогда не истекающий. Если nsecs больше 1 миллиарда наносекунд (1 секунды), то secs будет скорректировано соответственно.

См. также setDeadline(), deadline(), deadlineNSecs() и setRemainingTime().

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

Устанавливает оставшееся время для этого объекта QDeadlineTimer на secs секунд и nsecs наносекунд от текущего момента, если secs имеет положительное значение. Если secs равно -1, этот QDeadlineTimer будет установлен на никогда не истекающий. Если оба параметра равны нулю, этот QDeadlineTimer будет помечен как истекший.

Тип таймера для этого объекта QDeadlineTimer будет установлен на указанный timerType.

См. также setRemainingTime(), hasExpired(), isForever() и remainingTime().

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

Устанавливает оставшееся время для этого объекта QDeadlineTimer на msecs миллисекунд с текущего момента, если msecs имеет положительное значение. Если msecs равно нулю, этот QDeadlineTimer будет помечен как истекший, а значение -1 установит его на никогда не истекающий.

Тип таймера для этого объекта QDeadlineTimer будет установлен на указанный timerType.

См. также setPreciseRemainingTime(), hasExpired(), isForever() и remainingTime().

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

Это перегруженная функция.

Устанавливает оставшееся время для этого QDeadlineTimer на remaining. Если remaining равно нулю или отрицательно, этот QDeadlineTimer будет помечен как истекший, а если remaining равно duration::max(), объект будет установлен на никогда не истекающий.

Тип таймера для этого объекта QDeadlineTimer будет установлен на указанный тип type.

Эта функция может быть использована с пользовательскими литералами времени C++14, например:

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

Примечание: Qt определяет необходимую поддержку компилятора C++14, руководствуясь рекомендациями по проверке функций из Постоянного документа 6 Комитета по C++.

См. также setDeadline(), remainingTime(), hasExpired(), и isForever().

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

Изменяет тип таймера для этого объекта на timerType.

Поведение для каждого возможного значения timerType зависит от операционной системы. Qt::PreciseTimer будет использовать наиболее точный таймер, который Qt может найти, с разрешением 1 миллисекунда или лучше, тогда как QDeadlineTimer будет пытаться использовать более грубый таймер для Qt::CoarseTimer и Qt::VeryCoarseTimer.

См. также timerType() и Qt::TimerType.

void QDeadlineTimer::swap(QDeadlineTimer &other)

Меняет местами таймер отсчёта этого объекта с таймером отсчёта other.

Qt::TimerType QDeadlineTimer::timerType() const

Возвращает тип таймера, активный для этого объекта.

См. также setTimerType().

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

Удлиняет этот объект QDeadlineTimer на msecs миллисекунд и возвращает сам себя. Если этому объекту установлено никогда не истекать, эта функция ничего не делает.

Для добавления времен с точностью более 1 миллисекунды используйте addNSecs().

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

Укорачивает этот объект QDeadlineTimer на msecs миллисекунд и возвращает сам себя. Если этому объекту установлено никогда не истекать, эта функция ничего не делает.

Для вычитания времен с точностью более 1 миллисекунды используйте addNSecs().

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

Присваивает deadline_ этому таймеру отсчёта.

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

Устанавливает таймер отсчёта на оставшееся время remaining.

return d1.deadlineNSecs() != d2.deadlineNSecs();

return d1.deadlineNSecs() < d2.deadlineNSecs();

return d1.deadlineNSecs() <= d2.deadlineNSecs();

return d1.deadlineNSecs() == d2.deadlineNSecs();

return d1.deadlineNSecs() > d2.deadlineNSecs();

return d1.deadlineNSecs() >= d2.deadlineNSecs();