director

package
v0.0.0-...-1dd1f65 Latest Latest
Warning

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

 Go to latest Published: Feb 26, 2023 License: MIT Imports: 33 Imported by: 0

Documentation

Overview

Package director contains the top-level C4 test director, which manages a full testing campaign.

Index

Examples

Constants

This section is empty.

Variables

View Source 
var (
	// ErrObserverNil occurs when we try to pass a nil observer as an option.
	ErrObserverNil = errors.New("observer nil")

	// ErrNoMachines occurs when we try to build a director without defining any machines defined.
	ErrNoMachines = errors.New("no machines defined")

	// ErrNoOutDir occurs when we try to build a director with no output directory specified in the config.
	ErrNoOutDir = errors.New("no output directory specified in config")
)

Functions

func LowerToAnalyser 

func LowerToAnalyser(obs []InstanceObserver) []analyser.Observer

LowerToAnalyser lowers a slice of instance observers to a slice of analyser observers.

func LowerToBuilder 

func LowerToBuilder(obs []InstanceObserver) []builder.Observer

LowerToBuilder lowers a slice of instance observers to a slice of builder observers.

func LowerToCopy 

func LowerToCopy(obs []InstanceObserver) []copier.Observer

LowerToCopy lowers a slice of instance observers to a slice of copy observers.

func LowerToMach 

func LowerToMach(obs []InstanceObserver) []mach.Observer

LowerToMach lowers a slice of director observers to a slice of machine node observers.

func LowerToMachine 

func LowerToMachine(obs []Observer) []machine.Observer

LowerToMachine lowers a slice of director observers to a slice of machine observers.

func LowerToPerturber 

func LowerToPerturber(obs []InstanceObserver) []perturber.Observer

LowerToPerturber lowers a slice of instance observers to a slice of perturber observers.

func LowerToPlanner 

func LowerToPlanner(obs []Observer) []planner.Observer

LowerToPlanner lowers a slice of director observers to a slice of planner observers.

func LowerToSaver 

func LowerToSaver(obs []InstanceObserver) []saver.Observer

LowerToSaver lowers a slice of instance observers to a slice of saver observers.

func OnCycle 

func OnCycle(m CycleMessage, obs ...InstanceObserver)

OnCycle sends a cycle message to every instance observer in obs.

func OnInstance 

func OnInstance(m InstanceMessage, obs ...InstanceObserver)

OnInstance sends OnInstance to each observer in obs.

func OnPrepare 

func OnPrepare(m PrepareMessage, obs ...PrepareObserver)

OnPrepare sends OnPrepare to every observer in obs.

Types

type Cycle 

type Cycle struct {
	// Instance is the index of the instance running this cycle.
	// Indices currently start from 0, so the zero value is also a valid instance number; this may change.
	Instance int `json:"instance"`

	// MachineID is the ID of the machine on which this cycle is running.
	MachineID id.ID `json:"machine_id,omitempty"`

	// Iter is the iteration number of this cycle.
	// Iteration numbers currently start from 0, so the zero value is also a valid iteration number; this may change.
	Iter uint64 `json:"iter"`

	// Start is the start time of this cycle.
	Start time.Time `json:"start_time,omitempty"`
}

Cycle contains information about a particular test cycle.

func (Cycle) String 

func (r Cycle) String() string

String returns a string containing the components of this cycle in a human-readable manner.

type CycleAnalysis 

type CycleAnalysis struct {
	// Cycle contains information about the run that produced this collation.
	Cycle Cycle

	// Analysis is the collation proper.
	analysis.Analysis
}

CycleAnalysis contains an analysis as well as the cycle that produced it.

func (*CycleAnalysis) String 

func (s *CycleAnalysis) String() string

String formats a log header for this sourced analysis.

Example

ExampleCycleAnalysis_String is a runnable example for CycleAnalysis.String. 

package main

import (
	"fmt"
	"time"

	"github.com/c4-project/c4t/internal/director"

	"github.com/c4-project/c4t/internal/subject/status"

	"github.com/c4-project/c4t/internal/id"
	"github.com/c4-project/c4t/internal/plan/analysis"
	"github.com/c4-project/c4t/internal/subject/corpus"
)

