Home Original page

hrtime package - github.com/loov/hrtime - Go Packages

Package hrtime implements High-Resolution Timing functions for benchmarking.

`hrtime` relies on using the best timing mechanism on a particular system. At the moment, for Windows it is using Performance Counters and on other platforms standard `time.Now` (since it's good enough).

Package also supports using hardware time stamp counters (TSC). They offer better accuracy and on some platforms correspond to the processor cycles. However, they are not supported on all platforms.

The basic usage of this package looks like: 

package main

import (
    "fmt"
    "github.com/loov/hrtime"
)

func main() {
    const numberOfExperiments = 4096
    bench := hrtime.NewBenchmark(numberOfExperiments)
    for bench.Next() {
        time.Sleep(10)
    }
    fmt.Println(bench.Histogram(10))
}

To see more complex examples refer to the _example folder. (https://github.com/loov/hrtime/tree/master/_example)

This section is empty.

This section is empty.

Now returns current time.Duration with best possible precision.

Now returns time offset from a specific time. The values aren't comparable between computer restarts or between computers.

NowPrecision returns maximum possible precision for Nanos in nanoseconds.

Overhead returns approximate overhead for a call to Now() or Since()

RDTSC returns Read Time-Stamp Counter value using RDTSC asm instruction.

If a platform doesn't support the instruction it returns 0. Use TSCSupported to check.

RDTSCP returns Read Time-Stamp Counter value using RDTSCP asm instruction.

If a platform doesn't support the instruction it returns 0. Use TSCSupported to check.

Since returns time.Duration since start

TSCSupported returns whether processor supports giving invariant time stamp counter values 

type Benchmark struct {
	
}

Benchmark helps benchmarking using time. 

package main

import (
	"fmt"
	"time"

	"github.com/loov/hrtime"
)

func main() {
	const numberOfExperiments = 4096
	bench := hrtime.NewBenchmark(numberOfExperiments)
	for bench.Next() {
		time.Sleep(1000 * time.Nanosecond)
	}
	fmt.Println(bench.Histogram(10))
}

func NewBenchmark(count int) *Benchmark

NewBenchmark creates a new benchmark using time. Count defines the number of samples to measure.

Float64s returns all measurements. 

func (bench *Benchmark) Histogram(binCount int) *Histogram

Histogram creates an histogram of all the laps.

It creates binCount bins to distribute the data and uses the 99.9 percentile as the last bucket range. However, for a nicer output it might choose a larger value.

HistogramClamp creates an historgram of all the laps clamping minimum and maximum time.

It creates binCount bins to distribute the data and uses the maximum as the last bucket.

Laps returns timing for each lap.

Name returns name of the benchmark. 

func (bench *Benchmark) Next() bool

Next starts measuring the next lap. It will return false, when all measurements have been made.

Unit returns units it measures. 

type BenchmarkTSC struct {
	
}

BenchmarkTSC helps benchmarking using CPU counters. 

package main

import (
	"fmt"
	"time"

	"github.com/loov/hrtime"
)

func main() {
	const numberOfExperiments = 4096
	bench := hrtime.NewBenchmarkTSC(numberOfExperiments)
	for bench.Next() {
		time.Sleep(1000 * time.Nanosecond)
	}
	fmt.Println(bench.Histogram(10))
}

func NewBenchmarkTSC(count int) *BenchmarkTSC

NewBenchmarkTSC creates a new benchmark using CPU counters. Count defines the number of samples to measure. 

func (bench *BenchmarkTSC) Counts() []Count

Counts returns counts for each lap.

Float64s returns all measurements as float64s 

func (bench *BenchmarkTSC) Histogram(binCount int) *Histogram

Histogram creates an histogram of all the laps.

It creates binCount bins to distribute the data and uses the 99.9 percentile as the last bucket range. However, for a nicer output it might choose a larger value.

HistogramClamp creates an historgram of all the laps clamping minimum and maximum time.

It creates binCount bins to distribute the data and uses the maximum as the last bucket.

Laps returns timing for each lap using the approximate conversion of Count.

Name returns name of the benchmark. 

func (bench *BenchmarkTSC) Next() bool

Next starts measuring the next lap. It will return false, when all measurements have been made.

Unit returns units it measures.

Count represents represents Time Stamp Counter value, when available.

Count doesn't depend on power throttling making it useful for benchmarking. However it is not reliably convertible to a reasonable time-value.

TSC reads the current Time Stamp Counter value.

Reminder: Time Stamp Count are processor specific and need to be converted to time.Duration with Count.ApproxDuration.

TSCOverhead returns overhead of Count call 

func TSCSince(start Count) Count

TSCSince returns count since start.

Reminder: Count is processor specific and need to be converted to time.Duration with Count.ApproxDuration.

ApproxDuration returns approximate conversion into a Duration.

First call to this function will do calibration and can take several milliseconds.

Histogram is a binned historgram with different statistics.

NewDurationHistogram creates a histogram from time.Duration-s. 

func NewHistogram(nanoseconds []float64, opts *HistogramOptions) *Histogram

NewHistogram creates a new histogram from the specified nanosecond values. 

func (hist *Histogram) Divide(n int)

Divide divides histogram by number of repetitions for the tests.

String returns a string representation of the histogram.

StringStats returns a string representation of the histogram stats.

WriteStatsTo writes formatted statistics to w.

WriteTo writes formatted statistics and histogram to w.

HistogramBin is a single bin in histogram 

type HistogramOptions struct {
	BinCount int
	
	NiceRange bool
	
	ClampMaximum    float64
	ClampPercentile float64
}

HistogramOptions is configuration.

Span defines a time.Duration span

Duration returns the duration of the time span. 

type SpanTSC struct {
	Start  Count
	Finish Count
}

SpanTSC defines a Count span

ApproxDuration returns the approximate duration of the span. 

func (span *SpanTSC) Count() Count

Count returns the duration in count of the count span. 

type Stopwatch struct {
	
}

Stopwatch allows concurrent benchmarking using Now 

package main

import (
	"fmt"
	"time"

	"github.com/loov/hrtime"
)

func main() {
	const numberOfExperiments = 4096
	bench := hrtime.NewStopwatch(numberOfExperiments)
	for i := 0; i < numberOfExperiments; i++ {
		go func() {
			lap := bench.Start()
			defer bench.Stop(lap)

			time.Sleep(1000 * time.Nanosecond)
		}()
	}
	bench.Wait()
	fmt.Println(bench.Histogram(10))
}

func NewStopwatch(count int) *Stopwatch

NewStopwatch creates a new concurrent benchmark using Now

Durations returns measured durations.

Float64s returns all measurements. 

func (bench *Stopwatch) Histogram(binCount int) *Histogram

Histogram creates an histogram of all the durations.

It creates binCount bins to distribute the data and uses the 99.9 percentile as the last bucket range. However, for a nicer output it might choose a larger value.

HistogramClamp creates an historgram of all the durations clamping minimum and maximum time.

It creates binCount bins to distribute the data and uses the maximum as the last bucket.

Name returns name of the benchmark. 

func (bench *Stopwatch) Spans() []Span

Spans returns measured time-spans.

Start starts measuring a new lap. It returns the lap number to pass in for Stop. It will return -1, when all measurements have been made.

Call to Stop with -1 is ignored. 

func (bench *Stopwatch) Stop(lap int32)

Stop stops measuring the specified lap.

Call to Stop with -1 is ignored.

Unit returns units it measures. 

func (bench *Stopwatch) Wait()

Wait waits for all measurements to be completed. 

type StopwatchTSC struct {
	
}

StopwatchTSC allows concurrent benchmarking using TSC 

package main

import (
	"fmt"
	"time"

	"github.com/loov/hrtime"
)

func main() {
	const numberOfExperiments = 4096
	bench := hrtime.NewStopwatchTSC(numberOfExperiments)
	for i := 0; i < numberOfExperiments; i++ {
		go func() {
			lap := bench.Start()
			defer bench.Stop(lap)

			time.Sleep(1000 * time.Nanosecond)
		}()
	}
	bench.Wait()
	fmt.Println(bench.Histogram(10))
}

func NewStopwatchTSC(count int) *StopwatchTSC

NewStopwatchTSC creates a new concurrent benchmark using TSC

ApproxDurations returns measured durations.

Float64s returns all measurements. 

func (bench *StopwatchTSC) Histogram(binCount int) *Histogram

Histogram creates an histogram of all the durations.

It creates binCount bins to distribute the data and uses the 99.9 percentile as the last bucket range. However, for a nicer output it might choose a larger value.

HistogramClamp creates an historgram of all the durations clamping minimum and maximum time.

It creates binCount bins to distribute the data and uses the maximum as the last bucket.

Name returns name of the benchmark. 

func (bench *StopwatchTSC) Spans() []SpanTSC

Spans returns measured time-spans.

Start starts measuring a new lap. It returns the lap number to pass in for Stop. It will return -1, when all measurements have been made.

Call to Stop with -1 is ignored.

Stop stops measuring the specified lap.

Call to Stop with -1 is ignored.

Unit returns units it measures. 

func (bench *StopwatchTSC) Wait()

Wait waits for all measurements to be completed.