testing

Documentation

Index

• func RunBenchmarks(a mem.Allocator, benchmarks []Benchmark)
• type B
  • func (b *B) Allocator() mem.Allocator
  • func (b *B) Elapsed() time.Duration
  • func (b *B) Loop() bool
  • func (b *B) ResetTimer()
  • func (b *B) SetBytes(n int64)
  • func (b *B) StartTimer()
  • func (b *B) StopTimer()
• type BenchTime
• type Benchmark
• type BenchmarkFunc
• type BenchmarkResult
  • func RunBenchmark(a mem.Allocator, f func(b *B)) BenchmarkResult
  • func (r BenchmarkResult) AllocedBytesPerOp() int64
  • func (r BenchmarkResult) AllocsPerOp() int64
  • func (r BenchmarkResult) MemString(buf []byte) string
  • func (r BenchmarkResult) NsPerOp() int64
  • func (r BenchmarkResult) String(buf []byte) string

Functions

func RunBenchmarks

func RunBenchmarks(a mem.Allocator, benchmarks []Benchmark)

RunBenchmarks runs the given benchmarks and prints the results to stdout.

Types

type B

type B struct {
	N int
	// contains filtered or unexported fields
}

B is used to manage benchmark timing and control the number of iterations.

func (*B) Allocator

func (b *B) Allocator() mem.Allocator

Allocator returns the allocator used by the benchmark. The benchmarking function should use this allocator if it wants to track memory allocations and report them in the benchmark results.

func (*B) Elapsed

func (b *B) Elapsed() time.Duration

Elapsed returns the measured elapsed time of the benchmark. The duration reported by Elapsed matches the one measured by B.StartTimer, B.StopTimer, and B.ResetTimer.

func (*B) Loop

func (b *B) Loop() bool

Loop returns true as long as the benchmark should continue running.

A typical benchmark is structured like:

func Benchmark(b *testing.B) {
	... setup ...
	for b.Loop() {
		... code to measure ...
	}
	... cleanup ...
}

Loop resets the benchmark timer the first time it is called in a benchmark, so any setup performed prior to starting the benchmark loop does not count toward the benchmark measurement. Likewise, when it returns false, it stops the timer so cleanup code is not measured.

Within the body of a "for b.Loop() { ... }" loop, arguments to and results from function calls and assigned variables within the loop are kept alive, preventing the compiler from fully optimizing away the loop body. Currently, this is implemented as a compiler transformation that wraps such variables with a runtime.KeepAlive intrinsic call. This applies only to statements syntactically between the curly braces of the loop, and the loop condition must be written exactly as "b.Loop()".

After Loop returns false, b.N contains the total number of iterations that ran, so the benchmark may use b.N to compute other average metrics.

Prior to the introduction of Loop, benchmarks were expected to contain an explicit loop from 0 to b.N. Benchmarks should either use Loop or contain a loop to b.N, but not both. Loop offers more automatic management of the benchmark timer, and runs each benchmark function only once per measurement, whereas b.N-based benchmarks must run the benchmark function (and any associated setup and cleanup) several times.

func (*B) ResetTimer

func (b *B) ResetTimer()

ResetTimer zeroes the elapsed benchmark time and memory allocation counters and deletes user-reported metrics. It does not affect whether the timer is running.

func (*B) SetBytes

func (b *B) SetBytes(n int64)

SetBytes records the number of bytes processed in a single operation. If this is called, the benchmark will report ns/op and MB/s.

func (*B) StartTimer

func (b *B) StartTimer()

StartTimer starts timing a test. This function is called automatically before a benchmark starts, but it can also be used to resume timing after a call to B.StopTimer.

func (*B) StopTimer

func (b *B) StopTimer()

StopTimer stops timing a test. This can be used to pause the timer while performing steps that you don't want to measure.

type BenchTime

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

BenchTime specifies the amount of time to run a benchmark for, or the number of iterations to run.

type Benchmark

type Benchmark struct {
	Name string
	F    func(b *B)
}

Benchmark represents a single benchmark to be run by the benchmark runner.

type BenchmarkFunc

type BenchmarkFunc func(b *B)

BenchmarkFunc is a function that benchmarks a piece of code.

type BenchmarkResult

type BenchmarkResult struct {
	N         int           // The number of iterations.
	T         time.Duration // The total time taken.
	Bytes     int64         // Bytes processed in one iteration.
	MemAllocs uint64        // The total number of memory allocations.
	MemBytes  uint64        // The total number of bytes allocated.
}

BenchmarkResult contains the results of a benchmark run.

func RunBenchmark

func RunBenchmark(a mem.Allocator, f func(b *B)) BenchmarkResult

RunBenchmark benchmarks a single function and returns the results.

func (BenchmarkResult) AllocedBytesPerOp

func (r BenchmarkResult) AllocedBytesPerOp() int64

AllocedBytesPerOp returns the "B/op" metric, which is calculated as r.MemBytes / r.N.

func (BenchmarkResult) AllocsPerOp

func (r BenchmarkResult) AllocsPerOp() int64

AllocsPerOp returns the "allocs/op" metric, which is calculated as r.MemAllocs / r.N.

func (BenchmarkResult) MemString

func (r BenchmarkResult) MemString(buf []byte) string

MemString returns r.AllocedBytesPerOp and r.AllocsPerOp in the same format as 'go test'.

func (BenchmarkResult) NsPerOp

func (r BenchmarkResult) NsPerOp() int64

NsPerOp returns the "ns/op" metric.

func (BenchmarkResult) String

func (r BenchmarkResult) String(buf []byte) string

String returns a summary of the benchmark results. It follows the benchmark result line format from https://golang.org/design/14313-benchmark-format, not including the benchmark name. Extra metrics override built-in metrics of the same name. String does not include allocs/op or B/op, since those are reported by BenchmarkResult.MemString.