microbench

README

Go support for running microbenchmarks

For API usage and examples, see

Documentation

Overview

Package microbench provides support for simple microbenchmark. It supports benchmarks that have some set-up and cleanup for each iteration.

Example usage:

  import(
	"github.com/terry-sm/gometastore/microbench"
  )

func benchSomething(warmup int, iterations int) *microbench.Stats {
	return microbench.Measure(
		func() { do_some_setup() },
		func() { do_some_work_to_measure },
		func() { do_some_cleanup() },
		warmup, iterations)
}

Index

• type BenchmarkSuite
  • func MakeBenchmarkSuite(scale int, sanitize bool) *BenchmarkSuite
  • func (b *BenchmarkSuite) Add(name string, f Runner) *BenchmarkSuite
  • func (b *BenchmarkSuite) Display(buffer *bytes.Buffer)
  • func (b *BenchmarkSuite) DisplayCSV(buffer *bytes.Buffer, separator string)
  • func (b *BenchmarkSuite) GetResults() map[string]*Stats
  • func (b *BenchmarkSuite) List() []string
  • func (b *BenchmarkSuite) Run() *BenchmarkSuite
  • func (b *BenchmarkSuite) RunSelected(names []string) *BenchmarkSuite
• type Runner
• type Stats
  • func MakeStats() *Stats
  • func Measure(pre func(), what func(), post func(), warmupCount int, iterations int) *Stats
  • func MeasureSimple(f func(), warmup int, iterations int) *Stats
  • func (dt *Stats) Add(val float64)
  • func (dt *Stats) Max() float64
  • func (dt *Stats) Mean() float64
  • func (dt *Stats) Min() float64
  • func (dt *Stats) Sanitized() *Stats
  • func (dt *Stats) StDev() float64
  • func (dt *Stats) Write(buffer *bytes.Buffer)

Examples

• Measure
• MeasureSimple
• Stats.Max
• Stats.Min

Types

type BenchmarkSuite

type BenchmarkSuite struct {
	// contains filtered or unexported fields
}

BenchmarkSuite is a collection of individual benchmarks. Each benchmark has a name, associated Runner and associated Stats once it is executed.

func MakeBenchmarkSuite

func MakeBenchmarkSuite(scale int, sanitize bool) *BenchmarkSuite

MakeBenchmarkSuite returns a new instance of BenchmarkSuite. Parameters:

scale - time scale (1 means results are collected in nanoseconds, 1000 means milliseconds, etc).
sanitize - if true, outliers are removed when results are presented.

func (*BenchmarkSuite) Add

func (b *BenchmarkSuite) Add(name string, f Runner) *BenchmarkSuite

Add benchmark to the suite. Parameters:

name - benchmark name
f - benchmark runner

func (*BenchmarkSuite) Display

func (b *BenchmarkSuite) Display(buffer *bytes.Buffer)

Display benchmark results as a formatted table. Parameters:

buffer - output buffer

func (*BenchmarkSuite) DisplayCSV

func (b *BenchmarkSuite) DisplayCSV(buffer *bytes.Buffer, separator string)

DisplayCSV displays results in CSV format Parameters:

buffer - output buffer
separator - column separator

func (*BenchmarkSuite) GetResults

func (b *BenchmarkSuite) GetResults() map[string]*Stats

GetResults returns raw test results

func (*BenchmarkSuite) List

func (b *BenchmarkSuite) List() []string

List returns list of benchmarks names

func (*BenchmarkSuite) Run

func (b *BenchmarkSuite) Run() *BenchmarkSuite

Run all benchmarks in the suite

func (*BenchmarkSuite) RunSelected

func (b *BenchmarkSuite) RunSelected(names []string) *BenchmarkSuite

RunSelected runs only selected banchmarks

type Runner

type Runner func() *Stats

Runner is any function that produces Stats.

type Stats

type Stats struct {
	// contains filtered or unexported fields
}

Stats is simply a collection of datapoints with various methods to calculate statistics

func MakeStats

func MakeStats() *Stats

MakeStats returns a new Stats object

func Measure

func Measure(pre func(), what func(), post func(), warmupCount int, iterations int) *Stats

Measure calls given function f multiple times and returns times for each run. Each iteration has 3 phases:

setup - prepares the test
test - actual test
cleanup - cleans up after the test

Measurement has a warmup phase during which times are not collected and execution phase during which actual times are collected. Params:

pre - setup function, may be nil
what - actual test function, must be non-nil
post - cleanup function, may be nil
warmup - number of warmup iterations
iterations - number of measured iterations

Example

microbench.Measure(
	func() {
		fmt.Print(" pretest")
	},
	func() {
		fmt.Print(" test")
	},
	func() {
		fmt.Print(" cleanup")
	}, 1, 1)

Output:

pretest test cleanup pretest test cleanup

func MeasureSimple

func MeasureSimple(f func(), warmup int, iterations int) *Stats

MeasureSimple calls given function f multiple times and returns times for each run. It has a warmup phase during which times are not collected and execution phase during which actual times are collected. Params:

warmup - number of warmup iterations
iterations - number of measured iterations

Example

microbench.MeasureSimple(func() {
	fmt.Print("hello ")
}, 1, 2)

Output:

hello hello hello

func (*Stats) Add

func (dt *Stats) Add(val float64)

Add a new datapoint to stats collection.

func (*Stats) Max

func (dt *Stats) Max() float64

Max computes the maximum value of datapoints

Example

stats := microbench.MakeStats()
stats.Add(1.0)
stats.Add(2.0)
fmt.Println("max =", stats.Max())

Output:

max = 2

func (*Stats) Mean

func (dt *Stats) Mean() float64

Mean computes the mean value of data

func (*Stats) Min

func (dt *Stats) Min() float64

Min computes the minimum value of datapoints

Example

stats := microbench.MakeStats()
stats.Add(1.0)
stats.Add(2.0)
fmt.Println("min =", stats.Min())

Output:

min = 1

func (*Stats) Sanitized

func (dt *Stats) Sanitized() *Stats

Sanitized returns sanitized statistics which has any datapoints outside of mean +/- stdev removed.

func (*Stats) StDev

func (dt *Stats) StDev() float64

StDev computes the standard deviation of datapoints.

func (*Stats) Write

func (dt *Stats) Write(buffer *bytes.Buffer)

Write writes data as string representation, one per line