cfg

Documentation

Overview

This package 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. For example, this source code:

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

produces this CFG:

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

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 CFG
  • func New(body *ast.BlockStmt, mayReturn func(*ast.CallExpr) bool) *CFG
  • 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
	// 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.

func (*Block) String

func (b *Block) String() string

type CFG

type CFG struct {
	Blocks []*Block // block[0] is entry; order otherwise undefined
}

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) Format

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

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