master

package
v0.1.1 Latest Latest
Warning

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

 Go to latest Published: Aug 15, 2023 License: MIT Imports: 13 Imported by: 0

Documentation

Overview

Package master implements the components for executing goals and sub-tasks across multiple plugins concurrently with proper interleaving and error handling.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func RunTasksAndAccumulate 

func RunTasksAndAccumulate[Idx comparable, In, Out any](
	ctx context.Context,
	inputs Iterable[Idx, In],
	task func(context.Context, Idx, In) (Out, error),
) ([]Out, error)

RunTasksAndAccumulate runs the task function for each input returned by the Iterable. Each task is run concurrently. The results and errors are accumulated. The accumulator values and errors and returned once all tasks have completed.

func RunTasksAndAccumulateErrors 

func RunTasksAndAccumulateErrors[Idx comparable, In any](
	ctx context.Context,
	inputs Iterable[Idx, In],
	task func(context.Context, Idx, In) error,
) error

RunTasksAndAccumulateErrors runs all the given task against all the inputs concurrently. Then it returns any errors that were returned by any of those tasks.

Types

type CompletionExecutor added in v0.1.0 

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

CompletionExecutor executes the Complete operation that must run when a task is complete. This runs Complete for all tasks concurrently, collects the errors, and returns them.

func (*CompletionExecutor) Execute added in v0.1.0 

func (c *CompletionExecutor) Execute(
	ctx context.Context,
) error

type Interface 

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

Interface is a plugin.Interface implementation that aids in the execution of a set of other plugin.Interface implementations. This is combined with the use of InterfaceExecutor to provide a full set of tools for concurrently executing a goal or task.

func NewInterface 

func NewInterface(
	logger hclog.Logger,
	cfg *config.Config,
	is map[string]plugin.Interface,
) *Interface

NewInterface creates a new Interface object for the given configuration and plugins.

func (*Interface) Cancel 

func (ti *Interface) Cancel(
	ctx context.Context,
	pluginTask plugin.Task,
) error

Cancel performs cancellation for task in progress. It works to immediately terminate and close out any resources held by all associated plugins.

func (*Interface) Complete 

func (ti *Interface) Complete(
	ctx context.Context,
	pluginTask plugin.Task,
) error

Complete performs completion for the task in progress. It frees up resources held by the master.Interface as well as telling each plugin to free up any resources associated with task execution on their end for all plugins associated with this task.

func (*Interface) Define 

func (ti *Interface) Define(values map[string]string)

Define records a new value to store in the in-memory properties used during interface execution.

func (*Interface) GetInterface 

func (ti *Interface) GetInterface(name string) plugin.Interface

GetInterface retrieves the plugin.Interface for the named plugin.

func (*Interface) Goal 

func (ti *Interface) Goal(
	ctx context.Context,
	name string,
) (plugin.GoalDescription, error)

Goal calls Goal for the given goal name on all associated plugins. If no plugin provides a plugin.GoalDescription for this goal, then plugin.ErrUnsupportedGoal is returned. Otherwise, the first GoalDescription received is returned. If multiple plugins describe a goal with the same name, the behavior is non-deterministic.

func (*Interface) Implements 

func (ti *Interface) Implements(ctx context.Context) ([]plugin.TaskDescription, error)

Implements calls Implements on all the associated plugins and returns a combined list of all the tasks defined by all the plugins. It fails with an error if any plugin fails with an error.

func (*Interface) Prepare 

func (ti *Interface) Prepare(
	ctx context.Context,
	taskName string,
) (plugin.Task, error)

Prepare calls the Prepare method on all plugins which implements the named task. This returns a pointer to a master.Task which is able to execute the task for all these plugins. If no plugin implements the named task, then this method fails with plugin.ErrUnsupportedTask instead.

func (*Interface) SetTargetName 

func (ti *Interface) SetTargetName(name string)

SetTargetName changes the target used to select the configuration used during execution.

type InterfaceExecutor 

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

InterfaceExecutor is a tool for executing plugin.Interface objects. It must be paired with the master.Interface to help perform this task.

These exist as separate objects because of the separation of concerns between these two objects. This object is focused on executing all the operations of a task in the correct order and then resolve any errors that occur correctly.

func NewExecutor 

func NewExecutor(logger hclog.Logger, m *Interface) *InterfaceExecutor

NewExecutor creates a new InterfaceExecutor paired with the given Interface.

func (*InterfaceExecutor) Define 

func (e *InterfaceExecutor) Define(values map[string]string)

Define is used to set properties from the command-line or other locations to be used when running the plugin.Interface.

func (*InterfaceExecutor) PotentialGoalsPhasesAndTasks added in v0.1.0 

