vm

Documentation

Overview

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

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 CompileOnly(l *MasterControl) error
• func DumpAst(l *MasterControl) error
• func DumpAstTypes(l *MasterControl) error
• func DumpBytecode(l *MasterControl) error
• func Equals(t1, t2 Type) bool
• func ErrorsAbort(l *MasterControl) error
• func IsComplete(t Type) bool
• func IsDimension(t Type) bool
• func IsFunction(t Type) bool
• func MergePosition(a, b *position) *position
• func OmitMetricSource(l *MasterControl) error
• func OverrideLocation(loc *time.Location) func(*MasterControl) error
• func Parse(name string, input io.Reader) (astNode, error)
• func SyslogUseCurrentYear(l *MasterControl) error
• func Unify(a, b Type) error
• func Walk(v Visitor, node astNode)
• type ErrorList
  • func (p *ErrorList) Add(pos *position, msg string)
  • func (p *ErrorList) Append(l ErrorList)
  • func (p ErrorList) Error() string
• type MasterControl
  • func NewLoader(programPath string, store *metrics.Store, lines <-chan *logline.LogLine, ...) (*MasterControl, error)
  • func (l *MasterControl) CompileAndRun(name string, input io.Reader) error
  • func (l *MasterControl) LoadAllPrograms() error
  • func (l *MasterControl) LoadProgram(programPath string) error
  • func (l *MasterControl) SetOption(options ...func(*MasterControl) error) error
  • func (l *MasterControl) UnloadProgram(pathname string)
  • func (l *MasterControl) WriteStatusHTML(w io.Writer) error
• type Scope
  • func NewScope(parent *Scope) *Scope
  • func (s *Scope) CopyFrom(o *Scope)
  • func (s *Scope) Insert(sym *Symbol) (alt *Symbol)
  • func (s *Scope) InsertAlias(sym *Symbol, alias string) (alt *Symbol)
  • func (s *Scope) Lookup(name string, kind SymbolKind) *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
  • func (k SymbolKind) String() string
• type Type
  • func FreshType(t Type) Type
  • func LeastUpperBound(a, b Type) Type
• type TypeError
  • func (e *TypeError) Error() string
• type TypeOperator
  • func Dimension(args ...Type) *TypeOperator
  • func Function(args ...Type) *TypeOperator
  • func (t *TypeOperator) Root() Type
  • func (t *TypeOperator) String() (s string)
• type TypeVariable
  • func NewTypeVariable() *TypeVariable
  • func (t *TypeVariable) Root() Type
  • func (t *TypeVariable) SetInstance(t1 *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, emitAst bool, emitAstTypes bool, ...) (*VM, error)
  • func New(name string, obj *object, syslogUseCurrentYear bool, loc *time.Location) *VM
  • func (v *VM) DumpByteCode(name string) string
  • func (v *VM) ParseTime(layout, value string) (tm time.Time)
  • func (v *VM) Run(_ uint32, lines <-chan *logline.LogLine, shutdown chan<- struct{}, ...)
• type Visitor

Constants

const ADD_ASSIGN = 57390

const AND = 57388

const AS = 57351

const ASSIGN = 57391

const BITAND = 57384

const BITOR = 57386

const BUILTIN = 57360

const BY = 57352

const CAPREF = 57363

const CAPREF_NAMED = 57364

const COMMA = 57401

const CONCAT = 57392

const CONST = 57353

const COUNTER = 57347

const DECO = 57366

const DEF = 57355

const DEL = 57356

const DIV = 57370

const ELSE = 57359

const EOF = 0

EOF is a marker for end of file.

const EQ = 57382

const FLOATLITERAL = 57368

const GAUGE = 57348

const GE = 57381

const GT = 57379

const HIDDEN = 57354

const ID = 57365

const INC = 57369

const INTLITERAL = 57367

const INVALID = 57346

const LCURLY = 57395

const LE = 57380

const LPAREN = 57397

const LSQUARE = 57399

const LT = 57378

const MATCH = 57393

const MINUS = 57373

const MOD = 57371

const MUL = 57372

const NE = 57383

const NEXT = 57357

const NL = 57402

const NOT = 57387

const NOT_MATCH = 57394

const OR = 57389

const OTHERWISE = 57358

const PLUS = 57374

const POW = 57375

const RCURLY = 57396

const REGEX = 57361

const RPAREN = 57398

const RSQUARE = 57400

const SHL = 57376

const SHR = 57377

