benchclock.go

// Package benchclock provides a precision benchmarking utility that corrects for
// clock drift, CPU scaling, and warm-up bias, providing statistically meaningful
// measurements with confidence intervals and variance metrics.
package benchclock

import (
	"fmt"
	"math"
	"sort"
	"time"
)

// Result holds the statistical results of a benchmark run.
type Result struct {
	// Name of the benchmark
	Name string

	// Number of iterations performed
	Iterations int

	// Mean duration per operation
	Mean time.Duration

	// Median duration per operation
	Median time.Duration

	// Standard deviation
	StdDev time.Duration

	// Variance
	Variance float64

	// 95% Confidence Interval
	ConfidenceInterval95 struct {
		Lower time.Duration
		Upper time.Duration
	}

	// 99% Confidence Interval
	ConfidenceInterval99 struct {
		Lower time.Duration
		Upper time.Duration
	}

	// Minimum duration observed
	Min time.Duration

	// Maximum duration observed
	Max time.Duration

	// Clock drift correction applied (nanoseconds)
	ClockDriftCorrection int64

	// CPU scaling factor detected
	CPUScalingFactor float64

	// Number of warm-up iterations discarded
	WarmupIterationsDiscarded int
}

// Config holds configuration for benchmark execution.
type Config struct {
	// Minimum number of iterations to run
	MinIterations int

	// Maximum number of iterations to run
	MaxIterations int

	// Minimum duration to run the benchmark
	MinDuration time.Duration

	// Number of warm-up iterations to discard
	WarmupIterations int

	// Enable clock drift correction
	CorrectClockDrift bool

	// Enable CPU scaling detection
	DetectCPUScaling bool
}

// DefaultConfig returns a default configuration suitable for most benchmarks.
func DefaultConfig() *Config {
	return &Config{
		MinIterations:     100,
		MaxIterations:     100000,
		MinDuration:       time.Second,
		WarmupIterations:  10,
		CorrectClockDrift: true,
		DetectCPUScaling:  true,
	}
}

// Benchmark represents a benchmark to be executed.
type Benchmark struct {
	Name   string
	Fn     func()
	Config *Config
}

// New creates a new Benchmark with the given name and function.
func New(name string, fn func()) *Benchmark {
	return &Benchmark{
		Name:   name,
		Fn:     fn,
		Config: DefaultConfig(),
	}
}

// WithConfig sets a custom configuration for the benchmark.
func (b *Benchmark) WithConfig(cfg *Config) *Benchmark {
	b.Config = cfg
	return b
}

// Run executes the benchmark and returns the statistical results.
func (b *Benchmark) Run() (*Result, error) {
	if b.Fn == nil {
		return nil, fmt.Errorf("benchmark function cannot be nil")
	}

	cfg := b.Config
	if cfg == nil {
		cfg = DefaultConfig()
	}

	// Perform warm-up runs to eliminate warm-up bias
	for i := 0; i < cfg.WarmupIterations; i++ {
		b.Fn()
	}

	// Detect clock drift
	var clockDrift int64
	if cfg.CorrectClockDrift {
		clockDrift = measureClockDrift()
	}

	// Detect CPU scaling
	var cpuScaling float64 = 1.0
	if cfg.DetectCPUScaling {
		cpuScaling = detectCPUScaling()
	}

	// Collect timing measurements
	durations := make([]time.Duration, 0, cfg.MaxIterations)
	startTime := time.Now()
	iterations := 0

	for iterations < cfg.MinIterations || (time.Since(startTime) < cfg.MinDuration && iterations < cfg.MaxIterations) {
		start := time.Now()
		b.Fn()
		elapsed := time.Since(start)

		// Apply clock drift correction
		corrected := elapsed - time.Duration(clockDrift)
		// Ensure we don't have negative durations
		if corrected < 0 {
			corrected = elapsed
		}
		durations = append(durations, corrected)

		iterations++
	}

	// Calculate statistics
	result := &Result{
		Name:                      b.Name,
		Iterations:                iterations,
		ClockDriftCorrection:      clockDrift,
		CPUScalingFactor:          cpuScaling,
		WarmupIterationsDiscarded: cfg.WarmupIterations,
	}

	// Sort durations for percentile calculations
	sorted := make([]time.Duration, len(durations))
	copy(sorted, durations)
	sort.Slice(sorted, func(i, j int) bool {
		return sorted[i] < sorted[j]
	})

	// Calculate mean
	var sum int64
	for _, d := range durations {
		sum += int64(d)
	}
	result.Mean = time.Duration(sum / int64(len(durations)))

	// Calculate median
	if len(sorted)%2 == 0 {
		result.Median = (sorted[len(sorted)/2-1] + sorted[len(sorted)/2]) / 2
	} else {
		result.Median = sorted[len(sorted)/2]
	}

	// Calculate variance and standard deviation
	var varianceSum float64
	for _, d := range durations {
		diff := float64(d - result.Mean)
		varianceSum += diff * diff
	}
	result.Variance = varianceSum / float64(len(durations))
	result.StdDev = time.Duration(math.Sqrt(result.Variance))

	// Calculate confidence intervals
	// Using t-distribution critical values for 95% and 99% confidence
	// For large samples (n > 30), we can use z-scores
	n := float64(len(durations))
	stdErr := float64(result.StdDev) / math.Sqrt(n)

	// 95% confidence interval (z = 1.96)
	margin95 := 1.96 * stdErr
	lower95 := result.Mean - time.Duration(margin95)
	if lower95 < 0 {
		lower95 = 0
	}
	result.ConfidenceInterval95.Lower = lower95
	result.ConfidenceInterval95.Upper = result.Mean + time.Duration(margin95)

	// 99% confidence interval (z = 2.576)
	margin99 := 2.576 * stdErr
	lower99 := result.Mean - time.Duration(margin99)
	if lower99 < 0 {
		lower99 = 0
	}
	result.ConfidenceInterval99.Lower = lower99
	result.ConfidenceInterval99.Upper = result.Mean + time.Duration(margin99)

	// Min and Max
	result.Min = sorted[0]
	result.Max = sorted[len(sorted)-1]

	return result, nil
}

