Help us shape the future of Go! Take the 2026 Go Developer Survey

scenarios

package
v1.4.15 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 19, 2026 License: MIT Imports: 17 Imported by: 0

Documentation

Overview

Package scenarios is the registration API of tools/perfbench (contract:cli.perfbench v1). A scenario measures one thing about a built nself binary and returns raw samples; perfbench turns the samples into the perfbench/v1 JSON document.

Adding a scenario: implement Scenario in a new file of this package and call Register from that file's init(). A scenario that probes the binary with fixed argument lists should also implement Prober, so `perfbench ab` can interleave two binaries over the same probes.

Index

Constants

View Source
const DefaultTimeout = 30 * time.Second

DefaultTimeout bounds one probe run when Config.Timeout / Opts.Timeout is 0.

View Source
const PluginCount = 31

PluginCount is the number of CLI plugins in the generated HOME (the v1 count).

Variables

View Source
var ErrTimeout = errors.New("timed out")

ErrTimeout is returned (wrapped) by RunOnce when the process was killed for running past Opts.Timeout.

Functions

func Names

func Names() []string

Names lists the registered scenario names, sorted.

func PluginName

func PluginName(i int) (slug, binary string)

PluginName returns the slug and binary of generated plugin i. The command name is never an ADR 0016 verb: names are tool-0 ... tool-30.

func Register

func Register(s Scenario)

Register adds s to the registry. It panics on an empty or duplicate name, because both are programming errors caught at process start.

func RunChecked

func RunChecked(ctx context.Context, bin, side string, p Probe, o Opts) (float64, error)

RunChecked runs probe p once and returns its wall time in ms. A timeout, a signal death or an exit code other than p.Exit is a *ProbeFailure naming the probe and side. side is "" outside `ab`.

func RunOnce

func RunOnce(ctx context.Context, bin string, args []string, o Opts) (float64, int, error)

RunOnce runs bin with args in a clean environment and returns the wall time in milliseconds and the exit code (-1 when a signal killed the process). The probe gets a fresh empty HOME and an empty working directory, telemetry off, stdin at /dev/null and stdout and stderr discarded. Only a failure to start or a timeout is an error; judging the exit code is RunChecked's job.

func WritePluginHome

func WritePluginHome(home string, n int) error

WritePluginHome creates n CLI plugins under home/.nself/plugins: one <slug>/plugin.json each and one executable stub per binary in plugins/bin.

Types

type Config

type Config struct {
	Bin    string   // path of the nself binary under test
	Runs   int      // measured runs per probe
	Warmup int      // discarded runs per probe, before the measured ones
	Env    []string // extra KEY=VALUE entries appended to the probe environment

	// Timeout kills one probe run that takes longer (0 means DefaultTimeout).
	Timeout time.Duration
}

Config is what perfbench hands to a scenario run.

type Opts

type Opts struct {
	Env      []string      // extra KEY=VALUE entries appended to the probe environment
	Slowdown float64       // self-test only: > 1 makes the timed window Slowdown x the measured time
	Timeout  time.Duration // kill the process after this long; 0 means DefaultTimeout
}

Opts tunes one process run.

type Probe

type Probe struct {
	Metric string
	Args   []string
	Exit   int
}

Probe is one named measurement of a fresh process: the binary is started with Args and its wall time (start to exit) is the sample, in milliseconds. Exit is the exit code the probe must produce (0 for most commands, 1 for a command that is expected to fail, such as `status` in an empty directory). Any other code, including death by signal, fails the run: a binary that crashes at startup is not fast.

type ProbeFailure

type ProbeFailure struct {
	Metric string
	Side   string // "base" or "head" for `ab`, empty for `run`
	Reason string
}

ProbeFailure is a measured run that must fail the scenario or the A/B verdict: an unexpected exit code, death by signal, or a timeout.

func (*ProbeFailure) Error

func (e *ProbeFailure) Error() string

type Prober

type Prober interface {
	Probes() []Probe
}

Prober is implemented by scenarios made of fixed probes. `perfbench ab` needs it to interleave two binaries over the same probes.

type Sample

type Sample struct {
	Metric string
	Unit   string
	Value  float64
}

Sample is one measurement. Every sample of one Metric must carry the same Unit; perfbench fails the run otherwise.

func RunProbes

func RunProbes(ctx context.Context, cfg Config, probes []Probe) ([]Sample, error)

RunProbes measures every probe cfg.Runs times after cfg.Warmup discarded runs and returns one ms sample per measured run, probe by probe. Warm-up runs are checked too: a binary that is dead on its first run fails at once.

type Scenario

type Scenario interface {
	Name() string
	Run(ctx context.Context, cfg Config) ([]Sample, error)
}

Scenario measures one aspect of the binary.

func Get

func Get(name string) (Scenario, bool)

Get returns the scenario registered under name.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL