Класс QElapsedTimer

Класс QElapsedTimer предоставляет быстрый способ вычисления прошедших времен. Подробнее...

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

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

Типы публичного доступа

Функции публичного доступа

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

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

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

Класс QElapsedTimer предоставляет быстрый способ вычисления прошедших времен.

Класс QElapsedTimer обычно используется для быстрого вычисления времени, прошедшего между двумя событиями. Его API похож на API класса QTime, поэтому код, использующий его, можно быстро перенести на новый класс.

Однако, в отличие от QTime, QElapsedTimer пытается использовать монотонные часы, если это возможно. Это означает, что невозможно преобразовать объекты QElapsedTimer в читаемое человеком время.

Типичным случаем использования класса является определение времени, затраченного на медленную операцию. Самый простой пример такого случая — для отладки, как в следующем примере:

    QElapsedTimer timer;
    timer.start();

    slowOperation1();

    qDebug() << "The slow operation took" << timer.elapsed() << "milliseconds";

В этом примере таймер запускается вызовом start(), а прошедшее время вычисляется функцией elapsed().

Прошедшее время также можно использовать для перерасчета времени, доступного для другой операции после завершения первой. Это полезно, когда выполнение должно завершиться в определенный период времени, но для этого требуются несколько шагов. Функции типа waitFor в QIODevice и его подклассах являются хорошими примерами такой необходимости. В этом случае код может быть следующим:

void executeSlowOperations(int timeout)
{
    QElapsedTimer timer;
    timer.start();
    slowOperation1();

    int remainingTime = timeout - timer.elapsed();
    if (remainingTime > 0)
        slowOperation2(remainingTime);
}

Еще один случай использования — выполнение определенной операции в течение определенного временного интервала. Для этого QElapsedTimer предоставляет удобную функцию hasExpired(), которая может использоваться для определения, истекло ли определенное количество миллисекунд:

void executeOperationsForTime(int ms)
{
    QElapsedTimer timer;
    timer.start();

    while (!timer.hasExpired(ms))
        slowOperation1();
}

В этом случае часто удобнее использовать QDeadlineTimer, который отсчитывает время до таймаута в будущем, а не отслеживает прошедшее время.

Справочные часы

QElapsedTimer будет использовать монотонные часы платформы на всех платформах, которые их поддерживают (см. QElapsedTimer::isMonotonic()). Это добавляет преимущество, что QElapsedTimer невосприимчив к корректировкам времени, например, к исправлению времени пользователем. В отличие от QTime, QElapsedTimer невосприимчив к изменениям настроек часового пояса, например, к периодам перехода на летнее время.

С другой стороны, это означает, что значения QElapsedTimer можно сравнивать только со значениями, использующими ту же ссылку. Это особенно актуально, если значение времени с момента ссылки извлекается из объекта QElapsedTimer (QElapsedTimer::msecsSinceReference()) и сериализуется. Эти значения никогда не следует обменивать через сеть или сохранять на диск, так как нельзя сказать, является ли узел компьютера, получающий данные, таким же, как узел, который их отправляет, или компьютер перезагрузился с момента отправки.

Однако обмен значениями с другими процессами на том же компьютере возможен, при условии, что они также используют те же справочные часы. QElapsedTimer всегда использует одни и те же часы, поэтому сравнение со значением, полученным из другого процесса на одном компьютере, безопасно. Если вы сравниваете значения с другими API, убедитесь, что используемые часы совпадают с QElapsedTimer (см. QElapsedTimer::clockType()).

Переполнения 32-битных значений

Некоторые из часов, используемых QElapsedTimer, имеют ограниченный диапазон и могут переполниться после достижения максимального значения (обычно 32-битное). QElapsedTimer обрабатывает проблему переполнения и предоставляет согласованное измерение времени. Однако при извлечении значения времени с момента ссылки из QElapsedTimer два разных процесса на одном компьютере могут по-разному понимать, сколько времени фактически прошло.

Информация о типах часов, которые могут переполниться, и о способах устранения этой проблемы описана вместе с типами часов.

