Класс 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 совместим с std::chrono API из 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

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

template <typename Rep, typename Period> 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().

template <typename Clock, typename Duration> 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(qint64 msecs, Qt::TimerType type = Qt::CoarseTimer)

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

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

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

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

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

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

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

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

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

Создаёт истекший объект QDeadlineTimer. Для этого объекта remainingTime() возвращает 0.

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

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

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

Возвращает объект QDeadlineTimer, срок действия которого продлён на nsecs наносекунд от срока действия dt. Если 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().

template <typename Clock, typename Duration> 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().

template <typename Rep, typename Period> 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().

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

Присваивает deadline_ этому таймеру истечения срока действия.

template <typename Rep, typename Period> 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();