Cleanup Ordering — Professional Level¶

Table of Contents¶

1. Introduction
2. Prerequisites
3. Glossary
4. Runtime Architecture
5. Open-Coded Defers
6. Heap-Allocated Defers
7. Defer Records and the Defer Chain
8. Compiler Strategy and Code Generation
9. context.AfterFunc Implementation
10. Panic and Recover Internals
11. runtime.Goexit and Defer Unwinding
12. Performance Engineering
13. Memory Layout and Alignment
14. Defer in Generic Functions
15. Defer in Inlined Functions
16. Reading the Source: A Guided Tour
17. Cross-Version Differences
18. Common Misconceptions at the Runtime Level
19. Edge Cases
20. Debugging Cleanup Issues
21. Tests, Benchmarks, and Profiling
22. Interview-Level Internals Questions
23. Cheat Sheet
24. Summary
25. Further Reading
26. Related Topics
27. Diagrams & Visual Aids

Introduction¶

Focus: "How does the Go runtime actually implement defer, context.AfterFunc, panic/recover, and runtime.Goexit? What is the exact memory and CPU cost of each? How do these primitives interact with the scheduler, the GC, and the compiler?"

You have arrived at the level where you need to know not just how to use Go's cleanup mechanisms but how they are built. This file walks through the runtime source, the compiler's code generation strategies, the memory layouts of internal structures, and the performance characteristics of each primitive at the level of CPU cycles and cache lines.

The audience for this file is small. You are here because:

• You are profiling a hot path where defer shows up.
• You are debugging a goroutine scheduler issue involving deferred cleanups.
• You are writing a library that wraps context.AfterFunc and want to predict its costs.
• You are a Go runtime contributor or a runtime-curious senior engineer.
• You teach Go and want to be unimpeachable on internals questions.

Most teams never need this depth. But when you need it, you really need it, and nothing else suffices. This file is a reference. Read it once for completeness. Bookmark the sections that match your specific problem.

A note on versioning: the runtime is a moving target. The patterns described here are accurate as of Go 1.22 (released February 2024). Earlier versions differ in some details — most notably, open-coded defers arrived in 1.14, context.AfterFunc in 1.21, and the loop-variable scoping fix in 1.22. Where it matters, we call out the version.

Prerequisites¶

• Required: Complete mastery of the junior, middle, and senior files. You should be writing senior-level Go in your sleep.
• Required: Ability to read and reason about Go assembly output (go build -gcflags=-S).
• Required: Familiarity with the Go runtime's basic structures: G (goroutine), M (OS thread), P (processor).
• Required: Understanding of memory layouts, alignment, and cache lines.
• Required: Comfort reading the Go runtime source. Have a checkout of the Go repository handy.
• Helpful: Experience with delve, pprof, and the trace tool.
• Helpful: A working knowledge of x86-64 and ARM64 calling conventions for Go.

If terms like "frame pointer," "SP," "writeBarrierEnabled," and "P-runnext" are familiar, you are ready.

Glossary¶

Runtime Architecture¶

The defer mechanism, at a high level¶

There are two distinct code paths for defer in modern Go:

1. Open-coded defer. The compiler analyses the function at compile time. If conditions are met (≤ 8 defers, none inside a loop, no defers behind unknown control flow), it emits the cleanup directly at the function's return points. No runtime calls. Cost: a few instructions per defer.

2. Heap defer. Used when open-coding is not possible. The compiler emits runtime.deferproc(fn, args) at the defer site. The runtime allocates a _defer record from a per-P pool, pushes it onto the goroutine's defer chain, and returns. At function exit, the compiler emits runtime.deferreturn(), which pops and runs the defers in LIFO order.

The choice happens at compile time. You can see it in the assembly output: open-coded defers show as compiler-emitted cleanup code; heap defers show as CALL runtime.deferproc and CALL runtime.deferreturn.

The runtime's data structures¶

// from runtime/runtime2.go (simplified)
type _defer struct {
    started bool   // defer is currently running
    heap    bool   // defer is heap-allocated
    openDefer bool // defer is from an open-coded defer
    sp      uintptr // stack pointer at registration
    pc      uintptr // program counter at registration
    fn      *funcval // the function to call
    _panic  *_panic // panic info, if running during a panic
    link    *_defer // next defer in the chain
    fd      unsafe.Pointer // funcdata; used for open-coded defers
    varp    uintptr // value of varp for the deferring frame
    framepc uintptr // pc for the deferring frame
}

type _panic struct {
    argp     unsafe.Pointer // pointer to arguments of panic
    arg      interface{}    // panic value
    link     *_panic        // next panic in the chain
    pc       uintptr        // where to resume after recover
    sp       unsafe.Pointer // sp at recover
    recovered bool          // recover() was called
    aborted  bool           // the panic was aborted
    goexit   bool           // this is from Goexit, not panic
}

These two structures and the goroutine's g._defer and g._panic fields (singly-linked lists, head pointers on the G) implement the entire defer/panic/recover machinery.

The goroutine and its defer chain¶

Each g (goroutine) has a _defer field pointing to the head of its defer chain. Each _defer record's link field points to the next record. New defers are prepended; defers pop from the head.

g._defer ──► [defer C] ──link──► [defer B] ──link──► [defer A] ──► nil

When the function that registered A, B, C returns, the runtime walks this chain from head to tail (C, then B, then A — LIFO).

Heap-allocated _defer records come from a per-P pool to reduce allocator pressure. The pool is managed by runtime.deferproc and runtime.deferreturn.

Open-coded defer's bit vector¶

For open-coded defers, there is no per-defer heap record. Instead, the compiler emits:

• An 8-bit (or 32-bit, depending) "active defer" bitmap in the function's stack frame.
• A "deferreturn" block at the end of the function.

When you write defer f(), the compiler emits code that sets the corresponding bit and stores the argument values in pre-allocated stack slots. At the function's end (or on panic), the deferreturn block checks each bit in LIFO order and, if set, calls the corresponding function with the stored arguments.

The savings: no heap allocation, no linked-list traversal, no atomic operations. The cost is paid at compile time (more code generated) but the runtime cost approaches zero.

Open-Coded Defers¶

What qualifies for open-coding¶

The compiler must be able to: - Count exact defer registrations at compile time. - Know the function's exit points. - Prove that defers are not inside loops. - Have eight or fewer total defers in the function.

Practical implications:

func A() {
    defer f1() // OK — open-coded
    defer f2() // OK
    return
}

func B() {
    for i := 0; i < 10; i++ {
        defer f1() // NOT open-coded — inside a loop
    }
}

func C() {
    defer f1()
    defer f2()
    defer f3()
    defer f4()
    defer f5()
    defer f6()
    defer f7()
    defer f8()
    defer f9() // 9th defer — NOT open-coded (exceeds budget)
}

func D() {
    if cond {
        defer f1() // OK — conditional but still countable
    }
    return
}

The compiler uses static analysis to make these determinations. The criteria are conservative: it would rather fall back to heap defers than incorrectly open-code.

The generated code¶

For a function with defer cleanup(), the open-coded version generates code like (pseudo-assembly):

func MyFunc():
    // Function prologue
    SUBQ $48, SP   ; allocate stack frame including:
                   ;   - defer bit (1 byte)
                   ;   - defer arg slots for cleanup

    ; defer cleanup() — at the defer statement
    MOVB $1, (SP+0x20)        ; set the defer bit
    ; evaluate args, store in slots (none here)

    ; ... function body ...

    ; At function exit:
    CMPB $0, (SP+0x20)         ; is the defer bit set?
    JE skip_cleanup
    CALL cleanup
skip_cleanup:
    ADDQ $48, SP
    RET

    ; Also, deferreturn fallback for panic case:
deferreturn:
    CMPB $0, (SP+0x20)
    JE done_deferreturn
    CALL cleanup
done_deferreturn:
    RET

The runtime cost: one byte set on the defer, one comparison at function exit, one conditional jump. Roughly 5 nanoseconds total on modern x86 — far less than a heap allocation.

The deferreturn block for panics¶

When a function with open-coded defers panics, the runtime needs to run the defers. The compiler emits a special deferreturn block, which the runtime can jump to. This block is essentially a copy of the cleanup logic but reachable from runtime.deferreturn.

