exec

Documentation

Overview

Package exec implements execution of a graph of Action and Events.

- Actions produce Events when they complete. - Events fulfill dependencies of Actions so they can be executed.

Example

- CreateForwardingRule (CFR) depends on the TargetProxyExists (TPE). - CreateTargetProxy (CTP) signals TargetProxyExists (TPE). - CTP does not have dependencies.

Then the execution trace will be CTP -> TPE -> CFR.

Index

• Variables
• func NewParallelExecutor(c cloud.Cloud, pending []Action, opts ...Option) (*parallelExecutor, error)
• func NewSerialExecutor(c cloud.Cloud, pending []Action, opts ...Option) (*serialExecutor, error)
• type Action
  • func NewDoesNotExistAction(id *cloud.ResourceID) Action
  • func NewExistsAction(id *cloud.ResourceID) Action
  • func NewRetriableAction(a Action, canRetry func(error) (bool, time.Duration)) Action
• type ActionBase
  • func (b *ActionBase) CanRun() bool
  • func (b *ActionBase) PendingEvents() EventList
  • func (b *ActionBase) Signal(ev Event) bool
• type ActionMetadata
• type ActionType
• type ActionWithErr
• type ErrorStrategy
• type Event
  • func NewDropRefEvent(from, to *cloud.ResourceID) Event
  • func NewExistsEvent(id *cloud.ResourceID) Event
  • func NewNotExistsEvent(id *cloud.ResourceID) Event
• type EventList
  • func (el EventList) Equal(other EventList) bool
• type Executor
• type ExecutorConfig
• type GraphvizTracer
  • func NewGraphvizTracer() *GraphvizTracer
  • func (tr *GraphvizTracer) Finish(pending []Action)
  • func (tr *GraphvizTracer) Record(entry *TraceEntry, err error)
  • func (tr *GraphvizTracer) String() string
• type Option
  • func DryRunOption(dryRun bool) Option
  • func ErrorStrategyOption(s ErrorStrategy) Option
  • func TimeoutOption(t time.Duration) Option
  • func TracerOption(t Tracer) Option
  • func WaitForOrphansTimeoutOption(t time.Duration) Option
• type Result
  • func (r *Result) DeepCopy() *Result
• type StringEvent
  • func (e StringEvent) Equal(other Event) bool
  • func (e StringEvent) String() string
• type TraceEntry
• type TraceSignal
• type Tracer

Variables

var (
	ErrPendingActions = errors.New("Executor did not process all actions")
)

Functions

func NewParallelExecutor

func NewParallelExecutor(c cloud.Cloud, pending []Action, opts ...Option) (*parallelExecutor, error)

NewParallelExecutor returns a new Executor that runs tasks multi-threaded.

func NewSerialExecutor

func NewSerialExecutor(c cloud.Cloud, pending []Action, opts ...Option) (*serialExecutor, error)

NewSerialExecutor returns a new Executor that runs tasks single-threaded.

Types

type Action

type Action interface {
	// CanRun returns true if all of the Events this Action is waiting for have
	// been signaled.
	CanRun() bool
	// Signal this Action with the Event that has occurred. Returns true if the
	// Action was waiting on the Event being Signaled.
	Signal(Event) bool
	// Run the Action, performing the operations. Returns a list of Events to
	// signal and/or any errors that have occurred.
	Run(context.Context, cloud.Cloud) (EventList, error)
	// DryRun simulates running the Action. Returns a list of Events to signal.
	DryRun() EventList
	// String returns a human-readable representation of the Action for logging.
	String() string

	// PendingEvents is the list of events that this Action is still waiting on.
	PendingEvents() EventList

	// Metadata returns metadata used for visualizations.
	Metadata() *ActionMetadata
}

Action is an operation that updates external resources. An Action depends on zero or more Events to be Signaled before the Action CanRun.

func NewDoesNotExistAction

func NewDoesNotExistAction(id *cloud.ResourceID) Action

func NewExistsAction

func NewExistsAction(id *cloud.ResourceID) Action

NewExistsAction returns an Action that signals the existence of a Resource. It has no other side effects.

func NewRetriableAction

func NewRetriableAction(a Action, canRetry func(error) (bool, time.Duration)) Action

NewRetriableAction is an Action which check if a given action can be retired after error. On error the action will be retried when canRetry(err) returns true and duration for backoff. Duration equals 0 means that the action needs to be retried right away.

type ActionBase

type ActionBase struct {
	// Want are the events this action is still waiting for.
	Want EventList
	// Done tracks the events that have happened. This is for debugging.
	Done EventList
}

ActionBase is a helper that implements some standard behaviors of common Action implementation.

func (*ActionBase) CanRun

func (b *ActionBase) CanRun() bool

func (*ActionBase) PendingEvents

func (b *ActionBase) PendingEvents() EventList

func (*ActionBase) Signal

func (b *ActionBase) Signal(ev Event) bool

type ActionMetadata

type ActionMetadata struct {
	// Name of this action. This must be unique to the execution graph.
	Name string
	// Type of this action.
	Type ActionType
	// Summary is a human readable description of this action.
	Summary string
}

