core

package
v9.3.0 Latest Latest
Warning

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

 Go to latest Published: Mar 17, 2019 License: Apache-2.0 Imports: 22 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	// ConfigPipelineDAGPath is the name of the Pipeline configuration option (Pipeline.Initialize())
	// which enables saving the items DAG to the specified file.
	ConfigPipelineDAGPath = "Pipeline.DAGPath"
	// ConfigPipelineDryRun is the name of the Pipeline configuration option (Pipeline.Initialize())
	// which disables Configure() and Initialize() invocation on each PipelineItem during the
	// Pipeline initialization.
	// Subsequent Run() calls are going to fail. Useful with ConfigPipelineDAGPath=true.
	ConfigPipelineDryRun = "Pipeline.DryRun"
	// ConfigPipelineCommits is the name of the Pipeline configuration option (Pipeline.Initialize())
	// which allows to specify the custom commit sequence. By default, Pipeline.Commits() is used.
	ConfigPipelineCommits = "Pipeline.Commits"
	// ConfigPipelineDumpPlan is the name of the Pipeline configuration option (Pipeline.Initialize())
	// which outputs the execution plan to stderr.
	ConfigPipelineDumpPlan = "Pipeline.DumpPlan"
	// ConfigPipelineHibernationDistance is the name of the Pipeline configuration option (Pipeline.Initialize())
	// which is the minimum number of actions between two sequential usages of
	// a branch to activate the hibernation optimization (cpu-memory trade-off). 0 disables.
	ConfigPipelineHibernationDistance = "Pipeline.HibernationDistance"
	// ConfigPipelinePrintActions is the name of the Pipeline configuration option (Pipeline.Initialize())
	// which enables printing the taken actions of the execution plan to stderr.
	ConfigPipelinePrintActions = "Pipeline.PrintActions"
	// DependencyCommit is the name of one of the three items in `deps` supplied to PipelineItem.Consume()
	// which always exists. It corresponds to the currently analyzed commit.
	DependencyCommit = "commit"
	// DependencyIndex is the name of one of the three items in `deps` supplied to PipelineItem.Consume()
	// which always exists. It corresponds to the currently analyzed commit's index.
	DependencyIndex = "index"
	// DependencyIsMerge is the name of one of the three items in `deps` supplied to PipelineItem.Consume()
	// which always exists. It indicates whether the analyzed commit is a merge commit.
	// Checking the number of parents is not correct - we remove the back edges during the DAG simplification.
	DependencyIsMerge = "is_merge"
	// MessageFinalize is the status text reported before calling LeafPipelineItem.Finalize()-s.
	MessageFinalize = "finalize"
)

Variables

View Source 
var Registry = &PipelineItemRegistry{
	provided:     map[string][]reflect.Type{},
	registered:   map[string]reflect.Type{},
	flags:        map[string]reflect.Type{},
	featureFlags: arrayFeatureFlags{Flags: []string{}, Choices: map[string]bool{}},
}

Registry contains all known pipeline item types.

Functions

func EnablePathFlagTypeMasquerade 

func EnablePathFlagTypeMasquerade()

EnablePathFlagTypeMasquerade changes the type of all "path" command line arguments from "string" to "path". This operation cannot be canceled and is intended to be used for better --help output.

func LoadCommitsFromFile 

func LoadCommitsFromFile(path string, repository *git.Repository) ([]*object.Commit, error)

LoadCommitsFromFile reads the file by the specified FS path and generates the sequence of commits by interpreting each line as a Git commit hash.

func PathifyFlagValue 

func PathifyFlagValue(flag *pflag.Flag)

PathifyFlagValue changes the type of a string command line argument to "path".

Types

type CommonAnalysisResult 

type CommonAnalysisResult struct {
	// BeginTime is the time of the first commit in the analysed sequence.
	BeginTime int64
	// EndTime is the time of the last commit in the analysed sequence.
	EndTime int64
	// CommitsNumber is the number of commits in the analysed sequence.
	CommitsNumber int
	// RunTime is the duration of Pipeline.Run().
	RunTime time.Duration
	// RunTimePerItem is the time elapsed by each PipelineItem.
	RunTimePerItem map[string]float64
}

CommonAnalysisResult holds the information which is always extracted at Pipeline.Run().

func MetadataToCommonAnalysisResult 

func MetadataToCommonAnalysisResult(meta *Metadata) *CommonAnalysisResult

MetadataToCommonAnalysisResult copies the data from a Protobuf message.

