vm

Documentation

Overview

Package vm provides a VirtualMachine that executes compiled Risor code.

Index

• Constants
• func Run(ctx context.Context, main *compiler.Code, options ...Option) (object.Object, error)
• type Option
  • func WithConcurrency() Option
  • func WithGlobals(globals map[string]any) Option
  • func WithImporter(importer importer.Importer) Option
  • func WithInstructionOffset(offset int) Option
• type VirtualMachine
  • func New(main *compiler.Code, options ...Option) *VirtualMachine
  • func (vm *VirtualMachine) Call(ctx context.Context, fn *object.Function, args []object.Object) (result object.Object, err error)
  • func (vm *VirtualMachine) Clone() (*VirtualMachine, error)
  • func (vm *VirtualMachine) Get(name string) (object.Object, error)
  • func (vm *VirtualMachine) GetIP() int
  • func (vm *VirtualMachine) GlobalNames() []string
  • func (vm *VirtualMachine) Run(ctx context.Context) (err error)
  • func (vm *VirtualMachine) SetIP(value int) error
  • func (vm *VirtualMachine) TOS() (object.Object, bool)

Constants

const (
	MaxArgs       = 256
	MaxFrameDepth = 1024
	MaxStackDepth = 1024
	StopSignal    = -1
	MB            = 1024 * 1024
)

const DefaultFrameLocals = 8

Functions

func Run

func Run(ctx context.Context, main *compiler.Code, options ...Option) (object.Object, error)

Run the given code in a new Virtual Machine and return the result.

Types

type Option

type Option func(*VirtualMachine)

Option is a configuration function for a Virtual Machine.

func WithConcurrency

func WithConcurrency() Option

WithConcurrency opts into allowing the spawning of goroutines.

func WithGlobals

func WithGlobals(globals map[string]any) Option

WithGlobals provides global variables with the given names.

func WithImporter

func WithImporter(importer importer.Importer) Option

WithImporter is used to supply an Importer to the Virtual Machine.

func WithInstructionOffset

func WithInstructionOffset(offset int) Option

WithInstructionOffset sets the initial instruction offset.

type VirtualMachine

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

func New

func New(main *compiler.Code, options ...Option) *VirtualMachine

New creates a new Virtual Machine.

func (*VirtualMachine) Call

func (vm *VirtualMachine) Call(
	ctx context.Context,
	fn *object.Function,
	args []object.Object,
) (result object.Object, err error)

Call a function with the given arguments. If isolation between VMs is important to you, do not provide a function that obtained from another VM, since it could be a closure over variables there. If this VM is already running, an error is returned.

func (*VirtualMachine) Clone

func (vm *VirtualMachine) Clone() (*VirtualMachine, error)

Clone the Virtual Machine. The returned clone has its own independent frame stack and data stack, but shares the loaded modules and global variables with the original VM.

Clone is designed to be safe to call from any goroutine.

The caller and the user code that runs are responsible for thread safety when using modules and global variables, since concurrently executing cloned VMs can modify the same objects.

The returned clone has an empty frame stack and data stack, which makes this most useful for cloning a VM then using vm.Call() to call a function, rather than calling vm.Run() on the clone, which would start execution at the beginning of the main entrypoint.

Do not use Clone if you want a strict guarantee of isolation between VMs.

func (*VirtualMachine) Get

func (vm *VirtualMachine) Get(name string) (object.Object, error)

Get a global variable by name as a Risor Object.

func (*VirtualMachine) GetIP

func (vm *VirtualMachine) GetIP() int

GetIP returns the current instruction pointer.

func (*VirtualMachine) GlobalNames

func (vm *VirtualMachine) GlobalNames() []string

GlobalNames returns the names of all global variables in the active code.

func (*VirtualMachine) Run

func (vm *VirtualMachine) Run(ctx context.Context) (err error)

func (*VirtualMachine) SetIP

func (vm *VirtualMachine) SetIP(value int) error

SetIP sets the instruction pointer on a stopped VM. If the VM is running, an error is returned.

func (*VirtualMachine) TOS

func (vm *VirtualMachine) TOS() (object.Object, bool)

TOS returns the top-of-stack object if there is one, without modifying the stack. The returned bool value indicates whether there was a valid TOS. This only works on a stopped VM. If the VM is running, (nil, false) is returned.