vm

Documentation

Overview

Package vm provides a compiler and virtual machine environment for executing mtail programs.

Index

• Constants
• Variables
• func Check(node astNode) error
• func CodeGen(name string, ast astNode) (*object, error)
• func Equals(t1, t2 Type) bool
• func MergePosition(a, b *position) *position
• func Parse(name string, input io.Reader) (astNode, error)
• func Walk(v Visitor, node astNode)
• type ErrorList
  • func (p *ErrorList) Add(pos *position, msg string)
  • func (p ErrorList) Error() string
• type Loader
  • func NewLoader(o LoaderOptions) (*Loader, error)
  • func (l *Loader) CompileAndRun(name string, input io.Reader) error
  • func (l *Loader) LoadProg(programPath string) error
  • func (l *Loader) LoadProgs(programPath string) error
  • func (l *Loader) UnloadProgram(pathname string)
• type LoaderOptions
• type Options
• type Scope
  • func NewScope(parent *Scope) *Scope
  • func (s *Scope) Insert(sym *Symbol) (alt *Symbol)
  • func (s *Scope) Lookup(name string) *Symbol
  • func (s *Scope) String() string
• type Sexp
  • func (s *Sexp) Dump(n astNode) string
  • func (s *Sexp) VisitAfter(node astNode)
  • func (s *Sexp) VisitBefore(n astNode) Visitor
• type Symbol
  • func NewSymbol(name string, kind SymbolKind, pos *position) (sym *Symbol)
• type SymbolKind
• type Type
  • func NewTypeVariable() Type
  • func Unify(a, b Type) Type
• type TypeOperator
  • func (t *TypeOperator) Root() Type
  • func (t *TypeOperator) String() string
• type TypeVariable
  • func (t *TypeVariable) Root() Type
  • func (t *TypeVariable) String() string
• type Unparser
  • func (u *Unparser) Unparse(n astNode) string
  • func (u *Unparser) VisitAfter(n astNode)
  • func (u *Unparser) VisitBefore(n astNode) Visitor
• type VM
  • func Compile(name string, input io.Reader, o *Options) (*VM, error)
  • func New(name string, obj *object, syslogUseCurrentYear bool) *VM
  • func (v *VM) DumpByteCode(name string) string
  • func (v *VM) Run(_ uint32, lines <-chan string, shutdown chan<- struct{})
• type Visitor

Constants

const EOF = 0

Variables

var (
	// ProgLoads counts the number of program load events.
	ProgLoads = expvar.NewMap("prog_loads_total")
	// ProgLoadErrors counts the number of program load errors.
	ProgLoadErrors = expvar.NewMap("prog_load_errors")
)

var (
	Undef  = &TypeOperator{"Undef"}
	None   = &TypeOperator{"None"}
	Int    = &TypeOperator{"Int"}
	Float  = &TypeOperator{"Float"}
	String = &TypeOperator{"String"}
)

Builtin types

var (
	// LineCount counts the number of lines read by the virtual machine engine from the input channel.
	LineCount = expvar.NewInt("line_count")
)

Functions

func Check

func Check(node astNode) error

Check performs a semantic check of the ast node, and returns a list of errors found, or nil if the program is semantically valid. At the completion of Check, the symbol table and type annotation is also complete.

func CodeGen

func CodeGen(name string, ast astNode) (*object, error)

CodeGen is the function that compiles the program to bytecode and data.

func Equals

func Equals(t1, t2 Type) bool

func MergePosition

func MergePosition(a, b *position) *position

func Parse

func Parse(name string, input io.Reader) (astNode, error)

func Walk

func Walk(v Visitor, node astNode)

Types

type ErrorList

type ErrorList []*compileError

ErrorList contains a list of compile errors.

func (*ErrorList) Add

func (p *ErrorList) Add(pos *position, msg string)

Add appends an error at a position to the list of errors.

func (ErrorList) Error

func (p ErrorList) Error() string

ErrorList implements the error interface.

type Loader

type Loader struct {
	VMsDone chan struct{} // Notify mtail when all running VMs are shutdown.
	// contains filtered or unexported fields
}

Loader handles the lifecycle of programs and virtual machines, by watching the configured program source directory, compiling changes to programs, and managing the running virtual machines that receive input from the lines channel.

func NewLoader

func NewLoader(o LoaderOptions) (*Loader, error)

NewLoader creates a new program loader. It takes a filesystem watcher and a filesystem interface as arguments. If fs is nil, it will use the default filesystem interface.

func (*Loader) CompileAndRun

func (l *Loader) CompileAndRun(name string, input io.Reader) error

CompileAndRun compiles a program read from the input, starting execution if it succeeds. If an existing virtual machine of the same name already exists, the previous virtual machine is terminated and the new loaded over it. If the new program fails to compile, any existing virtual machine with the same name remains running.

func (*Loader) LoadProg

func (l *Loader) LoadProg(programPath string) error

LoadProg loads or reloads a program from the path specified. The name of the program is the basename of the file.

func (*Loader) LoadProgs

func (l *Loader) LoadProgs(programPath string) error

LoadProgs loads all programs in a directory and starts watching the directory for filesystem changes. The total number of program errors is returned.

func (*Loader) UnloadProgram

func (l *Loader) UnloadProgram(pathname string)

UnloadProgram removes the named program from the watcher to prevent future updates, and terminates any currently running VM goroutine.

type LoaderOptions

