Класс 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, чья отметка времени расширена от дедлайна 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().

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();