func (*CommonAnalysisResult) BeginTimeAsTime 

func (car *CommonAnalysisResult) BeginTimeAsTime() time.Time

BeginTimeAsTime converts the UNIX timestamp of the beginning to Go time.

func (CommonAnalysisResult) Copy 

func (car CommonAnalysisResult) Copy() CommonAnalysisResult

Copy produces a deep clone of the object.

func (*CommonAnalysisResult) EndTimeAsTime 

func (car *CommonAnalysisResult) EndTimeAsTime() time.Time

EndTimeAsTime converts the UNIX timestamp of the ending to Go time.

func (*CommonAnalysisResult) FillMetadata 

func (car *CommonAnalysisResult) FillMetadata(meta *pb.Metadata) *pb.Metadata

FillMetadata copies the data to a Protobuf message.

func (*CommonAnalysisResult) Merge 

func (car *CommonAnalysisResult) Merge(other *CommonAnalysisResult)

Merge combines the CommonAnalysisResult with an other one. We choose the earlier BeginTime, the later EndTime, sum the number of commits and the elapsed run times.

type ConfigurationOption 

type ConfigurationOption struct {
	// Name identifies the configuration option in facts.
	Name string
	// Description represents the help text about the configuration option.
	Description string
	// Flag corresponds to the CLI token with "--" prepended.
	Flag string
	// Type specifies the kind of the configuration option's value.
	Type ConfigurationOptionType
	// Default is the initial value of the configuration option.
	Default interface{}
}

ConfigurationOption allows for the unified, retrospective way to setup PipelineItem-s.

func (ConfigurationOption) FormatDefault 

func (opt ConfigurationOption) FormatDefault() string

FormatDefault converts the default value of ConfigurationOption to string. Used in the command line interface to show the argument's default value.

type ConfigurationOptionType 

type ConfigurationOptionType int

ConfigurationOptionType represents the possible types of a ConfigurationOption's value. 

const (
	// BoolConfigurationOption reflects the boolean value type.
	BoolConfigurationOption ConfigurationOptionType = iota
	// IntConfigurationOption reflects the integer value type.
	IntConfigurationOption
	// StringConfigurationOption reflects the string value type.
	StringConfigurationOption
	// FloatConfigurationOption reflects a floating point value type.
	FloatConfigurationOption
	// StringsConfigurationOption reflects the array of strings value type.
	StringsConfigurationOption
	// PathConfigurationOption reflects the file system path value type.
	PathConfigurationOption
)

func (ConfigurationOptionType) String 

func (opt ConfigurationOptionType) String() string

String() returns an empty string for the boolean type, "int" for integers and "string" for strings. It is used in the command line interface to show the argument's type.

type FeaturedPipelineItem 

type FeaturedPipelineItem interface {
	PipelineItem
	// Features returns the list of names which enable this item to be automatically inserted
	// in Pipeline.DeployItem().
	Features() []string
}

FeaturedPipelineItem enables switching the automatic insertion of pipeline items on or off.

type HibernateablePipelineItem 

type HibernateablePipelineItem interface {
	PipelineItem
	// Hibernate signals that the item is temporarily not needed and it's memory can be optimized.
	Hibernate() error
	// Boot signals that the item is needed again and must be de-hibernate-d.
	Boot() error
}

HibernateablePipelineItem is the interface to allow pipeline items to be frozen (compacted, unloaded) while they are not needed in the hosting branch.

type LeafPipelineItem 

type LeafPipelineItem interface {
	PipelineItem
	// Flag returns the cmdline switch to run the analysis. Should be dash-lower-case
	// without the leading dashes.
	Flag() string
	// Description returns the text which explains what the analysis is doing.
	// Should start with a capital letter and end with a dot.
	Description() string
	// Finalize returns the result of the analysis.
	Finalize() interface{}
	// Serialize encodes the object returned by Finalize() to YAML or Protocol Buffers.
	Serialize(result interface{}, binary bool, writer io.Writer) error
}

LeafPipelineItem corresponds to the top level pipeline items which produce the end results.

type Metadata 

type Metadata = pb.Metadata

Metadata is defined in internal/pb/pb.pb.go - header of the binary file.

type NoopMerger 

type NoopMerger struct {
}

NoopMerger provides an empty Merge() method suitable for PipelineItem.

func (*NoopMerger) Merge 

func (merger *NoopMerger) Merge(branches []PipelineItem)

Merge does nothing.

type OneShotMergeProcessor 

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

OneShotMergeProcessor provides the convenience method to consume merges only once.

