Класс QElapsedTimer

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

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

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

Типы public

Функции public

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

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

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

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

MachAbsoluteTime

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

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

PerformanceCounter

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

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

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

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

[since 5.4] 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 приводит к неопределённому поведению.

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

См. также 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().