Класс 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, который также не будет истекать.

[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 секунды), то 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);

См. также 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();