kamikazechaser/vise
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Add documentation

Browse Source
This commit is contained in:
lash 2023-04-01 15:04:38 +01:00
parent 4f473c12f0
commit 172edf05d1
Signed by untrusted user who does not match committer: lash
GPG Key ID: 21D2E7BB88C2A746
2 changed files with 25 additions and 8 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

25
go/engine/engine.go
View File

@ -16,16 +16,21 @@ import (
// CacheSize uint32 // CacheSize uint32
//} //}
// Engine is an execution engine that handles top-level errors when running user inputs against currently exposed bytecode.
type Engine struct { type Engine struct {
st *state.State st *state.State
rs resource.Resource rs resource.Resource
} }
// NewEngine creates a new Engine
func NewEngine(st *state.State, rs resource.Resource) Engine { func NewEngine(st *state.State, rs resource.Resource) Engine {
engine := Engine{st, rs} engine := Engine{st, rs}
return engine return engine
} }
// Init must be explicitly called before using the Engine instance.
//
// It makes sure bootstrapping code has been executed, and that the exposed bytecode is ready for user input.
func(en *Engine) Init(ctx context.Context) error { func(en *Engine) Init(ctx context.Context) error {
b := vm.NewLine([]byte{}, vm.MOVE, []string{"root"}, nil, nil) b := vm.NewLine([]byte{}, vm.MOVE, []string{"root"}, nil, nil)
var err error var err error
@ -41,6 +46,20 @@ func(en *Engine) Init(ctx context.Context) error {
return en.st.AppendCode(code) return en.st.AppendCode(code)
} }
// Exec processes user input against the current state of the virtual machine environment.
//
// If successfully executed:
// - output of the last execution is available using the WriteResult(...) call
// - Exec(...) may be called again with new input
//
// This implementation is in alpha state. That means that any error emitted may have left the system in an undefined state.
//
// TODO: Disambiguate errors as critical and resumable errors.
//
// Fails if:
// - input is objectively invalid (too long etc)
// - no current bytecode is available
// - input processing against bytcode failed
func (en *Engine) Exec(input []byte, ctx context.Context) error { func (en *Engine) Exec(input []byte, ctx context.Context) error {
l := uint8(len(input)) l := uint8(len(input))
if l > 255 { if l > 255 {
@ -59,6 +78,12 @@ func (en *Engine) Exec(input []byte, ctx context.Context) error {
return err return err
} }
// WriteResult 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(en *Engine) WriteResult(w io.Writer) error { func(en *Engine) WriteResult(w io.Writer) error {
location := en.st.Where() location := en.st.Where()
v, err := en.st.Get() v, err := en.st.Get()

8
go/engine/engine_test.go
View File

@ -68,15 +68,7 @@ func(fs FsWrapper) GetCode(sym string) ([]byte, error) {
} }
func TestEngineInit(t *testing.T) { func TestEngineInit(t *testing.T) {
// cfg := Config{
// FlagCount: 12,
// CacheSize: 1024,
// }
st := state.NewState(17).WithCacheSize(1024) st := state.NewState(17).WithCacheSize(1024)
// dir, err := ioutil.TempDir("", "festive_test_")
// if err != nil {
// t.Fatal(err)
// }
dir := path.Join(testdataloader.GetBasePath(), "testdata") dir := path.Join(testdataloader.GetBasePath(), "testdata")
ctx := context.TODO() ctx := context.TODO()
rs := NewFsWrapper(dir, &st, ctx) rs := NewFsWrapper(dir, &st, ctx)