Класс QElapsedTimer

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

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

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

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

Типы

Открытые функции

Статические открытые члены

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

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

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

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