The runtime stores a pointer to this block in the function's metadata (PCDATA / FUNCDATA tables). On panic, the runtime walks the stack, finds each function's deferreturn pointer, and jumps to it to run that function's defers before continuing the panic unwind.

Performance characteristics¶

Benchmarks (Go 1.22 on a modern x86-64 CPU): - Open-coded defer: ~5 ns / call - Heap defer: ~30-50 ns / call (depending on pool state) - No defer at all: ~0 ns

The open-coded path is nearly free. The heap path is small but measurable. For most code, the cost is irrelevant. For tight loops, it matters.

When the compiler bails out¶

The compiler may decide not to open-code even when it could: - If the function has too many other deferred calls and the analysis would explode. - If there is unusual control flow (goto, recover branches). - If a defer's function is too dynamic (a function value held in a variable).

You can see the compiler's choice via:

go build -gcflags='-d=defer=2' main.go 2>&1 | grep defer

This emits diagnostic output showing each defer and whether it was open-coded.

Heap-Allocated Defers¶

When heap defers are used¶

• Defers inside loops.
• Defers beyond the open-coded budget (more than 8).
• Defers in functions where the compiler decided not to open-code for some reason.

The runtime path¶

When the compiler cannot open-code, it generates a call to runtime.deferproc:

// runtime/panic.go
func deferproc(fn func()) {
    // Get the current G
    gp := getg()
    if gp.m.curg != gp {
        throw("defer on system stack")
    }

    // Allocate a _defer record from the per-P pool
    d := newdefer(...)
    d.fn = fn
    d.link = gp._defer
    gp._defer = d
}

Simplified for clarity. The real implementation handles: - Argument size (deferred calls can have arbitrary arguments, stored in the record). - Pool management (per-P caches, allocation if pool is empty). - GC barriers (the defer's function value is a heap pointer; needs write barriers). - Stack growth (records must be relocated when the goroutine's stack grows).

runtime.deferreturn¶

The compiler emits runtime.deferreturn() at the end of every function that has heap defers:

// runtime/panic.go
func deferreturn() {
    gp := getg()
    for {
        d := gp._defer
        if d == nil || d.sp != getsp() {
            break // no more defers for this frame
        }
        // pop and run
        fn := d.fn
        gp._defer = d.link
        freedefer(d)
        fn()
    }
}

Each iteration: 1. Check the head of the defer chain. 2. If it belongs to the current stack frame (same sp), pop and run. 3. Otherwise, this frame has no more defers; return.

The check d.sp != getsp() is key: defers from other frames remain on the chain but are not run by this deferreturn.

Pool management¶

The runtime maintains a per-P pool of _defer records:

type p struct {
    // ...
    deferpool    []*_defer  // pool of available _defer records
    deferpoolbuf [32]*_defer
}

When newdefer is called: 1. Check the P's deferpool. If non-empty, pop and return. 2. Otherwise, check the global pool. 3. Otherwise, allocate a new _defer from the heap.

When freedefer is called: 1. If the P's pool has space, push back. 2. Otherwise, transfer half to the global pool.

This keeps allocation pressure low for high-throughput defer code.

Heap defer with arguments¶

Defers can have arbitrary argument types. The compiler emits code to copy the arguments into the _defer record at registration time, and to pass them to fn at execution time. The argument size determines the size of the _defer record.

For small functions with no closures (typical defer f() without arguments), the record is a fixed ~120 bytes. For functions with large argument lists, it grows.

This is one reason to prefer closure-based defers when the function arguments are large: a closure is a single pointer, so the defer record stays small.

Defer Records and the Defer Chain¶

Walking the chain¶

The G's _defer field is the head of the chain. Each record's link is the next.

G._defer ──► [d1] ──link──► [d2] ──link──► [d3] ──► nil

d1 is the most recently registered; d3 is the oldest. LIFO popping starts at d1.

Each record carries: - fn: the function to call. - Stored argument values (variable size, immediately after the record header). - sp: the stack pointer at registration, used to determine which frame this defer belongs to.

Cross-frame defer chains¶

A goroutine's defer chain spans all of its function call frames. If f calls g, and both register defers, the chain looks like:

g._defer ──► [g's defer] ──link──► [f's defer]

When g returns, deferreturn runs g's defer, then sees f's defer has a different sp, so it stops. Control returns to f's caller's return logic — which eventually calls deferreturn again to run f's defers.

This per-frame separation is what makes defers function-local even though the chain is goroutine-wide.

Defer records and the GC¶

The _defer record contains a function pointer and possibly argument pointers. These are heap-pointer references; the GC must scan them. The runtime's GC includes the defer chain in its root scan.

This is the cost the GC pays for defer. For a goroutine with hundreds of pending defers, the GC scans all of them. In practice, defer counts per goroutine are small (single digits), so this is negligible.

Defer records and stack copies¶

When a goroutine's stack grows (Go's stacks are growable), all data with stack pointers — including defer records that reference stack-allocated argument values — must be updated. The runtime walks the defer chain during stack copy and adjusts SPs.

This is why defer records carry the sp field: to identify which frame they belong to after a copy.

Compiler Strategy and Code Generation¶

The compilation pipeline¶

A high-level view of how the compiler handles defers:

1. Parse. Build the AST. defer X becomes a DeferStmt node.
2. Type check. Verify X is a function call.
3. Escape analysis. Determine if the deferred function captures variables that escape to the heap.
4. SSA construction. Build the SSA form, with explicit defer blocks at function exit.
5. Defer analysis. Decide open-coded vs heap.
6. Code generation. Emit either:
7. For open-coded: a stack bit, argument slots, and exit-block cleanup code.
8. For heap: calls to runtime.deferproc and runtime.deferreturn.

Inspecting compiler decisions¶

The flag -d=defer=2 shows defer analysis:

go build -gcflags='-d=defer=2'

Output:

./main.go:10:6: open-coded defer
./main.go:15:6: heap defer (in loop)

Use this to verify that performance-sensitive code is using the path you expect.

SSA form¶

In SSA, defers become explicit nodes that produce no value but have side effects. The compiler can analyse them like any other node:

b1:
    v1 = ... (some result)
    v2 = OpDeferRegister cleanup v1 // pseudo
    Goto b2
b2:
    ...
b_exit:
    v3 = OpDeferRun // pseudo
    Return

The SSA pass defer.go rewrites these into either open-coded blocks or deferproc/deferreturn calls.

Compiler heuristics¶

The eight-defer budget is a heuristic. It was chosen because: - 99% of real Go functions have fewer than 8 defers. - The bit vector fits in a byte for 8 defers. - Code expansion for 8 defers is acceptable.

Beyond 8, the compiler falls back to heap defers. This is a soft cliff in performance: a function with 8 defers is fast; a function with 9 is suddenly 5x slower per defer.

If you have a function with many defers, consider refactoring — not just for performance, but for readability.

Codegen for defer f() vs defer func() {...}()¶

For defer f(): - Open-coded: a slot for any arguments and the function value (if not directly known). - Heap: the same, packed into the _defer record.

For defer func() {...}(): - The closure is constructed at the defer line (capturing variables by reference). - The closure is a single pointer to a closure struct. - The defer captures this pointer. - At execution, the closure is called.

The closure has its own argument list (none, in this typical case). The defer record carries just the closure pointer.

This is why defer func() {...}() is often cheaper than defer f(big, args): the closure pointer is small and constant, regardless of what the closure captures.

context.AfterFunc Implementation¶

The data structure¶

context.AfterFunc registers a callback on a context's cancellation. The internal data structure:

// from context/context.go (simplified)
type cancelCtx struct {
    Context
    mu       sync.Mutex
    done     atomic.Value // chan struct{}
    children map[canceler]struct{}
    err      error
    cause    error
    afterFuncs map[*afterFuncCtx]struct{} // Go 1.21+
}

type afterFuncCtx struct {
    cancelCtx           // embeds a cancelCtx so it can be a child
    fn          func()
    once        sync.Once
}

Each AfterFunc registration: 1. Wraps the user's fn in an afterFuncCtx. 2. Registers it as a child of the target context. 3. Returns a stop function that removes it from the parent.