type LoaderOptions struct {
	Store *metrics.Store
	Lines <-chan string
	W     watcher.Watcher // Not required, will use watcher.LogWatcher if zero.
	FS    afero.Fs        // Not required, will use afero.OsFs if zero.

	CompileOnly          bool
	DumpAst              bool // print the AST after type check
	DumpAstTypes         bool // Instructs the loader to dump to stdout the compiled program after compilation.
	DumpBytecode         bool
	SyslogUseCurrentYear bool
}

LoaderOptions contains the required and optional parameters for creating a new Loader.

type Options

type Options struct {
	CompileOnly          bool // Do not start the program after compilation.
	SyslogUseCurrentYear bool // Use the current year if no year is present in the log file timestamp.
	EmitAst              bool // Print the AST after parse
	EmitAstTypes         bool // Print the AST with types after typechecking
}

Options contains all the parameters that affect the behaviour of the compiler.

type Scope

type Scope struct {
	Parent  *Scope
	Symbols map[string]*Symbol
}

Scope maintains a record of the identifiers declared in the current program scope, and a link to the parent scope.

func NewScope

func NewScope(parent *Scope) *Scope

NewScope creates a new scope within the parent scope

func (*Scope) Insert

func (s *Scope) Insert(sym *Symbol) (alt *Symbol)

Insert attempts to insert a symbol into the scope. If the scope already contains an object alt with the same name, the scope is unchanged and the function returns alt. Otherwise the symbol is inserted, and returns nil.

func (*Scope) Lookup

func (s *Scope) Lookup(name string) *Symbol

lookup returns the symbol with the given name if it is found in this or any parent scope, otherwise nil.

func (*Scope) String

func (s *Scope) String() string

String prints the current scope and all parents to a string, recursing up to the root scope. This method is only used for debugging.

type Sexp

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

Sexp is for converting program syntax trees into typed s-expression for printing

func (*Sexp) Dump

func (s *Sexp) Dump(n astNode) string

Dump begins the dumping of the syntax tree, returning the s-expression as a single string

func (*Sexp) VisitAfter

func (s *Sexp) VisitAfter(node astNode)

func (*Sexp) VisitBefore

func (s *Sexp) VisitBefore(n astNode) Visitor

type Symbol

type Symbol struct {
	Name    string      // identifier name
	Kind    SymbolKind  // kind of program object
	Type    Type        // object's type
	Pos     *position   // Source file position of definition
	Binding interface{} // binding to storage allocated in runtime
	Addr    int         // Address offset in another structure, object specific
}

Symbol describes a named program object.

func NewSymbol

func NewSymbol(name string, kind SymbolKind, pos *position) (sym *Symbol)

NewSymbol creates a record of a given symbol kind, named name, found at loc

type SymbolKind

type SymbolKind int

const (
	VarSymbol    SymbolKind = iota // Variables
	CaprefSymbol                   // Capture group references
	DecoSymbol                     // Decorators

)

SymbolKind enumerates the kinds of symbols found in the program text.

type Type

type Type interface {
	Root() Type
	String() string
}

func NewTypeVariable

func NewTypeVariable() Type

func Unify

func Unify(a, b Type) Type

Unify performs type unification of both parameter Types. It returns the least upper bound of both types, the smallest type that is capable of representing both parameters. If either type is a type variable, then that variable is unified with the LUB.

type TypeOperator

type TypeOperator struct {
	Name string
}

func (*TypeOperator) Root

func (t *TypeOperator) Root() Type

func (*TypeOperator) String

func (t *TypeOperator) String() string

type TypeVariable

type TypeVariable struct {
	Id       int
	Instance *Type
}

func (*TypeVariable) Root

func (t *TypeVariable) Root() Type

func (*TypeVariable) String

func (t *TypeVariable) String() string

type Unparser

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

Unparser is for converting program syntax trees back to program text.

func (*Unparser) Unparse

func (u *Unparser) Unparse(n astNode) string

Unparse begins the unparsing of the syntax tree, returning the program text as a single string.

func (*Unparser) VisitAfter

func (u *Unparser) VisitAfter(n astNode)

func (*Unparser) VisitBefore

func (u *Unparser) VisitBefore(n astNode) Visitor

type VM

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

VM describes the virtual machine for each program. It contains virtual segments of the executable bytecode, constant data (string and regular expressions), mutable state (metrics), and a stack for the current thread of execution.

func Compile

func Compile(name string, input io.Reader, o *Options) (*VM, error)

Compile compiles a program from the input into a virtual machine or a list of compile errors. It takes the program's name and the metric store as additional arguments to build the virtual machine.

func New

func New(name string, obj *object, syslogUseCurrentYear bool) *VM

New creates a new virtual machine with the given name, and compiler artifacts for executable and data segments.

func (*VM) DumpByteCode

func (v *VM) DumpByteCode(name string) string

DumpByteCode emits the program disassembly and program objects to string.

func (*VM) Run

func (v *VM) Run(_ uint32, lines <-chan string, shutdown chan<- struct{})

Run executes the virtual machine on each line of input received. When the input closes, it signals to the loader that it has terminated by closing the shutdown channel.

type Visitor

type Visitor interface {
	VisitBefore(n astNode) (v Visitor)
	VisitAfter(n astNode)
}

a Visitor's VisitBefore method is invoked for each node encountered by Walk. If the result Visitor v is not nil, Walk visits each of the children of that node with v. VisitAfter is called on n at the end.