engine

Documentation

Overview

Package engine orchestrates client input with vm execution.

Index

• Variables
• func Loop(ctx context.Context, en Engine, reader io.Reader, writer io.Writer, ...) error
• type Config
  • func (c Config) String() string
• type Debug
  • func NewSimpleDebug(w io.Writer) Debug
• type DefaultEngine
  • func NewEngine(cfg Config, rs resource.Resource) *DefaultEngine
  • func (en *DefaultEngine) AddValidInput(re string) error
  • func (en *DefaultEngine) Exec(ctx context.Context, input []byte) (bool, error)
  • func (en *DefaultEngine) Finish() error
  • func (en *DefaultEngine) Flush(ctx context.Context, w io.Writer) (int, error)
  • func (en *DefaultEngine) WithDebug(dbg Debug) *DefaultEngine
  • func (en *DefaultEngine) WithFirst(fn resource.EntryFunc) *DefaultEngine
  • func (en *DefaultEngine) WithMemory(ca cache.Memory) *DefaultEngine
  • func (en *DefaultEngine) WithPersister(pe *persist.Persister) *DefaultEngine
  • func (en *DefaultEngine) WithState(st *state.State) *DefaultEngine
• type Engine
• type SimpleDebug
  • func (dbg *SimpleDebug) Break(st *state.State, ca cache.Memory)

Variables

var (
	ErrFlushNoExec = errors.New("Attempted flush on unexecuted engine")
)

Functions

func Loop

func Loop(ctx context.Context, en Engine, reader io.Reader, writer io.Writer, initial []byte) error

Loop starts an engine execution loop with the given symbol as the starting node.

The root reads inputs from the provided reader, one line at a time.

It will execute until running out of bytecode in the buffer.

Any error not handled by the engine will terminate the oop and return an error.

Rendered output is written to the provided writer.

If initial is set, the value will be used for the first (initializing) execution If nil, an empty byte value will be used.

Types

type Config

type Config struct {
	// OutputSize sets the maximum size of output from a single rendered page. If set to 0, no size limit is imposed.
	OutputSize uint32
	// SessionId is used to segment the context of state and application data retrieval and storage.
	SessionId string
	// Root is the node name of the bytecode entry point.
	Root string
	// FlagCount is used to set the number of user-defined signal flags used in the execution state.
	FlagCount uint32
	// CacheSize determines the total allowed cumulative cache size for a single SessionId storage segment. If set to 0, no size limit is imposed.
	CacheSize uint32
	// Language determines the ISO-639-3 code of the default translation language. If not set, no language translations will be looked up.
	Language string
	// StateDebug activates string translations of flags in output logs if set
	StateDebug bool
	// EngineDebug activates the engine debug output
	EngineDebug bool
}

Config globally defines behavior of all components driven by the engine.

func (Config) String

func (c Config) String() string

String implements the string interface.

type Debug

type Debug interface {
	// Break receives the state and cache in order to generate its output.
	Break(*state.State, cache.Memory)
}

Debug implementations output details about the execution state on each execution halt.

func NewSimpleDebug

func NewSimpleDebug(w io.Writer) Debug

NewSimpleDebug instantiates a new SimpleDebug object.

type DefaultEngine

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

func NewEngine

func NewEngine(cfg Config, rs resource.Resource) *DefaultEngine

NewEngine instantiates the default Engine implementation.

func (*DefaultEngine) AddValidInput

func (en *DefaultEngine) AddValidInput(re string) error

AddValidInput defines a regular expressing string to match input against.

The added regular expression will be evaluated after the builtin match (see vm/input.go for the actual string details).

The function may be called more than once. Input will be validated against each in the sequence they were added.

When a match is found, remaining regular expressions will be skipped.

func (*DefaultEngine) Exec

func (en *DefaultEngine) Exec(ctx context.Context, input []byte) (bool, error)

Exec implements the Engine interface.

It processes user input against the current state of the virtual machine environment.

If successfully executed, output of the last execution is available using the Flush call.

A bool return valus of false indicates that execution should be terminated. Calling Exec again has undefined effects.

Fails if:

• input is formally invalid (too long etc)
• no current bytecode is available
• input processing against bytcode failed

func (*DefaultEngine) Finish

func (en *DefaultEngine) Finish() error

Finish implements the Engine interface.

If persister is set, this call will save the state and memory.

An error will be logged and returned if:

• persistence was attempted and failed (takes precedence)
• resource backend did not close cleanly.

func (*DefaultEngine) Flush

func (en *DefaultEngine) Flush(ctx context.Context, w io.Writer) (int, error)

Flush implements the Engine interface.

The method writes the output of the last vm execution to the given writer.

Fails if

• required data inputs to the template are not available.
• the template for the given node point is note available for retrieval using the resource.Resource implementer.
• the supplied writer fails to process the writes.

func (*DefaultEngine) WithDebug

func (en *DefaultEngine) WithDebug(dbg Debug) *DefaultEngine

WithDebug is a chainable method that sets the debugger to use for the engine.

If the argument is nil, the default debugger will be used.

func (*DefaultEngine) WithFirst

func (en *DefaultEngine) WithFirst(fn resource.EntryFunc) *DefaultEngine

WithFirst is a chainable method that defines the function that will be run before control is handed over to the VM bytecode from the current state.

If this function returns an error, execution will be aborted in engine.Init.

func (*DefaultEngine) WithMemory

func (en *DefaultEngine) WithMemory(ca cache.Memory) *DefaultEngine

WithMemory is a chainable method that explicitly sets the memory object to use for the engine.

If not set, the cache.Memory object provided by the persist.Persister will be used. If that is not available, a new instance will be created according to engine.Config.

Note that engine.Init will fail if memory is set both explicitly and in a provided persist.Persister.

func (*DefaultEngine) WithPersister

func (en *DefaultEngine) WithPersister(pe *persist.Persister) *DefaultEngine

WithPersister is a chainable method that sets the persister to use with the engine.

If the persister is missing state, memory or both, it will inherit them from the engine.

func (*DefaultEngine) WithState

func (en *DefaultEngine) WithState(st *state.State) *DefaultEngine

WithState is a chainable method that explicitly sets the state object to use for the engine.

If not set, the state.State object provided by the persist.Persister will be used. If that is not available, a new instance will be created according to engine.Config.

Note that engine.Init will fail if state is set both explicitly and in a provided persist.Persister.

type Engine

type Engine interface {
	// Init sets the engine up for vm execution. It must be called before Exec.
	//Init(ctx context.Context) (bool, error)
	// Exec executes the pending bytecode.
	Exec(ctx context.Context, input []byte) (bool, error)
	// Flush renders output according to the state of VM execution
	// to the given io.Writer, and prepares the engine for another
	// VM execution.
	Flush(ctx context.Context, w io.Writer) (int, error)
	// Finish must be called after the last call to Exec.
	Finish() error
}

EngineIsh defines the interface for execution engines that handle vm initialization and execution, and rendering outputs.

type SimpleDebug

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

SimpleDebug is a vanilla implementation of the Debug interface.

func (*SimpleDebug) Break

func (dbg *SimpleDebug) Break(st *state.State, ca cache.Memory)

Break implements the Debug interface.