cfg

Documentation

Overview

Package cfg constructs a simple control-flow graph (CFG) of the statements and expressions within a single function.

Use cfg.New to construct the CFG for a function body.

The blocks of the CFG contain all the function's non-control statements. The CFG does not contain control statements such as If, Switch, Select, and Branch, but does contain their subexpressions; also, each block records the control statement (Block.Stmt) that gave rise to it and its relationship (Block.Kind) to that statement.

For example, this source code:

if x := f(); x != nil {
	T()
} else {
	F()
}

produces this CFG:

1:  x := f()		Body
    x != nil
    succs: 2, 3
2:  T()			IfThen
    succs: 4
3:  F()			IfElse
    succs: 4
4:			IfDone

The CFG does contain Return statements; even implicit returns are materialized (at the position of the function's closing brace).

The CFG does not record conditions associated with conditional branch edges, nor the short-circuit semantics of the && and || operators, nor abnormal control flow caused by panic. If you need this information, use golang.org/x/tools/go/ssa instead.

Index

• type Block
  • func (b *Block) Return() (ret *ast.ReturnStmt)
  • func (b *Block) String() string
• type BlockKind
  • func (kind BlockKind) String() string
• type CFG
  • func New(body *ast.BlockStmt, mayReturn func(*ast.CallExpr) bool) *CFG
  • func (g *CFG) Dot(fset *token.FileSet) string
  • func (g *CFG) Format(fset *token.FileSet) string

Types

type Block

type Block struct {
	Nodes []ast.Node // statements, expressions, and ValueSpecs
	Succs []*Block   // successor nodes in the graph
	Index int32      // index within CFG.Blocks
	Live  bool       // block is reachable from entry
	Kind  BlockKind  // block kind
	Stmt  ast.Stmt   // statement that gave rise to this block (see BlockKind for details)
	// contains filtered or unexported fields
}

A Block represents a basic block: a list of statements and expressions that are always evaluated sequentially.

A block may have 0-2 successors: zero for a return block or a block that calls a function such as panic that never returns; one for a normal (jump) block; and two for a conditional (if) block.

func (*Block) Return

func (b *Block) Return() (ret *ast.ReturnStmt)

Return returns the return statement at the end of this block if present, nil otherwise.

When control falls off the end of the function, the ReturnStmt is synthetic and its ast.Node.End position may be beyond the end of the file.

func (*Block) String

func (b *Block) String() string

type BlockKind

type BlockKind uint8

A BlockKind identifies the purpose of a block. It also determines the possible types of its Stmt field.

const (
	KindInvalid BlockKind = iota // Stmt=nil

	KindUnreachable     // unreachable block after {Branch,Return}Stmt / no-return call ExprStmt
	KindBody            // function body BlockStmt
	KindForBody         // body of ForStmt
	KindForDone         // block after ForStmt
	KindForLoop         // head of ForStmt
	KindForPost         // post condition of ForStmt
	KindIfDone          // block after IfStmt
	KindIfElse          // else block of IfStmt
	KindIfThen          // then block of IfStmt
	KindLabel           // labeled block of BranchStmt (Stmt may be nil for dangling label)
	KindRangeBody       // body of RangeStmt
	KindRangeDone       // block after RangeStmt
	KindRangeLoop       // head of RangeStmt
	KindSelectCaseBody  // body of SelectStmt
	KindSelectDone      // block after SelectStmt
	KindSelectAfterCase // block after a CommClause
	KindSwitchCaseBody  // body of CaseClause
	KindSwitchDone      // block after {Type.}SwitchStmt
	KindSwitchNextCase  // secondary expression of a multi-expression CaseClause
)

func (BlockKind) String

func (kind BlockKind) String() string

type CFG

type CFG struct {
	Blocks []*Block // block[0] is entry; order otherwise undefined
	// contains filtered or unexported fields
}

A CFG represents the control-flow graph of a single function.

The entry point is Blocks[0]; there may be multiple return blocks.

func New

func New(body *ast.BlockStmt, mayReturn func(*ast.CallExpr) bool) *CFG

New returns a new control-flow graph for the specified function body, which must be non-nil.

The CFG builder calls mayReturn to determine whether a given function call may return. For example, calls to panic, os.Exit, and log.Fatal do not return, so the builder can remove infeasible graph edges following such calls. The builder calls mayReturn only for a CallExpr beneath an ExprStmt.

func (*CFG) Dot

func (g *CFG) Dot(fset *token.FileSet) string

Dot returns the control-flow graph in the [Dot graph description language]. Use a command such as 'dot -Tsvg' to render it in a form viewable in a browser. This method is provided as a debugging aid; the details of the output are unspecified and may change.

[Dot graph description language]: ​​https://en.wikipedia.org/wiki/DOT_(graph_description_language)

func (*CFG) Format

func (g *CFG) Format(fset *token.FileSet) string

Format formats the control-flow graph for ease of debugging.