checkescape

Documentation

Overview

Package checkescape allows recursive escape analysis for hot paths.

The analysis tracks multiple types of escapes, in two categories. First, 'hard' escapes are explicit allocations. Second, 'soft' escapes are interface dispatches or dynamic function dispatches; these don't necessarily escape but they *may* escape. The analysis is capable of making assertions recursively: soft escapes cannot be analyzed in this way, and therefore count as escapes for recursive purposes.

The different types of escapes are as follows, with the category in parentheses:

heap:      A direct allocation is made on the heap (hard).
builtin:   A call is made to a built-in allocation function (hard).
stack:     A stack split as part of a function preamble (soft).
interface: A call is made via an interface which *may* escape (soft).
dynamic:   A dynamic function is dispatched which *may* escape (soft).

To the use the package, annotate a function-level comment with either the line "// +checkescape" or "// +checkescape:OPTION[,OPTION]". In the second case, the OPTION field is either a type above, or one of:

local: Escape analysis is limited to local hard escapes only.
all: All the escapes are included.
hard: All hard escapes are included.

If the "// +checkescape" annotation is provided, this is equivalent to provided the local and hard options.

Some examples of this syntax are:

+checkescape:all - Analyzes for all escapes in this function and all calls. +checkescape:local - Analyzes only for default local hard escapes. +checkescape:heap - Only analyzes for heap escapes. +checkescape:interface,dynamic - Only checks for dynamic calls and interface calls. +checkescape - Does the same as +checkescape:local,hard.

Note that all of the above can be inverted by using +mustescape. The +checkescape keyword will ensure failure if the class of escape occurs, whereas +mustescape will fail if the given class of escape does not occur.

Local exemptions can be made by a comment of the form "// escapes: reason." This must appear on the line of the escape and will also apply to callers of the function as well (for non-local escape analysis).

Index

• Variables
• type CallSite
  • func (cs *CallSite) IsValid() bool
• type EscapeReason
  • func (e EscapeReason) String() string
• type Escapes
  • func MergeAll(others []Escapes) (es Escapes)
  • func (es *Escapes) Add(r EscapeReason, detail string, callSites ...CallSite)
  • func (es *Escapes) Filter(reasons []EscapeReason, local bool)
  • func (es *Escapes) IsEmpty() bool
  • func (es *Escapes) MergeWithCall(other Escapes, callSite CallSite)
  • func (es *Escapes) Reportf(pass *analysis.Pass)
• type LinePosition
  • func (e LinePosition) Simplified() string
  • func (e LinePosition) String() string

Variables

var Analyzer = &analysis.Analyzer{
	Name:      "checkescape",
	Doc:       "escape analysis checks based on +checkescape annotations",
	Run:       runSelectEscapes,
	Requires:  []*analysis.Analyzer{buildssa.Analyzer},
	FactTypes: []analysis.Fact{(*packageEscapeFacts)(nil)},
}

Analyzer includes specific results.

var EscapeAnalyzer = &analysis.Analyzer{
	Name:     "checkescape",
	Doc:      "complete local escape analysis results (requires Analyzer facts)",
	Run:      runAllEscapes,
	Requires: []*analysis.Analyzer{buildssa.Analyzer},
}

EscapeAnalyzer includes all local escape results.

Types

type CallSite

type CallSite struct {
	LocalPos token.Pos
	Resolved LinePosition
}

CallSite is a single call site.

These can be chained.

func (*CallSite) IsValid

func (cs *CallSite) IsValid() bool

IsValid indicates whether the CallSite is valid or not.

type EscapeReason

type EscapeReason int

EscapeReason is an escape reason.

This is a simple enum.

func (EscapeReason) String

func (e EscapeReason) String() string

String returns the string for the EscapeReason.

Note that this also implicitly defines the reverse string -> EscapeReason mapping, which is the word before the colon (computed below).

type Escapes

type Escapes struct {
	CallSites [reasonCount][]CallSite
	Details   [reasonCount]string
	Omitted   [reasonCount]int
}

Escapes is a collection of escapes.

We record at most one escape for each reason, but record the number of escapes that were omitted.

This object should be used to summarize all escapes for a single line (local analysis) or a single function (package facts).

All fields are exported for gob.

func MergeAll

func MergeAll(others []Escapes) (es Escapes)

MergeAll merges a sequence of escapes.

func (*Escapes) Add

func (es *Escapes) Add(r EscapeReason, detail string, callSites ...CallSite)

Add adds a single escape.

func (*Escapes) Filter

func (es *Escapes) Filter(reasons []EscapeReason, local bool)

Filter filters out all escapes except those matches the given reasons.

If local is set, then non-local escapes will also be filtered.

func (*Escapes) IsEmpty

func (es *Escapes) IsEmpty() bool

IsEmpty returns true iff this Escapes is empty.

func (*Escapes) MergeWithCall

func (es *Escapes) MergeWithCall(other Escapes, callSite CallSite)

MergeWithCall merges these escapes with another.

If callSite is nil, no call is added.

func (*Escapes) Reportf

func (es *Escapes) Reportf(pass *analysis.Pass)

Reportf will call Reportf for each class of escapes.

type LinePosition

type LinePosition struct {
	Filename string
	Line     int
}

LinePosition is a low-resolution token.Position.

This is used to match against possible exemptions placed in the source.

func (LinePosition) Simplified

func (e LinePosition) Simplified() string

Simplified returns the simplified name.

func (LinePosition) String

func (e LinePosition) String() string

String implements fmt.Stringer.String.