Класс QDeadlineTimer

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

Этот класс был представлен в Qt 5.8.

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

Примечание: Все функции в этом классе являются взаимоисключающими.

Общие типы

Общие функции

Статические публичные члены

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

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

Класс 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, так как на операционных системах, поддерживающих грубое (coarse) время, вызов функций тайминга для этого источника времени часто более эффективен. Степень грубости зависит от операционной системы, но должна быть порядка нескольких миллисекунд.

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

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

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 с помощью рекомендаций по тестированию возможностей из C++ Committee's Standing Document 6.

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