// measureClockDrift detects clock drift by measuring the overhead of time measurements.
func measureClockDrift() int64 {
	// Measure the overhead of calling time.Now() repeatedly
	samples := 100
	var totalOverhead int64

	for i := 0; i < samples; i++ {
		start := time.Now()
		_ = time.Now()
		overhead := time.Since(start)
		totalOverhead += int64(overhead)
	}

	// Return average overhead (clock drift)
	return totalOverhead / int64(samples)
}

// detectCPUScaling attempts to detect CPU frequency scaling by running
// a simple computational benchmark.
func detectCPUScaling() float64 {
	// Run a simple computation benchmark multiple times
	// If CPU scaling is active, we'll see variance in execution time
	samples := 10
	durations := make([]float64, samples)

	for i := 0; i < samples; i++ {
		start := time.Now()
		// Simple computational task
		sum := 0
		for j := 0; j < 100000; j++ {
			sum += j
		}
		durations[i] = float64(time.Since(start))
	}

	// Calculate coefficient of variation (CV = stddev / mean)
	var sum, mean float64
	for _, d := range durations {
		sum += d
	}
	mean = sum / float64(len(durations))

	var varianceSum float64
	for _, d := range durations {
		diff := d - mean
		varianceSum += diff * diff
	}
	variance := varianceSum / float64(len(durations))
	stddev := math.Sqrt(variance)

	cv := stddev / mean

	// CPU scaling factor: 1.0 means stable, higher means more scaling
	return 1.0 + cv
}

// String returns a formatted string representation of the benchmark results.
func (r *Result) String() string {
	return fmt.Sprintf(`Benchmark: %s
Iterations: %d
Mean: %v
Median: %v
StdDev: %v
Variance: %.2f ns²
Min: %v
Max: %v
95%% Confidence Interval: [%v, %v]
99%% Confidence Interval: [%v, %v]
Clock Drift Correction: %v ns
CPU Scaling Factor: %.4f
Warmup Iterations Discarded: %d`,
		r.Name,
		r.Iterations,
		r.Mean,
		r.Median,
		r.StdDev,
		r.Variance,
		r.Min,
		r.Max,
		r.ConfidenceInterval95.Lower,
		r.ConfidenceInterval95.Upper,
		r.ConfidenceInterval99.Lower,
		r.ConfidenceInterval99.Upper,
		r.ClockDriftCorrection,
		r.CPUScalingFactor,
		r.WarmupIterationsDiscarded,
	)
}

// RunMultiple runs multiple benchmarks and returns their results.
func RunMultiple(benchmarks []*Benchmark) ([]*Result, error) {
	results := make([]*Result, 0, len(benchmarks))

	for _, b := range benchmarks {
		result, err := b.Run()
		if err != nil {
			return nil, fmt.Errorf("benchmark %s failed: %w", b.Name, err)
		}
		results = append(results, result)
	}

	return results, nil
}

// Compare compares two benchmark results and returns a comparison string.
func Compare(r1, r2 *Result) string {
	diff := float64(r2.Mean-r1.Mean) / float64(r1.Mean) * 100
	direction := "slower"
	if diff < 0 {
		direction = "faster"
		diff = -diff
	}

	return fmt.Sprintf("%s vs %s: %.2f%% %s", r2.Name, r1.Name, diff, direction)
}