func main() {
	sc := director.CycleAnalysis{
		Cycle: director.Cycle{
			Instance:  4,
			MachineID: id.FromString("foo.bar.baz"),
			Iter:      42,
			Start:     time.Date(1997, time.May, 1, 10, 0, 0, 0, time.FixedZone("BST", 60*60)),
		},
		Analysis: analysis.Analysis{
			ByStatus: map[status.Status]corpus.Corpus{
				status.Ok:             corpus.New("a", "b", "c", "ch"),
				status.Filtered:       corpus.New("a", "i", "u", "e", "o"),
				status.Flagged:        corpus.New("barbaz"),
				status.CompileFail:    corpus.New("foo", "bar", "baz"),
				status.CompileTimeout: corpus.New(),
				status.RunFail:        corpus.New("foobaz", "barbaz"),
				status.RunTimeout:     corpus.New(),
			},
		},
	}
	fmt.Println(&sc)

}

Output:

[4: foo.bar.baz #42 (May  1 10:00:00)] 4 Ok, 5 Filtered, 1 Flagged, 3 CompileFail, 2 RunFail

type CycleMessage 

type CycleMessage struct {
	// Cycle names the cycle on which this message is occurring.
	Cycle Cycle
	// Kind gives the kind of message.
	Kind CycleMessageKind
	// Err holds the error if Kind is CycleError.
	Err error
}

CycleMessage is the type of observer messages pertaining to the control flow of a specific cycle.

func CycleErrorMessage 

func CycleErrorMessage(c Cycle, err error) CycleMessage

CycleErrorMessage constructs a CycleError message with cycle c and error err.

func CycleFinishMessage 

func CycleFinishMessage(c Cycle) CycleMessage

CycleFinishMessage constructs a CycleFinish message with cycle c.

func CycleStartMessage 

func CycleStartMessage(c Cycle) CycleMessage

CycleStartMessage constructs a CycleStart message with cycle c.

type CycleMessageKind 

type CycleMessageKind uint8

CycleMessageKind is the enumeration of kinds of cycle message. 

const (
	// CycleStart denotes the start of a cycle.
	// Future messages from an InstanceObserver should be ascribed to this cycle, until another CycleStart.
	CycleStart CycleMessageKind = iota
	// CycleFinish denotes the successful completion of a cycle.
	CycleFinish
	// CycleError denotes a message carrying an error from a cycle (replacing CycleFinish).
	// Errors in cycles generally cause the cycle to restart, maybe with backoff.
	CycleError
)

type CycleObserver 

type CycleObserver interface {
	// OnCycle observes a message relating to this instance's current cycle.
	OnCycle(m CycleMessage)
}

CycleObserver is an interface for types that observe cycles.

This is a separate sub-interface of InstanceObserver because some things implement one, but not the other.

type Director 

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

Director contains the main state and configuration for the test director.

func New 

func New(e Env, ms machine.ConfigMap, files []string, opt ...Option) (*Director, error)

New creates a new Director with driver set e, input paths files, machines ms, and options opt.

func (*Director) Direct 

func (d *Director) Direct(ctx context.Context) error

Direct runs the director d.

type Env 

type Env struct {
	// Fuzzer is a single-shot fuzzing driver.
	// TODO(@MattWindsor91): this overlaps nontrivially with Planner; both should use the same dumper!
	Fuzzer fuzzer.Driver

	// BResolver is a backend resolver.
	BResolver backend.Resolver

	// CInspector is the compiler inspector used for perturbing compiler optimisation levels.
	CInspector compiler.Inspector

	// Planner instructs any planners built for this director as to how to acquire information about compilers, etc.
	Planner planner.Source
}

Env groups together the bits of configuration that pertain to dealing with the environment.

func (Env) Check 

func (e Env) Check() error

Check makes sure the environment is sensible.

type Instance 

type Instance struct {
	// Index is the index of the instance in the director.
	Index int
	// Env contains the parts of the director's config that tell it how to do various environmental tasks.
	Env Env
	// Machine is the machine installed into the instance.
	Machine *Machine
	// Observers is this machine's observer set.
	Observers []InstanceObserver
	// SSHConfig contains top-level SSH configuration.
	SSHConfig *remote.Config
	// Filters contains the precompiled filter set for this instance.
	Filters analysis.FilterSet

	// CycleHooks contains a number of callbacks that are executed before beginning a cycle.
	CycleHooks []func(*Instance) error

	// FuzzerConfig contains the fuzzer config for this instance.
	FuzzerConfig *fuzzer2.Config
	// contains filtered or unexported fields
}

Instance contains the state necessary to run a single loop of a director.

func (*Instance) Run 

func (i *Instance) Run(ctx context.Context) error

Run runs this instance's testing loop.

type InstanceMessage 

type InstanceMessage struct {
	Kind   InstanceMessageKind
	Mutant mutation.Mutant
}

InstanceMessage is the type of observer messages pertaining to the control flow of an instance.

func InstanceClosedMessage 

func InstanceClosedMessage() InstanceMessage

InstanceClosedMessage constructs an InstanceMessage stating that the instance has closed.

func InstanceMutantMessage 

func InstanceMutantMessage(m mutation.Mutant) InstanceMessage

InstanceMutantMessage constructs an InstanceMessage stating that the instance has changed mutant to m.

type InstanceMessageKind 

type InstanceMessageKind uint8

InstanceMessageKind is the enumeration of kinds of instance message. 

const (
	// KindInstanceClosed means that the instance has closed.
	// Observers should free any resources specific to this instance.
	KindInstanceClosed InstanceMessageKind = iota
	// KindInstanceMutant means that the instance has changed to a new mutant (in Mutant).
	KindInstanceMutant
)

type InstanceObserver 

type InstanceObserver interface {
	// CycleObserver captures that InstanceObserver observers can observe cycles.
	CycleObserver

	// OnInstance observes something about that the instance this observer is observing.
	OnInstance(m InstanceMessage)

	// Observer captures that InstanceObserver observers can observe plan analyses.
	analyser.Observer

	// Observer captures that InstanceObserver observers can observe plan saves.
	saver.Observer

	// Observer captures that InstanceObserver observers can observe perturber operations.
	perturber.Observer

	// Observer captures that InstanceObserver observers can observe file copies.
	copier.Observer

	// Observer captures that InstanceObserver observers can observe machine node actions.
	mach.Observer
}

InstanceObserver is an interface for types that observe a director instance.

type Machine 

type Machine struct {
	// ID is the ID for this machine.
	ID id.ID

	// InitialPlan is the plan that is perturbed to form the plan for each test cycle.
	InitialPlan plan.Plan

	// Pathset contains the pathset for this instance.
	Pathset *pathset.Instance

	// Quantities contains the quantity set for this machine.
	Quantities quantity.MachineSet

	// Config contains the machine config for this machine.
	Config machine.Config
	// contains filtered or unexported fields
}

Machine contains the state for a particular machine attached to an instance.

type Observer 

type Observer interface {
	// Observer captures that observers can observe machine configuration.
	machine.Observer

	// Observer captures that observers can observe planner operations.
	planner.Observer

	// PrepareObserver captures that observers can observe director preparations.
	PrepareObserver

	// Instance gets a sub-observer for the machine with ID id.
	// It can fail if no such observer is available.
	Instance(id id.ID) (InstanceObserver, error)
}

Observer is an interface for types that implement multi-machine test progress observation.

type Option 

type Option func(*Director) error

Option is the type of options for the director.

func ConfigFromGlobal 

func ConfigFromGlobal(g *config.Config) Option

ConfigFromGlobal extracts the parts of a global config file relevant to a director, and builds a config from them.

func FilterMachines 

func FilterMachines(glob id.ID) Option

FilterMachines filters the director's machine set with glob.

func Filters 

func Filters(fs analysis.FilterSet) Option

Filters adds fs to the set of filters to use for any analyses this director runs.

func FiltersFromFile 

func FiltersFromFile(path string) Option

FiltersFromFile loads a filter set from path, if it is non-blank.

func FuzzerConfig 

func FuzzerConfig(cfg *fuzzer2.Config) Option

FuzzerConfig sets the fuzzer configuration to cfg.

func ObserveWith 

func ObserveWith(obs ...Observer) Option

ObserveWith adds obs to the director's observer pool.

func Options 

func Options(ops ...Option) Option

Options bundles the separate options ops into a single option.

func OutDir 

func OutDir(dir string) Option

OutDir sets the director's paths relative to dir. It performs home directory expansion in dir.

func OverrideQuantities 

func OverrideQuantities(qs quantity.RootSet) Option

OverrideQuantities overrides the director's quantities with qs.

func SSH 

func SSH(s *remote.Config) Option

SSH sets the director's SSH config to s.

type PrepareKind 

type PrepareKind uint8

PrepareKind is the enumeration of kinds of PrepareMessage. 

const (
	// PrepareInstances states that the director is preparing its instance set; NumInstances is set.
	PrepareInstances PrepareKind = iota
	// PrepareQuantities states the director's quantity set; Quantities is set.
	PrepareQuantities
	// PreparePaths states that the director is about to make its top-level paths; Paths is set.
	PreparePaths
	// PrepareStart states that the director has started experiments; Time is set.
	PrepareStart
	// PrepareTimeout states that the director has a global timeout; Time is set.
	PrepareTimeout
)

type PrepareMessage 

type PrepareMessage struct {
	// Kind states the kind of message.
	Kind PrepareKind `json:"kind"`

	// NumInstances states, if Kind is PrepareInstances, the number of instances that the director is going to run.
	// This can be used by observers to pre-allocate instance sub-observers.
	NumInstances int `json:"num_instances,omitempty"`
	// Quantities states, if Kind is PrepareQuantities, the quantities the director is going to make.
	Quantities *quantity.RootSet `json:"quantities,omitempty"`
	// Paths states, if Kind is PreparePaths, where the director is going to make its top-level paths.
	Paths *pathset.Pathset `json:"paths,omitempty"`
	// Time states, if Kind is PrepareStart or PrepareTimeout, what the start/end time of the experiment will be.
	Time time.Time `json:"deadline,omitempty"`
}

PrepareMessage is a message from the director stating some aspect of its pre-experiment preparation.

func PrepareInstancesMessage 

func PrepareInstancesMessage(ninst int) PrepareMessage

PrepareInstancesMessage creates a PrepareMessage with kind PrepareInstances and instance count ninst.

func PreparePathsMessage 

func PreparePathsMessage(ps pathset.Pathset) PrepareMessage

PreparePathsMessage creates a PrepareMessage with kind PreparePaths and path set ps.

func PrepareQuantitiesMessage 

func PrepareQuantitiesMessage(qs quantity.RootSet) PrepareMessage

PrepareQuantitiesMessage creates a PrepareMessage with kind PrepareQuantities and quantity set qs.

func PrepareStartMessage 

func PrepareStartMessage(dl time.Time) PrepareMessage

PrepareStartMessage creates a PrepareMessage with kind PrepareStart and start time dl.

func PrepareTimeoutMessage 

func PrepareTimeoutMessage(dl time.Time) PrepareMessage

PrepareTimeoutMessage creates a PrepareMessage with kind PrepareTimeout and experiment deadline dl.

type PrepareObserver 

type PrepareObserver interface {

	// OnPrepare lets the observer know that the director is performing some sort of preparation.
	OnPrepare(message PrepareMessage)
}

PrepareObserver is an interface for types that observer director preparations.

func LowerToPrepare 

func LowerToPrepare(obs []Observer) []PrepareObserver

LowerToPrepare lowers a slice of director observers to a slice of prepare observers.

Source Files

View all Source files

Directories

Path Synopsis
Package pathset contains the various path-sets for the director.
 Package pathset contains the various path-sets for the director.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.