ActionMetadata is used by visualizations.

type ActionType

type ActionType string

var (
	ActionTypeCreate ActionType = "Create"
	ActionTypeDelete ActionType = "Delete"
	ActionTypeUpdate ActionType = "Update"
	ActionTypeMeta   ActionType = "Meta"
	ActionTypeCustom ActionType = "Custom"
)

type ActionWithErr

type ActionWithErr struct {
	Action Action
	Err    error
}

type ErrorStrategy

type ErrorStrategy string

ErrorStrategy to use when an Action returns an error.

var (
	// ContinueOnError tells the Executor to continue to execute as much of the
	// plan as possible. Note that the dependencies of failed Actions will
	// remain pending and not run.
	ContinueOnError ErrorStrategy = "ContinueOnError"
	// StopOnError attempts to stop execution early if there are errors. Due to
	// asynchronous execution, some Actions may continue to be executed after
	// error detection.
	StopOnError ErrorStrategy = "StopOnError"
)

type Event

type Event interface {
	// Equal returns true if this event is == to other.
	Equal(other Event) bool
	// String implements Stringer. The values returned by String() must satisfy
	// the same behavior as Equal(), i.e. a.String() == b.String() if and only
	// if a.Equal(b).
	String() string
}

Event occurs when an Action completes. Events can signal dependent Actions to be available for execution.

func NewDropRefEvent

func NewDropRefEvent(from, to *cloud.ResourceID) Event

NewDropRefEvent returns an event that signals that a resource reference has changed (From no longer refers to To).

func NewExistsEvent

func NewExistsEvent(id *cloud.ResourceID) Event

NewExistsEvent returns and event that signals that the resource ID exists.

func NewNotExistsEvent

func NewNotExistsEvent(id *cloud.ResourceID) Event

NewNotExistsEvent returns and event that signals that the resource ID no longer exists.

type EventList

type EventList []Event

EventList is a list of events.

func (EventList) Equal

func (el EventList) Equal(other EventList) bool

Equal is true if other contains the same set (order independent) of events.

type Executor

type Executor interface {
	// Run the actions. Returns non-nil if there was an error in execution of
	// one or more Actions.
	Run(context.Context) (*Result, error)
}

Executor performs the operations given by a list of Actions.

type ExecutorConfig

type ExecutorConfig struct {
	Tracer                Tracer
	DryRun                bool
	ErrorStrategy         ErrorStrategy
	Timeout               time.Duration
	WaitForOrphansTimeout time.Duration
}

ExecutorConfig for the executor implementation.

type GraphvizTracer

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

GraphvizTracer outputs Graphviz .dot format. This object is thread-safe.

func NewGraphvizTracer

func NewGraphvizTracer() *GraphvizTracer

NewGraphvizTracer returns a new Tracer that outputs Graphviz.

func (*GraphvizTracer) Finish

func (tr *GraphvizTracer) Finish(pending []Action)

func (*GraphvizTracer) Record

func (tr *GraphvizTracer) Record(entry *TraceEntry, err error)

func (*GraphvizTracer) String

func (tr *GraphvizTracer) String() string

type Option

type Option func(*ExecutorConfig)

func DryRunOption

func DryRunOption(dryRun bool) Option

DryRunOption will run in dry run mode if true.

func ErrorStrategyOption

func ErrorStrategyOption(s ErrorStrategy) Option

ErrorStrategyOption sets the error handling strategy.

func TimeoutOption

func TimeoutOption(t time.Duration) Option

TimeoutOption sets timeout for executor Run function. This option can be used with parallel executor only.

func TracerOption

func TracerOption(t Tracer) Option

TracerOption sets a tracer to accumulate the execution of the Actions.

func WaitForOrphansTimeoutOption

func WaitForOrphansTimeoutOption(t time.Duration) Option

WaitForOrphansTimeoutOption sets timeout for cleaning up the orphans when the executor finishes with error. This option can be used with parallel executor only.

type Result

type Result struct {
	// Completed Actions with no errors.
	Completed []Action
	// Errors are Actions that failed with an error.
	Errors []ActionWithErr
	// Pending are Actions that could not be executed due to missing
	// preconditions.
	Pending []Action
}

func (*Result) DeepCopy

func (r *Result) DeepCopy() *Result

type StringEvent

type StringEvent string

StringEvent is an Event identified by a string. This is an easy way to create custom events.

func (StringEvent) Equal

func (e StringEvent) Equal(other Event) bool

func (StringEvent) String

func (e StringEvent) String() string

type TraceEntry

type TraceEntry struct {
	Action   Action
	Err      error
	Signaled []TraceSignal

	Start time.Time
	End   time.Time
}

TraceEntry represents the execution of an Action.

type TraceSignal

type TraceSignal struct {
	Event          Event
	SignaledAction Action
}

TraceSignal represents the signal of an Event.

type Tracer

type Tracer interface {
	Record(entry *TraceEntry, err error)
	Finish(pending []Action)
}

Tracer is a sink for tracing an execution.