Interfaces: itab & eface

This page goes below the fundamentals interfaces page, which covers what interfaces are and how to use them. Here we open the box and look at the runtime representation.

Two words: iface and eface

Every interface value is exactly two machine words (16 bytes on a 64-bit machine — confirm it yourself below). There are two internal shapes:

• eface — the empty interface (any / interface{}). It’s (type pointer, data pointer): a *_type describing the dynamic type, and a pointer to the value.
• iface — any non-empty interface (has methods, like io.Reader). It’s (itab pointer, data pointer): the data word is the same, but the type word points at an itab.

graph TD
subgraph eface["eface — any / interface{}"]
  E1["_type *  →  dynamic type"]
  E2["data  *  →  the value"]
end
subgraph iface["iface — io.Reader, etc."]
  I1["itab  *  →  type + method table"]
  I2["data  *  →  the value"]
end

The itab: where methods live

An itab describes how one concrete type satisfies one interface. It holds:

• the interface type and the concrete (dynamic) type,
• a hash for fast type switches,
• and the method table: resolved pointers to the concrete type’s implementations of the interface’s methods, in a fixed compile-time order.

The runtime builds an itab the first time a given (interface, concrete type) pair is converted, then caches it in a global table keyed by that pair. So the first var r io.Reader = myFile does real work; every subsequent conversion of an *os.File to io.Reader is a cheap cached lookup.

Dynamic dispatch, type assertions, and size

This program proves the two-word size, exercises dynamic dispatch (the call goes through the itab’s method pointer), and shows a type assertion and a type switch recovering the concrete type:

package main

import (
"fmt"
"unsafe"
)

type Speaker interface{ Speak() string }

type Dog struct{ Name string }
func (d Dog) Speak() string { return d.Name + " says woof" }

type Cat struct{ Name string }
func (c Cat) Speak() string { return c.Name + " says meow" }

func main() {
// Both interface kinds are two words wide.
var s Speaker
var e any
fmt.Println("sizeof(Speaker) =", unsafe.Sizeof(s)) // 16 on 64-bit
fmt.Println("sizeof(any)     =", unsafe.Sizeof(e)) // 16

// Dynamic dispatch: the concrete method is found via the itab.
speakers := []Speaker{Dog{"Rex"}, Cat{"Lily"}}
for _, sp := range speakers {
	fmt.Println(sp.Speak())
}

// Type assertion: recover the concrete type from the interface.
var x Speaker = Dog{"Buddy"}
if d, ok := x.(Dog); ok {
	fmt.Println("asserted Dog:", d.Name)
}

// Type switch: dispatch on the dynamic type.
for _, sp := range speakers {
	switch v := sp.(type) {
	case Dog:
		fmt.Println("a dog named", v.Name)
	case Cat:
		fmt.Println("a cat named", v.Name)
	}
}
}

The call sp.Speak() doesn’t search by name — it loads the Speak pointer from sp’s itab and jumps. One indirection, known offset.

The typed-nil trap

Because an interface is (type, data), it is nil only when both words are nil. Assign a typed nil pointer and the type word is set, so the interface compares non-nil — the single most infamous Go gotcha:

package main

import "fmt"

type MyError struct{ msg string }

func (e *MyError) Error() string { return e.msg }

// BUG: returns a concrete *MyError, not the error interface.
func doWork(fail bool) error {
var e *MyError // nil pointer
if fail {
	e = &MyError{"it failed"}
}
return e // even when nil, this wraps a non-nil (type=*MyError, data=nil) interface!
}

func main() {
err := doWork(false) // we expect "no error"
fmt.Println("err == nil?", err == nil) // false! 😱
fmt.Printf("but the value is: type=%T value=%v\n", err, err)

// The fix: return nil explicitly, or use the error type throughout.
}

err == nil is false even though no error occurred, because the interface carries the type *MyError. The fix is to return a literal nil on the success path (or not funnel typed-nil pointers into interfaces).

Reference

See also

• interfaces (fundamentals) — what interfaces are and how to use them.
• escape analysis — why interface assignment heap-allocates.
• unsafe & pointers — peeking at the two-word representation.
• memory layout & alignment — the two-word, 16-byte size.

Next: how goroutines actually get on a CPU — scheduler internals.

Related topics