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

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