Registration¶

func AfterFunc(ctx Context, fn func()) (stop func() bool) {
    a := &afterFuncCtx{
        fn: fn,
    }
    a.cancelCtx.Context = ctx
    if propagateCancel(ctx, a) {
        // ctx was already done — schedule fn immediately
        go a.run()
    }
    return func() bool {
        stopped := a.once.Do(func() {})
        // ... remove from parent's child list ...
        return stopped
    }
}

func (a *afterFuncCtx) run() {
    a.once.Do(a.fn)
}

Slightly simplified. The key points: - propagateCancel registers a as a child of ctx. When ctx is cancelled, all children are too. - once.Do(fn) ensures fn runs at most once, whether triggered by cancel or by stop. - stop uses the same once to deregister: if once is unused, stop returns true; if used, stop returns false.

Cancellation propagation¶

When a context is cancelled, the runtime calls cancel on each child. For an afterFuncCtx child:

func (a *afterFuncCtx) cancel(...) {
    a.cancelCtx.cancel(...)
    go a.run()
}

The cancel: 1. Marks the wrapped context as done. 2. Schedules a.run in a new goroutine.

The new goroutine is what gives AfterFunc its "runs in a new goroutine" semantics. The cost is one goroutine creation per fired AfterFunc.

stop() semantics¶

stop is the inverse of registration. It: 1. Marks a.once as used (so subsequent run calls are no-ops). 2. Removes a from the parent's child list.

Whether it returns true or false depends on whether once was already used by the time stop was called. The race is real: stop and the cancel-fired goroutine can both call once.Do. The first wins.

Cost analysis¶

Per registration: - Allocate afterFuncCtx (~64 bytes). - Atomic compare-and-swap to add to parent's child list. - Return a closure (~16 bytes).

Per fire: - One goroutine creation (~1 μs). - Closure invocation.

Per stop: - One atomic compare-and-swap. - Remove from parent's child list.

Total: small but measurable. For 10,000 AfterFunc registrations per second, the cost is ~10 ms / s, which is 1% of one core. Negligible.

Interaction with context.WithCancelCause¶

AfterFunc works on any context, including those with causes. The callback can read context.Cause(ctx) to learn why it ran. This is implemented by the cancellation cause being stored on the cancelCtx, and Cause walking up the parent chain.

Panic and Recover Internals¶

The panic process¶

When panic(x) is called: 1. Allocate a _panic record on the goroutine's stack. 2. Link it onto the goroutine's _panic list (head insert). 3. Walk the defer chain from the head: - For each defer, pop it from the chain. - Set d.started = true. - Call d.fn. - If recover() was called inside d.fn, mark the panic as recovered. Stop unwinding. 4. If the panic was not recovered, terminate the program with a stack trace.

The runtime function is runtime.gopanic in runtime/panic.go.

The recover process¶

recover() is implemented in runtime.gorecover: 1. Find the goroutine's current panic. 2. If a panic is in flight AND we are inside a deferred function AND the panic is not yet recovered: - Mark the panic as recovered. - Return the panic value. 3. Otherwise return nil.

The check "inside a deferred function" is what makes recover only useful in defers. It examines stack frames to determine the call context.

Nested panics¶

A panic during a deferred function while another panic is in flight: 1. The new panic replaces the old (_panic.aborted = true on the old). 2. The old panic value is lost. 3. The new panic propagates from where it occurred.

This is why "panic during cleanup" is dangerous: it hides the original error.

Panic + Goexit interaction¶

runtime.Goexit is similar to panic but: - It does not have a value. - It cannot be recovered via recover (recover returns nil during Goexit). - It terminates the goroutine, not the program.

The defer chain still runs. The exit is clean.

Panic value boxing¶

panic(x) accepts interface{}. If x is a non-interface type, the runtime boxes it into an interface value. Boxing involves a type-info pointer and a data pointer. For small types (≤ pointer size), the data is stored inline; for larger types, the data is heap-allocated.

This is one reason panic is more expensive than return: the boxing cost.

Stack trace generation¶

When a panic terminates the program, the runtime walks the stack and prints a trace. The trace shows: - The panic value. - Each goroutine's stack. - Each frame's function name and file:line.

The walk uses the PCDATA / FUNCDATA tables emitted by the compiler. It is robust to optimisation; inlined functions are reported as inlined.

runtime.Goexit and Defer Unwinding¶

Goexit semantics¶

runtime.Goexit ends the current goroutine. Unlike panic: - No panic value. - recover returns nil during Goexit. - The goroutine's defers all run. - The program continues.

The runtime implementation walks the defer chain, runs each defer (with Goexit-context marked on the _panic record), and then calls goexit0 to release the goroutine.

Why Goexit exists¶

Goexit is used by: - testing.T.FailNow() and friends. - runtime.Goexit() directly. - Some test helpers in golang.org/x/....

It is the right tool when you want to end a goroutine cleanly but cannot use return (e.g., from deep in a helper function). Plain return exits only the current function.

Cost¶

Goexit is essentially a panic that does not propagate. Its cost is the cost of running all defers, plus releasing the goroutine. For typical goroutines with ≤ 5 defers, this is microseconds.

Performance Engineering¶

Benchmarking defers¶

func BenchmarkDeferNone(b *testing.B) {
    for i := 0; i < b.N; i++ {
        f()
    }
}

func BenchmarkDeferOne(b *testing.B) {
    for i := 0; i < b.N; i++ {
        deferOne()
    }
}

func deferOne() {
    defer func() {}()
}

func f() {}

On Go 1.22: - BenchmarkDeferNone: ~0.3 ns / op. - BenchmarkDeferOne (open-coded): ~1 ns / op. - BenchmarkDeferOne (heap, in a loop): ~30 ns / op.

The open-coded path is nearly free. The heap path is small but real.

Profile interpretation¶

In a CPU profile (pprof / go tool pprof), defer overhead shows as: - runtime.deferproc (registration cost). - runtime.deferreturn (run cost). - runtime.gopanic and runtime.gorecover (panic path). - runtime.newdefer and runtime.freedefer (pool management).

If any of these dominate, examine the calling functions to see whether defers are inside loops or beyond the open-coded budget.

When defers cost more than expected¶

• Defers in tight loops. Each iteration registers; the budget is exceeded. Heap defers dominate.
• Defers with large argument lists. The _defer record grows. Allocation cost increases.
• Long defer chains. If a function has 100 defers, deferreturn walks all of them. 100 × 30ns = 3μs per function call.
• Defers in functions that almost never return. A goroutine that runs for hours and registers defers slowly accumulates them. Probably a bug.

When defers cost less than you'd think¶

• The function is called rarely. Per-function overhead is amortised away.
• Open-coded defers. They cost roughly the same as inline code.
• Defers inside a function that does I/O. I/O dominates; defer cost is invisible.

AfterFunc cost¶

Per registration: ~30-60 ns (allocation + atomic CAS). Per fire: ~1-2 μs (goroutine creation + closure invocation). Per stop: ~30 ns.

For high-frequency cancellation, profile. AfterFunc can dominate in extreme cases.

Memory Layout and Alignment¶

_defer record layout¶

offset  size  field
0       1     started (bool)
1       1     heap (bool)
2       1     openDefer (bool)
... padding ...
8       8     sp (uintptr)
16      8     pc (uintptr)
24      8     fn (*funcval)
32      8     _panic (*_panic)
40      8     link (*_defer)
48      8     fd (unsafe.Pointer)
56      8     varp (uintptr)
64      8     framepc (uintptr)
72      [...] (additional fields)

Approximately 80 bytes per record on 64-bit. Plus argument storage if arguments are non-zero size.

Alignment¶

All pointers are 8-byte aligned on 64-bit. The booleans at the start pack into a single byte each but are followed by 5 bytes of padding before sp. This wastes a few bytes but keeps subsequent pointer fields aligned.

Cache behaviour¶

A single _defer record fits in one cache line (64 bytes). A goroutine with 5-10 pending defers has all of them within a few cache lines. Good locality.

For goroutines with hundreds of defers, the chain spans many cache lines. deferreturn's walk has poor locality. This is one more reason to keep defer counts small.

Closure layout¶

A closure is a struct:

