Класс 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

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

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 с помощью рекомендаций по тестированию возможностей из постоянного документа комитета 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();