determinism

Documentation

Index

• Variables
• func NewIdentRefsFlag(refs IdentRefs) flag.Value
• type Checker
  • func NewChecker(config Config) *Checker
  • func (c *Checker) NewAnalyzer() *analysis.Analyzer
  • func (c *Checker) Run(pass *analysis.Pass) (*Result, 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, includePos bool) []string
  • func (n *NonDeterminisms) 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) 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
• type Result
  • func (r *Result) Dump(includePos bool) (lines []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,

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

Types

type Checker

type Checker struct {
	IdentRefs  IdentRefs
	DebugfFunc func(string, ...interface{})
	Debug      bool
}

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) (*Result, error)

Run executes this checker for the given pass and returns the result.

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.
	DefaultIdentRefs IdentRefs
	// If nil, uses log.Printf.
	DebugfFunc func(string, ...interface{})
	// Must be set to true to see advanced debug logs.
	Debug bool
}

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 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,
	includePos 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 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 {
	Kind ConcurrencyKind
	// contains filtered or unexported fields
}

ReasonConcurrency represents a non-deterministic concurrency construct.

func (*ReasonConcurrency) Pos

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

func (*ReasonConcurrency) String

func (r *ReasonConcurrency) String() string

String returns the reason.

type ReasonDecl

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

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

func (*ReasonDecl) Pos

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

func (*ReasonDecl) String

func (r *ReasonDecl) String() string

String returns the reason.

type ReasonFuncCall

type ReasonFuncCall struct {
	Func  *types.Func
	Child NonDeterminisms
	// contains filtered or unexported fields
}

ReasonFuncCall represents a call to a non-deterministic function.

func (*ReasonFuncCall) Pos

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

func (*ReasonFuncCall) String

func (r *ReasonFuncCall) String() string

String returns the reason.

type ReasonMapRange

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

ReasonMapRange represents iterating over a map via range.

func (*ReasonMapRange) Pos

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

func (*ReasonMapRange) String

func (r *ReasonMapRange) String() string

String returns the reason.

type ReasonVarAccess

type ReasonVarAccess struct {
	Var *types.Var
	// contains filtered or unexported fields
}

ReasonVarAccess represents accessing a non-deterministic global variable.

func (*ReasonVarAccess) Pos

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

func (*ReasonVarAccess) String

func (r *ReasonVarAccess) String() string

String returns the reason.

type Result

type Result struct {
	// Only includes top-level functions
	Funcs map[*types.Func]NonDeterminisms
}

Result is the result from Run and the result on the Analyzer.

func (*Result) Dump

func (r *Result) Dump(includePos bool) (lines []string)

Dump returns the result as a set of lines.