analysis

Documentation

Overview

Package analysis handles analysing a Corpus and filing its subjects into categorised sub-corpora.

Index

• type Analysis
  • func Analyse(ctx context.Context, p *plan.Plan, opts ...Option) (*Analysis, error)
  • func (a *Analysis) HasBadOutcomes() bool
  • func (a *Analysis) HasFailures() bool
  • func (a *Analysis) HasFlagged() bool
  • func (a *Analysis) String() string
• type Compiler
• type Filter
  • func (f Filter) Filter(ci compiler.Instance, log string) (bool, error)
• type FilterSet
  • func Compile(fs FilterSet) (FilterSet, error)
  • func LoadFilterSet(fpath string) (FilterSet, error)
  • func ReadFilterSet(r io.Reader) (FilterSet, error)
  • func (f FilterSet) Filter(ci compiler.Instance, log string) (bool, error)
  • func (f FilterSet) FilteredStatus(s status.Status, ci compiler.Instance, log string) (status.Status, error)
• type Option
  • func Options(opts ...Option) Option
  • func WithFilters(fs FilterSet) Option
  • func WithFiltersFromFile(path string) Option
  • func WithWorkerCount(nworkers int) Option
• type TimeSet
  • func NewTimeSet(raw ...time.Duration) *TimeSet
  • func (t TimeSet) Mean() time.Duration

Examples

• Analysis.HasBadOutcomes
• Analysis.HasFailures
• Analysis.HasFlagged
• Analysis.String
• NewTimeSet

Types

type Analysis

type Analysis struct {
	// Plan points to the plan that created this analyser.
	Plan *plan.Plan

	// ByStatus maps each status to the corpus of subjects that fall into it.
	ByStatus map[status.Status]corpus.Corpus

	// Compilers maps each compiler ID (or full-ID, depending on configuration) to an analysis of that compiler.
	Compilers map[id.ID]Compiler

	// Flags aggregates all flags found during the analysis.
	Flags status.Flag

	// Mutation, if non-nil, contains information about mutation testing done over this plan.
	Mutation mutation.Analysis
}

Analysis represents an analysis of a plan.

func Analyse

func Analyse(ctx context.Context, p *plan.Plan, opts ...Option) (*Analysis, error)

Analyse runs the analyser with context ctx, on plan p and with options opts.

func (*Analysis) HasBadOutcomes

func (a *Analysis) HasBadOutcomes() bool

HasBadOutcomes tests whether an analysis has any bad (flagged, failed, or timed-out) cases.

Example

ExampleAnalysis_HasBadOutcomes is a runnable example for Analysis.HasBadOutcomes.

package main

