runner

Documentation

Overview

Package runner implements sandboxed Go benchmark execution.

Index

• func HostSnapshotBuilderType() (string, bool)
• func SnapshotBuilderType(goos, goarch string) (string, bool)
• func ToolchainConfigurationProvider(tc Toolchain) cfg.Provider
• type Option
  • func InheritEnviron() Option
  • func WithArtifactStore(fs fs.Writable) Option
  • func WithEnviron(env []string) Option
  • func WithHTTPClient(c *http.Client) Option
  • func WithLogger(l *zap.Logger) Option
  • func WithWorkDir(d string) Option
• type Runner
  • func NewRunner(w *Workspace, tc Toolchain) *Runner
  • func (r *Runner) AddConfigurationProvider(p cfg.Provider)
  • func (r *Runner) Benchmark(ctx context.Context, s job.Suite, output string)
  • func (r *Runner) Clean(ctx context.Context)
  • func (r *Runner) Go(ctx context.Context, arg ...string) *exec.Cmd
  • func (r *Runner) GoExec(ctx context.Context, arg ...string)
  • func (r *Runner) Init(ctx context.Context)
  • func (r *Runner) SetGoProxy(proxy string)
  • func (r *Runner) Tune(t Tuner)
  • func (r *Runner) Wrap(w ...Wrapper)
• type Toolchain
  • func NewRelease(version, os, arch string) Toolchain
  • func NewSnapshot(buildertype, rev string) Toolchain
  • func NewToolchain(typ string, params map[string]string) (Toolchain, error)
• type Tuner
• type Workspace
  • func NewWorkspace(opts ...Option) (*Workspace, error)
  • func (w *Workspace) AddEnviron(env ...string)
  • func (w *Workspace) AppendPATH(path string)
  • func (w *Workspace) Artifact(path, name string)
  • func (w *Workspace) Cd(path string)
  • func (w *Workspace) CdRoot()
  • func (w *Workspace) Clean()
  • func (w *Workspace) DefineTool(key, dflt string)
  • func (w *Workspace) Download(url, path string)
  • func (w *Workspace) EnsureDir(rel string) string
  • func (w *Workspace) Error() error
  • func (w *Workspace) Exec(cmd *exec.Cmd)
  • func (w *Workspace) ExposeTool(name string)
  • func (w *Workspace) GetEnv(key string) string
  • func (w *Workspace) InheritEnv(key string)
  • func (w *Workspace) Move(src, dst string)
  • func (w *Workspace) Options(opts ...Option)
  • func (w *Workspace) Path(rel string) string
  • func (w *Workspace) Sandbox(task string) string
  • func (w *Workspace) SetEnv(key, value string)
  • func (w *Workspace) SetEnvDefault(key, value string) string
  • func (w *Workspace) Uncompress(src, dst string)
• type Wrapper
  • func RunUnder(name string, arg ...string) Wrapper

Functions

func HostSnapshotBuilderType

func HostSnapshotBuilderType() (string, bool)

HostSnapshotBuilderType gives looks for a builder type for host platform.

func SnapshotBuilderType

func SnapshotBuilderType(goos, goarch string) (string, bool)

SnapshotBuilderType looks for a suitable builder type to download snapshots for the given GOOS/GOARCH.

func ToolchainConfigurationProvider

func ToolchainConfigurationProvider(tc Toolchain) cfg.Provider

ToolchainConfigurationProvider provides benchmark configuration lines about the given toolchain.

Types

type Option

type Option func(*Workspace)

func InheritEnviron

func InheritEnviron() Option

func WithArtifactStore

func WithArtifactStore(fs fs.Writable) Option

func WithEnviron

func WithEnviron(env []string) Option

func WithHTTPClient

func WithHTTPClient(c *http.Client) Option

func WithLogger

func WithLogger(l *zap.Logger) Option

func WithWorkDir

func WithWorkDir(d string) Option

type Runner

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

func NewRunner

func NewRunner(w *Workspace, tc Toolchain) *Runner

func (*Runner) AddConfigurationProvider

func (r *Runner) AddConfigurationProvider(p cfg.Provider)

AddConfigurationProvider adds a configuration provider that will be applied to every benchmark run.

func (*Runner) Benchmark

func (r *Runner) Benchmark(ctx context.Context, s job.Suite, output string)

Benchmark runs the benchmark suite.

func (*Runner) Clean

func (r *Runner) Clean(ctx context.Context)

Clean up the runner.

func (*Runner) Go

func (r *Runner) Go(ctx context.Context, arg ...string) *exec.Cmd

Go builds a command with the downloaded go version.

func (*Runner) GoExec

func (r *Runner) GoExec(ctx context.Context, arg ...string)

GoExec executes the go binary with the given arguments.

func (*Runner) Init

func (r *Runner) Init(ctx context.Context)

Init initializes the runner.

func (*Runner) SetGoProxy

func (r *Runner) SetGoProxy(proxy string)

SetGoProxy sets the GOPROXY environment variable.

