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
- type EscapeReason
- type Escapes
- func (*Escapes) AFact()
- 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
Constants ¶
This section is empty.
Variables ¶
var Analyzer = &objdumpAnalyzer{ Analyzer: analysis.Analyzer{ Name: "checkescape", Doc: "escape analysis checks based on +checkescape annotations", Run: nil, Requires: []*analysis.Analyzer{buildssa.Analyzer}, FactTypes: []analysis.Fact{(*Escapes)(nil)}, }, }
Analyzer includes specific results.
Functions ¶
This section is empty.
Types ¶
type CallSite ¶
type CallSite struct {
LocalPos token.Pos
Resolved LinePosition
}
CallSite is a single call site.
These can be chained.
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 (*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) MergeWithCall ¶
MergeWithCall merges these escapes with another.
If callSite is nil, no call is added.
type LinePosition ¶
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.
Source Files
Directories