determinism

Documentation

Index

• Variables
• func NewIdentRefsFlag(refs IdentRefs) flag.Value
• func UpdateIgnoreMap(fset *token.FileSet, f *ast.File, m map[ast.Node]struct{})
• type Checker
  • func NewChecker(config Config) *Checker
  • func (c *Checker) NewAnalyzer() *analysis.Analyzer
  • func (c *Checker) Run(pass *analysis.Pass) (PackageNonDeterminisms, error)
• type ConcurrencyKind
• type Config
• type IdentRefs
  • func (i IdentRefs) Clone() IdentRefs
  • func (i IdentRefs) SetAll(refs IdentRefs) IdentRefs
  • func (i IdentRefs) SetAllStrings(refs []string) IdentRefs
• type NonDeterminisms
  • func (*NonDeterminisms) AFact()
  • func (n NonDeterminisms) AppendChildReasonLines(subject string, s []string, depth int, depthRepeat string, includePos bool, ...) []string
  • func (n *NonDeterminisms) String() string
• type PackageLookupCache
  • func NewPackageLookupCache(pass *analysis.Pass) *PackageLookupCache
  • func (p *PackageLookupCache) PackageNonDeterminisms(pkg *types.Package) PackageNonDeterminisms
  • func (p *PackageLookupCache) PackageNonDeterminismsFromName(pkgInScope *types.Package, importedPkg string) (*types.Package, PackageNonDeterminisms)
• type PackageNonDeterminisms
  • func (*PackageNonDeterminisms) AFact()
  • func (n *PackageNonDeterminisms) String() string
• type Reason
• type ReasonConcurrency
  • func (r *ReasonConcurrency) Pos() *token.Position
  • func (r *ReasonConcurrency) String() string
• type ReasonDecl
  • func (r *ReasonDecl) Pos() *token.Position
  • func (r *ReasonDecl) String() string
• type ReasonFuncCall
  • func (r *ReasonFuncCall) PackageName() string
  • func (r *ReasonFuncCall) Pos() *token.Position
  • func (r *ReasonFuncCall) String() string
• type ReasonMapRange
  • func (r *ReasonMapRange) Pos() *token.Position
  • func (r *ReasonMapRange) String() string
• type ReasonVarAccess
  • func (r *ReasonVarAccess) Pos() *token.Position
  • func (r *ReasonVarAccess) String() string

Variables

var DefaultIdentRefs = IdentRefs{
	"os.Stderr":  true,
	"os.Stdin":   true,
	"os.Stdout":  true,
	"time.Now":   true,
	"time.Sleep": true,

	"(reflect.Value).Interface": false,
	"runtime.Caller":            false,
	"fmt.Append":                false,
	"fmt.Appendf":               false,
	"fmt.Appendln":              false,
	"fmt.Errorf":                false,
	"fmt.Sprintf":               false,
	"fmt.Sprint":                false,
	"fmt.Sprintln":              false,
	"fmt.Sscan":                 false,
	"fmt.Sscanf":                false,
	"fmt.Sscanln":               false,

	"math/rand.globalRand": true,

	"crypto/rand.Reader": true,
}

DefaultIdentRefs are the built-in set of known non-deterministic functions and vars and overrides for ones that should be treated as deterministic.

Functions

func NewIdentRefsFlag

func NewIdentRefsFlag(refs IdentRefs) flag.Value

NewIdentRefsFlag creates a flag.Value implementation for using IdentRefs.SetAllStrings as a CLI flag value.

func UpdateIgnoreMap

func UpdateIgnoreMap(fset *token.FileSet, f *ast.File, m map[ast.Node]struct{})

Types

type Checker

type Checker struct{ Config }

Checker is a checker that can run analysis passes to check for non-deterministic code.

func NewChecker

func NewChecker(config Config) *Checker

NewChecker creates a Checker for the given config.

func (*Checker) NewAnalyzer

func (c *Checker) NewAnalyzer() *analysis.Analyzer

NewAnalyzer creates a Go analysis analyzer that can be used in existing tools. There is a -set-decl flag for adding ident refs overrides and a -determinism-debug flag for enabling debug logs. The result is Result and the facts on functions are *NonDeterminisms.

func (*Checker) Run

func (c *Checker) Run(pass *analysis.Pass) (PackageNonDeterminisms, error)

Run executes this checker for the given pass and stores the fact.

type ConcurrencyKind

type ConcurrencyKind int

ConcurrencyKind is a construct that is non-deterministic for ReasonConcurrency.

const (
	ConcurrencyKindGo ConcurrencyKind = iota
	ConcurrencyKindRecv
	ConcurrencyKindSend
	ConcurrencyKindRange
)

type Config

type Config struct {
	// If empty, uses DefaultIdentRefs.
	IdentRefs IdentRefs
	// If file matches any here, it is not checked at all.
	SkipFiles []*regexp.Regexp
	// If nil, uses log.Printf.
	DebugfFunc func(string, ...interface{})
	// Must be set to true to see advanced debug logs.
	Debug bool
	// Whether to export a *NonDeterminisms fact per object.
	EnableObjectFacts bool
	// Map `package -> function names` with functions making any argument deterministic
	AcceptsNonDeterministicParameters map[string][]string
}

Config is config for NewChecker.

