Documentation
¶
Overview ¶
multistep is a Go library for building up complex actions using discrete, individual "steps." These steps are strung together and run in sequence to achieve a more complex goal. The runner handles cleanup, cancelling, etc. if necessary.
## Basic Example
Make a step to perform some action. The step can access your "state", which is passed between steps by the runner.
```go type stepAdd struct{}
func (s *stepAdd) Run(ctx context.Context, state multistep.StateBag) multistep.StepAction {
// Read our value and assert that it is they type we want
value := state.Get("value").(int)
fmt.Printf("Value is %d\n", value)
// Store some state back
state.Put("value", value + 1)
return multistep.ActionContinue
}
func (s *stepAdd) Cleanup(multistep.StateBag) {
// This is called after all the steps have run or if the runner is
// cancelled so that cleanup can be performed.
}
```
Make a runner and call your array of Steps.
```go
func main() {
// Our "bag of state" that we read the value from
state := new(multistep.BasicStateBag)
state.Put("value", 0)
steps := []multistep.Step{
&stepAdd{},
&stepAdd{},
&stepAdd{},
}
runner := &multistep.BasicRunner{Steps: steps}
// Executes the steps
runner.Run(context.Background(), state)
}
```
This will produce:
``` Value is 0 Value is 1 Value is 2 ```
multistep is a library for building up complex actions using individual, discrete steps.
Index ¶
Constants ¶
const StateCancelled = "cancelled"
This is the key set in the state bag when using the basic runner to signal that the step sequence was cancelled.
const StateHalted = "halted"
This is the key set in the state bag when a step halted the sequence.
Variables ¶
This section is empty.
Functions ¶
func DebugPauseDefault ¶
func DebugPauseDefault(loc DebugLocation, name string, state StateBag)
DebugPauseDefault is the default pause function when using the DebugRunner if no PauseFn is specified. It outputs some information to stderr about the step and waits for keyboard input on stdin before continuing.
Types ¶
type BasicRunner ¶
type BasicRunner struct {
// Steps is a slice of steps to run. Once set, this should _not_ be
// modified.
Steps []Step
// contains filtered or unexported fields
}
BasicRunner is a Runner that just runs the given slice of steps.
type BasicStateBag ¶
type BasicStateBag struct {
// contains filtered or unexported fields
}
BasicStateBag implements StateBag by using a normal map underneath protected by a RWMutex.
func (*BasicStateBag) Get ¶
func (b *BasicStateBag) Get(k string) interface{}
func (*BasicStateBag) GetOk ¶
func (b *BasicStateBag) GetOk(k string) (interface{}, bool)
func (*BasicStateBag) Put ¶
func (b *BasicStateBag) Put(k string, v interface{})
func (*BasicStateBag) Remove ¶
func (b *BasicStateBag) Remove(k string)
type DebugLocation ¶
type DebugLocation uint
DebugLocation is the location where the pause is occurring when debugging a step sequence. "DebugLocationAfterRun" is after the run of the named step. "DebugLocationBeforeCleanup" is before the cleanup of the named step.
const ( DebugLocationAfterRun DebugLocation = iota DebugLocationBeforeCleanup )
type DebugPauseFn ¶
type DebugPauseFn func(DebugLocation, string, StateBag)
DebugPauseFn is the type signature for the function that is called whenever the DebugRunner pauses. It allows the caller time to inspect the state of the multi-step sequence at a given step.
type DebugRunner ¶
type DebugRunner struct {
// Steps is the steps to run. These will be run in order.
Steps []Step
// PauseFn is the function that is called whenever the debug runner
// pauses. The debug runner continues when this function returns.
// The function is given the state so that the state can be inspected.
PauseFn DebugPauseFn
// contains filtered or unexported fields
}
DebugRunner is a Runner that runs the given set of steps in order, but pauses between each step until it is told to continue.
type Runner ¶
type Runner interface {
// Run runs the steps with the given initial state.
Run(context.Context, StateBag)
}
Runner is a thing that runs one or more steps.
type StateBag ¶
type StateBag interface {
Get(string) interface{}
GetOk(string) (interface{}, bool)
Put(string, interface{})
Remove(string)
}
StateBag holds the state that is used by the Runner and Steps. The StateBag implementation must be safe for concurrent access.
type Step ¶
type Step interface {
// Run is called to perform the action. The passed through context will be
// cancelled when the runner is cancelled. The second parameter is a "state
// bag" of untyped things. Please be very careful about type-checking the
// items in this bag.
//
// The return value determines whether multi-step sequences continue
// or should halt.
Run(context.Context, StateBag) StepAction
// Cleanup is called in reverse order of the steps that have run
// and allow steps to clean up after themselves. Do not assume if this
// ran that the entire multi-step sequence completed successfully. This
// method can be ran in the face of errors and cancellations as well.
//
// The parameter is the same "state bag" as Run, and represents the
// state at the latest possible time prior to calling Cleanup.
Cleanup(StateBag)
}
Step is a single step that is part of a potentially large sequence of other steps, responsible for performing some specific action.
type StepAction ¶
type StepAction uint
A StepAction determines the next step to take regarding multi-step actions.
const ( ActionContinue StepAction = iota ActionHalt )
func (StepAction) String ¶
func (a StepAction) String() string
Implement the stringer interface; useful for testing.
type StepWrapper ¶
type StepWrapper interface {
// InnerStepName should return the human readable name of the wrapped step.
InnerStepName() string
}
StepWrapper is an interface that wrapped steps can implement to expose their inner step names to the debug runner.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
The commonsteps package contains the multistep runner that comprises the main architectural convention of Packer builder plugins.
|
The commonsteps package contains the multistep runner that comprises the main architectural convention of Packer builder plugins. |