builder

Documentation

Overview

Package builder describes a set of types and methods for building corpora asynchronously.

Index

• Variables
• func OnBuild(m Message, obs ...Observer)
• func ParBuild(ctx context.Context, nworkers int, src corpus.Corpus, cfg Config, ...) (corpus.Corpus, error)
• type Add
• type Builder
  • func New(cfg Config) (*Builder, error)
  • func (b *Builder) Run(ctx context.Context) (corpus.Corpus, error)
• type Compile
• type Config
• type Manifest
• type Message
  • func EndMessage() Message
  • func StartMessage(m Manifest) Message
  • func StepMessage(i int, r Request) Message
• type Observer
• type Recipe
• type Request
  • func AddRequest(s *subject.Named) Request
  • func CompileRequest(name compilation.Name, r compilation.CompileResult) Request
  • func RecipeRequest(sname string, arch id.ID, r recipe.Recipe) Request
  • func RunRequest(name compilation.Name, r compilation.RunResult) Request
  • func (b Request) SendTo(ctx context.Context, ch chan<- Request) error
• type Run

Variables

var (
	// ErrBadTarget occurs when the target request count for a Builder is non-positive.
	ErrBadTarget = errors.New("number of builder requests must be positive")

	// ErrBadBuilderName occurs when a builder request specifies a name that isn't in the builder's corpus.
	ErrBadBuilderName = errors.New("requested subject name not in builder")

	// ErrBadBuilderRequest occurs when a builder request has an unknown body type.
	ErrBadBuilderRequest = errors.New("unhandled builder request type")
)

Functions

func OnBuild

func OnBuild(m Message, obs ...Observer)

OnBuild sends an OnBuild message to each observer in obs.

func ParBuild

func ParBuild(ctx context.Context, nworkers int, src corpus.Corpus, cfg Config, f func(context.Context, subject.Named, chan<- Request) error) (corpus.Corpus, error)

ParBuild runs f in a parallelised manner across the subjects in src. It uses the responses from f in a Builder, and returns the resulting corpus. Note that src may be different from cfg.Init; this is useful when building a new corpus from scratch.

Types

type Add

type Add subject.Subject

Add is a request to add the given subject to the corpus.

type Builder

type Builder struct {

	// SendCh is the channel to which requests for the builder should be sent.
	SendCh chan<- Request
	// contains filtered or unexported fields
}

Builder handles the assembly of corpora from asynchronously-constructed subjects.

func New

func New(cfg Config) (*Builder, error)

New constructs a Builder according to cfg. It fails if the number of target requests is negative.

func (*Builder) Run

func (b *Builder) Run(ctx context.Context) (corpus.Corpus, error)

Run runs the builder in context ctx. Run is not thread-safe.

type Compile

type Compile struct {
	// CompilerID is the ID of the compiler that produced this result.
	CompilerID id.ID `json:"compiler_id,omitempty"`

	// Result is the compile result.
	Result compilation.CompileResult `json:"result,omitempty"`
}

Compile is a request to add the given compiler result to the named subject.

type Config

type Config struct {
	// Init is the initial corpus.
	// If nil, the Builder starts with a new corpus with capacity equal to NReqs.
	// Otherwise, it copies this corpus.
	Init corpus.Corpus

	// Manifest gives us the name of the task and the number of requests in it.
	Manifest

	// Obs is the list of observers to notify as the builder performs various tasks.
	Observers []Observer
}

Config is a configuration for a Builder.

type Manifest

type Manifest struct {
	// Name describes the build task that is starting.
	Name string `json:"name"`

	// NReqs is the number of requests in the build task.
	// The corpus builder will wait for this number of requests to arrive.
	NReqs int `json:"nreqs"`
}

Manifest describes the layout of a corpus build task.

type Message

type Message struct {
	observing.Batch

	// Manifest carries the name of the subject being (re-)built, if we're on a build-start.
	Name string `json:"name,omitempty"`

	// Request carries a builder request, if we're on a build-step.
	Request *Request `json:"request,omitempty"`
}

Message is the type of builder observation messages.

func EndMessage

func EndMessage() Message

EndMessage creates a build-end message.

func StartMessage

func StartMessage(m Manifest) Message

StartMessage creates an build-start message using manifest m.

func StepMessage

func StepMessage(i int, r Request) Message

StepMessage creates a build-step message for step i and request r.

type Observer

type Observer interface {
	// OnBuild sends a builder observation message.
	OnBuild(Message)
}

Observer is the interface for things that observe a builder.

type Recipe

type Recipe struct {
	// Arch is the ID of the architecture for which this lifting is occurring.
	Arch id.ID `json:"arch,omitempty"`

	// Recipe is the produced recipe.
	Recipe recipe.Recipe `json:"recipe,omitempty"`
}

Recipe is a request to add the given recipe to the named subject, under the named architecture.

type Request

type Request struct {
	// Name is the name of the subject to add or modify
	Name string `json:"name"`

	// Add is populated if this request is an Add.
	Add *Add `json:"add,omitempty"`

	// Compile is populated if this request is a Compile.
	Compile *Compile `json:"compile,omitempty"`

	// Recipe is populated if this request is a Recipe.
	Recipe *Recipe `json:"recipe,omitempty"`

	// Run is populated if this request is a Run.
	Run *Run `json:"run,omitempty"`
}

Request is the type of requests to a Builder.

func AddRequest

func AddRequest(s *subject.Named) Request

AddRequest constructs an add-subject request for subject s.

func CompileRequest

func CompileRequest(name compilation.Name, r compilation.CompileResult) Request

CompileRequest constructs an add-compile request for the compilation with name name and result r.

func RecipeRequest

func RecipeRequest(sname string, arch id.ID, r recipe.Recipe) Request

RecipeRequest constructs an add-recipe request for the subject with name sname, arch ID arch, and recipe r.

func RunRequest

func RunRequest(name compilation.Name, r compilation.RunResult) Request

RunRequest constructs an add-run request for the compilation with name name and result r.

func (Request) SendTo

func (b Request) SendTo(ctx context.Context, ch chan<- Request) error

SendTo tries to send this request down ch while checking to see if ctx has been cancelled.

type Run

type Run struct {
	// CompilerID is the ID of the compiler that produced this result.
	CompilerID id.ID `json:"compiler_id,omitempty"`

	// Run is the run result.
	Result compilation.RunResult `json:"result,omitempty"`
}

Run is a request to add the given run result to the named subject.