Interfaces on Opensource internals

Go's Interfaces Are Two Words and a Cached itab

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

TL;DR: A non-empty interface value is two words: a pointer to an itab and a pointer to the data. The empty interface swaps the itab for a plain type descriptor. The itab itself is a small table of method pointers, and for a concrete type the compiler emits it as a static symbol, so the conversion costs nothing at run time. When the type is not known statically – an interface-to-interface conversion, a type switch on a value of unknown type – the runtime builds the itab and caches it in a global hash table.

Go’s interfaces are famous for being two words. That part is easy. The part that catches people out is where the first word points, and what happens when the compiler cannot know the concrete type.

This is a walk through the layout and the lookup paths, based on reading the Go 1.28 development tree: src/runtime/iface.go, src/internal/abi/iface.go, and the compiler’s walk/convert.go and reflectdata/reflect.go.

The two layouts

The runtime keeps two interface representations. The first word of an empty interface is a type descriptor; the first word of a non-empty interface is an itab:

 go
 
 
// src/runtime/runtime2.go:184
type iface struct {
	tab *itab
	data unsafe.Pointer
}

type eface struct {
	_type *_type
	data unsafe.Pointer
}

The internal/abi package gives the same thing a name and documents the difference:

 go
 
 
// src/internal/abi/iface.go:12
// The first word of every non-empty interface type contains an *ITab.
// It records the underlying concrete type (Type), the interface type it
// is implementing (Inter), and some ancillary information.
//
// allocated in non-garbage-collected memory
type ITab struct {
	Inter *InterfaceType
	Type *Type
	Hash uint32 // copy of Type.Hash. Used for type switches.
	Fun [1]uintptr // variable sized. fun[0]==0 means Type does not implement Inter.
}

and:

 go
 
 
// src/internal/abi/iface.go:33
// EmptyInterface describes the layout of a "interface{}" or a "any."
// These are represented differently than non-empty interface, as the first
// word always points to an abi.Type.
type EmptyInterface struct {
	Type *Type
	Data unsafe.Pointer
}

// NonEmptyInterface describes the layout of an interface that contains any methods.
type NonEmptyInterface struct {
	ITab *ITab
	Data unsafe.Pointer
}

// CommonInterface describes the layout of both [EmptyInterface] and [NonEmptyInterface].
type CommonInterface struct {
	// Either an *ITab or a *Type, unexported to avoid accidental use.
	_ unsafe.Pointer

	Data unsafe.Pointer
}

CommonInterface is the interesting one: it is the common part of the two layouts, and it is what a generic function or an unsafe cast sees. The first word is deliberately untyped, because at that level you cannot know which of the two you have.

So, in memory:

 text
 
 
 var x error = myError{} // non-empty interface
 +-----------------------+
 | *itab ---------------> { Inter, Type, Hash, Fun[0], Fun[1], ... }
 +-----------------------+
 | data ---------------> the myError value (or a pointer to it)
 +-----------------------+

 var y any = 42 // empty interface
 +-----------------------+
 | *_type ---------------> the runtime type descriptor for int
 +-----------------------+
 | data ---------------> pointer to a copy of 42
 +-----------------------+

The data word: direct or boxed

The data word is a pointer, but not always to a separate object. If the concrete type is pointer-shaped, the value is the pointer and is stored directly. The runtime caches that decision in a flag on the type descriptor:

 go
 
 
// src/internal/abi/type.go:124
	// TFlagDirectIface means that a value of this type is stored directly
	// in the data field of an interface, instead of indirectly.
	// This flag is just a cached computation of Size_ == PtrBytes == goarch.PtrSize.
	TFlagDirectIface TFlag = 1 << 5

So boxing a *T, a map, a channel, or a func into an interface costs nothing: no allocation, no copy. Boxing an int costs an allocation, unless the compiler can find a cheaper home for it.

The compiler’s dataWord function is where all of that is decided, and it is worth reading because the list of special cases is long:

 go
 
 
