std.datetime.stopwatch

Модуль, содержащий некоторые базовые функции для бенчмаркинга и измерения времени.

Для удобства этот модуль публично импортирует core.time.

import std.datetime;
import std.datetime.stopwatch : benchmark, StopWatch;

Лицензия:

Лицензия Boost 1.0.

Авторы:

Jonathan M Davis и Kato Shoichi

Исходный код

std/datetime/stopwatch.d

alias AutoStart = std.typecons.Flag!"autoStart".Flag;

Используется StopWatch для указания, должен ли он начинаться сразу после создания.

Если установлено значение AutoStart.no, то StopWatch не запускается при создании.

В противном случае, если установлено значение AutoStart.yes, то StopWatch запускается при создании.

struct StopWatch;

StopWatch используется для измерения времени так же, как это делается с физическими секундомером, включая остановку, перезапуск и/или сброс.

core.time.MonoTime используется для хранения времени, и он использует монотонные часы системы, которые имеют высокую точность и никогда не отсчитывают время назад (в отличие от времени реальных часов, которое может отсчитывать время назад, поэтому std.datetime.systime.SysTime не следует использовать для измерения времени).

Обратите внимание, что точность StopWatch различается в зависимости от системы. Невозможно, чтобы она была одинаковой для всех систем, так как точность системных часов и другие зависящие от системы и ситуации факторы (например, накладные расходы на контекстный переход между потоками) отличаются в зависимости от системы и могут повлиять на точность StopWatch.

Примеры:

Измерьте время в миллисекундах, микросекундах или наносекундах

auto sw = StopWatch(AutoStart.no);
sw.start();
// ... Insert operations to be timed here ...
sw.stop();

long msecs = sw.peek.total!"msecs";
long usecs = sw.peek.total!"usecs";
long nsecs = sw.peek.total!"nsecs";

assert(usecs >= msecs * 1000);
assert(nsecs >= usecs * 1000);

Примеры:

import core.thread : Thread;

auto sw = StopWatch(AutoStart.yes);

Duration t1 = sw.peek();
Thread.sleep(usecs(1));
Duration t2 = sw.peek();
assert(t2 > t1);

Thread.sleep(usecs(1));
sw.stop();

Duration t3 = sw.peek();
assert(t3 > t2);
Duration t4 = sw.peek();
writeln(t3); // t4

sw.start();
Thread.sleep(usecs(1));

Duration t5 = sw.peek();
assert(t5 > t4);

// If stopping or resetting the StopWatch is not required, then
// MonoTime can easily be used by itself without StopWatch.
auto before = MonoTime.currTime;
// do stuff...
auto timeElapsed = MonoTime.currTime - before;

nothrow @nogc @safe this(AutoStart autostart);

Создаёт StopWatch. Его мгновенный запуск зависит от аргумента AutoStart.

Если StopWatch.init используется, то созданный StopWatch не работает (и не может работать, поскольку ни один конструктор не запустился).

Примеры:

import core.thread : Thread;

{
    auto sw = StopWatch(AutoStart.yes);
    assert(sw.running);
    Thread.sleep(usecs(1));
    assert(sw.peek() > Duration.zero);
}
{
    auto sw = StopWatch(AutoStart.no);
    assert(!sw.running);
    Thread.sleep(usecs(1));
    writeln(sw.peek()); // Duration.zero
}
{
    StopWatch sw;
    assert(!sw.running);
    Thread.sleep(usecs(1));
    writeln(sw.peek()); // Duration.zero
}

writeln(StopWatch.init); // StopWatch(AutoStart.no)
assert(StopWatch.init != StopWatch(AutoStart.yes));

nothrow @nogc @safe void reset();

Сбрасывает StopWatch.

StopWatch можно сбросить, когда он работает, и сброс его во время работы не заставит его остановиться.

Примеры:

import core.thread : Thread;

auto sw = StopWatch(AutoStart.yes);
Thread.sleep(usecs(1));
sw.stop();
assert(sw.peek() > Duration.zero);
sw.reset();
writeln(sw.peek()); // Duration.zero

nothrow @nogc @safe void start();

Запускает StopWatch.

start не должен вызываться, если StopWatch уже работает.

Примеры:

import core.thread : Thread;

StopWatch sw;
assert(!sw.running);
writeln(sw.peek()); // Duration.zero
sw.start();
assert(sw.running);
Thread.sleep(usecs(1));
assert(sw.peek() > Duration.zero);

nothrow @nogc @safe void stop();

Останавливает StopWatch.

stop не должен вызываться, если StopWatch не работает.

Примеры:

import core.thread : Thread;

auto sw = StopWatch(AutoStart.yes);
assert(sw.running);
Thread.sleep(usecs(1));
immutable t1 = sw.peek();
assert(t1 > Duration.zero);

sw.stop();
assert(!sw.running);
immutable t2 = sw.peek();
assert(t2 >= t1);
immutable t3 = sw.peek();
writeln(t2); // t3

const nothrow @nogc @safe Duration peek();

Просмотреть количество времени, в течение которого StopWatch работал.

Это не включает время, в течение которого StopWatch был остановлен, но включает все время, в течение которого он работал, а не только время с момента последнего запуска.

Вызов reset сбросит это значение до Duration.zero.

Примеры:

import core.thread : Thread;

auto sw = StopWatch(AutoStart.no);
writeln(sw.peek()); // Duration.zero
sw.start();

Thread.sleep(usecs(1));
assert(sw.peek() >= usecs(1));

Thread.sleep(usecs(1));
assert(sw.peek() >= usecs(2));

sw.stop();
immutable stopped = sw.peek();
Thread.sleep(usecs(1));
writeln(sw.peek()); // stopped

sw.start();
Thread.sleep(usecs(1));
assert(sw.peek() > stopped);

nothrow @nogc @safe void setTimeElapsed(Duration timeElapsed);

Устанавливает общее время работы StopWatch (т.е. то, что возвращает peek).

StopWatch не обязательно должен быть остановлен для вызова setTimeElapsed, и его вызов не заставит StopWatch остановиться.

Примеры:

import core.thread : Thread;

StopWatch sw;
sw.setTimeElapsed(hours(1));

// As discussed in MonoTime's documentation, converting between
// Duration and ticks is not exact, though it will be close.
// How exact it is depends on the frequency/resolution of the
// system's monotonic clock.
assert(abs(sw.peek() - hours(1)) < usecs(1));

sw.start();
Thread.sleep(usecs(1));
assert(sw.peek() > hours(1) + usecs(1));

const pure nothrow @nogc @property @safe bool running();

Возвращает значение true, если StopWatch в настоящее время работает, иначе false.

Примеры:

StopWatch sw;
assert(!sw.running);
sw.start();
assert(sw.running);
sw.stop();
assert(!sw.running);

Duration[fun.length] benchmark(fun...)(uint n);

Оценивает производительность кода для оценки и сравнения скорости.

Параметры:

fun	псевдонимы вызываемых объектов (например, имена функций). Каждый вызываемый объект не должен принимать аргументы.
uint n	Число раз, которое каждая функция должна быть выполнена.

Возвращаемое значение:

Время (в виде core.time.Duration), затраченное на вызов каждой функции n раз. Первое значение — это время, затраченное на вызов fun[0] n раз. Второе значение — это время, затраченное на вызов fun[1] n раз. И т.д.

Примеры:

import std.conv : to;

int a;
void f0() {}
void f1() { auto b = a; }
void f2() { auto b = to!string(a); }
auto r = benchmark!(f0, f1, f2)(10_000);
Duration f0Result = r[0]; // time f0 took to run 10,000 times
Duration f1Result = r[1]; // time f1 took to run 10,000 times
Duration f2Result = r[2]; // time f2 took to run 10,000 times