import (
	"fmt"

	"github.com/c4-project/c4t/internal/plan/analysis"

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

func main() {
	var empty analysis.Analysis
	fmt.Println("empty:", empty.HasBadOutcomes())

	cfails := analysis.Analysis{Flags: status.FlagCompileFail}
	fmt.Println("compiler failures:", cfails.HasBadOutcomes())

	rfails := analysis.Analysis{Flags: status.FlagRunFail}
	fmt.Println("run failures:", rfails.HasBadOutcomes())

	ctos := analysis.Analysis{Flags: status.FlagCompileTimeout}
	fmt.Println("compiler timeouts:", ctos.HasBadOutcomes())

	rtos := analysis.Analysis{Flags: status.FlagRunTimeout}
	fmt.Println("run timeouts:", rtos.HasBadOutcomes())

	flags := analysis.Analysis{Flags: status.FlagFlagged}
	fmt.Println("flagged:", flags.HasBadOutcomes())

	filts := analysis.Analysis{Flags: status.FlagFiltered}
	fmt.Println("filtered:", filts.HasBadOutcomes())

}

Output:

empty: false
compiler failures: true
run failures: true
compiler timeouts: true
run timeouts: true
flagged: true
filtered: false

func (*Analysis) HasFailures

func (a *Analysis) HasFailures() bool

HasFailures tests whether an analysis has failure cases.

Example

ExampleAnalysis_HasFailures is a runnable example for Analysis.HasFailures.

package main

import (
	"fmt"

	"github.com/c4-project/c4t/internal/plan/analysis"

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

func main() {
	var empty analysis.Analysis
	fmt.Println("empty:", empty.HasFailures())

	cfails := analysis.Analysis{Flags: status.FlagCompileFail}
	fmt.Println("compiler failures:", cfails.HasFailures())

	rfails := analysis.Analysis{Flags: status.FlagRunFail}
	fmt.Println("run failures:", rfails.HasFailures())

	ctos := analysis.Analysis{Flags: status.FlagCompileTimeout}
	fmt.Println("compiler timeouts:", ctos.HasFailures())

	rtos := analysis.Analysis{Flags: status.FlagRunTimeout}
	fmt.Println("run timeouts:", rtos.HasFailures())

	flags := analysis.Analysis{Flags: status.FlagFlagged}
	fmt.Println("flagged:", flags.HasFailures())

	filts := analysis.Analysis{Flags: status.FlagFiltered}
	fmt.Println("filtered:", filts.HasFailures())

}

Output:

empty: false
compiler failures: true
run failures: true
compiler timeouts: false
run timeouts: false
flagged: false
filtered: false

func (*Analysis) HasFlagged

func (a *Analysis) HasFlagged() bool

HasFlagged tests whether an analysis has flagged cases.

Example

ExampleAnalysis_HasFlagged is a runnable example for Analysis.HasFlagged.

package main

import (
	"fmt"

	"github.com/c4-project/c4t/internal/plan/analysis"

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

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

func main() {
	var empty analysis.Analysis
	fmt.Println("empty:", empty.HasFlagged())

	flagged := analysis.Analysis{
		ByStatus: map[status.Status]corpus.Corpus{
			status.Flagged: corpus.New("foo", "bar", "baz"),
		},
		Flags: status.FlagFlagged,
	}
	fmt.Println("flagged:", flagged.HasFlagged())

}

Output:

empty: false
flagged: true

func (*Analysis) String

func (a *Analysis) String() string

String summarises this collation as a string.

Example

ExampleAnalysis_String is a runnable example for String.

package main

import (
	"fmt"

	"github.com/c4-project/c4t/internal/plan/analysis"

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

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

func main() {
	c := 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(&c)

}

Output:

4 Ok, 5 Filtered, 1 Flagged, 3 CompileFail, 2 RunFail

type Compiler

type Compiler struct {
	// Info contains the compiler's plan record.
	Info compiler.Instance

	// Counts maps each status to the number of times it was observed across the corpus.
	Counts map[status.Status]int

	// Logs maps each subject name to its compiler log.
	Logs map[string]string

	// Time gathers statistics about how long, on average, this compiler took to compile corpus subjects.
	// It doesn't contain information about failed compilations.
	Time *TimeSet

	// RunTime gathers statistics about how long, on average, this compiler's compiled subjects took to run.
	// It doesn't contain information about failed compilations or runs (flagged runs are counted).
	RunTime *TimeSet
}

Compiler represents information about a compiler in a corpus analysis.

type Filter

type Filter struct {
	// Style is a glob identifier that selects a particular compiler style.
	Style id.ID `yaml:"style"`
	// MajorVersionBelow is a lower bound on the major version of the compiler, if set to a positive number.
	MajorVersionBelow int `yaml:"major_version_below,omitempty"`
	// ErrorPattern is an uncompiled regexp that selects a particular phrase in a compiler error.
	ErrorPattern string `yaml:"error_pattern,omitempty"`
	// contains filtered or unexported fields
}

Filter is the type of filters.

A filter, when triggered during analysis of a compilation, sets the 'filtered' flag on that compilation. This suppresses any non-OK status, replacing it with the 'filtered' status.

func (Filter) Filter

func (f Filter) Filter(ci compiler.Instance, log string) (bool, error)

Filter returns true if, and only if, this filter matches cm, ci, and log.

type FilterSet

type FilterSet []Filter

FilterSet is the type of sets of filter.

func Compile

func Compile(fs FilterSet) (FilterSet, error)

Compile compiles the filter set fs.

func LoadFilterSet

func LoadFilterSet(fpath string) (FilterSet, error)

LoadFilterSet loads a filter set from the filepath fpath.

func ReadFilterSet

func ReadFilterSet(r io.Reader) (FilterSet, error)

ReadFilterSet loads and compiles a filter set from the reader r.

func (FilterSet) Filter

func (f FilterSet) Filter(ci compiler.Instance, log string) (bool, error)

Filter returns true if, and only if, at least one filter in this set matches ci, and log.

func (FilterSet) FilteredStatus

func (f FilterSet) FilteredStatus(s status.Status, ci compiler.Instance, log string) (status.Status, error)

FilteredStatus returns s if FilterSet.Filter returns false over ci and log, or Filtered otherwise.

type Option

type Option func(*analyser) error

Option is the type of options to Analyse.

func Options

func Options(opts ...Option) Option

Options applies each option in opts onto the analyser.

func WithFilters

func WithFilters(fs FilterSet) Option

WithFilters appends the filters in fs to the filter set.

func WithFiltersFromFile

func WithFiltersFromFile(path string) Option

WithFiltersFromFile appends the filters in the filter file at path to the filter set. If the path is empty, we don't add any filters.

func WithWorkerCount

func WithWorkerCount(nworkers int) Option

WithWorkerCount sets the worker count of the analyser to nworkers.

type TimeSet

type TimeSet struct {
	// Min contains the minimum time reported across the corpus.
	Min time.Duration
	// Sum contains the total time reported across the corpus.
	Sum time.Duration
	// Max contains the maximum time reported across the corpus.
	Max time.Duration
	// Count contains the number of samples taken for this time set.
	Count int
}

TimeSet contains aggregate statistics about timing (of compilers, runs, etc).

func NewTimeSet

func NewTimeSet(raw ...time.Duration) *TimeSet

NewTimeSet produces a timeset from the given raw times.

Example

ExampleNewTimeSet is a runnable example for NewTimeSet.

package main

import (
	"fmt"
	"time"

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

func main() {
	ts := analysis.NewTimeSet(1*time.Second, 1*time.Second, 2*time.Second, 4*time.Second)
	fmt.Println("min", ts.Min)
	fmt.Println("avg", ts.Mean())
	fmt.Println("max", ts.Max)
	fmt.Println("sum", ts.Sum)
	fmt.Println("count", ts.Count)

}

Output:

min 1s
avg 2s
max 4s
sum 8s
count 4

func (TimeSet) Mean

func (t TimeSet) Mean() time.Duration

Mean calculates the arithmetic mean of the times in this set.