D Programming Language 2.0

- Comments
- D
- Search
- Home

Last update Thu Oct 28 17:54:32 2010

# std.datetime

Platform-independent high precision StopWatch.

This module provide:

- StopWatch
- Benchmarks
- Some helper functions

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

Copyright © 1999-2010 by Digital Mars, All Rights Reserved | Page generated by Ddoc.