instrumentor

Documentation

Index

• Constants
• func ExportsFunctions(file *ast.File, fset *token.FileSet) bool
• func HasLinkname(file *ast.File, fset *token.FileSet) bool
• func IsFunctionExported(group *ast.CommentGroup, name string) bool
• func IsLineDirectiveCompatible(file *ast.File, fset *token.FileSet) bool
• func RequiresFileNameOrLineNumber(n ast.Node, fset *token.FileSet) bool
• type CoverageInstrumentor
  • func (cI *CoverageInstrumentor) InstrumentFile(file_name string) string
  • func (cI *CoverageInstrumentor) SummarizeWork(numFiles int)
  • func (cI *CoverageInstrumentor) WrapUp() (edge_count int)
• type Instrumentor
  • func CreateInstrumentor(basePath string, shimPkg string, table *SymbolTable) *Instrumentor
  • func (instrumentor *Instrumentor) Instrument(path string) (string, error)
  • func (instrumentor *Instrumentor) TrimComments(path string, file *ast.File)
  • func (instrumentor *Instrumentor) Visit(node ast.Node) ast.Visitor
  • func (instrumentor *Instrumentor) VisitAndAddLines(node ast.Node) ast.Visitor
  • func (instrumentor *Instrumentor) VisitAndInstrument(node ast.Node) ast.Visitor
• type Stack
  • func (s *Stack) IsEmpty() bool
  • func (s *Stack) Peek() (ast.Node, bool)
  • func (s *Stack) Pop() (ast.Node, bool)
  • func (s *Stack) Push(x ast.Node)
• type SymbolTable
  • func CreateInMemorySymbolTable(symbolTablePath, instrumentedModule string) *SymbolTable
  • func CreateSymbolTableFile(symbolTablePath, instrumentedModule string) (err error, symbolTable *SymbolTable)
  • func (t *SymbolTable) Close() error
  • func (t *SymbolTable) String() string
  • func (t *SymbolTable) WritePosition(p SymbolTablePosition) error
• type SymbolTablePosition

Constants

const AntithesisCallbackFunction = "Notify"

AntithesisCallbackFunction is the name of the instrumentor-generated callback function that delegates to wrapper.Notify() with the correct arguments. Multiple definitions of this function will lead to a (desirable) compile-time error.

const InstrumentationModuleName = "github.com/antithesishq/antithesis-sdk-go/instrumentation"

InstrumentationModuleName is our module wrapping the necessary C functions in libvoidstar.so. Generated code will be in the same package.

const InstrumentationPackageAlias = "__antithesis_instrumentation__"

InstrumentationPackageAlias will be used to prevent any collisions between possible other packages named "instrumentation". Underscore characters are considered bad style, which is why I'm using them: a collision is less likely.

Functions

func ExportsFunctions

func ExportsFunctions(file *ast.File, fset *token.FileSet) bool

ExportsFunctions warns the caller that the the .go file includes export directives in comments, which AST-rewriting may damage.

func HasLinkname

func HasLinkname(file *ast.File, fset *token.FileSet) bool

HasLinkname lets us exclude .go files that interact with other languages.

func IsFunctionExported

func IsFunctionExported(group *ast.CommentGroup, name string) bool

IsFunctionExported checks the comments preceding a function declaration for all known formats of export directive.

func IsLineDirectiveCompatible

func IsLineDirectiveCompatible(file *ast.File, fset *token.FileSet) bool

func RequiresFileNameOrLineNumber

func RequiresFileNameOrLineNumber(n ast.Node, fset *token.FileSet) bool

Check to see if this particular node represents a something which requires runtime-generated file names. If this is the case, we can't instrument this because we have to statically set the path in the comments, and there's no way to simultaneously:

1) Use //line directives to set the line numbers; and 2) Let the runtime set the absolute/relative file path.

The primary offenders are the runtime.(Caller|Callers) functions. See https://github.com/golang/go/issues/26207 for more details.

Types

type CoverageInstrumentor