// src/cmd/compile/internal/walk/convert.go:153
	// Try a bunch of cases to avoid an allocation.
	var value ir.Node
	byteVal, isConst := smallIntConst(n)
	switch {
	case fromType.Size() == 0:
		// n is zero-sized. Use zerobase.
		diagnose("using global for zero-sized interface value", n)
		w.cheapExpr(n, init) // Evaluate n for side-effects. See issue 19246.
		value = ir.NewLinksymExpr(base.Pos, ir.Syms.Zerobase, types.Types[types.TUINTPTR])
	case isBool || isInteger && (fromType.Size() == 1 || isConst):
		// n is a bool, a single-byte integer, or a compile-time constant in [0, 255].
		// Use staticuint64s[n * 8] on little-endian and staticuint64s[n * 8 + 7] on big-endian.
		diagnose("using global for small integer/boolean interface value", n)

The staticuint64s global is a 2 KiB table of pre-boxed small values. An int constant between 0 and 255 is boxed by pointing into that table, with no allocation at all.

If none of the special cases apply, the compiler calls into the runtime to box the value:

 go
 
 
// src/cmd/compile/internal/walk/convert.go:207
	// Time to do an allocation. We'll call into the runtime for that.
	fnname, argType, needsaddr := dataWordFuncName(fromType)
	var fn *ir.Name

and the runtime’s boxing helpers are small and specialised – one per shape of value:

 go
 
 
// src/runtime/iface.go:409
// convT64 should be an internal detail,
// but widely used packages access it using linkname.
// Notable members of the hall of shame include:
// - github.com/bytedance/sonic
//
// Do not remove or change the type signature.
// See go.dev/issue/67401.
//
//go:linkname convT64
func convT64(val uint64) (x unsafe.Pointer) {
	if val < uint64(len(staticuint64s)) {
		x = unsafe.Pointer(&staticuint64s[val])
	} else {
		x = mallocgc(8, uint64Type, false)
		*(*uint64)(x) = val
	}
	return
}

So convT64 has its own small-value cache, convTstring has a zero-value special case, convTslice avoids allocating a nil slice. These are the “conversion” routines that older Go versions called convT2E. In this tree they have been renamed and specialised, but the shape of the idea is the same: the data word is a pointer to a copy, and the runtime tries hard to avoid the copy.

Where the first word comes from

Now the interesting part. The compiler decides, for each conversion, what the first word should be:

 go
 
 
// src/cmd/compile/internal/reflectdata/helpers.go:95
// ConvIfaceTypeWord asserts that n is conversion to interface type,
// and returns an expression that yields the *runtime._type or
// *runtime.itab value necessary for implementing the conversion.
//
// - *runtime._type for the destination type, for I2I conversions
// - *runtime.itab, for T2I conversions
// - *runtime._type for the source type, for T2E conversions
func ConvIfaceTypeWord(curfunc *ir.Func, pos src.XPos, n *ir.ConvExpr) ir.Node {
	assertOp(n, ir.OCONVIFACE)
	src, dst := n.X.Type(), n.Type()
	base.AssertfAt(dst.IsInterface(), n.Pos(), "want interface type, have %L", n)
	if hasRType(n, n.TypeWord, "TypeWord") {
		return n.TypeWord
	}
	if dst.IsEmptyInterface() {
		return concreteRType(curfunc, pos, src) // direct eface construction
	}
	if !src.IsInterface() {
		return ITabAddrAt(curfunc, pos, src, dst) // direct iface construction
	}
	return TypePtrAt(curfunc, pos, dst) // convI2I
}

Three cases:

Concrete type to empty interface. The first word is a static pointer to the concrete type’s descriptor. No run-time work at all.
Concrete type to non-empty interface. The first word is a static pointer to an itab. No run-time work at all – but the itab has to exist in the binary first.
Interface to interface. The first word is the destination interface’s descriptor, and the conversion happens at run time, because the compiler does not know whether the source’s dynamic type implements the destination.

That third case is the one people remember as “every interface conversion costs a runtime call”. It is still true. But the first two cases, which is most of them, do not.

The static itab

The compiler emits the itab for a statically-known pair as an ordinary read-only global, and the runtime never sees it:

 go
 
 
// src/cmd/compile/internal/reflectdata/reflect.go:1077
	// dump empty itab symbol into i.sym
	// type itab struct {
	// inter *interfacetype
	// _type *_type
	// hash uint32 // copy of _type.hash. Used for type switches.
	// _ [4]byte
	// fun [1]uintptr // variable sized. fun[0]==0 means _type does not implement inter.
	// }
	c := rttype.NewCursor(lsym, 0, rttype.ITab)
	c.Field("Inter").WritePtr(writeType(iface))
	c.Field("Type").WritePtr(writeType(typ))
	c.Field("Hash").WriteUint32(types.TypeHash(typ)) // copy of type hash

	var delta int64
	c = c.Field("Fun")
	if !completeItab {
		// If typ doesn't implement iface, make method entries be zero.
		c.Elem(0).WriteUintptr(0)
	} else {
		var a rttype.ArrayCursor
		a, delta = c.ModifyArray(len(entries))
		for i, fn := range entries {
			a.Elem(i).WritePtrWeak(fn) // method pointer for each method
		}
	}
	// Nothing writes static itabs, so they are read only.
	objw.Global(lsym, int32(rttype.ITab.Size()+delta), int16(obj.DUPOK|obj.RODATA))

That comment block is the canonical description of the itab layout, and it matches the ITab struct in internal/abi exactly: Inter, Type, Hash, then a variable-length array of function pointers, one per interface method, in the interface’s sorted method order.

The itab is written into the read-only data section, so it is shared across the whole binary and costs one pointer load at run time.

The dynamic itab: `getitab`

When the compiler does not know the concrete type – an interface-to-interface conversion, or a type switch on a value whose type is not known – the runtime has to find or build the itab. That is getitab:

 go
 
 
// src/runtime/iface.go:44
func getitab(inter *interfacetype, typ *_type, canfail bool) *itab {
	if len(inter.Methods) == 0 {
		throw("internal error - misuse of itab")
	}

	// easy case
	if typ.TFlag&abi.TFlagUncommon == 0 {
		if canfail {
			return nil
		}
		name := toRType(&inter.Type).nameOff(inter.Methods[0].Name)
		panic(&TypeAssertionError{nil, typ, &inter.Type, name.Name()})
	}

	var m *itab

	// First, look in the existing table to see if we can find the itab we need.
	// This is by far the most common case, so do it without locks.
	// Use atomic to ensure we see any previous writes done by the thread
	// that updates the itabTable field (with atomic.Storep in itabAdd).
	t := (*itabTableType)(atomic.Loadp(unsafe.Pointer(&itabTable)))
	if m = t.find(inter, typ); m != nil {
		goto finish
	}

	// Not found. Grab the lock and try again.
	lock(&itabLock)
	if m = itabTable.find(inter, typ); m != nil {
		unlock(&itabLock)
		goto finish
	}

	// Entry doesn't exist yet. Make a new entry & add it.
	m = (*itab)(persistentalloc(unsafe.Sizeof(itab{})+uintptr(len(inter.Methods)-1)*goarch.PtrSize, 0, &memstats.other_sys))
	m.Inter = inter
	m.Type = typ

The structure is the classic “read without a lock, take the lock only to mutate” pattern. The fast path is a lock-free hash-table probe.

The table itself is a single global, swapped out when it grows:

 go
 
 
// src/runtime/iface.go:15
const itabInitSize = 512

var (
	itabLock mutex // lock for accessing itab table
	itabTable = &itabTableInit // pointer to current table
	itabTableInit = itabTableType{size: itabInitSize} // starter table
)

// Note: change the formula in the mallocgc call in itabAdd if you change these fields.
type itabTableType struct {
	size uintptr // length of entries array. Always a power of 2.
	count uintptr // current number of filled entries.
	entries [itabInitSize]*itab // really [size] large
}

The hash is the xor of the two type hashes:

 go
 
 
// src/runtime/iface.go:30
func itabHashFunc(inter *interfacetype, typ *_type) uintptr {
	// compiler has provided some good hash codes for us.
	return uintptr(inter.Type.Hash ^ typ.Hash)
}

and the probe sequence is quadratic:

 go
 
 
// src/runtime/iface.go:105
// find finds the given interface/type pair in t.
// Returns nil if the given interface/type pair isn't present.
func (t *itabTableType) find(inter *interfacetype, typ *_type) *itab {
	// Implemented using quadratic probing.
	// Probe sequence is h(i) = h0 + i*(i+1)/2 mod 2^k.
	// We're guaranteed to hit all table entries using this probe sequence.
	mask := t.size - 1
	h := itabHashFunc(inter, typ) & mask
	for i := uintptr(1); ; i++ {
		p := (**itab)(add(unsafe.Pointer(&t.entries), h*goarch.PtrSize))
		// Use atomic read here so if we see m != nil, we also see
		// the initializations of the fields of m.
		// m := *p
		m := (*itab)(atomic.Loadp(unsafe.Pointer(p)))
		if m == nil {
			return nil
		}
		if m.Inter == inter && m.Type == typ {
			return m
		}
		h += i
		h &= mask
	}
}

Growth happens under the lock, at a 75% load factor, and the whole table is replaced rather than rehashed in place:

 go
 
 
// src/runtime/iface.go:130
// itabAdd adds the given itab to the itab hash table.
// itabLock must be held.
func itabAdd(m *itab) {
	// Bugs can lead to calling this while mallocing is set,
	// typically because this is called while panicking.
	// Crash reliably, rather than only when we need to grow
	// the hash table.
	if getg().m.mallocing != 0 {
		throw("malloc deadlock")
	}

	t := itabTable
	if t.count >= 3*(t.size/4) { // 75% load factor
		// Grow hash table.
		// t2 = new(itabTableType) + some additional entries
		// We lie and tell malloc we want pointer-free memory because
		// all the pointed-to values are not in the heap.
		t2 := (*itabTableType)(mallocgc((2+2*t.size)*goarch.PtrSize, nil, true))
		t2.size = t.size * 2

Note the persistentalloc in getitab: itabs live outside the garbage collected heap, because a program can create them at any time and they must never be collected.

Filling in the itab

Building an itab means matching the interface’s methods against the concrete type’s methods, in name order:

 go
 
 
// src/runtime/iface.go:209
func itabInit(m *itab, firstTime bool) string {
	inter := m.Inter
	typ := m.Type
	x := typ.Uncommon()

	// both inter and typ have method sorted by name,
	// and interface names are unique,
	// so can iterate over both in lock step;
	// the loop is O(ni+nt) not O(ni*nt).
	ni := len(inter.Methods)
	nt := int(x.Mcount)

The O(ni+nt) not O(ni*nt) comment is a nice piece of runtime engineering: both sides are sorted by method name, so a single merge pass suffices.

Type assertions

A type assertion to a concrete type does not call the runtime either. The compiler inlines it as a pointer comparison:

 go
 
 
// src/cmd/compile/internal/ssagen/ssa.go:6585
	// Converting to a concrete type.
	direct := types.IsDirectIface(dst)
	itab := s.newValue1(ssaop.OpITab, byteptr, iface) // type word of interface
	if base.Debug.TypeAssert > 0 {
		base.WarnfAt(pos, "type assertion inlined")
	}
	var wantedFirstWord *ssa.Value
	if src.IsEmptyInterface() {
		// Looking for pointer to target type.
		wantedFirstWord = target
	} else {
		// Looking for pointer to itab for target type and source interface.
		wantedFirstWord = targetItab
	}

For an empty interface, the comparison is against the type descriptor; for a non-empty one, against the itab. Either way it is a single pointer compare, and on failure the runtime is only consulted to produce the panic.

An assertion to another interface does need the runtime, because the runtime has to find the itab for the dynamic type and the destination interface:

 go
 
 
// src/runtime/iface.go:482
// typeAssert builds an itab for the concrete type t and the
// interface type s.Inter. If the conversion is not possible it
// panics if s.CanFail is false and returns nil if s.CanFail is true.
func typeAssert(s *abi.TypeAssert, t *_type) *itab {
	var tab *itab
	if t == nil {
		if !s.CanFail {
			panic(&TypeAssertionError{nil, nil, &s.Inter.Type, ""})
		}
	} else {
		tab = getitab(s.Inter, t, s.CanFail)
	}

and because that is a hot path, the runtime caches the answers in a small per-site hash table:

 go
 
 
// src/runtime/iface.go:495
	if !abi.UseInterfaceSwitchCache(goarch.ArchFamily) {
		return tab
	}

	// Maybe update the cache, so the next time the generated code
	// doesn't need to call into the runtime.
	if cheaprand()&1023 != 0 {
		// Only bother updating the cache ~1 in 1000 times.
		return tab
	}

One call in a thousand rebuilds the cache; the rest of the time the generated code hits the cache directly. Type switches work the same way, via interfaceSwitch, which walks the cases calling getitab for each.

The special case of `error`

error is not special to the runtime. It is an ordinary interface with one method:

 go
 
 
// src/builtin/builtin.go:315
// The error built-in interface type is the conventional interface for
// representing an error condition, with the nil value representing no error.
type error interface {
	Error() string
}

What is special is that the compiler and the runtime both have a canonical descriptor for it, so that every error in the program shares one itab layout and one type descriptor. The runtime’s own errors use a tiny predeclared type:

 go
 
 
// src/runtime/error.go:86
// An errorString represents a runtime error described by a single string.
type errorString string

func (e errorString) RuntimeError() {}

func (e errorString) Error() string {
	return "runtime error: " + string(e)
}

The RuntimeError() method is a marker: runtime.Error is an interface with that method, and it is how code distinguishes a runtime error from an ordinary one.

The famous footgun with error is not about the interface at all. It is about the data word. Take any concrete error type with a pointer receiver, such as the one errors.New hands back:

 go
 
 
// src/errors/errors.go:68
// errorString is a trivial implementation of error.
type errorString struct {
	s string
}

func (e *errorString) Error() string {
	return e.s
}

Storing a nil *errorString in an error gives you an interface whose itab word is non-nil (it points at the *errorString itab) and whose data word is a nil *errorString. The interface as a whole is non-nil, and err != nil is true. Only the data word is nil.

That is the direct-iface rule in action: a pointer-shaped concrete type is stored directly in the data word, so a nil pointer becomes a nil data word inside a non-nil interface.

errors.Is and errors.As navigate this world for you, and they are careful about it:

 go
 
 
// src/errors/wrap.go:45
func Is(err, target error) bool {
	if err == nil || target == nil {
		return err == target
	}

	isComparable := reflectlite.TypeOf(target).Comparable()
	return is(err, target, isComparable)
}

errors.As refuses to assign to a target that is not a pointer to an error type, and it walks the Unwrap chain, so it is the tool to reach for rather than a hand-written type switch.

Trade-offs

What the two-word layout buys: an interface value is the same size as a pointer, it can be passed in a register, and assigning one is a two-word copy with no allocation.

What it costs: the first word is a pointer to shared, read-only data that has to be found somehow. For statically-known pairs the compiler finds it for free. For dynamic ones the runtime has to look it up, and that lookup is a hash-table probe.

The data word’s polymorphism costs too. Boxing a non-pointer value means an allocation, and the compiler works hard to avoid it – the staticuint64s table, the zerobase global, the “stack temporary if it does not escape” case. Each of those is a special case in dataWord.

The itab table is a global mutable structure, which means it needs a lock and careful publication. The runtime solves that with an atomic pointer to the table, so readers never take the lock; only the rare insert does.

Caching is the other lever. The runtime keeps a per-site cache for type assertions and type switches, updated only about once in a thousand misses, so the steady-state cost of an interface-to-interface assertion is a hash lookup in a small table rather than a trip through getitab.

Caveats

Converting a concrete type to an interface is not free in general. It is free if the value is pointer-shaped, or a small integer constant, or zero-sized. Otherwise it allocates.

Converting an interface to another interface is a runtime call. The compiler cannot know whether the dynamic type implements the destination.

The itab lookup happens once per pair, then forever. The first interface-to-interface conversion of a given pair builds an itab; every later one finds it in the table.

getitab takes a global lock on a miss. Two goroutines converting the same unknown type at the same time will contend. The lock is not held for lookups that hit.

The itab table grows forever. Every distinct (interface, concrete type) pair that is converted dynamically at run time adds an entry. A program that generates types dynamically can grow this table without bound.

A nil pointer in an interface is not a nil interface. This is the single most common interface bug in Go, and it is a consequence of the direct-iface rule.

The data word of an interface holding a non-pointer points to a copy. If you mutate the original value after boxing it, the interface still sees the old copy.

Comparing two interface values compares the type words first. Two interfaces holding equal values of different dynamic types are not equal, and the comparison does not panic.

reflect on an interface value gives you the dynamic type. That is the type descriptor in the first word, and it is why fmt.Printf("%T", x) works without any cooperation from the value.

Wrapping up

The one thing to remember: an interface value is two words, and the first word is a pointer to a table that says what the concrete type is and where its methods live. For a statically-known concrete type, that table is a read-only symbol in the binary; for a dynamic one, it is looked up in a global hash table and cached forever.

The part people get wrong: interfaces are not “free” in the sense of “never cost anything”, but the expensive case is not the one people think. Converting a concrete type to an interface is a static pointer load; converting an interface to another interface is the one that calls into the runtime.

What to go do about it: if a hot path is spending time in getitab or runtime.typeAssert, look for interface-to-interface conversions and type switches over values of unknown type. If a hot path is allocating on interface conversion, look for non-pointer values being boxed, and consider passing a pointer instead.

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.

Interfaces on Opensource internals

Go's Interfaces Are Two Words and a Cached itab

The two layouts

The data word: direct or boxed

Where the first word comes from

The static itab

The dynamic itab: `getitab`

Filling in the itab

Type assertions

The special case of `error`

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

Interfaces on Opensource internals

Go's Interfaces Are Two Words and a Cached itab

The two layouts

The data word: direct or boxed

Where the first word comes from

The static itab

The dynamic itab: getitab

Filling in the itab

Type assertions

The special case of error

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 dynamic itab: `getitab`

The special case of `error`