func (*OneShotMergeProcessor) Initialize 

func (proc *OneShotMergeProcessor) Initialize()

Initialize resets OneShotMergeProcessor.

func (*OneShotMergeProcessor) ShouldConsumeCommit 

func (proc *OneShotMergeProcessor) ShouldConsumeCommit(deps map[string]interface{}) bool

ShouldConsumeCommit returns true on regular commits. It also returns true upon the first occurrence of a particular merge commit.

type Pipeline 

type Pipeline struct {
	// OnProgress is the callback which is invoked in Analyse() to output it's
	// progress. The first argument is the number of complete steps, the
	// second is the total number of steps and the third is some description of the current action.
	OnProgress func(int, int, string)

	// HibernationDistance is the minimum number of actions between two sequential usages of
	// a branch to activate the hibernation optimization (cpu-memory trade-off). 0 disables.
	HibernationDistance int

	// DryRun indicates whether the items are not executed.
	DryRun bool

	// DumpPlan indicates whether to print the execution plan to stderr.
	DumpPlan bool

	// PrintActions indicates whether to print the taken actions during the execution.
	PrintActions bool
	// contains filtered or unexported fields
}

Pipeline is the core Hercules entity which carries several PipelineItems and executes them. See the extended example of how a Pipeline works in doc.go

func NewPipeline 

func NewPipeline(repository *git.Repository) *Pipeline

NewPipeline initializes a new instance of Pipeline struct.

func (*Pipeline) AddItem 

func (pipeline *Pipeline) AddItem(item PipelineItem) PipelineItem

AddItem inserts a PipelineItem into the pipeline. It does not check any dependencies. See also: DeployItem().

func (*Pipeline) Commits 

func (pipeline *Pipeline) Commits(firstParent bool) ([]*object.Commit, error)

Commits returns the list of commits from the history similar to `git log` over the HEAD. `firstParent` specifies whether to leave only the first parent after each merge (`git log --first-parent`) - effectively decreasing the accuracy but increasing performance.

func (*Pipeline) DeployItem 

func (pipeline *Pipeline) DeployItem(item PipelineItem) PipelineItem

DeployItem inserts a PipelineItem into the pipeline. It also recursively creates all of it's dependencies (PipelineItem.Requires()). Returns the same item as specified in the arguments.

func (*Pipeline) GetFact 

func (pipeline *Pipeline) GetFact(name string) interface{}

GetFact returns the value of the fact with the specified name.

func (*Pipeline) GetFeature 

func (pipeline *Pipeline) GetFeature(name string) (bool, bool)

GetFeature returns the state of the feature with the specified name (enabled/disabled) and whether it exists. See also: FeaturedPipelineItem.

func (*Pipeline) Initialize 

func (pipeline *Pipeline) Initialize(facts map[string]interface{}) error

Initialize prepares the pipeline for the execution (Run()). This function resolves the execution DAG, Configure()-s and Initialize()-s the items in it in the topological dependency order. `facts` are passed inside Configure(). They are mutable.

func (*Pipeline) Len 

func (pipeline *Pipeline) Len() int

Len returns the number of items in the pipeline.

func (*Pipeline) RemoveItem 

func (pipeline *Pipeline) RemoveItem(item PipelineItem)

RemoveItem deletes a PipelineItem from the pipeline. It leaves all the rest of the items intact.

func (*Pipeline) Run 

func (pipeline *Pipeline) Run(commits []*object.Commit) (map[LeafPipelineItem]interface{}, error)

Run method executes the pipeline.

`commits` is a slice with the git commits to analyse. Multiple branches are supported.

Returns the mapping from each LeafPipelineItem to the corresponding analysis result. There is always a "nil" record with CommonAnalysisResult.

func (*Pipeline) SetFact 

func (pipeline *Pipeline) SetFact(name string, value interface{})

SetFact sets the value of the fact with the specified name.

func (*Pipeline) SetFeature 

func (pipeline *Pipeline) SetFeature(name string)

SetFeature sets the value of the feature with the specified name. See also: FeaturedPipelineItem.

func (*Pipeline) SetFeaturesFromFlags 

func (pipeline *Pipeline) SetFeaturesFromFlags(registry ...*PipelineItemRegistry)

SetFeaturesFromFlags enables the features which were specified through the command line flags which belong to the given PipelineItemRegistry instance. See also: AddItem().

type PipelineItem 

