gcbench

Documentation

Index

• func ReportExtra(metric string, val float64)
• func WithStack(size Bytes, f func())
• type Benchmark
  • func NewBenchmark(name string, main func()) *Benchmark
  • func (b *Benchmark) Config(name string, value interface{}) *Benchmark
  • func (b *Benchmark) FullName() string
  • func (b *Benchmark) Run()
• type Bytes
  • func FlagBytes(name string, value Bytes, usage string) *Bytes
  • func ParseBytes(s string) (Bytes, error)
  • func (b *Bytes) Set(s string) error
  • func (b Bytes) String() string
• type Churner
  • func (c *Churner) Start()
  • func (c *Churner) Stop()
• type GCChecker
  • func NewGCChecker() *GCChecker
  • func (c *GCChecker) NumGCAtLeast(n int)
• type GCCycle
• type GCTrace
  • func ParseGCTrace(s string) (GCTrace, error)
  • func (t GCTrace) WithoutForced() GCTrace
• type LatencyDist
  • func (d *LatencyDist) Add(t time.Duration)
  • func (d *LatencyDist) Fprint(w io.Writer)
  • func (d *LatencyDist) FprintHist(w io.Writer, width, height int)
  • func (d *LatencyDist) FromBucket(b int) (lo, hi time.Duration)
  • func (d *LatencyDist) Quantile(q float64) time.Duration
  • func (d *LatencyDist) Start() *LatencyTracker
  • func (d *LatencyDist) ToBucket(t time.Duration) int
• type LatencyTracker
  • func (t *LatencyTracker) Done()
  • func (t *LatencyTracker) Tick()
• type Metric
• type RunInfo
• type TraceFormat

Functions

func ReportExtra

func ReportExtra(metric string, val float64)

ReportExtra can be used by a benchmark main function to report extra metrics.

func WithStack

func WithStack(size Bytes, f func())

WithStack grows the stack by ~size bytes and calls f.

The stack is grown with a mix of pointer and scalar data to simulate a real stack (though all pointers are nil).

Types

type Benchmark

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

func NewBenchmark

func NewBenchmark(name string, main func()) *Benchmark

func (*Benchmark) Config

func (b *Benchmark) Config(name string, value interface{}) *Benchmark

func (*Benchmark) FullName

func (b *Benchmark) FullName() string

func (*Benchmark) Run

func (b *Benchmark) Run()

type Bytes

type Bytes int64

const (
	B Bytes = 1

	KB Bytes = 1e3
	MB Bytes = 1e6
	GB Bytes = 1e9
	TB Bytes = 1e12
	PB Bytes = 1e15
	EB Bytes = 1e18

	KiB Bytes = 1 << 10
	MiB Bytes = 1 << 20
	GiB Bytes = 1 << 30
	TiB Bytes = 1 << 40
	PiB Bytes = 1 << 50
	EiB Bytes = 1 << 60
)

func FlagBytes

func FlagBytes(name string, value Bytes, usage string) *Bytes

func ParseBytes

func ParseBytes(s string) (Bytes, error)

func (*Bytes) Set

func (b *Bytes) Set(s string) error

func (Bytes) String

func (b Bytes) String() string

type Churner

type Churner struct {
	// BallastBytes is the minimum bytes to retain in the heap.
	//
	// This is implemented as a simple []byte allocation. A caller
	// may create their own ballast and set this to 0.
	BallastBytes uint64

	// BytesPerSec is how many bytes of garbage to allocate per
	// second.
	//
	// If BytesPerSec == BallastBytes, there will be approximately
	// one GC per second.
	BytesPerSec uint64
	// contains filtered or unexported fields
}

A Churner churns the heap to cause GCs at some rate.

func (*Churner) Start

func (c *Churner) Start()

func (*Churner) Stop

func (c *Churner) Stop()

type GCChecker

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

func NewGCChecker

func NewGCChecker() *GCChecker

func (*GCChecker) NumGCAtLeast

func (c *GCChecker) NumGCAtLeast(n int)

type GCCycle

type GCCycle struct {
	// N is the 1-based index of this GC cycle.
	N int

	// Format indicates the variant of the GC trace format for this line.
	Format TraceFormat

	// Start and End are the times this GC cycle started and
	// ended, relative to when the program began executing.
	Start, End time.Duration

	// Util is the overall CPU utilized by GC since the program
	// began executing. Util will be in [0, 1].
	Util float64

	// Forced is true is this GC cycle is a forced STW cycle.
	Forced bool

	// Clock* are the wall-clock durations of each phase.
	// ClockSweepTerm, ClockSync, and ClockMarkTerm are STW.
	// On Go 1.6, ClockRootScan and ClockSync will be 0.
	ClockSweepTerm, ClockRootScan, ClockSync, ClockMark, ClockMarkTerm time.Duration

	// CPU* are the CPU times of each phase.
	CPUSweepTerm, CPURootScan, CPUSync, CPUMark, CPUMarkTerm time.Duration

	// CPUAssist, CPUBackground, and CPUIdle break down CPUMark in
	// to its components.
	CPUAssist, CPUBackground, CPUIdle time.Duration

	// HeapTrigger is the size of the heap at which this GC cycle
	// was triggered.
	HeapTrigger Bytes

	// HeapActual is the size of the heap when this GC cycle
	// finished (before sweeping).
	HeapActual Bytes

	// HeapMarked is the bytes of heap that this GC cycle marked
	// (which will be retained by sweeping).
	HeapMarked Bytes

	// HeapGoal is the size of the heap this GC cycle was aiming
	// to finish at.
	HeapGoal Bytes

	// Procs is the value of GOMAXPROCS during this GC cycle.
	Procs int
}

type GCTrace

type GCTrace []GCCycle

func ParseGCTrace

func ParseGCTrace(s string) (GCTrace, error)

func (GCTrace) WithoutForced

func (t GCTrace) WithoutForced() GCTrace

type LatencyDist

type LatencyDist struct {
	N       int64
	Max     time.Duration
	Buckets [256]int64
}

LatencyDist records a distribution of latencies in exponential buckets between 1 ns and 1 sec.

func (*LatencyDist) Add

func (d *LatencyDist) Add(t time.Duration)

func (*LatencyDist) Fprint

func (d *LatencyDist) Fprint(w io.Writer)

func (*LatencyDist) FprintHist

func (d *LatencyDist) FprintHist(w io.Writer, width, height int)

FprintHist renders d to w as an ASCII art histogram.

The body of the plot will fit within a width x height cell box. Ticks and tick labels will be placed outside that box.

func (*LatencyDist) FromBucket

func (d *LatencyDist) FromBucket(b int) (lo, hi time.Duration)

func (*LatencyDist) Quantile

func (d *LatencyDist) Quantile(q float64) time.Duration

func (*LatencyDist) Start

func (d *LatencyDist) Start() *LatencyTracker

func (*LatencyDist) ToBucket

func (d *LatencyDist) ToBucket(t time.Duration) int

type LatencyTracker

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

func (*LatencyTracker) Done

func (t *LatencyTracker) Done()

func (*LatencyTracker) Tick

func (t *LatencyTracker) Tick()

type Metric

type Metric struct {
	Label string
	Fn    func(RunInfo) float64
	Check func(name string, value float64)
}

type RunInfo

type RunInfo struct {
	Trace GCTrace

	StartTime, EndTime time.Time
}

type TraceFormat

type TraceFormat int

const (
	// Trace1_5 is the trace format from Go 1.5.x.
	Trace1_5 TraceFormat = 1 + iota

	// Trace1_6 is the trace format from Go 1.6.x.
	Trace1_6
)