vm

Documentation

Overview

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

Index

• Constants
• Variables
• 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 Unparser
  • func (u *Unparser) Unparse(n node) string
• type VM
  • func Compile(name string, input io.Reader, ms *metrics.Store, compileOnly bool, ...) (*VM, error)
  • func New(name string, re []*regexp.Regexp, str []string, m []*metrics.Metric, ...) *VM
  • func (v *VM) DumpByteCode(name string)
  • func (v *VM) Run(lines <-chan string, shutdown chan<- struct{})

Constants

const (
	IDSymbol     symtype = iota // Identifiers
	CaprefSymbol                // Capture group references
	DefSymbol                   // Definitions

)

symtype enumerates the types of symbols found in the program text.

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 (
	// LineCount counts the number of lines read by the virtual machine engine from the input channel.
	LineCount = expvar.NewInt("line_count")
)

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
	DumpBytecode         bool
	SyslogUseCurrentYear bool
}

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

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 node) string

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

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, ms *metrics.Store, compileOnly bool, syslogUseCurrentYear bool) (*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, re []*regexp.Regexp, str []string, m []*metrics.Metric, prog []instr, 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)

DumpByteCode emits the program disassembly and data to standard out.

func (*VM) Run

func (v *VM) Run(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.