func (e *InterfaceExecutor) PotentialGoalsPhasesAndTasks(
	ctx context.Context,
) ([]*group.Goal, error)

PotentialGoalsPhasesAndTasks builds an returns a slice of TaskGroup objects that will be executed as part of this InterfaceExecutor.

func (*InterfaceExecutor) PrepareGoalPlan added in v0.1.0 

func (e *InterfaceExecutor) PrepareGoalPlan(
	goal *group.Goal,
) *PhasePlan

PrepareGoalPlan executes all the tasks in a goal. Tasks are grouped into phases. Each phase is run one at a time in order. These may be executed concurrently. The tasks within each phase are run simultaneously and interleaved (with individual operations sometimes running concurrently).

func (*InterfaceExecutor) PreparePhasePlan added in v0.1.0 

func (e *InterfaceExecutor) PreparePhasePlan(
	phases []*group.Phase,
) *PhasePlan

PreparePhasePlan executes all the tasks related to the listed phases.

func (*InterfaceExecutor) SetTargetName 

func (e *InterfaceExecutor) SetTargetName(name string)

SetTargetName is used to update the target name to use when configuring the plugin.Context used to execute plugin.Interface.

type Iterable 

type Iterable[Idx comparable, Val any] interface {
	// Next increments the internal cursor to refer to the next object. It
	// returns true if another object exists or false if the end of iteration
	// has been reached.
	Next() bool

	// Id returns the ID value of the current value.
	Id() Idx

	// Value returns the value of the current value.
	Value() Val

	// Len reports the lengths of the iterated object.
	Len() int
}

Iterable is a helper to the concurrent execution tools RunTasksAndAccumulate and RunTasksAndAccumulateErrors. It provides a generic iterator that can be used to iterate over slices and maps of whatever types.

type MapIterator 

type MapIterator[Idx comparable, Val any] struct {
	// contains filtered or unexported fields
}

MapIterator is a generic implementation of Iterable for maps.

func NewMapIterator 

func NewMapIterator[Idx comparable, Val any](
	is map[Idx]Val,
) *MapIterator[Idx, Val]

NewMapIterator will create an iterator that iterates over a given map.

func (*MapIterator[Idx, Val]) Id 

func (i *MapIterator[Idx, Val]) Id() Idx

Id returns the currnet key of the key/value pair iteration.

func (*MapIterator[Idx, Val]) Len 

func (i *MapIterator[Idx, Val]) Len() int

Len returns the len of the underlying map.

func (*MapIterator[Idx, Val]) Next 

func (i *MapIterator[Idx, Val]) Next() bool

Next returns false if there is no more work to do with this iterator. It returns true and increments the cursor pointer if there is more work to do.

func (*MapIterator[Idx, Val]) Value 

func (i *MapIterator[Idx, Val]) Value() Val

Value returns the current value of the key/value pair iteration.

type OperationExecutor added in v0.1.0 

type OperationExecutor interface {
	Execute(context.Context) error
}

OperationExecutor is the abstraction that abstracts away the differences between the different types of operations that are executed in the course of executing an operation.

type OperationFunc added in v0.1.0 

type OperationFunc func(plugin.Task, context.Context) error

OperationFunc is a more abstract version of plugin.OperationFunc.

type OperationHandler 

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

OperationHandler implements plugin.OperationHandler and is able to execute all the operations for all the plugins associated with executing a particular task, operation, stage, and priority order.

func (*OperationHandler) Call 

func (h *OperationHandler) Call(ctx context.Context) error

Call concurrently executes this associated operation and order in all plugins that can perform it. It initializes a plugin.Context for each and passes the associated configuration through to the plugin. Then, it updates the temporary properties for the task using the settings set by the plugin.

type PhaseContext added in v0.1.0 

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

PhaseContext provides a base context for use in tracking the state related to an execution phase.

func NewContext added in v0.1.0 

func NewContext(properties storage.KV) *PhaseContext

NewContext constructs and returns a new phase context.

func (*PhaseContext) ApplyChanges added in v0.1.0 

func (pc *PhaseContext) ApplyChanges(changes map[string]string)

ApplyChanges safely updates the changes applied to the current phase.

func (*PhaseContext) ListAdded added in v0.1.0 

func (pc *PhaseContext) ListAdded() []string

ListAdded returns the list of files added so far to this phase.

func (*PhaseContext) ToAdd added in v0.1.0 

func (pc *PhaseContext) ToAdd(files []string)

ToAdd adds more files to the phase.

type PhasePlan added in v0.1.0 

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

PhasePlan contains a set of phases to run and be executed.

func (*PhasePlan) CurrentPhase added in v0.1.0 

func (p *PhasePlan) CurrentPhase() *group.Phase

