Pgo on Opensource internals

Go's Inliner: A Budget of 80 Nodes and the Art of the Cheat Sheet

Jay Hubbert — Wed, 21 Oct 2026 04:16:00 +0000

TL;DR: Every Go function gets an inline budget of 80 IR nodes. Walk the body, subtract one per node, and if you go negative the function is not inlinable — that’s the “function too complex” message. defer, go and tail calls disqualify a function outright, and closures cost 15 nodes. Give the compiler a PGO profile and hot call sites get a budget of 2000 instead of 80.

The single most common question about Go performance is “why isn’t this function being inlined?”. The answer is usually a number: the function is cost 87, and the budget is 80.

That budget is not a guideline. It is a hard number in the compiler source, it has been 80 for well over a decade, and understanding how it is spent is most of what you need to write Go that inlines.

There is also a cheat sheet, and it is literally a table. When the new inliner runs, it can dump every call site in the package with the score it computed, the adjustment it applied, and whether the adjustment promoted or demoted the site. That table is how you find out why a particular call did or did not get inlined, and it is the subject of the second half of this article.

This is a walk through how it works, based on reading the Go 1.28 development tree (src/cmd/compile/internal/inline/).

Two passes, not one

The inliner is split into two halves. The header comment says it plainly:

 go
 
 
// src/cmd/compile/internal/inline/inl.go:5
// The inlining facility makes 2 passes: first CanInline determines which
// functions are suitable for inlining, and for those that are it
// saves a copy of the body. Then InlineCalls walks each function body to
// expand calls to inlinable functions.
//
// The Debug.l flag controls the aggressiveness. Note that main() swaps level 0 and 1,
// making 1 the default and -l disable. Additional levels (beyond -l) may be buggy and
// are not supported.
// 0: disabled
// 1: 80-nodes leaf functions, oneliners, panic, lazy typechecking (default)
// 2: (unassigned)
// 3: (unassigned)
// 4: allow non-leaf functions
//
// At some point this may get another default and become switch-offable with -N.
//
// The -d typcheckinl flag enables early typechecking of all imported bodies,
// which is useful to flush out bugs.
//
// The Debug.m flag enables diagnostic output. a single -m is useful for verifying
// which calls get inlined or not, more is for debugging, and may go away at any point.

So: pass one decides whether a function is inlinable and remembers its cost. Pass two walks each function body and substitutes the bodies of inlinable callees.

The flags are declared in base/flag.go:

 go
 
 
// src/cmd/compile/internal/base/flag.go:74
	LowerL CountFlag "help:\"disable inlining\""
	LowerM CountFlag "help:\"print optimization decisions\""

-l=0 disables inlining entirely. -l=1 is the default. -l=4 allows non-leaf functions (functions that themselves contain calls) to be inlined. -m prints the decisions.

The budget

Here is the whole cost model, in one constant block:

 go
 
 
// src/cmd/compile/internal/inline/inl.go:48
// Inlining budget parameters, gathered in one place
const (
	inlineMaxBudget = 80
	inlineExtraAppendCost = 0
	// default is to inline if there's at most one call. -l=4 overrides this by using 1 instead.
	inlineExtraCallCost = 57 // 57 was benchmarked to provided most benefit with no bad surprises; see https://github.com/golang/go/issues/19348#issuecomment-439370742
	inlineParamCallCost = 17 // calling a parameter only costs this much extra (inlining might expose a constant function)
	inlineExtraPanicCost = 1 // do not penalize inlining panics.
	inlineExtraThrowCost = inlineMaxBudget // with current (2018-05/1.11) code, inlining runtime.throw does not help.

	inlineBigFunctionNodes = 5000 // Functions with this many nodes are considered "big".
	inlineBigFunctionMaxCost = 20 // Max cost of inlinee when inlining into a "big" function.
	inlineClosureCalledOnceCost = 10 * inlineMaxBudget // if a closure is just called once, inline it.
)

The budget arithmetic, in one picture:

 text
 
 
 budget = 80
 |
 | -1 for every IR node
 | -57 for a call to a function that will not be inlined
 | -17 for a call through a function parameter
 | -15 for a closure literal
 | -1 for a panic
 | +2 for &s.f where f is at offset 0
 | +N for refunds from front-end rewrites
 v
 budget < 0 => "function too complex: cost N exceeds budget 80"

That block is worth reading closely, because the numbers encode several years of benchmark-driven decisions.

80 is the base budget. Every IR node costs 1.
57 is the cost of a call to a function the compiler cannot inline itself. The comment links to the issue where 57 was benchmarked. This is the single most important number after 80: a function containing one non-inlinable call has almost no budget left for anything else.
17 is the cheaper cost of a call to a parameter (a function value). Inlining through a parameter can expose a constant function, so it is worth more.
1 is the cost of panic. Panicking is rare and the panic path is cold, so it should not discourage inlining.
80 (the whole budget) is the cost of runtime.throw, because inlining it does not help.

Counting the nodes

The counter is hairyVisitor. It walks the IR tree, subtracting from v.budget as it goes, and returns “too hairy” the moment the budget goes negative:

 go
 
 
// src/cmd/compile/internal/inline/inl.go:476
func (v *hairyVisitor) tooHairy(fn *ir.Func) bool {
	v.do = v.doNode // cache closure
	if ir.DoChildren(fn, v.do) {
		return true
	}
	if v.budget < 0 {
		v.reason = fmt.Sprintf("function too complex: cost %d exceeds budget %d", v.maxBudget-v.budget, v.maxBudget)
		return true
	}
	return false
}

And the per-node charge is at the bottom of doNode:

 go
 
 
// src/cmd/compile/internal/inline/inl.go:831
	v.budget--

	// When debugging, don't stop early, to get full cost of inlining this function
	if v.budget < 0 && base.Flag.LowerM < 2 && !logopt.Enabled() && !v.debug {
		v.reason = "too expensive"
		return true
	}

	return ir.DoChildren(n, v.do)
}

The switch above the v.budget-- handles the special cases. A few examples that show how the model actually behaves:

 go
 
 
// src/cmd/compile/internal/inline/inl.go:703
	case ir.OGO, ir.ODEFER, ir.OTAILCALL:
		v.reason = "unhandled op " + n.Op().String()
		return true

	case ir.OAPPEND:
		v.budget -= inlineExtraAppendCost

	case ir.OADDR:
		n := n.(*ir.AddrExpr)
		// Make "&s.f" cost 0 when f's offset is zero.
		if dot, ok := n.X.(*ir.SelectorExpr); ok && (dot.Op() == ir.ODOT || dot.Op() == ir.ODOTPTR) {
			if _, ok := dot.X.(*ir.Name); ok && dot.Selection.Offset == 0 {
				v.budget += 2 // undo ir.OADDR+ir.ODOT/ir.ODOTPTR
			}
		}

go, defer and tail calls are hard rejects. Not “expensive” — rejected. There is no budget that will let a function containing a defer be inlined at any level.

append is free (cost 0), because inlineExtraAppendCost is 0. Taking the address of a field at offset zero is free, because the address-of and the field access together are worth exactly one node.

There are also refunds. Some constructs get added back to the budget, because they would otherwise distort the measurement:

 go
 
 
// src/cmd/compile/internal/inline/inl.go:771
	case ir.OAS2:
		n := n.(*ir.AssignListStmt)

		// Unified IR unconditionally rewrites:
		//
		//	a, b = f()
		//
		// into:
		//
		//	DCL tmp1
		//	DCL tmp2
		//	tmp1, tmp2 = f()
		//	a, b = tmp1, tmp2
		//
		// so that it can insert implicit conversions as necessary. To
		// minimize impact to the existing inlining heuristics (in
		// particular, to avoid breaking the existing inlinability regress
		// tests), we need to compensate for this here.
		//
		// See also identical logic in IsBigFunc.
		if len(n.Rhs) > 0 {
			if init := n.Rhs[0].Init(); len(init) == 1 {
				if _, ok := init[0].(*ir.AssignListStmt); ok {
					// 4 for each value, because each temporary variable now
					// appears 3 times (DCL, LHS, RHS), plus an extra DCL node.
					//
					// 1 for the extra "tmp1, tmp2 = f()" assignment statement.
					v.budget += 4*int32(len(n.Lhs)) + 1
				}
			}
		}