struct {
    fn *funcval // pointer to the actual function code
    // captured variables follow
}

*funcval is itself a struct with a code pointer. So defer func() { ... }() creates a closure struct on the stack (or heap, depending on escape) and stores a pointer to it in the _defer record.

Defer in Generic Functions¶

Generic functions in Go (1.18+) work the same way for defers. The compiler instantiates the generic for each type used; each instantiation has its own defer analysis.

func process[T any](items []T) {
    defer cleanup()
    for _, item := range items {
        // ...
    }
}

When called as process[int](...), the compiler emits a specialised version. The defer in this version is analysed for open-coding just like a non-generic defer.

This is unsurprising: defers are compile-time-known structurally, so generics do not change their behaviour.

Defer in Inlined Functions¶

Defers are not inlined. If a function with defers is a candidate for inlining, the compiler will refuse to inline it.

//go:inline
func helper() {
    defer cleanup() // forces no inlining
}

func caller() {
    helper() // remains a call, not inlined
}

The reason: defer semantics depend on the function's frame. Inlining would change what "function return" means for the defer.

If you have a performance-critical small function with a defer, consider whether the defer is necessary or whether you can inline manually and call cleanup explicitly.

Reading the Source: A Guided Tour¶

A small reading list for the curious:

runtime/panic.go¶

The core of defer/panic/recover. Look for: - deferproc — register a heap defer. - deferreturn — run pending heap defers. - gopanic — implement panic. - gorecover — implement recover. - Goexit — implement Goexit.

runtime/runtime2.go¶

Type definitions: - _defer struct. - _panic struct. - g struct (where the defer chain lives).

cmd/compile/internal/ssagen/ssa.go¶

The compiler's defer handling: - state.stmt — handles DeferStmt nodes. - The decision between open-coded and heap.

cmd/compile/internal/walk/order.go¶

The compiler's pre-SSA pass that orders defer evaluations.

context/context.go¶

AfterFunc and the cancelCtx machinery: - cancelCtx type. - afterFuncCtx type. - propagateCancel function.

sync/once.go¶

sync.Once is used inside afterFuncCtx. Worth understanding.

Cross-Version Differences¶

Go 1.14: open-coded defers introduced¶

Before 1.14, all defers were heap-allocated. Performance was a known pain point. 1.14 introduced open-coded defers, dramatically reducing cost for the common case.

Go 1.17: register-based calling convention¶

The Go 1.17 ABI change to register-based calling conventions affected how arguments are passed to deferred functions. The runtime had to be updated to copy argument registers into the defer record.

Go 1.20: WithCancelCause¶

Added context.WithCancelCause and context.Cause. AfterFunc was not yet available.

Go 1.21: AfterFunc, sync.OnceFunc, errors.Join¶

A bumper crop of cleanup primitives. AfterFunc filled the gap of "cleanup that runs after context cancel." sync.OnceFunc made idempotent closures easier. errors.Join standardised multi-error reporting.

Go 1.22: loop variable scope¶

The fix to for i := range xs making i per-iteration changed the semantics of defers inside loop closures. Code that relied on the old (shared variable) behaviour broke; code that used the explicit copy pattern was unaffected.

Common Misconceptions at the Runtime Level¶

"Defers always allocate."

Wrong. Open-coded defers do not allocate. Heap defers allocate one _defer record per defer (with pool reuse).

"Open-coded defers are always faster."

Mostly true, but the difference is small for most code. The advantage is more about avoiding allocator pressure than raw speed.

"AfterFunc is a runtime feature, not a library feature."

It is in the context package, but it uses runtime primitives (atomic ops, goroutine creation). The implementation is straightforward Go code.

"recover is a runtime intrinsic."

Sort of. It is implemented in runtime.gorecover, but the compiler does treat it specially to know when to enable the panic recovery path. The implementation is in Go, not assembly.

"panic uses exceptions like Java."

No. Go's panic is a runtime mechanism that walks the defer chain and either terminates the program or is caught by recover. No JIT exception tables, no zero-cost exception handling. Just a linked list traversal.

Edge Cases¶

Defer on a method with a value receiver¶

type S struct { ... }
func (s S) Close() error { ... }

var s S
defer s.Close()

The method value s.Close captures a copy of s at the defer line. If s is mutated later, the defer sees the original. For value receivers, this is usually the right behaviour.

For pointer receivers:

func (s *S) Close() error { ... }

var s S
defer s.Close()

The method value captures &s. Mutations to s are visible to the defer.

Defer in a function that has a recover¶

When a defer panics during a function that itself has a recover, the recover sees the new panic. The original (if any) is lost.

defer func() {
    if r := recover(); r != nil {
        // r might be the original panic OR a panic from another defer
    }
}()

The recover cannot distinguish; the panic value is just r.

Defer with runtime.LockOSThread¶

If a goroutine is locked to an OS thread (runtime.LockOSThread) and the deferred function unlocks via runtime.UnlockOSThread, the defer must run on the locked thread. The runtime handles this correctly: defers run on the goroutine that registered them, on whatever thread that goroutine is currently scheduled to.

Defer in cgo callbacks¶

When C code calls back into Go, the callback runs on a Go goroutine. Defers in the callback work normally. However, the C call interruption point may not be a safe point for the scheduler; defers should not assume normal scheduling.

Defer in init functions¶

Init functions can defer. The defer runs when init returns. If multiple init functions are present (across files in a package), they run sequentially; each has its own defer scope.

Defer in main¶

main can defer. The defer runs when main returns. But if main calls os.Exit, the defer does not run. This catches many people.

Defer with runtime.SetFinalizer (anti-pattern)¶

SetFinalizer is not a defer. It does not run at function exit; it runs (if ever) during GC. Confusing the two is a real bug source.

Debugging Cleanup Issues¶

Identifying defer-related bugs¶

Symptoms: - Resource leaks (FDs, memory) that grow over time. - "Use of closed connection" panics. - "Already closed" errors on second access. - Hung shutdowns. - Goroutine leaks visible in pprof goroutine.

Tools: - runtime.NumGoroutine() for goroutine counts. - go tool pprof -goroutine for goroutine state breakdown. - lsof -p PID for FD counts. - delve for live debugging.

Reading a goroutine dump¶

A goroutine dump (SIGQUIT or runtime.Stack(buf, true)) shows each goroutine's stack. Look for: - Goroutines stuck in chan receive / chan send — usually a leak. - Goroutines stuck in Lock — possible deadlock. - Many goroutines with the same stack — fan-out without bound.

Defers in flight do not appear distinctly in the trace, but the runtime path through runtime.deferreturn will be visible.

Reading a heap profile¶

If memory is growing, take a heap profile:

go tool pprof http://service/debug/pprof/heap

In the profile, look for: - runtime._defer (heap defers). - The function values held by defers.

If _defer records dominate, you have a defer leak — probably defers in a goroutine that never exits.

Tests, Benchmarks, and Profiling¶

Test patterns¶

func TestNoLeaks(t *testing.T) {
    defer goleak.VerifyNone(t)
    // ... test code ...
}

Add this to every test for a service component. It catches goroutine leaks reliably.

Benchmark patterns¶

func BenchmarkCleanup(b *testing.B) {
    for i := 0; i < b.N; i++ {
        withCleanup()
    }
}

Measure the cost of cleanup paths. If runtime.deferproc shows up in the benchmark profile, consider open-coding or refactoring.

Profiling production¶

Sample profiles in production with pprof.StartCPUProfile. Look for: - runtime.gopanic — panics happening more than expected. - runtime.deferreturn — high defer cost. - Custom cleanup functions — slow individual cleanups.

Interview-Level Internals Questions¶

Q. Why does defer have a per-goroutine chain rather than a per-function structure?

A. Because defers can span function calls: a function f registers a defer, then calls g. While g is running, f's defer is still pending on the same goroutine. The chain is per-goroutine; the sp field distinguishes which frame each defer belongs to.

Q. How does open-coded defer interact with the panic path?

A. The compiler emits both a normal-exit cleanup block and a panic-path deferreturn block. The runtime's stack unwinder finds the deferreturn block via PCDATA, jumps there to run defers, then continues unwinding.

Q. What happens to a heap defer's argument storage during stack growth?

