benchmark

Documentation

Index

• Constants
• func Bits(defaults ...uint64) ([]uint64, error)
• func Curves(curveIDs ...math.CurveID) []math.CurveID
• func Duration() time.Duration
• func Integers[T constraints.Integer](str string, defaults ...T) ([]T, error)
• func NumInputs(defaults ...int) ([]int, error)
• func NumOutputs(defaults ...int) ([]int, error)
• func ProfileEnabled() bool
• func SetupSamples() uint
• func Workers(defaults ...int) ([]int, error)
• type Bucket
• type Case
• type Config
  • func NewConfig(workers int, duration time.Duration, warmupDuration time.Duration) Config
• type Result
  • func RunBenchmark[T any](cfg Config, setup func() T, work func(T) error) Result
  • func (r Result) Print()
• type Test
  • func NewTest[T any](testCases []TestCase) *Test[T]
  • func (test *Test[T]) GoBenchmark(b *testing.B, newEnv func(*Case) (T, error), ...)
  • func (test *Test[T]) GoBenchmarkParallel(b *testing.B, newEnv func(*Case) (T, error), ...)
  • func (test *Test[T]) RunBenchmark(t *testing.T, newEnv func(*Case) (T, error), ...)
• type TestCase
  • func GenerateCases(bits []uint64, curves []math.CurveID, inputs []int, outputs []int, ...) []TestCase
  • func GenerateCasesWithDefaults() ([]uint64, []math.CurveID, []TestCase, error)
• type TimePoint

Constants

const (
	ColorReset  = "\033[0m"
	ColorRed    = "\033[31m"
	ColorGreen  = "\033[32m"
	ColorYellow = "\033[33m"
	ColorBlue   = "\033[34m"
	ColorCyan   = "\033[36m"
)

ANSI Color Codes for output.

Functions

func Bits

func Bits(defaults ...uint64) ([]uint64, error)

Bits parses the package-level `-bits` flag and returns a slice of bit sizes. If the flag is empty the provided defaults are returned. The returned values are uint64 and an error is returned if parsing fails.

func Curves

func Curves(curveIDs ...math.CurveID) []math.CurveID

Curves parses the package-level `-curves` flag and returns a slice of math.CurveID. The flag may contain comma-separated numeric curve IDs or known curve names (e.g. "BN254", "BLS12_381_BBS_GURVY", "BLS12_381_BBS_GURVY_FAST_RNG"). If the flag is empty, the provided curveIDs are returned as defaults.

func Duration

func Duration() time.Duration

Duration returns the parsed package-level `-duration` flag as a time.Duration. If the flag is zero, Duration returns 1 second as a sane default.

func Integers

func Integers[T constraints.Integer](str string, defaults ...T) ([]T, error)

Integers is a generic helper that parses a comma-separated string of unsigned integers into a slice of type T (which must be an integer type). If the input string is empty the provided defaults are returned. It trims whitespace and returns a parsing error on invalid numeric values.

func NumInputs

func NumInputs(defaults ...int) ([]int, error)

NumInputs parses the package-level `-num_inputs` flag and returns a slice of ints. If the flag is empty the provided defaults are returned. Parsing errors are returned.

func NumOutputs

func NumOutputs(defaults ...int) ([]int, error)

NumOutputs parses the package-level `-num_outputs` flag and returns a slice of ints. If the flag is empty the provided defaults are returned. Parsing errors are returned.

func ProfileEnabled

func ProfileEnabled() bool

ProfileEnabled returns true if profiling has been requested, false otherwise

func SetupSamples

func SetupSamples() uint

SetupSamples returns the number of setup samples to use. When 0, a setup will be generated for each evaluation.

func Workers

func Workers(defaults ...int) ([]int, error)

Workers parses the package-level `-workers` flag and returns a slice of worker counts. The flag accepts comma-separated integers and the special token "NumCPU" which is translated to the runtime.NumCPU() value. If the flag is empty the provided defaults are returned. Parsing errors are returned.

Types

type Bucket

type Bucket struct {
	LowBound  time.Duration
	HighBound time.Duration
	Count     int
}

Bucket represents a latency range and its frequency.

type Case

type Case struct {
	Workers    int
	Bits       uint64
	CurveID    math.CurveID
	NumInputs  int
	NumOutputs int
}

type Config

type Config struct {
	Workers        int           // Number of concurrent goroutines
	Duration       time.Duration // Time to record execution
	WarmupDuration time.Duration // Time to run before recording
	RateLimit      float64       // Total Ops/Sec limit (0 = Unlimited/Closed-Loop)
}

Config controls the benchmark execution.