This is a nice illustration of how the cost model is a proxy. The cost is not “how much machine code will this generate”; it is “how many IR nodes did the front end hand me”, with hand-tuned corrections so that front-end rewrites do not penalise the programmer.

What disqualifies a function outright

Two separate mechanisms. The first is InlineImpossible, which returns a reason string before any costing happens at all:

 go
 
 
// src/cmd/compile/internal/inline/inl.go:347
// InlineImpossible returns a non-empty reason string if fn is impossible to
// inline regardless of cost or contents.
func InlineImpossible(fn *ir.Func) string {
	var reason string // reason, if any, that the function can not be inlined.
	if fn.Nname == nil {
		reason = "no name"
		return reason
	}

	// If marked "go:noinline", don't inline.
	if fn.Pragma&ir.Noinline != 0 {
		reason = "marked go:noinline"
		return reason
	}

The pragma itself is defined in ir/node.go:

 go
 
 
// src/cmd/compile/internal/ir/node.go:435
const (
	// Func pragmas.
	Nointerface PragmaFlag = 1 << iota
	Noescape // func parameters don't escape
	Norace // func must not have race detector annotations
	Nosplit // func should not execute on separate stack
	Noinline // func should not be inlined
	NoCheckPtr // func should not be instrumented by checkptr
	CgoUnsafeArgs // treat a pointer to one arg as a pointer to them all
	UintptrKeepAlive // pointers converted to uintptr must be kept alive
	UintptrEscapes // pointers converted to uintptr escape

//go:noinline is the pragma you will actually use. There is no //go:inline in the compiler: the opt-in direction is handled by a different mechanism entirely (see the source-level inliner section below).

InlineImpossible also blocks functions with //go:uintptrescapes and //go:uintptrkeepalive (because inlining loses the keep-alive information), //go:yeswritebarrierrec, and functions with no body at all.

The second mechanism is the doNode switch, which rejects:

go, defer, tail calls — "unhandled op ...".
Closures, unless the debug flag InlFuncsWithClosures allows them:

 go
 
 
// src/cmd/compile/internal/inline/inl.go:689
	case ir.OCLOSURE:
		if base.Debug.InlFuncsWithClosures == 0 {
			v.reason = "not inlining functions with closures"
			return true
		}

		// TODO(danscales): Maybe make budget proportional to number of closure
		// variables, e.g.:
		//v.budget -= int32(len(n.(*ir.ClosureExpr).Func.ClosureVars) * 3)
		// TODO(austin): However, if we're able to inline this closure into
		// v.curFunc, then we actually pay nothing for the closure captures. We
		// should try to account for that if we're going to account for captures.
		v.budget -= 15

A closure costs 15 nodes. That’s not a rejection, just a chunk of your 80.

Calls to runtime.GetCallerPC and runtime.GetCallerSP, because inlining them would change what the program sees:

 go
 
 
// src/cmd/compile/internal/inline/inl.go:522
				case "internal/runtime/sys":
					switch fn {
					case "GetCallerPC", "GetCallerSP":
						// Functions that call GetCallerPC/SP can not be inlined
						// because users expect the PC/SP of the logical caller,
						// but GetCallerPC/SP returns the physical caller.
						v.reason = "call to " + fn
						return true
					}

deferrangefunc, the helper the compiler synthesises for defer inside a range-over-func.

Note that recover() is allowed to be inlined, but at the full non-leaf call cost of 57:

 go
 
 
// src/cmd/compile/internal/inline/inl.go:684
	case ir.ORECOVER:
		// recover matches panics to frames via stack unwinding
		// (including inlined frames), so it is safe to inline.
		v.budget -= v.extraCallCost

So a function containing recover() has 23 nodes of budget left. That is usually enough for one or two simple statements and nothing more.

Big functions get a smaller budget

If the caller is big, the budget for the callee drops from 80 to 20:

 go
 
 
// src/cmd/compile/internal/inline/inl.go:842
// IsBigFunc reports whether fn is a "big" function.
//
// Note: The criteria for "big" is heuristic and subject to change.
func IsBigFunc(fn *ir.Func) bool {
	budget := inlineBigFunctionNodes
	return ir.Any(fn, func(n ir.Node) bool {

“Big” means more than 5000 IR nodes. The reasoning is straightforward: a 5000-node function is already generating a lot of machine code, and inlining 80 more nodes of callee into it makes the code worse, not better. This exists because issue #26546 and #17566 both asked for it.

PGO: the budget goes to 2000

Now the interesting part. If you build with a profile, the compiler knows which call sites are hot, and hot call sites get a much larger budget.

First, the profile is turned into a set of “hot” call sites. The threshold is not a flat percentage; it is based on the cumulative distribution function of edge weights:

 go
 
 
// src/cmd/compile/internal/inline/inl.go:75
	// Threshold in percentage for hot callsite inlining.
	inlineHotCallSiteThresholdPercent float64

	// Threshold in CDF percentage for hot callsite inlining,
	// that is, for a threshold of X the hottest callsites that
	// make up the top X% of total edge weight will be
	// considered hot for inlining candidates.
	inlineCDFHotCallSiteThresholdPercent = float64(99)

	// Budget increased due to hotness.
	inlineHotMaxBudget int32 = 2000

99% of total edge weight. So the hot set is “the smallest set of call sites that accounts for 99% of the profile’s total weight”. That is a much better rule than “top 100 call sites”, because a profile is usually dominated by a handful of genuinely hot edges.

The CDF is computed here:

 go
 
 
// src/cmd/compile/internal/inline/inl.go:141
// hotNodesFromCDF computes an edge weight threshold and the list of hot
// nodes that make up the given percentage of the CDF. The threshold, as
// a percent, is the lower bound of weight for nodes to be considered hot
// (currently only used in debug prints) (in case of equal weights,
// comparing with the threshold may not accurately reflect which nodes are
// considered hot).
func hotNodesFromCDF(p *pgoir.Profile) (float64, []pgo.NamedCallEdge) {
	cum := int64(0)
	for i, n := range p.NamedEdgeMap.ByWeight {
		w := p.NamedEdgeMap.Weight[n]
		cum += w
		if pgo.WeightInPercentage(cum, p.TotalWeight) > inlineCDFHotCallSiteThresholdPercent {
			// nodes[:i+1] to include the very last node that makes it to go over the threshold.
			// (Say, if the CDF threshold is 50% and one hot node takes 60% of weight, we want to
			// include that node instead of excluding it.)
			return pgo.WeightInPercentage(w, p.TotalWeight), p.NamedEdgeMap.ByWeight[:i+1]
		}
	}
	return 0, p.NamedEdgeMap.ByWeight
}

Then the budget function, which is where 80 becomes 2000:

 go
 
 
// src/cmd/compile/internal/inline/inl.go:201
// inlineBudget determines the max budget for function 'fn' prior to
// analyzing the hairiness of the body of 'fn'. We pass in the pgo
// profile if available (which can change the budget), also a
// 'relaxed' flag, which expands the budget slightly to allow for the
// possibility that a call to the function might have its score
// adjusted downwards. If 'verbose' is set, then print a remark where
// we boost the budget due to PGO.
// Note that inlineCostOK has the final say on whether an inline will
// happen; changes here merely make inlines possible.
func inlineBudget(fn *ir.Func, profile *pgoir.Profile, relaxed bool, verbose bool) int32 {
	// Update the budget for profile-guided inlining.
	budget := int32(inlineMaxBudget)

	budget *= simdCreditMultiplier(fn)

	if strings.HasPrefix(ir.FuncName(fn), "runtime_mapaccess2") &&
		fn.Sym().Pkg.Path == "internal/runtime/maps" {
		// Increase budget for mapaccess2* functions so they could be
		// inlined to mapaccess1* wrappers
		budget = inlineHotMaxBudget
		if verbose {
			fmt.Printf("mapaccess enabled increased budget=%v for func=%v\n", budget, ir.PkgFuncName(fn))
		}
	}

	if IsPgoHotFunc(fn, profile) {
		budget = inlineHotMaxBudget
		if verbose {
			fmt.Printf("hot-node enabled increased budget=%v for func=%v\n", budget, ir.PkgFuncName(fn))
		}
	}
	if relaxed {
		budget += inlheur.BudgetExpansion(inlineMaxBudget)
	}
	if fn.ClosureParent != nil {
		// be very liberal here, if the closure is only called once, the budget is large
		budget = max(budget, inlineClosureCalledOnceCost)
	}

	return budget
}

Three multipliers on top of 80:

SIMD: 3x if the function takes or returns a SIMD vector type, 16x if it captures one. SIMD code is long and the payoff for inlining is large.
Hot: 2000 if the function is a hot callee in the profile.
Closure called once: 800 (10 × 80) if this is a closure.

And crucially, this budget is only about whether a function is eligible. The final decision is per-call-site, and it is stricter:

 go
 
 
// src/cmd/compile/internal/inline/inl.go:978
// inlineCostOK returns true if call n from caller to callee is cheap enough to
// inline. bigCaller indicates that caller is a big function.
//
// In addition to the "cost OK" boolean, it also returns
// - the "max cost" limit used to make the decision (which may differ depending on func size)
// - the score assigned to this specific callsite
// - whether the inlined function is "hot" according to PGO.
func inlineCostOK(n *ir.CallExpr, caller, callee *ir.Func, bigCaller, closureCalledOnce bool) (bool, int32, int32, bool) {
	maxCost := int32(inlineMaxBudget)

and then the hot path:

 go
 
 
// src/cmd/compile/internal/inline/inl.go:1023
	if metric <= maxCost {
		// Simple case. Function is already cheap enough.
		return true, 0, metric, hot
	}

	// We'll also allow inlining of hot functions below inlineHotMaxBudget,
	// but only in small functions.

	if !hot {
		// Cold
		return false, maxCost, metric, false
	}

	// Hot

	if bigCaller {
		if base.Debug.PGODebug > 0 {
			fmt.Printf("hot-big check disallows inlining for call %s (cost %d) at %v in big function %s\n", ir.PkgFuncName(callee), callee.Inl.Cost, ir.Line(n), ir.PkgFuncName(caller))
		}
		return false, maxCost, metric, false
	}

	if metric > inlineHotMaxBudget {
		return false, inlineHotMaxBudget, metric, false
	}

So a hot call site in a small function can be inlined at up to cost 2000. A hot call site in a big function cannot, no matter how hot.

The new inliner: score adjustments

The GOEXPERIMENT=newinliner build changes the cost model from “count nodes” to “count nodes, then adjust the score based on the call site’s context”. It lives in src/cmd/compile/internal/inline/inlheur/.

The idea: the same function should be inlined at one call site and not another. A call in a loop benefits from inlining (the call overhead is paid every iteration). A call on a panic path does not (you are about to die anyway). A call whose argument is a constant benefits (the compiler can then fold a branch). A call passing a concrete type to an interface parameter benefits (the interface call can be devirtualised).

The adjustment table is a list of named bits:

 go
 
 
// src/cmd/compile/internal/inline/inlheur/scoring.go:46
const (
	// Category 1 adjustments (see above)
	panicPathAdj scoreAdjustTyp = (1 << iota)
	initFuncAdj
	inLoopAdj

	// Category 2 adjustments (see above).
	passConstToIfAdj
	passConstToNestedIfAdj
	passConcreteToItfCallAdj
	passConcreteToNestedItfCallAdj
	passFuncToIndCallAdj
	passFuncToNestedIndCallAdj
	passInlinableFuncToIndCallAdj
	passInlinableFuncToNestedIndCallAdj

	// Category 3 adjustments.
	returnFeedsConstToIfAdj
	returnFeedsFuncToIndCallAdj
	returnFeedsInlinableFuncToIndCallAdj
	returnFeedsConcreteToInterfaceCallAdj

	sentinelScoreAdj // sentinel; not a real adjustment
)

and the values, with the compiler’s own admission about them:

 go
 
 
// src/cmd/compile/internal/inline/inlheur/scoring.go:71
// This table records the specific values we use to adjust call
// site scores in a given scenario.
// NOTE: these numbers are chosen very arbitrarily; ideally
// we will go through some sort of turning process to decide
// what value for each one produces the best performance.

var adjValues = map[scoreAdjustTyp]int{
	panicPathAdj: 40,
	initFuncAdj: 20,
	inLoopAdj: -5,
	passConstToIfAdj: -20,
	passConstToNestedIfAdj: -15,
	passConcreteToItfCallAdj: -30,
	passConcreteToNestedItfCallAdj: -25,
	passFuncToIndCallAdj: -25,
	passFuncToNestedIndCallAdj: -20,
	passInlinableFuncToIndCallAdj: -45,
	passInlinableFuncToNestedIndCallAdj: -40,
	returnFeedsConstToIfAdj: -15,
	returnFeedsFuncToIndCallAdj: -25,
	returnFeedsInlinableFuncToIndCallAdj: -40,
	returnFeedsConcreteToInterfaceCallAdj: -25,
}

Negative numbers mean “promote” (inline it anyway), positive means “demote”. A call in a loop gets -5. A call on a panic path gets +40, which effectively disqualifies it.

The scoring itself starts from the raw cost and applies the adjustments:

 go
 
 
// src/cmd/compile/internal/inline/inlheur/scoring.go:193
func (cs *CallSite) computeCallSiteScore(csa *callSiteAnalyzer, calleeProps *FuncProps) {
	callee := cs.Callee
	csflags := cs.Flags
	call := cs.Call

	// Start with the size-based score for the callee.
	score := int(callee.Inl.Cost)
	var tmask scoreAdjustTyp

There is a subtlety with the budget: the new inliner does not know at CanInline time whether a score will later be adjusted downwards, so it starts with a relaxed budget:

 go
 
 
// src/cmd/compile/internal/inline/inlheur/scoring.go:582
// BudgetExpansion returns the amount to relax/expand the base
// inlining budget when the new inliner is turned on; the inliner
// will add the returned value to the hairiness budget.
//
// Background: with the new inliner, the score for a given callsite
// can be adjusted down by some amount due to heuristics, however we
// won't know whether this is going to happen until much later after
// the CanInline call. This function returns the amount to relax the
// budget initially (to allow for a large score adjustment); later on
// in RevisitInlinability we'll look at each individual function to
// demote it if needed.
func BudgetExpansion(maxBudget int32) int32 {
	if base.Debug.InlBudgetSlack != 0 {
		return int32(base.Debug.InlBudgetSlack)
	}
	// In the default case, return maxBudget, which will effectively
	// double the budget from 80 to 160; this should be good enough
	// for most cases.
	return maxBudget
}

80 becomes 160 under the new inliner, so that a function whose score will be knocked down by -45 still fits.

The experiment flag itself is:

 go
 
 
// src/internal/goexperiment/flags.go:99
	// NewInliner enables a new+improved version of the function
	// inlining phase within the Go compiler.
	NewInliner bool

and the inlheur package is enabled exactly when that experiment is on (or when the debug dumping flags are set):

 go
 
 
// src/cmd/compile/internal/inline/inlheur/analyze.go:217
func Enabled() bool {
	return buildcfg.Experiment.NewInliner || UnitTesting()
}

You can see the whole scoring model in action with a debug dump:

 go
 
 
// src/cmd/compile/internal/inline/inlheur/scoring.go:605
// DumpInlCallSiteScores is invoked by the inliner if the debug flag
// "-d=dumpinlcallsitescores" is set; it dumps out a human-readable
// summary of all (potentially) inlinable callsites in the package,
// along with info on call site scoring and the adjustments made to a
// given score. Here profile is the PGO profile in use (may be
// nil), budgetCallback is a callback that can be invoked to find out
// the original pre-adjustment hairiness limit for the function, and
// inlineHotMaxBudget is the constant of the same name used in the
// inliner. Sample output lines:
//
// Score Adjustment Status Callee CallerPos ScoreFlags
// 115 40 DEMOTED cmd/compile/internal/abi.(*ABIParamAssignment).Offset expand_calls.go:1679:14|6 panicPathAdj
// 76 -5n PROMOTED runtime.persistentalloc mcheckmark.go:48:45|3 inLoopAdj
// 201 0 --- PGO unicode.DecodeRuneInString utf8.go:312:30|1
// 7 -5 --- PGO internal/abi.Name.DataChecked type.go:625:22|0 inLoopAdj

“PROMOTED” and “DEMOTED” are the two outcomes. A promoted site was above the budget on raw cost but the adjustment brought it under.

The source-level inliner: `//go:fix inline`

There is a second, completely separate inliner in the Go tree, and it is not part of cmd/compile at all. It lives in the vendored x/tools and is driven by the go fix tool.

The directive is //go:fix inline, and it marks a function as a candidate for source-level inlining — the compiler rewrites your source, not your machine code:

 go
 
 
// src/go/types/signature.go:57
//go:fix inline
func NewSignature(recv *Var, params, results *Tuple, variadic bool) *Signature {
	return NewSignatureType(recv, nil, nil, params, results, variadic)
}

The machinery that finds these directives is gofixdirective:

 go
 
 
// src/cmd/vendor/golang.org/x/tools/go/analysis/passes/internal/gofixdirective/gofixdirective.go:1
// Package gofixdirective searches for and validates go:fix directives. The
// go/analysis/passes/inline package uses findgofix to perform inlining.
// The go/analysis/passes/gofix package uses findgofix to check for problems
// with go:fix directives.
//
// gofixdirective is separate from gofix to avoid depending on refactor/inline,
// which is large.
package gofixdirective

And the analyzer that performs the inlining:

 go
 
 
// src/cmd/vendor/golang.org/x/tools/go/analysis/passes/inline/inline.go:36
var Analyzer = &analysis.Analyzer{
	Name: "inline",
	Doc: analyzerutil.MustExtractDoc(doc, "inline"),
	URL: "https://pkg.go.dev/golang.org/x/tools/go/analysis/passes/inline",
	Run: run,
	FactTypes: []analysis.Fact{
		(*goFixInlineFuncFact)(nil),
		(*goFixInlineConstFact)(nil),
		(*goFixInlineAliasFact)(nil),
	},
	Requires: []*analysis.Analyzer{
		inspect.Analyzer,
		typeindexanalyzer.Analyzer,
	},
}

This is a genuinely different design. cmd/compile’s inliner is a cost-budget decision made per call site during compilation, invisible in the source. The go fix inliner is a source transformation that bakes the inlined body into your file permanently, so it can inline across package boundaries and across type-parameter instantiations — things the compiler’s inliner cannot do.

The modernize analyzer adds these directives automatically when it finds a wrapper function that could be inlined:

 go
 
 
// src/cmd/vendor/golang.org/x/tools/go/analysis/passes/modernize/newexpr.go:91
								// Add a //go:fix inline annotation, if not already present.
								//
								// The inliner will not inline a newer callee body into an
								// older Go file; see https://go.dev/issue/75726.
								if !slices.ContainsFunc(astutil.Directives(decl.Doc), func(d ast.Directive) bool {
									return d.Tool == "go" && d.Name == "fix" && d.Args == "inline"
								}) {
									edits = append(edits, analysis.TextEdit{
										Pos: decl.Pos(),
										End: decl.Pos(),
										NewText: []byte("//go:fix inline\n"),
									})
								}

Note the constraint in that comment: the inliner will not inline a newer callee body into an older Go file. The source-level inliner respects the language version of the file it is rewriting.

Reading the diagnostics

go build -gcflags=-m prints the decisions:

 text
 
 
./main.go:10:6: can inline f with cost 34 as: func(i int) int { ... }
./main.go:20:6: cannot inline g: function too complex: cost 102 exceeds budget 80
./main.go:30:6: inlining call to f

The cost number is the number you are trying to reduce. A few practical notes:

The cost is per function, not per call site (except under PGO and the new inliner).
A cost just over 80 (say 85) usually means one non-inlinable call (57) plus a bit of body. Refactoring that call out usually fixes it.
Cost under 80 does not guarantee inlining. The call site must also pass the recursion check and the other canInlineCallExpr conditions.
-m=2 gives more detail, including the “cannot inline” reason.

Trade-offs

What inlining buys you: the ability to constant-fold, to propagate constants into the callee, to eliminate dead code, to devirtualise an interface call that becomes concrete after inlining the callee, and to avoid the call overhead entirely.

What it costs you: code size, and compile time. Inlining a 60-node function into 20 call sites produces 20 copies of that code. The budget exists to bound exactly this.

Why the budget is a count of IR nodes and not a count of instructions: IR nodes are what the front end produced, which is a stable quantity the compiler can compute without running the backend. It is a proxy, and the refund cases (OAS2, OADDR at offset 0) exist because the proxy drifts from reality.

Why hotness helps so much: the cost of inlining is paid at compile time and in binary size, but the benefit is paid at runtime, only on the paths that actually execute. A profile tells you which call sites are on the hot path, so you can spend code size where it pays.

Why PGO inlining is restricted to small callers: the point of PGO inlining is to remove overhead from a hot loop. A 5000-node function is not a hot loop; it is a big chunk of code where an extra copy of a callee is pure bloat.

Caveats

The budget is not a guarantee. A function with cost 40 might still not be inlined if the call site is inside a recursive cycle, or if the callee is a closure whose captured variables come from another closure frame.

//go:noinline is a blunt instrument. It blocks inlining of that function entirely, everywhere, including in the runtime and in the standard library’s hot paths. Use it when the function is genuinely large or when inlining it would change semantics (for example, a function that must keep its own stack frame for runtime.Callers).

The m output is not stable. The Go project explicitly says that -m beyond a single -m “may go away at any point”. Do not write tests that depend on the exact wording of the “cannot inline” message. The project does, however, maintain a list of functions that are intended to be inlinable, and TestIntendedInlining in src/cmd/compile/internal/test/inl_test.go checks that list by parsing the -m output.

The 128 KiB MaxStackVarSize and the inliner’s budget are unrelated. Inlining a function that allocates a big local makes the caller’s frame bigger, and there is a separate limit on frame size. The inliner does not check it; the backend does.

The new inliner’s numbers are explicitly arbitrary. The comment in adjValues says so. They are benchmark-derived but not principled, and they will change.

PGO inlining only applies to the top 99% of edge weight. If your profile is noisy, or your program has many equally-hot call sites, the hot set can be large and the code-size benefit shrinks.

Wrapping up

The one thing to remember: the inliner charges one unit per IR node against a budget of 80, and a call to a function it cannot inline costs 57 of those units. If your function is “too complex”, the culprit is almost always one non-inlinable call.

The part people get wrong: inlining is decided per function in the default build, so making a function cheaper to inline helps every call site, but it also means a function that is hot at one call site and cold at fifty others is judged entirely on its own cost. That is what PGO and the new inliner’s score adjustments exist to fix.

What to go do about it: run go build -gcflags=-m and look at the cost of the functions you expected to be inlined. If a cost is just over 80, find the call inside it that is not itself inlinable and break that dependency. If the function is genuinely hot, build with -pgo=./default.pgo and let the profile lift the ceiling from 80 to 2000.

Go Removes Interface Calls With PGO: Devirtualization and Inlining Hot Call Sites

Jay Hubbert — Wed, 21 Oct 2026 04:16:00 +0000

TL;DR: An interface method call is an indirect call through a function pointer, and the CPU cannot predict it. PGO gives the compiler a profile showing that at one call site, 95% of the time the receiver is a *bytes.Buffer. The compiler rewrites that call into “assert to *bytes.Buffer, call it directly if that works, otherwise fall back to the interface call” — and now the direct call is a candidate for inlining too.

Every Go interface call is a small performance cliff. The compiler has known the concrete type at compile time in some cases, but in the general case it does not: w.Write(p) might be a *bytes.Buffer, a *bufio.Writer, an *os.File, or one of a hundred types in a plugin system. The call goes through an itab, and the branch predictor throws up its hands.

Profile-guided optimization gives the compiler the answer empirically. And the transformation it performs is surprisingly small.

This is a walk through how it works, based on reading the Go 1.28 development tree (src/cmd/compile/internal/devirtualize/, src/cmd/compile/internal/pgoir/, src/cmd/internal/pgo/).

What a PGO profile actually is

First, the input. A PGO profile is not a special format — it is an ordinary pprof CPU profile, the same one go tool pprof reads. The compiler parses it with the standard internal/profile package:

 go
 
 
// src/cmd/internal/pgo/pprof.go:18
// FromPProf parses Profile from a pprof profile.
func FromPProf(r io.Reader) (*Profile, error) {
	p, err := profile.Parse(r)
	if errors.Is(err, profile.ErrNoData) {
		// Treat a completely empty file the same as a profile with no
		// samples: nothing to do.
		return emptyProfile(), nil
	} else if err != nil {
		return nil, fmt.Errorf("error parsing profile: %w", err)
	}

	if len(p.Sample) == 0 {
		// We accept empty profiles, but there is nothing to do.
		return emptyProfile(), nil
	}

	valueIndex, err := sampleValueIndex(p)
	if err != nil {
		return nil, err
	}

	g := profile.NewGraph(p, &profile.Options{
		SampleValue: func(v []int64) int64 { return v[valueIndex] },
	})

One wrinkle: the compiler is picky about the sample type, because a heap profile or a mutex profile passed by mistake would produce nonsense optimizations:

 go
 
 
// src/cmd/internal/pgo/pprof.go:64
// sampleValueIndex returns the index of the sample value to use as the PGO
// weight. Non-Go CPU profiles (e.g., from Linux perf) use arbitrary sample
// types, so we accept the default sample type unless it indicates a Go
// non-CPU profile (heap, mutex, block, or goroutine) passed by mistake.
func sampleValueIndex(p *profile.Profile) (int, error) {
	if len(p.SampleType) == 0 {
		return 0, fmt.Errorf("profile has no sample types")
	}

and then it rejects the wrong kinds outright:

 go
 
 
// src/cmd/internal/pgo/pprof.go:93
	switch t := p.SampleType[index].Type; t {
	case "alloc_objects", "alloc_space", "inuse_objects", "inuse_space":
		return 0, fmt.Errorf("profile must be a CPU profile (default sample type %q indicates that this is a Go heap profile)", t)
	case "contentions", "delay":
		return 0, fmt.Errorf("profile must be a CPU profile (default sample type %q indicates that this is a Go mutex or block profile)", t)
	case "goroutine":
		return 0, fmt.Errorf("profile must be a CPU profile (default sample type %q indicates that this is a Go goroutine profile)", t)
	}
	return index, nil
}

So: CPU profile or nothing.

From samples to call edges

A pprof profile is a set of stacks with counts. The compiler turns those into a weighted call graph, and the weight of an edge is the number of samples that passed through it.

The key structure is the edge map:

 go
 
 
// src/cmd/internal/pgo/pgo.go:22
// NamedCallEdge identifies a call edge by linker symbol names and call site
// offset.
type NamedCallEdge struct {
	CallerName string
	CalleeName string
	CallSiteOffset int // Line offset from function start line.
}

// NamedEdgeMap contains all unique call edges in the profile and their
// edge weight.
type NamedEdgeMap struct {
	Weight map[NamedCallEdge]int64

	// ByWeight lists all keys in Weight, sorted by edge weight from
	// highest to lowest.
	ByWeight []NamedCallEdge
}

The CallSiteOffset is the interesting field. A profile records where in a function a sample was, as a line number. To match that against the compiler’s IR, the profile’s absolute line number is converted to an offset from the function’s start line:

 go
 
 
// src/cmd/internal/pgo/pprof.go:108
func createNamedEdgeMap(g *profile.Graph) (edgeMap NamedEdgeMap, totalWeight int64, err error) {
	seenStartLine := false

	// Process graph and build various node and edge maps which will
	// be consumed by AST walk.
	weight := make(map[NamedCallEdge]int64)
	for _, n := range g.Nodes {
		seenStartLine = seenStartLine || n.Info.StartLine != 0

		canonicalName := n.Info.Name
		// Create the key to the nodeMapKey.
		namedEdge := NamedCallEdge{
			CallerName: canonicalName,
			CallSiteOffset: n.Info.Lineno - n.Info.StartLine,
		}

		for _, e := range n.Out {
			totalWeight += e.WeightValue()
			namedEdge.CalleeName = e.Dest.Info.Name
			// Create new entry or increment existing entry.
			weight[namedEdge] += e.WeightValue()
		}
	}

	if !seenStartLine {
		// TODO(prattmic): If Function.start_line is missing we could
		// fall back to using absolute line numbers, which is better
		// than nothing.
		return NamedEdgeMap{}, 0, fmt.Errorf("profile missing Function.start_line data (Go version of profiled application too old? Go 1.20+ automatically adds this to profiles)")
	}
	return postProcessNamedEdgeMap(weight, totalWeight)
}

So the edges are keyed by a triple, and the result looks like this for a function main.handle that calls (*bytes.Buffer).Write and (*os.File).Write from the same line:

 text
 
 
 (caller, callee, line offset) weight
 ---------------------------------------------------
 (main.handle, (*bytes.Buffer).Write, 12) 900
 (main.handle, (*os.File).Write, 12) 100

That seenStartLine check is a real constraint: profiles from Go 1.20 and later carry Function.start_line; older ones do not, and the compiler refuses to use them rather than guessing.

Note that an edge is identified by (caller, callee, call-site offset). So the same function calling the same callee from two different lines produces two different edges. That is what makes the analysis per-call-site rather than per-function.

From edges to IR

The profile’s edges are in terms of linker symbol names. The compiler needs them in terms of IR, so it builds an IRGraph that maps names to ir.Func nodes:

 go
 
 
// src/cmd/compile/internal/pgoir/irgraph.go:67
type IRGraph struct {
	// Nodes of the graph. Each node represents a function, keyed by linker
	// symbol name.
	IRNodes map[string]*IRNode
}

// IRNode represents a node (function) in the IRGraph.
type IRNode struct {
	// Pointer to the IR of the Function represented by this node.
	AST *ir.Func
	// Linker symbol name of the Function represented by this node.
	// Populated only if AST == nil.
	LinkerSymbolName string

	// Set of out-edges in the callgraph. The map uniquely identifies each
	// edge based on the callsite and callee, for fast lookup.
	OutEdges map[pgo.NamedCallEdge]*IREdge
}

and the edge:

 go
 
 
// src/cmd/compile/internal/pgoir/irgraph.go:94
// IREdge represents a call edge in the IRGraph with source, destination,
// weight, callsite, and line number information.
type IREdge struct {
	// Source and destination of the edge in IRNode.
	Src, Dst *IRNode
	Weight int64
	CallSiteOffset int // Line offset from function start line.
}

The AST == nil case is important: it means “this callee is not visible from the package being compiled”. The callee might be in a transitive dependency, in which case the compiler can look it up in export data, or it might be genuinely unavailable (in a plugin, or in a package built without the right metadata).

Direct calls are discovered by walking the IR:

 go
 
 
// src/cmd/compile/internal/pgoir/irgraph.go:209
func createIRGraphEdge(fn *ir.Func, callernode *IRNode, name string, namedEdgeMap pgo.NamedEdgeMap, g *IRGraph) {
	ir.VisitList(fn.Body, func(n ir.Node) {
		switch n.Op() {
		case ir.OCALLFUNC:
			call := n.(*ir.CallExpr)
			// Find the callee function from the call site and add the edge.
			callee := DirectCallee(call.Fun)
			if callee != nil {
				addIREdge(callernode, name, n, callee, namedEdgeMap, g)
			}
		case ir.OCALLMETH:
			call := n.(*ir.CallExpr)
			// Find the callee method from the call site and add the edge.
			callee := ir.MethodExprName(call.Fun).Func
			addIREdge(callernode, name, n, callee, namedEdgeMap, g)
		}
	})
}

But the interesting edges for devirtualization are the indirect ones — the interface calls, which by definition do not appear in the IR as direct calls. Those come from the profile, and are added separately:

 go
 
 
// src/cmd/compile/internal/pgoir/irgraph.go:284
// addIndirectEdges adds indirect call edges found in the profile to the graph,
// to be used for devirtualization.
//
// N.B. despite the name, addIndirectEdges will add any edges discovered via
// the profile. We don't know for sure that they are indirect, but assume they
// are since direct calls would already be added. (e.g., direct calls that have
// been deleted from source since the profile was taken would be added here).
//
// TODO(prattmic): Devirtualization runs before inlining, so we can't devirtualize
// calls inside inlined call bodies. If we did add that, we'd need edges from
// inlined bodies as well.
func addIndirectEdges(g *IRGraph, namedEdgeMap pgo.NamedEdgeMap) {

So the only way the compiler learns “at this call site, the receiver is usually a *bytes.Buffer” is from the profile. There is no static inference at all in the PGO path.

Finding the hot callee

Now the actual analysis. findHotConcreteCallee looks at all the out-edges of the caller that share this call site’s offset, and picks the heaviest:

 go
 
 
// src/cmd/compile/internal/devirtualize/pgo.go:654
// findHotConcreteCallee returns the *ir.Func of the hottest callee of a call,
// if available, and its edge weight. extraFn can perform additional
// applicability checks on each candidate edge. If extraFn returns false,
// candidate will not be considered a valid callee candidate.
func findHotConcreteCallee(p *pgoir.Profile, caller *ir.Func, call *ir.CallExpr, extraFn func(callerName string, callOffset int, candidate *pgoir.IREdge) bool) (*ir.Func, int64) {
	callerName := ir.LinkFuncName(caller)
	callerNode := p.WeightedCG.IRNodes[callerName]
	callOffset := pgoir.NodeLineOffset(call, caller)

	if callerNode == nil {
		return nil, 0
	}

	var hottest *pgoir.IREdge

	// Returns true if e is hotter than hottest.
	//
	// Naively this is just e.Weight > hottest.Weight, but because OutEdges
	// has arbitrary iteration order, we need to apply additional sort
	// criteria when e.Weight == hottest.Weight to ensure we have stable
	// selection.
	hotter := func(e *pgoir.IREdge) bool {
		if hottest == nil {
			return true
		}
		if e.Weight != hottest.Weight {
			return e.Weight > hottest.Weight
		}

and the tie-breaking rules, which exist to make the build reproducible:

 go
 
 
// src/cmd/compile/internal/devirtualize/pgo.go:682:683
		// Now e.Weight == hottest.Weight, we must select on other
		// criteria.

		// If only one edge has IR, prefer that one.
		if (hottest.Dst.AST == nil) != (e.Dst.AST == nil) {
			if e.Dst.AST != nil {
				return true
			}
			return false
		}

		// Arbitrary, but the callee names will always differ. Select
		// the lexicographically first callee.

Then the loop over the candidate edges:

 go
 
 
// src/cmd/compile/internal/devirtualize/pgo.go:699
	for _, e := range callerNode.OutEdges {
		if e.CallSiteOffset != callOffset {
			continue
		}

		if !hotter(e) {
			// TODO(prattmic): consider total caller weight? i.e.,
			// if the hottest callee is only 10% of the weight,
			// maybe don't devirtualize? Similarly, if this is call
			// is globally very cold, there is not much value in
			// devirtualizing.
			if base.Debug.PGODebug >= 2 {
				fmt.Printf("%v: edge %s:%d -> %s (weight %d): too cold (hottest %d)\n", ir.Line(call), callerName, callOffset, e.Dst.Name(), e.Weight, hottest.Weight)
			}
			continue
		}

Note the TODO: there is no threshold on how dominant the hot callee has to be. If the profile says 51% *A and 49% *B, the compiler devirtualizes to *A and adds a type assertion. Whether that is a win depends on how expensive the type assertion is versus the indirect call. The TODO acknowledges this.

The type check that makes it safe

The one thing that must be true is that the hot callee actually implements the interface at that call site. Otherwise you would be rewriting a call to *bytes.Buffer.Write in a place where the receiver might be something else entirely.

 go
 
 
// src/cmd/compile/internal/devirtualize/pgo.go:756
// findHotConcreteInterfaceCallee returns the *ir.Func of the hottest callee of an
// interface call, if available, and its edge weight.
func findHotConcreteInterfaceCallee(p *pgoir.Profile, caller *ir.Func, call *ir.CallExpr) (*ir.Func, int64) {
	inter, method := interfaceCallRecvTypeAndMethod(call)

	return findHotConcreteCallee(p, caller, call, func(callerName string, callOffset int, e *pgoir.IREdge) bool {
		ctyp := methodRecvType(e.Dst.AST)
		if ctyp == nil {
			// Not a method.
			// TODO(prattmic): Support non-interface indirect calls.
			if base.Debug.PGODebug >= 2 {
				fmt.Printf("%v: edge %s:%d -> %s (weight %d): callee not a method\n", ir.Line(call), callerName, callOffset, e.Dst.Name(), e.Weight)
			}
			return false
		}

		// If ctyp doesn't implement inter it is most likely from a
		// different call on the same line
		if !typecheck.Implements(ctyp, inter) {

and the method name check, which handles the case of two different calls on the same line:

 go
 
 
// src/cmd/compile/internal/devirtualize/pgo.go:792:791
		// If the method name is different it is most likely from a
		// different call on the same line
		if !strings.HasSuffix(e.Dst.Name(), "."+method.Name) {
			if base.Debug.PGODebug >= 2 {
				fmt.Printf("%v: edge %s:%d -> %s (weight %d): callee is a different method\n", ir.Line(call), callerName, callOffset, e.Dst.Name(), e.Weight)
			}
			return false
		}

		return true
	})

Two filters, both necessary because call sites are identified by line offset, not by column. If you have two interface calls on the same line, the profile cannot tell them apart, so the compiler checks that the hot callee’s method name matches the method being called at this site.

The rewrite

Now the transformation. The compiler does not simply replace the call — it inserts a guarded direct call, falling back to the original interface call if the type assertion fails.

 go
 
 
// src/cmd/compile/internal/devirtualize/pgo.go:489
// rewriteInterfaceCall devirtualizes the given interface call using a direct
// method call to concretetyp.
func rewriteInterfaceCall(call *ir.CallExpr, curfn, callee *ir.Func, concretetyp *types.Type) ir.Node {
	if base.Flag.LowerM != 0 {
		fmt.Printf("%v: PGO devirtualizing interface call %v to %v\n", ir.Line(call), call.Fun, callee)
	}

The comment in the source describes the generated code precisely:

 go
 
 
// src/cmd/compile/internal/devirtualize/pgo.go:496
	// We generate an OINCALL of:
	//
	// var recv Iface
	//
	// var arg1 A1
	// var argN AN
	//
	// var ret1 R1
	// var retN RN
	//
	// recv, arg1, argN = recv expr, arg1 expr, argN expr
	//
	// t, ok := recv.(Concrete)
	// if ok {
	// ret1, retN = t.Method(arg1, ... argN)
	// } else {
	// ret1, retN = recv.Method(arg1, ... argN)
	// }
	//
	// OINCALL retvars: ret1, ... retN
	//
	// This isn't really an inlined call of course, but InlinedCallExpr
	// makes handling reassignment of return values easier.

So the generated code for w.Write(p) where w is usually a *bytes.Buffer is:

 go
 
 
t, ok := w.(*bytes.Buffer)
if ok {
 t.Write(p) // direct call
} else {
 w.Write(p) // original interface call
}

The receiver and arguments are copied to temporaries first, because they are evaluated twice now:

 go
 
 
// src/cmd/compile/internal/devirtualize/pgo.go:409
// copyInputs copies the inputs to a call: the receiver (for interface calls)
// or function value (for function value calls) and the arguments. These
// expressions are evaluated once and assigned to temporaries.
//
// The assignment statement is added to init and the copied receiver/fn
// expression and copied arguments expressions are returned.
func copyInputs(curfn *ir.Func, pos src.XPos, recvOrFn ir.Node, args []ir.Node, init *ir.Nodes) (ir.Node, []ir.Node) {

And the conditional itself is built by condCall, which wraps the two calls in an if and returns an InlinedCallExpr so that the return value plumbing works:

 go
 
 
// src/cmd/compile/internal/devirtualize/pgo.go:451
// condCall returns an ir.InlinedCallExpr that performs a call to thenCall if
// cond is true and elseCall if cond is false. The return variables of the
// InlinedCallExpr evaluate to the return values from the call.
func condCall(curfn *ir.Func, pos src.XPos, cond ir.Node, thenCall, elseCall *ir.CallExpr, init ir.Nodes) *ir.InlinedCallExpr {

Note nif.Likely = true — the compiler marks the direct-call branch as the likely one, so the branch predictor and the block layout both favour it.

The gating conditions

Before any of this happens, maybeDevirtualizeInterfaceCall checks a list of conditions:

 go
 
 
// src/cmd/compile/internal/devirtualize/pgo.go:182
// Devirtualize interface call if possible and eligible. Returns the new
// ir.Node if call was devirtualized, and if so also the callee and weight of
// the devirtualized edge.
func maybeDevirtualizeInterfaceCall(p *pgoir.Profile, fn *ir.Func, call *ir.CallExpr) (ir.Node, *ir.Func, int64) {
	if base.Debug.PGODevirtualize < 1 {
		return nil, nil, 0
	}

	// Bail if we do not have a hot callee.
	callee, weight := findHotConcreteInterfaceCallee(p, fn, call)
	if callee == nil {
		return nil, nil, 0
	}
	// Bail if we do not have a Type node for the hot callee.
	ctyp := methodRecvType(callee)
	if ctyp == nil {
		return nil, nil, 0
	}
	// Bail if we know for sure it won't inline.
	if !shouldPGODevirt(callee) {
		return nil, nil, 0
	}
	// Bail if de-selected by PGO Hash.
	if !base.PGOHash.MatchPosWithInfo(call.Pos(), "devirt", nil) {
		return nil, nil, 0
	}

	return rewriteInterfaceCall(call, fn, callee, ctyp), callee, weight
}

Five gates:

PGODevirtualize debug level at least 1 (it defaults to 2).
There must be a hot callee with a known concrete receiver type.
The callee must be a method (have a receiver).
The callee must be inlinable. This is the key one, and it is explained here:

 go
 
 
// src/cmd/compile/internal/devirtualize/pgo.go:297
// shouldPGODevirt checks if we should perform PGO devirtualization to the
// target function.
//
// PGO devirtualization is most valuable when the callee is inlined, so if it
// won't inline we can skip devirtualizing.
func shouldPGODevirt(fn *ir.Func) bool {

The whole point of devirtualizing is to enable inlining. If the callee will not be inlined, devirtualizing just replaces an indirect call with a type assertion plus a direct call, which is often not a win.

The PGOHash check, which is a debug mechanism for selecting a subset of call sites to devirtualize.

The PGOHash mechanism is worth knowing about, because it lets you experiment with the effect of devirtualization on a subset of call sites without changing any code. -d=PGOHash=... selects call sites by their position hash.

Function value calls too

The same machinery handles calls through a func value, not just interface methods. The transformation is different — it compares function pointers rather than doing a type assertion:

 go
 
 
// src/cmd/compile/internal/devirtualize/pgo.go:557
// rewriteFunctionCall devirtualizes the given OCALLFUNC using a direct
// function call to callee.
func rewriteFunctionCall(call *ir.CallExpr, curfn, callee *ir.Func) ir.Node {
	if base.Flag.LowerM != 0 {
		fmt.Printf("%v: PGO devirtualizing function call %v to %v\n", ir.Line(call), call.Fun, callee)
	}

with the generated shape spelled out:

 go
 
 
// src/cmd/compile/internal/devirtualize/pgo.go:564
	// We generate an OINCALL of:
	//
	// var fn FuncType
	//
	// var arg1 A1
	// var argN AN
	//
	// var ret1 R1
	// var retN RN
	//
	// fn, arg1, argN = fn expr, arg1 expr, argN expr
	//
	// fnPC := internal/abi.FuncPCABIInternal(fn)
	// concretePC := internal/abi.FuncPCABIInternal(concrete)
	//
	// if fnPC == concretePC {
	// ret1, retN = concrete(arg1, ... argN) // Same closure context passed (TODO)
	// } else {
	// ret1, retN = fn(arg1, ... argN)
	// }
	//
	// OINCALL retvars: ret1, ... retN

This path is gated at a higher debug level — PGODevirtualize < 2 — and has more exclusions, because closures need a context register that the compiler does not plumb through:

 go
 
 
// src/cmd/compile/internal/devirtualize/pgo.go:232
	// TODO(go.dev/issue/61577): Closures need the closure context passed
	// via the context register. That requires extra plumbing that we
	// haven't done yet.
	if callee.OClosure != nil {
		if base.Debug.PGODebug >= 3 {
			fmt.Printf("callee %s is a closure, skipping\n", ir.FuncName(callee))
		}
		return nil, nil, 0
	}

Static devirtualization: the other half

PGO devirtualization is the exciting one, but the compiler also does static devirtualization, with no profile at all. StaticCall replaces an interface call with a direct call when the concrete type is provable from the source:

 go
 
 
// src/cmd/compile/internal/devirtualize/devirtualize.go:5
// Package devirtualize implements two "devirtualization" optimization passes:
//
// - "Static" devirtualization which replaces interface method calls with
// direct concrete-type method calls where possible.
// - "Profile-guided" devirtualization which replaces indirect calls with a
// conditional direct call to the hottest concrete callee from a profile, as
// well as a fallback using the original indirect call.

The static version needs to know the concrete type of the receiver, which means tracking assignments to interface-typed variables. That is what concreteType does:

 go
 
 
// src/cmd/compile/internal/devirtualize/devirtualize.go:181
// concreteType determines the concrete type of n, following OCONVIFACEs and type asserts.
// Returns nil when the concrete type could not be determined, or when there are multiple
// (different) types assigned to an interface.
func concreteType(s *State, n ir.Node) (typ *types.Type) {

and it walks assignments:

 go
 
 
// src/cmd/compile/internal/devirtualize/devirtualize.go:314
		// Methods are only declared on named types, and each named type
		// is represented by a unique [*types.Type], thus pointer comparison
		// is fine here.
		//
		// The only scenario where [types.IdenticalStrict] could help here is with
		// unnamed struct types that embed another type (e.g. foo = struct { Impl }{}).
		// However, such patterns are uncommon and not worth the additional complexity
		// in the devirtualizer.
		if typ != nil && typ != t {
			return nil // assigned with a different type
		}

		typ = t

So if a variable is assigned two different concrete types at different points in the function, the static devirtualizer gives up. It is a whole-function, flow-insensitive-ish analysis.

The static rewrite is simpler than the PGO one — no fallback, because the type is known:

 go
 
 
// src/cmd/compile/internal/devirtualize/devirtualize.go:120
	dt := ir.NewTypeAssertExpr(sel.Pos(), sel.X, typ)

	if go126ImprovedConcreteTypeAnalysis {
		// Consider:
		//
		//	var v Iface
		//	v.A()
		//	v = &Impl{}
		//
		// Here in the devirtualizer, we determine the concrete type of v as being an *Impl,
		// but it can still be a nil interface, we have not detected that. The v.(*Impl)
		// type assertion that we make here would also have failed, but with a different
		// panic "pkg.Iface is nil, not *pkg.Impl", where previously we would get a nil panic.
		// We fix this, by introducing an additional nilcheck on the itab.
		// Calling a method on a nil interface (in most cases) is a bug in a program, so it is fine
		// to devirtualize and further (possibly) inline them, even though we would never reach
		// the called function.
		dt.UseNilPanic = true
		dt.SetPos(call.Pos())
	}

There are also several hard exclusions. Generics are the big one:

 go
 
 
// src/cmd/compile/internal/devirtualize/devirtualize.go:72
	// If typ is a shape type, then it was a type argument originally
	// and we'd need an indirect call through the dictionary anyway.
	// We're unable to devirtualize this call.
	if typ.IsShape() {
		return
	}

and go/defer statements are skipped entirely, because inlining a type assertion into a go statement can move a panic:

 go
 
 
// src/cmd/compile/internal/devirtualize/devirtualize.go:29
	// For promoted methods (including value-receiver methods promoted
	// to pointer-receivers), the interface method wrapper may contain
	// expressions that can panic (e.g., ODEREF, ODOTPTR,
	// ODOTINTER). Devirtualization involves inlining these expressions
	// (and possible panics) to the call site. This normally isn't a
	// problem, but for go/defer statements it can move the panic from
	// when/where the call executes to the go/defer statement itself,
	// which is a visible change in semantics (e.g., #52072). To prevent
	// this, we skip devirtualizing calls within go/defer statements
	// altogether.
	if call.GoDefer {
		return
	}

Interleaving with inlining

The two optimisations are not independent. Devirtualizing an interface call creates a direct call, and a direct call can be inlined. So the compiler runs them together, in an interleaved pass:

 go
 
 
// src/cmd/compile/internal/inline/interleaved/interleaved.go:20
// DevirtualizeAndInlinePackage interleaves devirtualization and inlining on
// all functions within pkg.
func DevirtualizeAndInlinePackage(pkg *ir.Package, profile *pgoir.Profile) {

and inside, the PGO devirtualization runs as a separate sweep first:

 go
 
 
// src/cmd/compile/internal/inline/interleaved/interleaved.go:30
	if profile != nil && base.Debug.PGODevirtualize > 0 {
		// TODO(mdempsky): Integrate into DevirtualizeAndInlineFunc below.
		ir.VisitFuncsBottomUp(typecheck.Target.Funcs, func(list []*ir.Func, recursive bool) {
			for _, fn := range list {
				devirtualize.ProfileGuided(fn, profile)
			}
		})
	}

and then the static devirtualization happens interleaved with the inlining, at each call site:

 go
 
 
// src/cmd/compile/internal/inline/interleaved/interleaved.go:195
// resolve attempts to resolve a call to a potentially inlineable callee
// and updates use counts on the callees. Returns the call site count
// for that callee.
func (s *inlClosureState) resolve(state *devirtualize.State, i int) (*ir.Func, int) {
	p := s.parens[i]
	if i < len(s.resolved) {
		if callee := s.resolved[i]; callee != nil {
			return callee, s.useCounts[callee]
		}
	}
	n := p.X
	call, ok := n.(*ir.CallExpr)
	if !ok { // previously inlined
		return nil, -1
	}
	devirtualize.StaticCall(s.fn, state, call)

Devirtualize first, then resolve the (now direct) call for inlining. The loop then iterates to a fixed point, because inlining a callee can expose new interface calls that are themselves devirtualizable.

The measured gains

The Go release notes are specific about this. Go 1.21, where PGO graduated from preview:

Profile-guide optimization (PGO), added as a preview in Go 1.20, is now ready for general use. … Performance improvements vary depending on application behavior, with most programs from a representative set of Go programs seeing between 2 and 7% improvement from enabling PGO.

PGO builds can now devirtualize some interface method calls, adding a concrete call to the most common callee. This enables further optimization, such as inlining the callee.

Go 1.22 improved it further:

Profile-guided Optimization (PGO) builds can now devirtualize a higher proportion of calls than previously possible. Most programs from a representative set of Go programs now see between 2 and 14% improvement at runtime from enabling PGO.

The compiler now interleaves devirtualization and inlining, so interface method calls are better optimized.

So: 2 to 7% in Go 1.21, 2 to 14% in Go 1.22, from PGO as a whole, of which devirtualization is one part. The devirtualization-specific number is not broken out separately in the release notes, which is worth knowing before you attribute a speedup to it.

The mechanism for the interleaving was experimental in Go 1.22:

Go 1.22 also includes a preview of an enhanced implementation of the compiler’s inlining phase that uses heuristics to boost inlinability at call sites deemed “important” (for example, in loops) and discourage inlining at call sites deemed “unimportant” (for example, on panic paths). Building with GOEXPERIMENT=newinliner enables the new call-site heuristics.

Using it

The mechanics are simple:

 bash
 
 
# Collect a CPU profile from a representative run.
go test -cpuprofile=cpu.out ./...
# or
go build -o myapp && ./myapp -cpuprofile=cpu.out

# Build with the profile.
go build -pgo=cpu.out

Since Go 1.21, if a file named default.pgo is present in the main package’s directory, the go command uses it automatically. That is the easiest way to set this up: drop default.pgo next to main.go.

To see what happened:

 bash
 
go build -gcflags='-m=2' 2>&1 | grep -i devirt

The messages come from the two places in the source:

text

PGO devirtualizing interface call w.Write to (*bytes.Buffer).Write

and, for the static path:

text

devirtualizing w.Write to (*bytes.Buffer).Write

The -d=PGOHash=... debug flag lets you select a subset of call sites, which is how the Go team A/B-tested the transformation. The PGOHash.MatchPosWithInfo call in maybeDevirtualizeInterfaceCall is the hook.

Trade-offs

What devirtualization buys you: the interface call becomes a direct call, which means (a) the branch predictor can learn it, (b) the callee becomes eligible for inlining, and (c) the call can be devirtualised further by the optimiser.

What it costs you: a type assertion and a branch on every execution of that call site, plus code size. If the hot callee is not actually dominant at runtime — say the profile is stale, or the workload shifted between profiling and building — the assertion always fails and you have paid for nothing.

Why the “must be inlinable” gate matters: devirtualizing a call to a function that will not be inlined replaces an indirect call with an assertion plus a direct call. The direct call is cheaper (no itab load, predictable target), but you have added a branch. Without inlining to pay for it, the win is marginal and sometimes negative. The compiler takes the conservative route.

Why the type check is on the concrete type and not the itab: a full type assertion checks the itab pointer, which is exactly what the interface call would have done. The compiler’s version is a plain type assertion to the concrete type, which is a comparison against a known itab.

Why the PGO path is guarded but the static path is not: the static path has type information, so it is always correct; the PGO path is correct only because the fallback preserves semantics. The PGO path’s worst case is a slower program, never a wrong one.

Caveats

A profile is a snapshot of one workload. If you profile a test suite and deploy to production, the hot call sites may be entirely different. PGO devirtualization is only as good as the profile.

There is no dominance threshold. The compiler devirtualizes to the hottest callee even if it is only 40% of the weight. The TODO in findHotConcreteCallee acknowledges this.

The profile must be a CPU profile. Heap, mutex, block and goroutine profiles are rejected with an error, not silently ignored.

Older profiles do not work. Profiles without Function.start_line — from Go 1.19 and earlier — are rejected, because the call-site offsets cannot be computed.

Call sites are identified by line offset, not column. Two calls on the same line are indistinguishable. The compiler mitigates this by checking the method name matches, but it is a real limitation.

Generic code is mostly excluded. Shape types cannot be devirtualized at all, and shaped interfaces are excluded too, because the itab pointer identity differs between the shaped and unshaped interface.

go and defer statements are never devirtualized, in either the static or the PGO path.

The static devirtualizer requires the concrete type to be consistent across the whole function. Assign two different concrete types to the same interface variable and it gives up on that variable entirely, even if each assignment is in a separate branch.

Devirtualization happens before inlining, so calls inside inlined bodies are not devirtualized. The TODO in addIndirectEdges says so explicitly.

Method values and method expressions are not devirtualized in the PGO path, for reasons spelled out in a long comment in maybeDevirtualizeFunctionCall about how types.Identical treats receivers.

Wrapping up

The one thing to remember: PGO devirtualization is a guarded rewrite, not a replacement. The compiler keeps the interface call as a fallback and only takes the direct path when the type assertion succeeds, so semantics never change — only speed.

The part people get wrong: the win is not from removing the indirect call. It is from enabling inlining of the concrete callee. A devirtualized call to a function that will not be inlined is barely faster than the interface call it replaced, which is why the compiler refuses to devirtualize in that case.

What to go do about it: profile a representative run, build with -pgo=cpu.out, and look for PGO devirtualizing lines in -gcflags=-m=2 output. If you see none, either your hot call sites are not polymorphic, or the callees are too big to inline — and the second case is the one worth acting on.

Pgo on Opensource internals

Go's Inliner: A Budget of 80 Nodes and the Art of the Cheat Sheet

Two passes, not one

The budget

Counting the nodes

What disqualifies a function outright

Big functions get a smaller budget

PGO: the budget goes to 2000

The new inliner: score adjustments

The source-level inliner: `//go:fix inline`

Reading the diagnostics

Trade-offs

Caveats

Wrapping up

Further reading

Go Removes Interface Calls With PGO: Devirtualization and Inlining Hot Call Sites

What a PGO profile actually is

From samples to call edges

From edges to IR

Finding the hot callee

The type check that makes it safe

The rewrite

The gating conditions

Function value calls too

Static devirtualization: the other half

Interleaving with inlining

The measured gains

Using it

Trade-offs

Caveats

Wrapping up

Further reading

Pgo on Opensource internals

Go's Inliner: A Budget of 80 Nodes and the Art of the Cheat Sheet

Two passes, not one

The budget

Counting the nodes

What disqualifies a function outright

Big functions get a smaller budget

PGO: the budget goes to 2000

The new inliner: score adjustments

The source-level inliner: //go:fix inline

Reading the diagnostics

Trade-offs

Caveats

Wrapping up

Further reading

Go Removes Interface Calls With PGO: Devirtualization and Inlining Hot Call Sites

What a PGO profile actually is

From samples to call edges

From edges to IR

Finding the hot callee

The type check that makes it safe

The rewrite

The gating conditions

Function value calls too

Static devirtualization: the other half

Interleaving with inlining

The measured gains

Using it

Trade-offs

Caveats

Wrapping up

Further reading

The source-level inliner: `//go:fix inline`