Класс QElapsedTimer

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

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

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

Типы public

Функции public

Статические public члены

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

Класс 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();
}

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

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

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

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

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

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

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

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

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

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

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

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

SystemTime

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

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

MonotonicClock

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

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

TickCounter

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

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

В системах Windows часы переполняются после 2^32 миллисекунд, что соответствует примерно 49,7 дням. Это означает, что отсчёт времени с момента ссылки у двух процессов на одном компьютере может отличаться на кратные 2^32 миллисекунд. При сравнении таких значений рекомендуется отбросить старшие 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] 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().

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 содержат одинаковое время.