A. Argument storage may be on the stack (for some defers); the runtime walks the defer chain during stack copy and adjusts pointers. For heap-allocated argument copies (common for closures), nothing needs to move.

Q. Why does context.AfterFunc use a fresh goroutine per fire?

A. To decouple the callback from the goroutine that triggered cancellation. The cancel-triggering goroutine may be on a hot path (e.g., signal handler); spawning a goroutine keeps the cancel itself fast.

Q. Why does recover only work inside a deferred function?

A. The runtime walks the defer chain on panic; it sets the panic's "currently in a defer" state during each defer's execution. recover checks this state. Outside a defer, it returns nil.

Q. What is the cost of defer in a tight loop?

A. Each iteration registers a heap defer (since defers in loops are not open-coded). One iteration: ~30-50 ns. A million iterations: 30-50 ms. The defers stack up and all run when the enclosing function returns.

Q. How does runtime.Goexit differ from panic?

A. Goexit: - Has no value. - Cannot be recovered. - Ends the goroutine only, not the program.

Both run the defer chain.

Q. What is the relationship between AfterFunc and the GC?

A. AfterFunc registrations are kept alive on the context's callback list. They are GC'd when the context is. A long-lived context with many registrations holds them all in memory until cancelled or until stop is called.

Q. Why is a defer chain a singly-linked list rather than a slice?

A. Insertion is O(1) at the head. The chain spans function calls; resizing a slice would require reallocation. The linked list is the right data structure.

Q. What happens if a defer's function is nil?

A. Calling a nil function panics. The defer registers fine; the panic happens at execution time.

Cheat Sheet¶

RUNTIME ENTRY POINTS
====================
runtime.deferproc(fn)        register a heap defer
runtime.deferreturn()        run pending heap defers
runtime.gopanic(v)           implement panic
runtime.gorecover()          implement recover
runtime.Goexit()             end the goroutine; run defers

OPEN-CODED DEFER (1.14+)
========================
Eligibility:
  - ≤ 8 defers in the function
  - none in a loop
  - countable at compile time
Cost: ~5 ns / call (vs ~30 ns for heap)
View: -gcflags='-d=defer=2'

HEAP DEFER
==========
_defer record: ~80 bytes + arg size
Per-P pool: 32-slot cache
Chain: G._defer linked list, sp-distinguished

CONTEXT.AFTERFUNC (1.21+)
=========================
afterFuncCtx wraps fn in a cancelCtx child
fn runs in new goroutine on cancel
stop deregisters; returns true if fn never ran

COST AT SCALE
=============
defer none:      0.3 ns
defer open:      1-5 ns
defer heap:      30-50 ns
AfterFunc reg:   30-60 ns
AfterFunc fire:  1-2 μs (goroutine creation)
panic+defer:     hundreds of ns to μs depending on chain length

Summary¶

You now know how defer, context.AfterFunc, panic, and recover are actually implemented in the Go runtime. You know the difference between open-coded and heap defers, the per-goroutine defer chain, the _defer record layout, the cost of each operation, and the trade-offs the compiler makes.

For 99% of Go programmers, this knowledge is unnecessary. For the 1% who write systems software, performance-critical libraries, or contribute to the runtime itself, it is indispensable.

The specification file (specification.md) contains the formal Go language rules for defers and panics — the contract that the runtime implements. The interview file (interview.md) has questions at every level, including some that touch on internals. The tasks, find-bug, and optimize files give you hands-on practice.

You have completed the deepest tier. Use it wisely.

Further Reading¶

• The Go runtime source: runtime/panic.go, runtime/runtime2.go
• The Go compiler source: cmd/compile/internal/ssagen
• The Go 1.14 release notes (open-coded defers)
• The Go 1.21 release notes (AfterFunc)
• "Toward a Better Defer" — Keith Randall's blog post on the open-coded defer design
• The Go FAQ on panic/recover
• Russ Cox, "Go Data Structures: Interfaces" (background on type info)
• The Go ABI specification

Related Topics¶

• 01-cooperative-vs-force (cancellation observation)
• 02-partial-cancellation (cancellation of sub-workflows)
• The Errors-and-Panics track (panic recovery in depth)
• The Go runtime track (GMP scheduler, GC internals)
• The compiler track (SSA, code generation)

Diagrams & Visual Aids¶

The defer chain (per goroutine)¶

g._defer ──► [d_top] ──link──► [d2] ──link──► ... ──► [d_bottom] ──► nil

d_top:    most recently registered, popped first
d_bottom: oldest, popped last

Each record:
   sp:        used to find which frame this belongs to
   fn:        function to call
   args:      stored argument values

Open-coded defer in the stack frame¶

function frame:
   ┌──────────────────────────┐
   │   local variables        │
   ├──────────────────────────┤
   │   defer bit vector       │  ← 1 byte (8 defers max)
   ├──────────────────────────┤
   │   arg slots for defer 0  │
   │   arg slots for defer 1  │
   │   ...                    │
   ├──────────────────────────┤
   │   saved registers        │
   │   return address         │
   └──────────────────────────┘

Heap defer record¶

_defer record (heap):
   ┌──────────────────┐
   │ started, heap, ... (flags)
   │ sp                │
   │ pc                │
   │ fn (function ptr) │
   │ link (next defer) │
   │ ...               │
   ├──────────────────┤
   │ argument storage  │ ← variable size
   └──────────────────┘

Panic walking the defer chain¶

panic(v) →
   create _panic record
   for d in g._defer (head to tail):
       d.started = true
       call d.fn  ←── may call recover()
       if recovered:
           clear panic state
           jump to recover's caller's return
           STOP
   if not recovered:
       print stack trace
       terminate program

context.AfterFunc structure¶

AfterFunc(ctx, fn) →
   create afterFuncCtx{fn: fn}
   register as child of ctx
   return stop function

on ctx cancel →
   for each child:
       child.cancel()
       if child is afterFuncCtx:
           go child.run()  ←── new goroutine

afterFuncCtx.run() →
   once.Do(fn)

Costs comparison¶

                ns / op
   ─────────────────────────
   no defer:         0.3
   open defer:       1-5
   heap defer:      30-50
   panic+recover:   ~500
   AfterFunc reg:   30-60
   AfterFunc fire:  1000-2000

(Approximate; varies by hardware and Go version.)

Appendix: A Reading of runtime.deferreturn¶

To make the internals concrete, here is a simplified walkthrough of runtime.deferreturn:

//go:nosplit
func deferreturn() {
    gp := getg()
    for {
        d := gp._defer
        if d == nil {
            return
        }
        sp := getsp()
        if d.sp != sp {
            return
        }
        if d.openDefer {
            done := runOpenDeferFrame(d, sp)
            if !done {
                throw("unfinished open-coded defers")
            }
            gp._defer = d.link
            freedefer(d)
            continue
        }
        fn := d.fn
        d.fn = nil
        gp._defer = d.link
        freedefer(d)
        fn()  // may panic
    }
}

Key points: - //go:nosplit — cannot be preempted; runs on a stack that may be small. - Loop until no more defers belong to this frame (d.sp != sp). - For open-coded defers, delegate to runOpenDeferFrame. - For heap defers, pop, free the record, then call the function.

The function returns when the frame's defers are exhausted. The caller (compiler-generated code) then completes the function's return.

Appendix: A Reading of runtime.gopanic¶

//go:nosplit
func gopanic(e interface{}) {
    gp := getg()
    var p _panic
    p.arg = e
    p.link = gp._panic
    gp._panic = (*_panic)(noescape(unsafe.Pointer(&p)))

    for {
        d := gp._defer
        if d == nil {
            break
        }
        d.started = true
        d._panic = (*_panic)(noescape(unsafe.Pointer(&p)))
        // run deferred function
        reflectcall(... d.fn ...)
        // if recovered, jump
        if p.recovered {
            gp._panic = p.link
            // jump to recover's caller's return
            mcall(recovery)
        }
        // pop defer, continue
        gp._defer = d.link
        freedefer(d)
    }

    // no recovery — terminate
    fatalpanic(gp._panic)
}

Simplified for clarity. The main loop walks defers; each defer can call recover to set p.recovered; if so, we jump out of the loop.

