Класс QElapsedTimer

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

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

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

Типы публичного доступа

Функции публичного доступа

Статические публичные члены

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

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

Класс QElapsedTimer обычно используется для быстрого вычисления времени, прошедшего между двумя событиями. Его API похож на API QTime, поэтому код, использующий 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 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().