См. также QTime, QTimer и QDeadlineTimer.

Документация по типам членов

перечисление QElapsedTimer::ClockType

Это перечисление содержит различные типы часов, которые может использовать QElapsedTimer.

QElapsedTimer всегда использует один и тот же тип часов на конкретном компьютере, поэтому это значение не изменяется в течение срока действия программы. Оно предоставляется для того, чтобы QElapsedTimer можно было использовать с другими реализациями, не связанными с Qt, для гарантии использования одной и той же справочной шкалы времени.

SystemTime

Часы системного времени — это чисто реальное время, выраженное в миллисекундах с момента 00:00 01.01.1970 UTC. Оно эквивалентно значению, возвращаемому функцией C и POSIX time, с добавленными миллисекундами. Этот тип часов в настоящее время используется только в системах Unix, не поддерживающих монотонные часы (см. ниже).

Это единственные немонотонные часы, которые QElapsedTimer может использовать.

MonotonicClock

Это монотонные часы системы, выраженные в миллисекундах с произвольной точки прошлого. Этот тип часов используется в системах Unix, которые поддерживают монотонные часы POSIX (_POSIX_MONOTONIC_CLOCK).

Эти часы не переполняются.

TickCounter

Тип часов tick counter основан на счётчике тиков системы или процессора, умноженном на продолжительность тика. Этот тип часов используется в платформах Windows. Если в Windows доступен высокоточный счётчик производительности, используется тип часов PerformanceCounter.

Тип таймера TickCounter — единственный тип таймера, который может переполниться. Windows Vista и Windows Server 2008 поддерживают расширенный 64-битный счётчик тиков, что позволяет избежать переполнения.

В системах Windows таймер переполняется после 2³² миллисекунд, что примерно соответствует 49,7 дням. Это означает, что подсчёт времени с момента отсчёта двумя процессами может отличаться на кратные 2³² миллисекунды. При сравнении таких значений рекомендуется скрыть старшие 32 бита миллисекундного отсчёта.

MachAbsoluteTime

Этот тип таймера основан на абсолютном времени, представленном ядрами Mach, например, на macOS. Этот тип таймера представлен отдельно от MonotonicClock, так как macOS и iOS также являются системами Unix и могут поддерживать POSIX-таймер с монотонным отсчётом, значения которого отличаются от абсолютного времени Mach.

Этот таймер монотонный и не переполняется.

PerformanceCounter

Этот таймер использует функции Windows QueryPerformanceCounter и QueryPerformanceFrequency для доступа к высокоточному счётчику производительности системы. Поскольку этот счётчик может быть недоступен во всех системах, QElapsedTimer автоматически переключится на таймер TickCounter, если этот таймер недоступен.

Этот таймер монотонный и не переполняется.

См. также clockType() и isMonotonic().

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

QElapsedTimer::QElapsedTimer()

Создаёт недействительный таймер QElapsedTimer. Таймер становится действительным после его запуска.

Эта функция была добавлена в Qt 5.4.

См. также isValid() и start().

[static] QElapsedTimer::ClockType QElapsedTimer::clockType()

Возвращает тип таймера, используемый этой реализацией QElapsedTimer.

См. также isMonotonic().

qint64 QElapsedTimer::elapsed() const

Возвращает количество миллисекунд, прошедших с момента последнего запуска этого таймера QElapsedTimer.

Вызов этой функции для недействительного таймера QElapsedTimer приводит к неопределённому поведению.

См. также start(), restart(), hasExpired(), isValid() и invalidate().

bool QElapsedTimer::hasExpired(qint64 timeout) const

Возвращает true, если этот таймер QElapsedTimer уже истек по timeout миллисекунд (то есть прошло более timeout миллисекунд). Значение timeout может быть -1, чтобы указать, что таймер не истекает, в этом случае функция всегда вернёт false.

См. также elapsed() и QDeadlineTimer.

void QElapsedTimer::invalidate()

Отмечает этот объект QElapsedTimer как недействительный.

Недействительный объект можно проверить с помощью isValid(). Вычисления истекшего времени таймера с недействительными данными неопределены и, вероятно, дадут странные результаты.

