stop

Documentation

Index

• Constants
• Variables
• type StopControl
  • func NewStopControl(unit *engine.Unit, maxGracefulStopDuration time.Duration, log zerolog.Logger, ...) *StopControl
  • func (s *StopControl) BlockFinalized(h *flow.Header)
  • func (s *StopControl) BlockFinalizedForTesting(h *flow.Header)
  • func (s *StopControl) GetStopParameters() StopParameters
  • func (s *StopControl) IsExecutionStopped() bool
  • func (s *StopControl) OnBlockExecuted(h *flow.Header)
  • func (s *StopControl) SetStopParameters(stop StopParameters) error
  • func (s *StopControl) ShouldExecuteBlock(blockID flow.Identifier, height uint64) bool
• type StopControlHeaders
• type StopParameters
  • func (p StopParameters) Set() bool

Constants

const (
	// TODO: figure out an appropriate graceful stop time (is 10 min. enough?)
	DefaultMaxGracefulStopDuration = 10 * time.Minute
)

Variables

var ErrCannotChangeStop = errors.New("cannot change stop control stopping parameters")

var NoStopHeight = uint64(math.MaxUint64)

Types

type StopControl

type StopControl struct {

	// Stop control needs to consume BlockFinalized events.
	// adding psEvents.Noop makes it a protocol.Consumer
	psEvents.Noop
	sync.RWMutex
	component.Component
	// contains filtered or unexported fields
}

StopControl is a specialized component used by ingestion.Engine to encapsulate control of stopping blocks execution. It is intended to work tightly with the Engine, not as a general mechanism or interface.

StopControl can stop execution or crash the node at a specific block height. The stop height can be set manually or by the version beacon service event. This leads to some edge cases that are handled by the StopControl:

1. stop is already set manually and is set again manually. This is considered as an attempt to move the stop height. The resulting stop height is the new one. Note, the new height can be either lower or higher than previous value.
2. stop is already set manually and is set by the version beacon. The resulting stop height is the lower one.
3. stop is already set by the version beacon and is set manually. The resulting stop height is the lower one.
4. stop is already set by the version beacon and is set by the version beacon. This means version boundaries were edited. The resulting stop height is the new one.

func NewStopControl

func NewStopControl(
	unit *engine.Unit,
	maxGracefulStopDuration time.Duration,
	log zerolog.Logger,
	exeState state.ReadOnlyExecutionState,
	headers StopControlHeaders,
	versionBeacons storage.VersionBeacons,
	nodeVersion *semver.Version,
	latestFinalizedBlock *flow.Header,
	withStoppedExecution bool,
	crashOnVersionBoundaryReached bool,
) *StopControl

NewStopControl creates new StopControl.

We currently have no strong guarantee that the node version is a valid semver. See build.SemverV2 for more details. That is why nil is a valid input for node version without a node version, the stop control can still be used for manual stopping.

func (*StopControl) BlockFinalized

func (s *StopControl) BlockFinalized(h *flow.Header)

BlockFinalized is called when a block is finalized.

This is a protocol event consumer. See protocol.Consumer.

func (*StopControl) BlockFinalizedForTesting

func (s *StopControl) BlockFinalizedForTesting(h *flow.Header)

BlockFinalizedForTesting is used for testing only.

func (*StopControl) GetStopParameters

func (s *StopControl) GetStopParameters() StopParameters

GetStopParameters returns the upcoming stop parameters or nil if no stop is set.

func (*StopControl) IsExecutionStopped

func (s *StopControl) IsExecutionStopped() bool

IsExecutionStopped returns true is block execution has been stopped

func (*StopControl) OnBlockExecuted

func (s *StopControl) OnBlockExecuted(h *flow.Header)

OnBlockExecuted should be called after a block has finished execution

func (*StopControl) SetStopParameters

func (s *StopControl) SetStopParameters(
	stop StopParameters,
) error

SetStopParameters sets new stop parameters manually.

Expected error returns during normal operations:

• ErrCannotChangeStop: this indicates that new stop parameters cannot be set. See stop.validateStopChange.

func (*StopControl) ShouldExecuteBlock

func (s *StopControl) ShouldExecuteBlock(blockID flow.Identifier, height uint64) bool

ShouldExecuteBlock should be called when new block can be executed. The block should not be executed if its height is above or equal to s.stopBoundary.StopBeforeHeight.

It returns a boolean indicating if the block should be executed.

type StopControlHeaders

type StopControlHeaders interface {
	BlockIDByHeight(height uint64) (flow.Identifier, error)
}

StopControlHeaders is an interface for fetching headers Its jut a small subset of storage.Headers for comments see storage.Headers

type StopParameters

type StopParameters struct {
	// desired StopBeforeHeight, the first value new version should be used,
	// so this height WON'T be executed
	StopBeforeHeight uint64

	// if the node should crash or just pause after reaching StopBeforeHeight
	ShouldCrash bool
}

func (StopParameters) Set

func (p StopParameters) Set() bool