Appendix: A Reading of context.AfterFunc¶

func AfterFunc(ctx Context, f func()) (stop func() bool) {
    a := &afterFuncCtx{
        f: f,
    }
    a.cancelCtx.Context = ctx
    propagateCancel(ctx, a)
    return func() bool {
        stopped := false
        a.once.Do(func() {
            stopped = true
        })
        if stopped {
            a.cancel(true, Canceled, nil)
        }
        return stopped
    }
}

type afterFuncCtx struct {
    cancelCtx
    once sync.Once
    f    func()
}

func (a *afterFuncCtx) cancel(removeFromParent bool, err, cause error) {
    a.cancelCtx.cancel(false, err, cause)
    if removeFromParent {
        removeChild(a.Context, a)
    }
    a.once.Do(func() {
        go func() {
            defer a.cancelCtx.cancel(true, ErrCanceled, nil)
            a.f()
        }()
    })
}

Slightly simplified. Note: - propagateCancel adds a as a child of ctx. - The cancel method is called when ctx is cancelled (via the parent chain) OR when stop is called. - The once.Do inside cancel ensures f runs at most once. - The goroutine launched runs f, then cancels a itself (so children of a are also cancelled).

This is roughly 30 lines of Go that implement the entire AfterFunc primitive. Elegantly small.

Appendix: Notes for Runtime Contributors¶

If you contribute to the Go runtime, things to know: - Defers and panics are deeply intertwined with the scheduler. Changes require regression tests. - The defer record format is part of the runtime ABI; changes are versioned. - The compiler emits PCDATA tables that the runtime walks during panic; both sides must agree. - The unsafe.Pointer usage in panic.go is essential and brittle; review carefully.

The Go contribution guide explains the testing infrastructure (all.bash, race detector, etc.). Cleanup-related changes must pass: - All standard tests. - The race detector. - Stress tests (runtime: stress). - Benchmarks (no regression in defer/panic micro-benchmarks).

If your change is in the cleanup hot path, expect detailed review.

Appendix: A Question to Test Your Internals Knowledge¶

Read the following code carefully. What is the minimum memory allocated per call to f?

func f() {
    defer cleanup()
    defer trace()
    return
}

func cleanup() {}
func trace() {}

Answer: zero. Both defers are open-coded. The defer bits and arg slots are part of the stack frame, which is reused. No heap allocation.

Compare:

func g() {
    for i := 0; i < 10; i++ {
        defer cleanup()
    }
}

Answer: 10 _defer records, each ~80 bytes. About 800 bytes of heap per call to g. Plus the per-P pool may amortise some of it, but on a cold cache, full allocation.

The difference between f and g is the difference between "free" and "expensive" defers. Knowing why is a senior+ skill; being able to predict it from reading is the professional level.

Closing¶

The runtime is large. The cleanup machinery is one corner of it — well-defined, mostly stable, occasionally extended (1.14, 1.21). Understanding how it works in detail is a useful skill but rarely a daily one.

If you have read this far, you are equipped to: - Debug performance issues involving defers. - Write libraries that wrap defer/AfterFunc with confidence. - Contribute to the runtime if you wish. - Teach Go at the deepest level.

The remaining files in this sub-topic (specification, interview, tasks, find-bug, optimize) are practical complements. The senior file is where the design wisdom lives. This file is where the engineering details live. Together they form the complete picture of cleanup ordering in Go.

Good luck.

Deep Dive: A Tour Through the Defer Source¶

The next sections do a tour of the runtime source, function by function, file by file. The Go runtime is written in Go (with sprinkles of assembly). Reading it requires comfort with low-level patterns: unsafe pointers, atomic operations, go:nosplit directives, and stack manipulation.

The G's defer field¶

In runtime/runtime2.go, the goroutine struct (g) has a field:

type g struct {
    // ... many fields ...
    _defer *_defer
    _panic *_panic
    // ...
}

These two pointers are the head of two singly-linked lists, both per-goroutine. Defers and panics travel together: each _defer may reference the panic it was created during; each _panic may reference defers as they execute.

The G struct is allocated once per goroutine, on creation, and lives until the goroutine exits. Its fields are accessed without locking (it is per-goroutine). The defer chain head changes as defers are pushed and popped, but only by the goroutine itself.

newdefer in detail¶

newdefer allocates a _defer record. It is called by deferproc (the compiler-emitted defer registration function).

func newdefer(siz int32) *_defer {
    var d *_defer
    sc := deferclass(uintptr(siz))
    gp := getg()
    if sc < uintptr(len(p{}.deferpool)) {
        pp := gp.m.p.ptr()
        if len(pp.deferpool[sc]) == 0 && sched.deferpool[sc] != nil {
            // grab from global pool
            systemstack(func() {
                lock(&sched.deferlock)
                for len(pp.deferpool[sc]) < cap(pp.deferpool[sc])/2 && sched.deferpool[sc] != nil {
                    d := sched.deferpool[sc]
                    sched.deferpool[sc] = d.link
                    d.link = nil
                    pp.deferpool[sc] = append(pp.deferpool[sc], d)
                }
                unlock(&sched.deferlock)
            })
        }
        if n := len(pp.deferpool[sc]); n > 0 {
            d = pp.deferpool[sc][n-1]
            pp.deferpool[sc][n-1] = nil
            pp.deferpool[sc] = pp.deferpool[sc][:n-1]
        }
    }
    if d == nil {
        systemstack(func() {
            total := roundupsize(totaldefersize(uintptr(siz)))
            d = (*_defer)(mallocgc(total, deferType, true))
        })
        if debugCachedWork {
            // Track adding this defer to the queue
        }
    }
    d.siz = siz
    d.heap = true
    return d
}

Simplified for readability. The flow: 1. Determine the size class for the defer (defers are grouped by argument size). 2. Look in the per-P pool. If empty, refill from the global pool. 3. If still empty, allocate from the heap. 4. Mark the record as heap-allocated.

The systemstack call switches to the system stack for the operations that require it (locking, heap allocation).

freedefer in detail¶

freedefer returns a _defer record to the pool:

func freedefer(d *_defer) {
    if d._panic != nil {
        freedeferpanic()
    }
    if d.fn != nil {
        freedeferfn()
    }
    if !d.heap {
        return
    }
    sc := deferclass(uintptr(d.siz))
    if sc >= uintptr(len(p{}.deferpool)) {
        return
    }
    pp := getg().m.p.ptr()
    if len(pp.deferpool[sc]) == cap(pp.deferpool[sc]) {
        // P-local pool is full, transfer half to global
        var first, last *_defer
        for len(pp.deferpool[sc]) > cap(pp.deferpool[sc])/2 {
            n := len(pp.deferpool[sc])
            d := pp.deferpool[sc][n-1]
            pp.deferpool[sc][n-1] = nil
            pp.deferpool[sc] = pp.deferpool[sc][:n-1]
            if first == nil {
                first = d
            } else {
                last.link = d
            }
            last = d
        }
        lock(&sched.deferlock)
        last.link = sched.deferpool[sc]
        sched.deferpool[sc] = first
        unlock(&sched.deferlock)
    }
    *d = _defer{}
    pp.deferpool[sc] = append(pp.deferpool[sc], d)
}

The flow: 1. Sanity checks (no in-flight panic, no fn). 2. If not heap-allocated, no-op. 3. If the P-local pool is full, transfer half to the global pool (under lock). 4. Zero the record and push onto the P-local pool.

This pattern — local cache, global overflow — is common throughout the Go runtime. It minimises contention.

deferproc in detail¶

deferproc is what the compiler calls at each defer statement:

//go:nosplit
func deferproc(siz int32, fn *funcval) {
    gp := getg()
    if gp.m.curg != gp {
        throw("defer on system stack")
    }

    sp := getcallersp()
    argp := uintptr(unsafe.Pointer(&fn)) + unsafe.Sizeof(fn)
    callerpc := getcallerpc()

    d := newdefer(siz)
    if d._panic != nil {
        throw("deferproc: d.panic != nil after newdefer")
    }
    d.link = gp._defer
    gp._defer = d
    d.fn = fn
    d.pc = callerpc
    d.sp = sp
    switch siz {
    case 0:
        // No args, nothing to copy
    case sys.PtrSize:
        *(*uintptr)(deferArgs(d)) = *(*uintptr)(unsafe.Pointer(argp))
    default:
        memmove(deferArgs(d), unsafe.Pointer(argp), uintptr(siz))
    }

    // deferproc returns 0 normally
    // If we panicked during deferproc, it returns 1
}