type PipelineItem interface {
	// Name returns the name of the analysis.
	Name() string
	// Provides returns the list of keys of reusable calculated entities.
	// Other items may depend on them.
	Provides() []string
	// Requires returns the list of keys of needed entities which must be supplied in Consume().
	Requires() []string
	// ListConfigurationOptions returns the list of available options which can be consumed by Configure().
	ListConfigurationOptions() []ConfigurationOption
	// Configure performs the initial setup of the object by applying parameters from facts.
	// It allows to create PipelineItems in a universal way.
	Configure(facts map[string]interface{}) error
	// Initialize prepares and resets the item. Consume() requires Initialize()
	// to be called at least once beforehand.
	Initialize(*git.Repository) error
	// Consume processes the next commit.
	// deps contains the required entities which match Depends(). Besides, it always includes
	// DependencyCommit and DependencyIndex.
	// Returns the calculated entities which match Provides().
	Consume(deps map[string]interface{}) (map[string]interface{}, error)
	// Fork clones the item the requested number of times. The data links between the clones
	// are up to the implementation. Needed to handle Git branches. See also Merge().
	// Returns a slice with `n` fresh clones. In other words, it does not include the original item.
	Fork(n int) []PipelineItem
	// Merge combines several branches together. Each is supposed to have been created with Fork().
	// The result is stored in the called item, thus this function returns nothing.
	// Merge() must update all the branches, not only self. When several branches merge, some of
	// them may continue to live, hence this requirement.
	Merge(branches []PipelineItem)
}

PipelineItem is the interface for all the units in the Git commits analysis pipeline.

func ForkCopyPipelineItem 

func ForkCopyPipelineItem(origin PipelineItem, n int) []PipelineItem

ForkCopyPipelineItem clones items by copying them by value from the origin.

func ForkSamePipelineItem 

func ForkSamePipelineItem(origin PipelineItem, n int) []PipelineItem

ForkSamePipelineItem clones items by referencing the same origin.

type PipelineItemRegistry 

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

PipelineItemRegistry contains all the known PipelineItem-s.

func (*PipelineItemRegistry) AddFlags 

func (registry *PipelineItemRegistry) AddFlags(flagSet *pflag.FlagSet) (
	map[string]interface{}, map[string]*bool)

AddFlags inserts the cmdline options from PipelineItem.ListConfigurationOptions(), FeaturedPipelineItem().Features() and LeafPipelineItem.Flag() into the global "flag" parser built into the Go runtime. Returns the "facts" which can be fed into PipelineItem.Configure() and the dictionary of runnable analysis (LeafPipelineItem) choices. E.g. if "BurndownAnalysis" was activated through "-burndown" cmdline argument, this mapping would contain ["BurndownAnalysis"] = *true.

func (*PipelineItemRegistry) CollectAllDependencies added in v9.3.0 

func (registry *PipelineItemRegistry) CollectAllDependencies(item PipelineItem) []PipelineItem

CollectAllDependencies recursively builds the list of all the items on which the specified item depends.

func (*PipelineItemRegistry) GetFeaturedItems 

func (registry *PipelineItemRegistry) GetFeaturedItems() map[string][]PipelineItem

GetFeaturedItems returns all FeaturedPipelineItem-s registered.

func (*PipelineItemRegistry) GetLeaves 

func (registry *PipelineItemRegistry) GetLeaves() []LeafPipelineItem

GetLeaves returns all LeafPipelineItem-s registered.

func (*PipelineItemRegistry) GetPlumbingItems 

func (registry *PipelineItemRegistry) GetPlumbingItems() []PipelineItem

GetPlumbingItems returns all non-LeafPipelineItem-s registered.

func (*PipelineItemRegistry) Register 

func (registry *PipelineItemRegistry) Register(example PipelineItem)

Register adds another PipelineItem to the registry.

func (*PipelineItemRegistry) Summon 

func (registry *PipelineItemRegistry) Summon(providesOrName string) []PipelineItem

Summon searches for PipelineItem-s which provide the specified entity or named after the specified string. It materializes all the found types and returns them.

type ResultMergeablePipelineItem 

type ResultMergeablePipelineItem interface {
	LeafPipelineItem
	// Deserialize loads the result from Protocol Buffers blob.
	Deserialize(pbmessage []byte) (interface{}, error)
	// MergeResults joins two results together. Common-s are specified as the global state.
	MergeResults(r1, r2 interface{}, c1, c2 *CommonAnalysisResult) interface{}
}

ResultMergeablePipelineItem specifies the methods to combine several analysis results together.

Source Files

View all Source files

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.