type IdentRefs

type IdentRefs map[string]bool

IdentRefs is a map of whether the key, as a qualified type or var name, is non-determinism (true value means non-deterministic, false means deterministic).

func (IdentRefs) Clone

func (i IdentRefs) Clone() IdentRefs

Clone copies the map and returns it.

func (IdentRefs) SetAll

func (i IdentRefs) SetAll(refs IdentRefs) IdentRefs

SetAll sets the given values on this map and returns this map.

func (IdentRefs) SetAllStrings

func (i IdentRefs) SetAllStrings(refs []string) IdentRefs

SetAllStrings sets values based on the given string values. The strings are qualified type names and are assumed as "true" (non-deterministic) unless the string ends with "=false" which is then treated as false in the map.

type NonDeterminisms

type NonDeterminisms []Reason

NonDeterminisms is a set of reasons why a function/var is non-deterministic.

func (*NonDeterminisms) AFact

func (*NonDeterminisms) AFact()

AFact is for implementing golang.org/x/tools/go/analysis.Fact.

func (NonDeterminisms) AppendChildReasonLines

func (n NonDeterminisms) AppendChildReasonLines(
	subject string,
	s []string,
	depth int,
	depthRepeat string,
	includePos bool,
	pkg *types.Package,
	lookupCache *PackageLookupCache,
	seenPos map[string]bool,
) []string

AppendChildReasonLines appends to lines the set of reasons in this slice. This will include newlines and indention based on depth.

func (*NonDeterminisms) String

func (n *NonDeterminisms) String() string

String returns all reasons as a comma-delimited string.

type PackageLookupCache

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

PackageLookupCache caches fact lookups across packages.

func NewPackageLookupCache

func NewPackageLookupCache(pass *analysis.Pass) *PackageLookupCache

NewPackageLookupCache creates a PackageLookupCache.

func (*PackageLookupCache) PackageNonDeterminisms

func (p *PackageLookupCache) PackageNonDeterminisms(pkg *types.Package) PackageNonDeterminisms

PackageNonDeterminisms returns non-determinisms for the package or an empty set if none found.

func (*PackageLookupCache) PackageNonDeterminismsFromName

func (p *PackageLookupCache) PackageNonDeterminismsFromName(
	pkgInScope *types.Package,
	importedPkg string,
) (*types.Package, PackageNonDeterminisms)

PackageNonDeterminismsFromName returns the package for the given name and its non-determinisms via PackageNonDeterminisms. The package name must be directly imported from the given package in scope. Nil is returned for a package that is not found.

type PackageNonDeterminisms

type PackageNonDeterminisms map[string]NonDeterminisms

PackageNonDeterminisms contains func/var non-determinisms keyed by name.

func (*PackageNonDeterminisms) AFact

func (*PackageNonDeterminisms) AFact()

AFact is for implementing golang.org/x/tools/go/analysis.Fact.

func (*PackageNonDeterminisms) String

func (n *PackageNonDeterminisms) String() string

type Reason

type Reason interface {
	Pos() *token.Position
	// String is expected to just include the brief reason, not any child reasons.
	String() string
}

Reason represents a reason for non-determinism.

type ReasonConcurrency

type ReasonConcurrency struct {
	SourcePos *token.Position
	Kind      ConcurrencyKind
}

ReasonConcurrency represents a non-deterministic concurrency construct.

func (*ReasonConcurrency) Pos

func (r *ReasonConcurrency) Pos() *token.Position

Pos returns the source position.

func (*ReasonConcurrency) String

func (r *ReasonConcurrency) String() string

String returns the reason.

type ReasonDecl

type ReasonDecl struct {
	SourcePos *token.Position
}

ReasonDecl represents a function or var that was explicitly marked non-deterministic via config.

func (*ReasonDecl) Pos

func (r *ReasonDecl) Pos() *token.Position

Pos returns the source position.

func (*ReasonDecl) String

func (r *ReasonDecl) String() string

String returns the reason.

type ReasonFuncCall

type ReasonFuncCall struct {
	SourcePos *token.Position
	// Fully qualified name
	FuncName string
}

ReasonFuncCall represents a call to a non-deterministic function.

func (*ReasonFuncCall) PackageName

func (r *ReasonFuncCall) PackageName() string

func (*ReasonFuncCall) Pos

func (r *ReasonFuncCall) Pos() *token.Position

Pos returns the source position.

func (*ReasonFuncCall) String

func (r *ReasonFuncCall) String() string

String returns the reason.

type ReasonMapRange

type ReasonMapRange struct {
	SourcePos *token.Position
}

ReasonMapRange represents iterating over a map via range.

func (*ReasonMapRange) Pos

func (r *ReasonMapRange) Pos() *token.Position

Pos returns the source position.

func (*ReasonMapRange) String

func (r *ReasonMapRange) String() string

String returns the reason.

type ReasonVarAccess

type ReasonVarAccess struct {
	SourcePos *token.Position
	// Fully qualified name
	VarName string
}

ReasonVarAccess represents accessing a non-deterministic global variable.

func (*ReasonVarAccess) Pos

func (r *ReasonVarAccess) Pos() *token.Position

Pos returns the source position.

func (*ReasonVarAccess) String

func (r *ReasonVarAccess) String() string

String returns the reason.