const STRING = 57362

const TEXT = 57350

const TIMER = 57349

const XOR = 57385

Variables

var (
	// LineCount counts the number of lines read by the program loader from the input channel.
	LineCount = expvar.NewInt("line_count")
	// 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", []Type{}}
	Error   = &TypeOperator{"Error", []Type{}}
	None    = &TypeOperator{"None", []Type{}}
	Bool    = &TypeOperator{"Bool", []Type{}}
	Int     = &TypeOperator{"Int", []Type{}}
	Float   = &TypeOperator{"Float", []Type{}}
	String  = &TypeOperator{"String", []Type{}}
	Pattern = &TypeOperator{"Pattern", []Type{}}
)

Builtin types

var Builtins = map[string]Type{
	"int":         Function(NewTypeVariable(), Int),
	"bool":        Function(NewTypeVariable(), Bool),
	"float":       Function(NewTypeVariable(), Float),
	"string":      Function(NewTypeVariable(), String),
	"timestamp":   Function(Int),
	"len":         Function(String, Int),
	"settime":     Function(Int, None),
	"strptime":    Function(String, String, None),
	"strtol":      Function(String, Int, Int),
	"tolower":     Function(String, String),
	"getfilename": Function(String),
}

Builtins is a mapping of the builtin language functions to their type definitions.

Functions

func Check

func Check(node astNode) error

Check performs a semantic check of the astNode, 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 are 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 CompileOnly

func CompileOnly(l *MasterControl) error

CompileOnly sets the Loader to compile programs only, without executing them.

func DumpAst

func DumpAst(l *MasterControl) error

DumpAst instructs the Loader to print the AST after program compilation.

func DumpAstTypes

func DumpAstTypes(l *MasterControl) error

DumpAstTypes instructs the Loader to print the AST after type checking.

func DumpBytecode

func DumpBytecode(l *MasterControl) error

DumpBytecode instructs the loader to print the compiled bytecode after code generation.

func Equals

func Equals(t1, t2 Type) bool

Equals compares two types, testing for equality

func ErrorsAbort

func ErrorsAbort(l *MasterControl) error

ErrorsAbort sets the Loader to abort the Loader on compile errors.

func IsComplete

func IsComplete(t Type) bool

IsComplete returns true if the type and all its arguments have non-variable exemplars.

func IsDimension

func IsDimension(t Type) bool

IsDimension returns true if the given type is a Dimension type.

func IsFunction

func IsFunction(t Type) bool

IsFunction returns true if the given type is a Function type.

func MergePosition

func MergePosition(a, b *position) *position

MergePosition returns the union of two positions such that the result contains both inputs.

func OmitMetricSource

func OmitMetricSource(l *MasterControl) error

OmitMetricSource instructs the Loader to not annotate metrics with their program source when added to the metric store.

func OverrideLocation

func OverrideLocation(loc *time.Location) func(*MasterControl) error

OverrideLocation sets the timezone location for the VM.

func Parse

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

Parse reads the program named name from the input, and if successful returns an astNode for the root of the AST, or parser errors.

func SyslogUseCurrentYear

func SyslogUseCurrentYear(l *MasterControl) error

SyslogUseCurrentYear instructs the VM to annotate yearless timestamps with the current year.

func Unify

func Unify(a, b Type) error

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. In reporting errors, it is assumed that a is the expected type and b is the type observed.

func Walk

func Walk(v Visitor, node astNode)

Walk traverses (walks) an AST node with the provided Visitor v.

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) Append

func (p *ErrorList) Append(l ErrorList)

Append puts an ErrorList on the end of this ErrorList.

func (ErrorList) Error

func (p ErrorList) Error() string

ErrorList implements the error interface.

type MasterControl

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

MasterControl 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(programPath string, store *metrics.Store, lines <-chan *logline.LogLine, w watcher.Watcher, fs afero.Fs, options ...func(*MasterControl) error) (*MasterControl, error)

NewLoader creates a new program loader that reads programs from programPath.

func (*MasterControl) CompileAndRun

func (l *MasterControl) 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 (*MasterControl) LoadAllPrograms

func (l *MasterControl) LoadAllPrograms() error

LoadAllPrograms loads all programs in a directory and starts watching the directory for filesystem changes. Any compile errors are stored for later retrieival. This function returns an error if an internal error occurs.

func (*MasterControl) LoadProgram

func (l *MasterControl) LoadProgram(programPath string) error

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

func (*MasterControl) SetOption

