interp

Documentation

Overview

Package interp defines an interpreter for the SSA representation of Go programs.

This interpreter is provided as an adjunct for testing the SSA construction algorithm. Its purpose is to provide a minimal metacircular implementation of the dynamic semantics of each SSA instruction. It is not, and will never be, a production-quality Go interpreter.

The following is a partial list of Go features that are currently unsupported or incomplete in the interpreter.

* Unsafe operations, including all uses of unsafe.Pointer, are impossible to support given the "boxed" Ivalue representation we have chosen.

* The reflect package is only partially implemented.

* "sync/atomic" operations are not currently atomic due to the "boxed" Ivalue representation: it is not possible to read, modify and write an interface Ivalue atomically. As a consequence, Mutexes are currently broken. TODO(adonovan): provide a metacircular implementation of Mutex avoiding the broken atomic primitives.

* recover is only partially implemented. Also, the interpreter makes no attempt to distinguish target panics from interpreter crashes.

* map iteration is asymptotically inefficient.

* the sizes of the int, uint and uintptr types in the target program are assumed to be the same as those of the interpreter itself.

* all Ivalues occupy space, even those of types defined by the spec to have zero size, e.g. struct{}. This can cause asymptotic performance degradation.

* os.Exit is implemented using panic, causing deferred functions to run.

Index

• func IvalIface(iv Ivalue) interface{}
• func IvalIfaceSlice(ivs []Ivalue) []interface{}
• func IvalueToBytes(v Ivalue) []byte
• type Context
  • func Interpret(mainpkg *ssa.Package, mode Mode, sizes types.Sizes, filename string, ...) (context *Context, exitCode int)
  • func (cont *Context) Call(name string, args []Ivalue) Ivalue
• type Externals
  • func NewExternals() *Externals
  • func (ext *Externals) AddExtFunc(name string, fn func([]Ivalue) Ivalue)
• type Ivalue
• type Mode

Functions

func IvalIface

func IvalIface(iv Ivalue) interface{}

IvalIface converts an Ivalue into an interface{}.

func IvalIfaceSlice

func IvalIfaceSlice(ivs []Ivalue) []interface{}

IvalIfaceSlice converts a slice of Ivalues into a slice of empty interfaces.

func IvalueToBytes

func IvalueToBytes(v Ivalue) []byte

IvalueToBytes converts an Ivalue containing the interpreter internal representation of "[]byte" into a []byte.

Types

type Context

type Context struct {
	Interp *interpreter
}

Context provides the execution context for subsequent calls

func Interpret

func Interpret(mainpkg *ssa.Package, mode Mode, sizes types.Sizes, filename string, args []string, ext *Externals, output io.Writer) (context *Context, exitCode int)

Interpret interprets the Go program whose main package is mainpkg. mode specifies various interpreter options. filename and args are the initial Ivalues of os.Args for the target program. sizes is the effective type-sizing function for this program.

Interpret returns the exit code of the program: 2 for panic (like gc does), or the argument to os.Exit for normal termination.

The SSA program must include the "runtime" package.

func (*Context) Call

func (cont *Context) Call(name string, args []Ivalue) Ivalue

Call a function in the interpreter's execution context

type Externals

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

Externals describes usable objects external to the interpreter.

func NewExternals

func NewExternals() *Externals

NewExternals makes an Externals type.

func (*Externals) AddExtFunc

func (ext *Externals) AddExtFunc(name string, fn func([]Ivalue) Ivalue)

AddExtFunc adds an external function to the known map.

type Ivalue

type Ivalue interface{}

Ivalue is an interpreter internal value.

All interpreter Ivalues are "boxed" in the empty interface, Ivalue. The range of possible dynamic types within Ivalue are:

• bool
• numbers (all built-in int/float/complex types are distinguished)
• string
• map[Ivalue]Ivalue --- maps for which usesBuiltinMap(keyType) *hashmap --- maps for which !usesBuiltinMap(keyType)
• chan Ivalue
• []Ivalue --- slices
• iface --- interfaces.
• structure --- structs. Fields are ordered and accessed by numeric indices.
• array --- arrays.
• *Ivalue --- pointers. Careful: *Ivalue is a distinct type from *array etc.
• *ssa.Function \ *ssa.Builtin } --- functions. A nil 'func' is always of type *ssa.Function. *closure /
• tuple --- as returned by Return, Next, "Ivalue,ok" modes, etc.
• iter --- iterators from 'range' over map or string.
• bad --- a poison pill for locals that have gone out of scope.
• rtype -- the interpreter's concrete implementation of reflect.Type

Note that nil is not on this list.

Pay close attention to whether or not the dynamic type is a pointer. The compiler cannot help you since Ivalue is an empty interface.

type Mode

type Mode uint

Mode is a bitmask of options affecting the interpreter.

const (
	DisableRecover Mode = 1 << iota // Disable recover() in target programs; show interpreter crash instead.
	EnableTracing                   // Print a trace of all instructions as they are interpreted.
)