func (*Runner) Tune

func (r *Runner) Tune(t Tuner)

Tune applies the given tuning method to benchmark executions.

func (*Runner) Wrap

func (r *Runner) Wrap(w ...Wrapper)

Wrap configures the wrapper w to be applied to benchmark runs. Wrappers are applied in the order they are added.

type Toolchain

type Toolchain interface {
	// Type identifier.
	Type() string
	// String gives a concise identifier for the toolchain.
	String() string
	// Ref is a git reference to the Go repository version (sha or tag).
	Ref() string
	// Configuration returns configuration lines for the
	Configuration() (cfg.Configuration, error)
	// Install the toolchain to the given location in the workspace.
	Install(w *Workspace, root string)
}

func NewRelease

func NewRelease(version, os, arch string) Toolchain

NewRelease constructs a release toolchain for the given version, os and architecture. Version is expected to begin with "go", for example "go1.13.4".

func NewSnapshot

func NewSnapshot(buildertype, rev string) Toolchain

func NewToolchain

func NewToolchain(typ string, params map[string]string) (Toolchain, error)

type Tuner

type Tuner interface {
	// Name identifies the tuning method.
	Name() string

	// Available checks whether the method can be applied at all. Note this is
	// intended to be a basic environment check, it is still possible that
	// Apply() could fail if Available() returns true.
	Available() bool

	// Apply the tuning method.
	Apply() error

	// Reset state to default configuration.
	Reset() error
}

Tuner tunes a system for benchmarking.

type Workspace

type Workspace struct {
	Log *zap.Logger
	// contains filtered or unexported fields
}

func NewWorkspace

func NewWorkspace(opts ...Option) (*Workspace, error)

func (*Workspace) AddEnviron

func (w *Workspace) AddEnviron(env ...string)

AddEnviron is a convenience for setting multiple environment variables given a list of "KEY=value" strings. Provided for easy interoperability with functions like os.Environ().

func (*Workspace) AppendPATH

func (w *Workspace) AppendPATH(path string)

AppendPATH appends a directory to the PATH variable, if it is not already present.

func (*Workspace) Artifact

func (w *Workspace) Artifact(path, name string)

Artifact saves the given path as a named artifact.

func (*Workspace) Cd

func (w *Workspace) Cd(path string)

Cd sets the working directory to path.

func (*Workspace) CdRoot

func (w *Workspace) CdRoot()

CdRoot sets the working directory to the root of the workspace.

func (*Workspace) Clean

func (w *Workspace) Clean()

Clean up the workspace.

func (*Workspace) DefineTool

func (w *Workspace) DefineTool(key, dflt string)

DefineTool defines a standard tool with environment variable key and default dflt, for example "CC" with default "gcc". If the environment variable is set in the host environment, it is inherited, otherwise it is set to the default and the PATH is edited to ensure it is accessible within the workspace.

func (*Workspace) Download

func (w *Workspace) Download(url, path string)

Download url to path.

func (*Workspace) EnsureDir

func (w *Workspace) EnsureDir(rel string) string

EnsureDir ensure the relative path exists.

func (*Workspace) Error

func (w *Workspace) Error() error

Error returns the first error that occurred in the workspace, if any.

func (*Workspace) Exec

func (w *Workspace) Exec(cmd *exec.Cmd)

Exec the provided command.

func (*Workspace) ExposeTool

func (w *Workspace) ExposeTool(name string)

ExposeTool makes the named tool available to the workspace by looking up its location and adding the directory to the PATH.

func (*Workspace) GetEnv

func (w *Workspace) GetEnv(key string) string

GetEnv returns the environment variable key.

func (*Workspace) InheritEnv

func (w *Workspace) InheritEnv(key string)

InheritEnv sets the environment variable key to the same as the surrounding environment, if it is defined. Otherwise does nothing.

func (*Workspace) Move

func (w *Workspace) Move(src, dst string)

Move src to dst.

func (*Workspace) Options

func (w *Workspace) Options(opts ...Option)

Options applies options to the workspace.

func (*Workspace) Path

func (w *Workspace) Path(rel string) string

Path relative to working directory.

func (*Workspace) Sandbox

func (w *Workspace) Sandbox(task string) string

Sandbox creates a fresh temporary directory, sets it as the working directory and returns it.

func (*Workspace) SetEnv

func (w *Workspace) SetEnv(key, value string)

SetEnv sets an environment variable for all workspace operations.

func (*Workspace) SetEnvDefault

func (w *Workspace) SetEnvDefault(key, value string) string

SetEnvDefault sets an environment variable if it does not already have a value.

func (*Workspace) Uncompress

func (w *Workspace) Uncompress(src, dst string)

Uncompress archive src to the directory dst.

type Wrapper

type Wrapper func(*exec.Cmd)

Wrapper is a method of modifying commands before execution.

func RunUnder

func RunUnder(name string, arg ...string) Wrapper

RunUnder builds a wrapper that inserts the named command and arguments before a command before execution.