std.datetime.stopwatch

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

public import core.time;

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

Used by StopWatch to indicate whether it should start immediately upon construction.

If set to AutoStart.no, then the StopWatch is not started when it is constructed.

Otherwise, if set to AutoStart.yes, then the StopWatch is started when it is constructed.

struct StopWatch;

StopWatch is used to measure time just like one would do with a physical stopwatch, including stopping, restarting, and/or resetting it.

core.time.MonoTime is used to hold the time, and it uses the system's monotonic clock, which is high precision and never counts backwards (unlike the wall clock time, which can count backwards, which is why std.datetime.systime.SysTime should not be used for timing).

Note that the precision of StopWatch differs from system to system. It is impossible for it to be the same for all systems, since the precision of the system clock and other system-dependent and situation-dependent factors (such as the overhead of a context switch between threads) varies from system to system and can affect StopWatch's accuracy.

Examples:

Measure a time in milliseconds, microseconds, or nanoseconds

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);

Examples:

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);

Constructs a StopWatch. Whether it starts immediately depends on the AutoStart argument.

If StopWatch.init is used, then the constructed StopWatch isn't running (and can't be, since no constructor ran).

Examples:

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();

Resets the StopWatch.

The StopWatch can be reset while it's running, and resetting it while it's running will not cause it to stop.

Examples:

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();

Starts the StopWatch.

start should not be called if the StopWatch is already running.

Examples:

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();

Stops the StopWatch.

stop should not be called if the StopWatch is not running.

Examples:

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();

Peek at the amount of time that the the StopWatch has been running.

This does not include any time during which the StopWatch was stopped but does include all of the time that it was running and not just the time since it was started last.

Calling reset will reset this to Duration.zero.

Examples:

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);

Sets the total time which the StopWatch has been running (i.e. what peek returns).

The StopWatch does not have to be stopped for setTimeElapsed to be called, nor will calling it cause the StopWatch to stop.

Examples:

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();

Returns whether this StopWatch is currently running.

Examples:

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

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

Benchmarks code for speed assessment and comparison.

Parameters:

fun	aliases of callable objects (e.g. function names). Each callable object should take no arguments.
uint n	The number of times each function is to be executed.

Returns:

The amount of time (as a core.time.Duration) that it took to call each function n times. The first value is the length of time that it took to call fun[0] n times. The second value is the length of time it took to call fun[1] n times. Etc.

Examples:

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