См. также isValid(), start() и restart().

[static] bool QElapsedTimer::isMonotonic()

Возвращает true, если это монотонный таймер, в противном случае — false. См. информацию о различных типах таймеров, чтобы понять, какие из них являются монотонными.

См. также clockType() и QElapsedTimer::ClockType.

bool QElapsedTimer::isValid() const

Возвращает false, если таймер никогда не запускался или был аннулирован вызовом invalidate().

См. также invalidate(), start() и restart().

qint64 QElapsedTimer::msecsSinceReference() const

Возвращает количество миллисекунд между последним запуском этого объекта QElapsedTimer и началом его опорного таймера.

Это число обычно произвольное для всех таймеров, кроме таймера QElapsedTimer::SystemTime. Для этого типа таймера это количество миллисекунд с 1 января 1970 года в 0:00 по UTC (то есть это время Unix, выраженное в миллисекундах).

В Linux, Windows и Apple платформах это значение обычно представляет время с момента загрузки системы, хотя оно обычно не включает время, потраченное системой в спящих состояниях.

См. также clockType() и elapsed().

qint64 QElapsedTimer::msecsTo(const QElapsedTimer &other) const

Возвращает количество миллисекунд между этим таймером QElapsedTimer и other. Если other был запущен раньше этого объекта, возвращаемое значение будет отрицательным. Если он был запущен позже, возвращаемое значение будет положительным.

Возвращаемое значение неопределено, если этот объект или other были аннулированы.

См. также secsTo() и elapsed().

qint64 QElapsedTimer::nsecsElapsed() const

Возвращает количество наносекунд, прошедших с момента последнего запуска этого таймера QElapsedTimer.

Вызов этой функции для недействительного таймера QElapsedTimer приводит к неопределённому поведению.

В платформах, которые не обеспечивают разрешение наносекунд, возвращаемое значение будет наилучшей доступной оценкой.

Эта функция была добавлена в Qt 4.8.

См. также start(), restart(), hasExpired() и invalidate().

qint64 QElapsedTimer::restart()

Перезапускает таймер и возвращает время, прошедшее с момента предыдущего запуска. Эта функция эквивалентна получению истекшего времени с помощью elapsed() и последующему повторному запуску таймера с помощью start(), но делает это в одной операции, избегая необходимости получения значения таймера дважды.

Вызов этой функции для недействительного таймера QElapsedTimer приводит к неопределённому поведению.

Следующий пример иллюстрирует, как использовать эту функцию для калибровки параметра для медленной операции (например, счётчика итераций), чтобы эта операция занимала не менее 250 миллисекунд:

    QElapsedTimer timer;

    int count = 1;
    timer.start();
    do {
        count *= 2;
        slowOperation2(count);
    } while (timer.restart() < 250);

    return count;

См. также start(), invalidate(), elapsed() и isValid().

qint64 QElapsedTimer::secsTo(const QElapsedTimer &other) const

Возвращает количество секунд между этим таймером QElapsedTimer и other. Если other был запущен раньше этого объекта, возвращаемое значение будет отрицательным. Если он был запущен позже, возвращаемое значение будет положительным.

Вызов этой функции для или с недействительным таймером QElapsedTimer приводит к неопределённому поведению.

См. также msecsTo() и elapsed().

void QElapsedTimer::start()

Запускает этот таймер. После запуска значение таймера можно проверить с помощью elapsed() или msecsSinceReference().

Обычно таймер запускается непосредственно перед длительной операцией, например:

    QElapsedTimer timer;
    timer.start();

    slowOperation1();

    qDebug() << "The slow operation took" << timer.elapsed() << "milliseconds";

Также запуск таймера делает его снова действительным.

См. также restart(), invalidate() и elapsed().

bool QElapsedTimer::operator!=(const QElapsedTimer &other) const

Возвращает true, если этот объект и other содержат разные времена.

bool QElapsedTimer::operator==(const QElapsedTimer &other) const

Возвращает true, если этот объект и other содержат одинаковое время.