Класс QElapsedTimer

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

Этот класс был представлен в Qt 4.7.

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

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

Типы 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 UTC 1 января 1970 года. Оно эквивалентно значению, возвращаемому функцией C и POSIX time, с добавленными миллисекундами. В настоящее время этот тип часов используется только в системах Unix, которые не поддерживают монотонные часы (см. ниже).

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

Монотонные часы

Это монотонные системные часы, выраженные в миллисекундах с момента произвольной точки прошлого. Этот тип часов используется в системах 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] 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 приводит к неопределённому поведению.

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

Эта функция была добавлена в 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 содержат одинаковое время.