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

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