www.digitalmars.com

D Programming Language 2.0

Last update Thu Oct 28 17:54:32 2010

std.datetime

Platform-independent high precision StopWatch.

This module provide:

License:
Boost License 1.0.

Authors:
Kato Shoichi

struct Ticks;
System clock time.

This type maintains the most high precision ticks of system clock in each environment. (For StopWatch)

static immutable long ticksPerSec;
Ticks that is counted per 1[s].

Confirm that it is not 0, to examine whether you can use Ticks.

static immutable Ticks appOrigin;
Ticks when application begins.

long value;
Unknown value for Ticks

You can convert this value into number of seconds by dividing it by ticksPerSec.

T toSeconds(T)();
T toSeconds(T)();
[s] as integer or real number

Attention:
This method truncate the number of digits after decimal point.

alias seconds;
[s] as real number

alias sec;
[s] as integer

Ticks fromSeconds(T)(T sec);
Create Ticks from [s] as integer

T toMilliseconds(T)();
T toMilliseconds(T)();
[ms] as integer or real number

alias milliseconds;
[ms] as real number

alias msec;
[ms] as integer

static Ticks fromMilliseconds(long msec);
Create Ticks from [ms] as integer

T toMicroseconds(T)();
T toMicroseconds(T)();
[us] as integer or real number

alias microseconds;
[us] as real number

alias usec;
[us] as integer

static Ticks fromMicroseconds(long usec);
Create Ticks from [us] as integer

void opOpAssign(string op)(in Ticks t);
operator overroading "-=, +="

BUG:
This should be return "ref Ticks", but bug2460 prevents that.

Ticks opBinary(string op)(in Ticks t);
operator overroading "-, +"

const equals_t opEquals(ref const Ticks t);
operator overroading "=="

const int opCmp(ref const Ticks t);
operator overroading "<, >, <=, >="

void opOpAssign(string op, T)(T x);
operator overroading "*=, /="

Ticks opBinary(string op, T)(T x);
operator overroading "*", "/"

real opBinary(string op)(Ticks x);
operator overroading "/"

enum AutoStart;
Special type for constructor

no

yes

AutoStart autoStart;
StopWatch's AutoStart flag

struct StopWatch;
StopWatch measures time highly precise as possible.

This class uses performance counter. On Windows, This uses QueryPerformanceCounter. For Posix, This uses clock_gettime if available, gettimeofday otherwise.

But this has dispersion in accuracy by environment. It is impossible to remove this dispersion. This depends on multi task system for example overhead from change of the context switch of the thread.

Usage is here:

Example:
void foo() {
    StopWatch sw;
    static immutable N = 100;
    Ticks[N] times;
    Ticks last = Ticks.fromSeconds(0);
    foreach (i; 0..N) {
        sw.start(); // start/resume mesuring.
        foreach (Unused; 0..1000000) bar();
        sw.stop();  // stop/pause mesuring.
        // Return value of peek() after having stopped are the always same.
        writeln((i+1)*1000000, " times done, lap time: ",
                sw.peek().msec, "[ms]");
        times[i] = sw.peek() - last;
        last = sw.peek();
    }
    real sum = 0;
    // When you want to know the number of seconds of the fact,
    // you can use properties of Ticks.
    // (seconds, mseconds, useconds, interval)
    foreach (e; times) sum += e.interval;
    writeln("Average time: ", sum/N, "[s]");
}

this(AutoStart autostart);
auto start with constructor

void reset();
Reset the time measurement.

void start();
Start the time measurement.

void stop();
Stop the time measurement.

const Ticks peek();
Peek Ticks of measured time.

Ticks systime();
Ticks of system time.

Ticks apptime();
Ticks when application begin running.

Ticks[lengthof!(fun)()] benchmark(fun...)(uint times);
Benchmarks code for speed assessment and comparison.

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

Returns:
An array of n uints. Element at slot i contains the number of milliseconds spent in calling the ith function times times.

Examples:
int a;
void f0() { }
void f1() { auto b = a; }
void f2() { auto b = to!(string)(a); }
auto r = benchmark!(f0, f1, f2)(10_000_000);

struct ComparingBenchmarkResult;
Return value of benchmark with two functions comparing.

immutable real point();
Evaluation value

This return the evaluation value of performance as the ratio that is compared between BaseFunc's time and TargetFunc's time. If performance is high, this returns a high value.

immutable Ticks targetTime();
The time required of the target function

immutable Ticks baseTime();
The time required of the base function

ComparingBenchmarkResult comparingBenchmark(alias baseFunc, alias targetFunc, int times = 4095)();
ComparingBenchmarkResult comparingBenchmark(alias baseFunc, alias targetFunc, int times = 4095)();
Benchmark with two functions comparing.

Parameters:
baseFunc The function to become the base of the speed.
targetFunc The function that wants to measure speed.
times The number of times each function is to be executed.

Examples:
void f1() {
    // ...
}
void f2() {
    // ...
}

void main() {
    auto b = comparingBenchmark!(f1, f2, 0x80);
    writeln(b.point);
}

TemporaryValue measureTime(alias func)();
Scope base measuring time.

When a value that is returned by this function is destroyed, func will run. func is unaly function that requires Ticks.

Examples:
writeln("benchmark start!");
{
    auto mt = measureTime!((a){assert(a.seconds);});
    doSomething();
}
writeln("benchmark end!");