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

Часы системного времени — это чисто реальное время, выраженное в миллисекундах с момента 01.01.1970 00:00 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] 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 содержат одинаковое значение времени.