type CoverageInstrumentor struct {
	GoInstrumentor    *Instrumentor
	UsingSymbols      string
	FullCatalogPath   string
	PreviousEdge      int
	FilesInstrumented int
	SymTable          *SymbolTable
	FilesSkipped      int
	// contains filtered or unexported fields
}

Capitalized struct items are accessed outside this file

func (*CoverageInstrumentor) InstrumentFile

func (cI *CoverageInstrumentor) InstrumentFile(file_name string) string

func (*CoverageInstrumentor) SummarizeWork

func (cI *CoverageInstrumentor) SummarizeWork(numFiles int)

func (*CoverageInstrumentor) WrapUp

func (cI *CoverageInstrumentor) WrapUp() (edge_count int)

type Instrumentor

type Instrumentor struct {
	ShimPkg     string
	SymbolTable *SymbolTable
	CurrentEdge int
	// contains filtered or unexported fields
}

Instrumentor *is* the Antithesis Go source-code instrumentor.

func CreateInstrumentor

func CreateInstrumentor(basePath string, shimPkg string, table *SymbolTable) *Instrumentor

CreateInstrumentor is the factory method.

func (*Instrumentor) Instrument

func (instrumentor *Instrumentor) Instrument(path string) (string, error)

Instrument inserts calls to the Golang bridge to the Antithesis fuzzer. Errors should be logged, but are generally not fatal, since the input file can simply be copied to the output uninstrumented. If a file contains no executable code (i.e. contains only variable declarations, exports, or imports, an empty string is returned, so that the caller can simply copy the input file. TODO Return a * to a string, rather that returning the empty string to signal "I didn't instrument this input."

func (*Instrumentor) TrimComments

func (instrumentor *Instrumentor) TrimComments(path string, file *ast.File)

TrimComments uses the CommentMap structure to discard all comments not relevant to compilation.

func (*Instrumentor) Visit

func (instrumentor *Instrumentor) Visit(node ast.Node) ast.Visitor

Visit is part of the FileWalker interface. TODO: (justin.moore) See how difficult it would be to merge the Visit sub-functions back into a single Visit() function, and just switch on control flow based on the addLines boolean, rather than duplicating most of the switch statement in each function.

func (*Instrumentor) VisitAndAddLines

func (instrumentor *Instrumentor) VisitAndAddLines(node ast.Node) ast.Visitor

func (*Instrumentor) VisitAndInstrument

func (instrumentor *Instrumentor) VisitAndInstrument(node ast.Node) ast.Visitor

type Stack

type Stack []ast.Node

func (*Stack) IsEmpty

func (s *Stack) IsEmpty() bool

IsEmpty: check if stack is empty

func (*Stack) Peek

func (s *Stack) Peek() (ast.Node, bool)

Peek: return top element of stack, return false if stack is empty

func (*Stack) Pop

func (s *Stack) Pop() (ast.Node, bool)

Pop: remove and return top element of stack, return false if stack is empty

func (*Stack) Push

func (s *Stack) Push(x ast.Node)

Push a new integer onto the stack

type SymbolTable

type SymbolTable struct {
	Path string
	// contains filtered or unexported fields
}

SymbolTable is the serialization of the edges that the instrumentor finds and instruments.

func CreateInMemorySymbolTable

func CreateInMemorySymbolTable(symbolTablePath, instrumentedModule string) *SymbolTable

CreateInMemorySymbolTable creates an in memory symbol table for testing.

func CreateSymbolTableFile

func CreateSymbolTableFile(symbolTablePath, instrumentedModule string) (err error, symbolTable *SymbolTable)

CreateSymbolTableFile opens an Antithesis-standard .symbols.tsv file on disk.

func (*SymbolTable) Close

func (t *SymbolTable) Close() error

Close closes the underlying file resources.

func (*SymbolTable) String

func (t *SymbolTable) String() string

func (*SymbolTable) WritePosition

func (t *SymbolTable) WritePosition(p SymbolTablePosition) error

WritePosition describes a callback to the Antithesis instrumentation.

type SymbolTablePosition

type SymbolTablePosition struct {
	Path        string
	Function    string
	StartLine   int
	StartColumn int
	EndLine     int
	EndColumn   int
	Edge        int
}