The flow: 1. Get the goroutine and validate state. 2. Get the caller's SP and PC. 3. Allocate a _defer record. 4. Link it at the head of the goroutine's defer chain. 5. Store the function and argument values.

Note the getcallersp() and getcallerpc() calls: these are compiler intrinsics that read the calling function's SP/PC. They are essential for matching defers to their owning frame.

deferreturn in detail¶

deferreturn is the function the compiler calls at the end of a function to run any pending defers:

//go:nosplit
func deferreturn(arg0 uintptr) {
    gp := getg()
    d := gp._defer
    if d == nil {
        return
    }
    sp := getcallersp()
    if d.sp != sp {
        return
    }
    if d.openDefer {
        done := runOpenDeferFrame(gp, d)
        if !done {
            throw("unfinished open-coded defers in deferreturn")
        }
        gp._defer = d.link
        freedefer(d)
        return
    }

    // copy args back
    switch d.siz {
    case 0:
    case sys.PtrSize:
        *(*uintptr)(unsafe.Pointer(&arg0)) = *(*uintptr)(deferArgs(d))
    default:
        memmove(unsafe.Pointer(&arg0), deferArgs(d), uintptr(d.siz))
    }
    fn := d.fn
    d.fn = nil
    gp._defer = d.link
    freedefer(d)
    jmpdefer(fn, uintptr(unsafe.Pointer(&arg0)))
}

Notable: - jmpdefer is an assembly function that performs a tail call into fn while preserving the deferreturn frame. After fn returns, control returns to deferreturn to process the next defer. - The arguments are copied back to the call site for the deferred call. - For open-coded defers, control delegates to runOpenDeferFrame.

jmpdefer assembly¶

In runtime/asm_amd64.s (and other architecture files), jmpdefer is a small assembly routine:

TEXT runtime·jmpdefer(SB), NOSPLIT, $0-16
    MOVQ    fv+0(FP), DX
    MOVQ    argp+8(FP), BX
    LEAQ    -8(BX), SP
    MOVQ    -8(SP), BP
    SUBQ    $5, (SP)
    JMP     0(DX)

This is a tail call: it sets up registers for the deferred function and jumps to it without growing the stack. The deferred function returns to deferreturn's return point, looking as if it had been called directly from deferreturn's caller.

This is why jmpdefer is not a regular call: a regular call would build a new stack frame each time, blowing the stack for many defers.

Deep Dive: Open-Coded Defer Internals¶

Open-coded defers were introduced in Go 1.14 (Keith Randall, "Toward a Better Defer"). The mechanism:

The bit vector¶

For each function with open-coded defers, the compiler allocates: - 1 byte for the defer bit vector (up to 8 defers). - N slots for argument storage, one per defer.

The bit vector is initialised to 0 at function entry. At each defer X statement, the compiler emits code to set the corresponding bit and store the argument values.

// At function entry:
   defer_bits = 0

// At "defer cleanup()" (defer index 0):
   defer_bits |= 1 << 0    // set bit 0
   // (no arguments to store)

// At "defer log(elapsed)" (defer index 1):
   defer_bits |= 1 << 1    // set bit 1
   defer_args_1 = elapsed  // store argument

// At function return:
   run deferreturn block

The deferreturn block¶

The compiler emits a special block at the function's exit. It tests each bit and runs the corresponding cleanup:

deferreturn_block:
   if defer_bits & (1 << 1) {
       call log(defer_args_1)
       defer_bits &= ^(1 << 1)
   }
   if defer_bits & (1 << 0) {
       call cleanup()
       defer_bits &= ^(1 << 0)
   }
   return

The bits are tested in reverse order (high bit first), which gives LIFO unwinding.

Reaching the deferreturn block on panic¶

When a function panics, the runtime needs to run the function's defers before unwinding further. For open-coded defers, the runtime jumps to the deferreturn block via the FUNCDATA tables.

The compiler emits a _FUNCDATA_OpenCodedDeferInfo entry for each function with open-coded defers. The runtime walks the stack on panic, finds each frame's FUNCDATA, and (if present) jumps to the deferreturn block to run the defers.

The FUNCDATA contains: - The offset of the defer bit vector within the frame. - The offsets of each defer's argument storage. - The PC to jump to for the deferreturn block. - A list of (PC range, active bits) pairs — what defers are registered at each PC range.

This lets the runtime know exactly which defers to run at any given PC.

Why this is fast¶

• No heap allocation.
• No linked-list traversal.
• The bit test is one comparison.
• The call is direct.

A function with one open-coded defer has effectively zero overhead beyond the cleanup call itself. This is why "always use defer" became viable advice after Go 1.14.

When the compiler bails out¶

The compiler examines the function during the walk pass. If it finds: - A defer inside a loop (any loop). - More than 8 defers. - A defer behind a goto or other unusual control flow. - A defer whose function is not statically known (rare, but possible with reflection-heavy code).

It bails out and emits heap defers instead. The fallback is correct but slower.

Diagnostics¶

Compile with -gcflags='-d=defer=2' to see the compiler's choice:

./main.go:5:2: defer cleanup() (open-coded)
./main.go:10:3: defer fmt.Println(i) (heap, in loop)

If a defer you expected to be open-coded is heap, the diagnostic explains why.

Code size impact¶

Open-coded defers grow the function's code somewhat: - 1 byte for the bit vector. - N slots for argument storage. - The cleanup logic in the deferreturn block (one branch per defer).

For 8 defers, this is roughly 1 byte + 8 slots + 50 bytes of code. Negligible.

Interaction with inlining¶

Functions with defers are not inlined. This is a deliberate trade-off: inlining would require duplicating the defer logic at every call site, which complicates the runtime's stack walking for panics. The decision keeps the runtime simple at the cost of one missed inlining opportunity per defer.

Deep Dive: Panic and Recover¶

The full gopanic flow¶

func gopanic(e interface{}) {
    gp := getg()
    if gp.m.curg != gp {
        // Panicking on the system stack is a programming error.
        throw("panic on system stack")
    }

    if gp.m.mallocing != 0 {
        throw("panic during malloc")
    }

    var p _panic
    p.arg = e
    p.link = gp._panic
    gp._panic = (*_panic)(noescape(unsafe.Pointer(&p)))

    runningPanicDefers.Add(1)

    addOneOpenDeferFrame(gp, getcallerpc(), unsafe.Pointer(getcallersp()))

    for {
        d := gp._defer
        if d == nil {
            break
        }

        if d.started {
            // Defer already started; this is a recursive panic during a defer.
            // Mark this panic as aborted and continue with the next defer.
            if d._panic != nil {
                d._panic.aborted = true
            }
            d._panic = nil
            if !d.openDefer {
                d.fn = nil
                gp._defer = d.link
                freedefer(d)
                continue
            }
        }
        d.started = true
        d._panic = (*_panic)(noescape(unsafe.Pointer(&p)))

        done := true
        if d.openDefer {
            done = runOpenDeferFrame(gp, d)
            if done {
                d._panic = nil
                d.fn = nil
            }
        } else {
            p.argp = unsafe.Pointer(getargp())
            fn := d.fn
            reflectcall(nil, unsafe.Pointer(fn), deferArgs(d), uint32(d.siz), uint32(d.siz))
        }
        p.argp = nil

        d._panic = nil
        d.fn = nil
        gp._defer = d.link
        pc := d.pc
        sp := unsafe.Pointer(d.sp)
        freedefer(d)
        if p.recovered {
            gp._panic = p.link
            if gp._panic != nil && gp._panic.goexit && gp._panic.aborted {
                // A normal recover() should ignore an aborted Goexit.
                gp.sigcode0 = uintptr(gp._panic.sp)
                gp.sigcode1 = uintptr(gp._panic.pc)
                mcall(recovery)
                throw("bypassed recovery failed")
            }
            runningPanicDefers.Add(-1)
            gp.sigcode0 = uintptr(sp)
            gp.sigcode1 = pc
            mcall(recovery)
            throw("recovery failed")
        }
    }

    preprintpanics(gp._panic)
    fatalpanic(gp._panic)
}