CurrentPhase returns information for the current phase. This may only be called after NextPhase has been called.

func (*PhasePlan) ExecutePhase added in v0.1.0 

func (p *PhasePlan) ExecutePhase(
	ctx context.Context,
) error

ExecutePhase will execute the next phase. It returns an error if the phase fails. If an error occurs, this will only return an error from then on.

func (*PhasePlan) NextPhase added in v0.1.0 

func (p *PhasePlan) NextPhase() bool

NextPhase will move on to the next phase. It must be called before each phase. Failing to call this between phases will cause an error. Returns false when there are no more phases to run.

type PluginTaskContext added in v0.1.0 

type PluginTaskContext struct {
	*PhaseContext
	// contains filtered or unexported fields
}

PluginTaskContext provides a value to be stored in context.Context to track the state of execution for the master interface and executor for a particular phase, task, target, and plugin. This object is accessible to the plugins.

func (*PluginTaskContext) KV added in v0.1.0 

func (ptc *PluginTaskContext) KV() *storage.KVCon

KV returns the configuration properties for the current task and plugin along with any per-phase changes that have been accumulated thus far.

type PrepareFunc added in v0.1.0 

type PrepareFunc func(plugin.Task, context.Context) (plugin.Operations, error)

PrepareFunc is an abstract version of plugin.Task operation functuons.

type SimpleExecutor added in v0.1.0 

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

SimpleExecutor is an executor that can execute one of the simple operations on a task. As of this writing, this includes the setup, check, finish, and teardown operations.

func (*SimpleExecutor) Execute added in v0.1.0 

func (s *SimpleExecutor) Execute(
	ctx context.Context,
) error

Execute runs all the configured operation stage for all tasks concurrently, collects the errors, and returns them.

type SliceIterator 

type SliceIterator[Val any] struct {
	// contains filtered or unexported fields
}

SliceIterator provide a generic implementation of Iterable over slice objects. The Idx type is always int, in this case.

func NewSliceIterator 

func NewSliceIterator[Val any](
	is []Val,
) *SliceIterator[Val]

NewSliceIterator creates a new iterator for the given slice.

func (*SliceIterator[Val]) Id 

func (i *SliceIterator[Val]) Id() int

Id returns the index of the current slice element during iteration.

func (*SliceIterator[Val]) Len 

func (i *SliceIterator[Val]) Len() int

Len returns the len of the underlying slice.

func (*SliceIterator[Val]) Next 

func (i *SliceIterator[Val]) Next() bool

Next returns false if there are no more elements in the slice to process. It returns true and increments the index to operate upon if there is another element to process.

func (*SliceIterator[Val]) Value 

func (i *SliceIterator[Val]) Value() Val

Value returns the value of the current slice element during iteration.

type StagedExecutor added in v0.1.0 

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

StagedExecutor handles the primary staged phases: begin, run, and end. This works by pulling all the prioritized operations and then executing each group in priority order. Operations with the same priority will be executed concurrently. Otherwise, operations are ordered by their plugin.Ordering, from lowest numbered ordering to highest. If an error happens at any point, the errors are returned and the operation terminates immediately without continuing on to any remaining operations.

func (*StagedExecutor) Execute added in v0.1.0 

func (s *StagedExecutor) Execute(
	ctx context.Context,
) error

Execute builds a plan for executing a staged operation and then executes that plan. Any errors that occur along the way are returned.

type Task 

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

Task implements plugin.Task by running the operations associated with a set of plugins whenever those operations are executed on this task object.

func (*Task) Begin 

func (t *Task) Begin(ctx context.Context) (plugin.Operations, error)

Begin collects all the prioritized operations for the Begin stage of all associated plugins and returns a set of master.Operation objects that can execute them.

func (*Task) Check 

func (t *Task) Check(ctx context.Context) error

Check executes the Check operation on all associated plugins concurrently.

func (*Task) End 

func (t *Task) End(ctx context.Context) (plugin.Operations, error)

End collects all the prioritized operations for the End stage of all associated plugins and returns a set of master.Operation objects that can execute them.

func (*Task) Finish 

func (t *Task) Finish(ctx context.Context) error

Finish executes the Finish operation on all associated plugins concurrently.

func (*Task) Run 

func (t *Task) Run(ctx context.Context) (plugin.Operations, error)

Run collects all the prioritized operations for the Run stage of all associated plugins and returns a set of master.Operation objects that can execute them.

func (*Task) Setup 

func (t *Task) Setup(ctx context.Context) error

Setup executes the Setup operation on all associated plugins concurrently.

func (*Task) Teardown 

func (t *Task) Teardown(ctx context.Context) error

Teardown executes the Teardown operation on all associated plugins concurrently.

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.