func NewConfig

func NewConfig(workers int, duration time.Duration, warmupDuration time.Duration) Config

type Result

type Result struct {
	Config     Config
	GoRoutines int // Workers (kept for compatibility)

	// Throughput
	OpsTotal      uint64
	Duration      time.Duration
	OpsPerSecReal float64 // Wall-clock throughput
	OpsPerSecPure float64 // Theoretical concurrency / avg_latency

	// Latency Stats
	AvgLatency    time.Duration
	StdDevLatency time.Duration
	Variance      float64       // Variance in nanoseconds^2
	P50Latency    time.Duration // Median
	P75Latency    time.Duration
	P95Latency    time.Duration
	P99Latency    time.Duration
	P999Latency   time.Duration // 99.9th percentile
	P9999Latency  time.Duration // 99.99th percentile
	MinLatency    time.Duration
	MaxLatency    time.Duration
	IQR           time.Duration // Interquartile Range (P75 - P25)
	Jitter        time.Duration // Avg change between consecutive latencies
	CoeffVar      float64       // Coefficient of Variation (StdDev / Mean)

	// Stability & Time Series
	Timeline []TimePoint

	// Memory & GC Stats
	BytesPerOp    uint64
	AllocsPerOp   uint64
	AllocRateMBPS float64       // Allocations in MB per second
	NumGC         uint32        // Number of GC cycles during the recorded phase
	GCPauseTotal  time.Duration // Total time the world was stopped for GC
	GCOverhead    float64       // Percentage of time spent in GC

	// Reliability
	ErrorCount uint64
	ErrorRate  float64
	Histogram  []Bucket
}

Result holds the comprehensive benchmark metrics.

func RunBenchmark

func RunBenchmark[T any](
	cfg Config,
	setup func() T,
	work func(T) error,
) Result

RunBenchmark executes the benchmark.

func (Result) Print

func (r Result) Print()

type Test

type Test[T any] struct {
	TestCases []TestCase
}

Test groups a set of benchmark TestCase values. The type is generic and can be used with any environment value produced by the provided newEnv constructor when running the benchmark functions on Test.

func NewTest

func NewTest[T any](testCases []TestCase) *Test[T]

NewTest constructs and returns a pointer to a Test initialized with the provided testCases.

func (*Test[T]) GoBenchmark

func (test *Test[T]) GoBenchmark(b *testing.B, newEnv func(*Case) (T, error), work func(ctx context.Context, env T) error)

GoBenchmark runs the provided work function as standard go benchmarks using *testing.B. For each TestCase in the Test, it uses newEnv to create an environment value of type T and repeatedly invokes work on randomly chosen environments. If profiling is enabled, a profile is started and stopped around the benchmark. The function calls b.Helper() internally.

func (*Test[T]) GoBenchmarkParallel

func (test *Test[T]) GoBenchmarkParallel(b *testing.B, newEnv func(*Case) (T, error), work func(ctx context.Context, env T) error)

GoBenchmarkParallel runs the provided work function in parallel using b.RunParallel. For each TestCase it prepares a set of environments via newEnv and then executes work concurrently across goroutines managed by the testing package. Profiling is started if enabled. The method calls b.Helper().

func (*Test[T]) RunBenchmark

func (test *Test[T]) RunBenchmark(t *testing.T, newEnv func(*Case) (T, error), work func(ctx context.Context, env T) error)

RunBenchmark runs the provided work function using the RunBenchmark harness (which returns a result that is printed). For each TestCase it prepares an environment constructor that either selects from prepared samples or creates a fresh environment via newEnv. Profiling is started if enabled. The function calls t.Helper().

type TestCase

type TestCase struct {
	Name          string
	BenchmarkCase *Case
}

func GenerateCases

func GenerateCases(bits []uint64, curves []math.CurveID, inputs []int, outputs []int, workers []int) []TestCase

GenerateCases returns all combinations of Case created from the provided slices of bits, curve IDs, number of inputs and outputs.

func GenerateCasesWithDefaults

func GenerateCasesWithDefaults() ([]uint64, []math.CurveID, []TestCase, error)

GenerateCasesWithDefaults returns all combinations of TestCase created from the value of the flags: bits, curves, num_inputs, num_outputs, workers. The concrete defaults used are: bits=32, curves=math.BN254, num_inputs=2, num_outputs=2 and workers=runtime.NumCPU(). It is a helper for tests and benchmarks and calls tb.Helper().

type TimePoint

type TimePoint struct {
	Timestamp   time.Duration
	OpsSec      float64
	ActiveCount int
}

TimePoint captures system state at a specific moment.