Major points: - The panic record is created on the goroutine's stack (no heap allocation for the panic itself). - The loop walks the defer chain. - For each defer, d.started is set so that nested panics can detect recursion. - For heap defers, reflectcall invokes the function with the stored arguments. - For open-coded defers, runOpenDeferFrame runs the function-level deferreturn block. - If recover set p.recovered, mcall(recovery) jumps to the recovery point.

mcall and recovery¶

mcall switches to the M's g0 stack (the scheduler stack) to perform an operation that cannot be done on the user goroutine's stack. recovery is one such operation: it manipulates the user stack to jump to the deferred function's caller's return point.

func recovery(gp *g) {
    sp := gp.sigcode0
    pc := gp.sigcode1
    if sp != 0 && (sp < gp.stack.lo || gp.stack.hi < sp) {
        print("recover: SP not on the goroutine's stack\n")
        throw("recovery failed")
    }
    gp.sched.sp = sp
    gp.sched.pc = pc
    gp.sched.lr = 0
    gp.sched.ret = 1
    gogo(&gp.sched)
}

This sets up the goroutine's saved registers to "return" with value 1 from deferproc (which is the signal to the compiler that a recovery occurred), and resumes execution.

Recover's mechanics¶

recover examines the panic state:

//go:nosplit
func gorecover(argp uintptr) interface{} {
    gp := getg()
    p := gp._panic
    if p != nil && !p.goexit && !p.recovered && argp == uintptr(p.argp) {
        p.recovered = true
        return p.arg
    }
    return nil
}

Conditions: - p != nil — a panic is in flight. - !p.goexit — not a Goexit (which cannot be recovered). - !p.recovered — not already recovered. - argp == p.argp — we are in the right deferred function.

The argp check is what restricts recover to deferred functions. The runtime sets p.argp to the deferred function's argp before calling it; recover reads its own caller's argp and compares.

Why recover returns nil outside a defer¶

If you call recover() outside a deferred function: - p is the in-flight panic (if any). - argp is the recover's caller's argp. - p.argp is the most recent deferred function's argp. - They do not match.

So recover returns nil.

Even more clearly: if no panic is in flight, p == nil and recover returns nil immediately.

Deep Dive: runtime.Goexit¶

The Goexit flow¶

func Goexit() {
    gp := getg()
    addOneOpenDeferFrame(gp, getcallerpc(), unsafe.Pointer(getcallersp()))

    for {
        d := gp._defer
        if d == nil {
            break
        }
        if d.started {
            if d._panic != nil {
                d._panic.aborted = true
                d._panic = nil
            }
            if !d.openDefer {
                d.fn = nil
                gp._defer = d.link
                freedefer(d)
                continue
            }
        }
        d.started = true
        d._panic = (*_panic)(unsafe.Pointer(&_panic{goexit: true}))

        if d.openDefer {
            done := runOpenDeferFrame(gp, d)
            if !done {
                addOneOpenDeferFrame(gp, 0, nil)
                break
            }
        } else {
            reflectcall(nil, unsafe.Pointer(d.fn), deferArgs(d), uint32(d.siz), uint32(d.siz))
        }
        if gp._defer != d {
            throw("bad defer entry in Goexit")
        }
        d._panic = nil
        d.fn = nil
        gp._defer = d.link
        freedefer(d)
    }
    goexit1()
}

The flow: - Walk the defer chain just like a panic. - Run each defer, marking goexit: true in the panic record so recover() will ignore it. - After all defers, call goexit1 to terminate the goroutine cleanly.

Note that Goexit creates a fake _panic record with goexit: true. This is what makes recover return nil during a Goexit unwind.

goexit1¶

func goexit1() {
    if raceenabled {
        racegoend()
    }
    if traceEnabled() {
        traceGoEnd()
    }
    mcall(goexit0)
}

func goexit0(gp *g) {
    _g_ := getg()
    casgstatus(gp, _Grunning, _Gdead)
    gp.m.curg = nil
    // ... clean up the goroutine ...
    schedule()
}

The goroutine is marked dead, the M is detached, and the scheduler picks the next runnable goroutine.

Why Goexit is separate from panic¶

The distinction matters because: - recover should not catch a Goexit. - A test framework calling t.FailNow wants to end the goroutine without aborting the program. - The defer chain must still run (for cleanup).

Goexit is the surgical tool. Panic is the dramatic one.

Deep Dive: context.AfterFunc Source Walk¶

Let's read the actual implementation in context/context.go.

The cancelCtx extensions¶

In Go 1.21, cancelCtx gained support for AfterFunc:

type cancelCtx struct {
    Context

    mu       sync.Mutex
    done     atomic.Value
    children map[canceler]struct{}
    err      error
    cause    error
}

The children map already existed; AfterFunc reuses it. Each afterFuncCtx is registered as a child.

afterFuncCtx¶

type afterFuncCtx struct {
    cancelCtx
    once sync.Once
    f    func()
}

It embeds a cancelCtx so it can be a child of another context. It carries the function f and a sync.Once to ensure single execution.

AfterFunc¶

func AfterFunc(ctx Context, f func()) (stop func() bool) {
    a := &afterFuncCtx{
        f: f,
    }
    a.cancelCtx.Context = ctx
    a.cancel(ctx.Done(), Canceled, nil)
    return func() bool {
        var stopped bool
        a.once.Do(func() {
            stopped = true
        })
        if stopped {
            a.cancel(true, Canceled, nil)
        }
        return stopped
    }
}

Wait — the real source is slightly different from this. Let's correct. The actual structure:

func AfterFunc(ctx Context, f func()) (stop func() bool) {
    a := &afterFuncCtx{
        f: f,
    }
    a.cancelCtx.Context = ctx
    propagateCancel(ctx, a)
    return func() bool {
        stopped := false
        a.once.Do(func() {
            stopped = true
        })
        if stopped {
            a.cancel(true, Canceled, nil)
        }
        return stopped
    }
}

propagateCancel is the function that registers a as a child of ctx. If ctx is already done, propagateCancel triggers a.cancel immediately.

propagateCancel¶

func propagateCancel(parent Context, child canceler) {
    done := parent.Done()
    if done == nil {
        return // parent is never cancelled
    }

    select {
    case <-done:
        // parent is already cancelled
        child.cancel(false, parent.Err(), Cause(parent))
        return
    default:
    }

    if p, ok := parentCancelCtx(parent); ok {
        p.mu.Lock()
        if p.err != nil {
            child.cancel(false, p.err, p.cause)
        } else {
            if p.children == nil {
                p.children = make(map[canceler]struct{})
            }
            p.children[child] = struct{}{}
        }
        p.mu.Unlock()
        return
    }

    // parent is a non-stdlib Context; spin a goroutine
    goroutines.Add(1)
    go func() {
        select {
        case <-parent.Done():
            child.cancel(false, parent.Err(), Cause(parent))
        case <-child.Done():
        }
    }()
}

The flow: - If parent is never cancellable, nothing to do. - If parent is already done, immediately cancel the child. - If parent is a standard cancelCtx, add child to its children map. - Otherwise, spin a goroutine that watches the parent.

The goroutine fallback is the price of supporting non-stdlib Context implementations.

cancelCtx.cancel¶

func (c *cancelCtx) cancel(removeFromParent bool, err, cause error) {
    if err == nil {
        panic("context: internal error: missing cancel error")
    }
    if cause == nil {
        cause = err
    }
    c.mu.Lock()
    if c.err != nil {
        c.mu.Unlock()
        return // already cancelled
    }
    c.err = err
    c.cause = cause
    d, _ := c.done.Load().(chan struct{})
    if d == nil {
        c.done.Store(closedchan)
    } else {
        close(d)
    }
    for child := range c.children {
        // NOTE: acquiring the child's lock while holding parent's lock
        child.cancel(false, err, cause)
    }
    c.children = nil
    c.mu.Unlock()

    if removeFromParent {
        removeChild(c.Context, c)
    }
}