Класс QElapsedTimer

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

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

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

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

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

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

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

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

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

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

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

enum 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

Тип часов счетчика тиков основан на счетчике тиков системы или процессора, умноженном на продолжительность тика. Этот тип часов используется в платформах 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 содержат одинаковое время.