func (l *MasterControl) SetOption(options ...func(*MasterControl) error) error

SetOption takes one or more option functions and applies them in order to Loader.

func (*MasterControl) UnloadProgram

func (l *MasterControl) UnloadProgram(pathname string)

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

func (*MasterControl) WriteStatusHTML

func (l *MasterControl) WriteStatusHTML(w io.Writer) error

WriteStatusHTML writes the current state of the loader as HTML to the given writer w.

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) CopyFrom

func (s *Scope) CopyFrom(o *Scope)

CopyFrom copies all the symbols from another scope object into this one. It recurses up the input scope copying all visible symbols into one.

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) InsertAlias

func (s *Scope) InsertAlias(sym *Symbol, alias string) (alt *Symbol)

InsertAlias attempts to insert a duplicate name for an existing symbol into the scope. If the scope already contains an object alt with the alias, the scope is unchanged and the function returns alt. Otherwise, the symbol is inserted and the function returns nil.

func (*Scope) Lookup

func (s *Scope) Lookup(name string, kind SymbolKind) *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)

VisitAfter implements the astNode Visitor interface.

func (*Sexp) VisitBefore

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

VisitBefore implements the astNode Visitor interface.

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
	Used    bool        // Optional marker that this symbol is used after declaration.
}

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

SymbolKind enumerates the kind of a Symbol.

const (
	VarSymbol     SymbolKind = iota // Variables
	CaprefSymbol                    // Capture group references
	DecoSymbol                      // Decorators
	PatternSymbol                   // Named pattern constants
)

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

func (SymbolKind) String

func (k SymbolKind) String() string

type Type

type Type interface {
	// Root returns an exemplar Type after unification occurs.  If the type
	// system is complete after unification, Root will be a TypeOperator.
	Root() Type

	// String returns a string representation of a Type.
	String() string
}

Type represents a type in the mtail program.

func FreshType

func FreshType(t Type) Type

FreshType returns a new type from the provided type scheme, replacing any unbound type variables with new type variables.

func LeastUpperBound

func LeastUpperBound(a, b Type) Type

LeastUpperBound returns the smallest type that may contain both parameter types.

type TypeError

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

TypeError describes an error in which a type was expected, but another was encountered.

func (*TypeError) Error

func (e *TypeError) Error() string

type TypeOperator

type TypeOperator struct {
	// Name is a common name for this operator
	Name string
	// Args is the sequence of types that are parameters to this type.  They
	// may be fully bound type operators, or partially defined (i.e. contain
	// TypeVariables) in which case they represent polymorphism in the operator
	// they are argyments to.
	Args []Type
}

TypeOperator represents a type scheme in the type system.

func Dimension

func Dimension(args ...Type) *TypeOperator

Dimension is a convenience method which instantiates a new Dimension type scheme, with the given args as the dimensions of the type.

func Function

func Function(args ...Type) *TypeOperator

Function is a convenience method, which instantiates a new Function type scheme, with the given args as parameters.

func (*TypeOperator) Root

func (t *TypeOperator) Root() Type

Root returns an exemplar of a TypeOperator, i.e. itself.

func (*TypeOperator) String

func (t *TypeOperator) String() (s string)

type TypeVariable

type TypeVariable struct {
	ID int

	Instance *Type
	// contains filtered or unexported fields
}

TypeVariable represents an unbound type variable in the type system.

func NewTypeVariable

func NewTypeVariable() *TypeVariable

NewTypeVariable constructs a new unique TypeVariable.

func (*TypeVariable) Root

func (t *TypeVariable) Root() Type

Root returns an exemplar of this TypeVariable, in this case the root of the unification tree.

func (*TypeVariable) SetInstance

func (t *TypeVariable) SetInstance(t1 *Type)

SetInstance sets the exemplar instance of this TypeVariable, during unification.

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)

VisitAfter implements the astNode Visitor interface.

func (*Unparser) VisitBefore

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

VisitBefore implements the astNode Visitor interface.

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, emitAst bool, emitAstTypes bool, syslogUseCurrentYear bool, loc *time.Location) (*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, loc *time.Location) *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 a string.

func (*VM) ParseTime

func (v *VM) ParseTime(layout, value string) (tm time.Time)

ParseTime performs location and syslog-year aware timestamp parsing.

func (*VM) Run

func (v *VM) Run(_ uint32, lines <-chan *logline.LogLine, shutdown chan<- struct{}, started 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)
}

Visitor 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.