Cancellation Propagation — Professional Level¶

Table of Contents¶

1. Scope
2. The context Package Implementation
3. How WithCancel Builds the Tree
4. The Closed-Channel Trick
5. Scheduler Interactions
6. Cost of select with ctx.Done()
7. AfterFunc Internals
8. WithCancelCause and Cause
9. WithoutCancel
10. Custom Context Implementations
11. Cancellation Latency in the Scheduler
12. Memory Footprint of the Context Tree
13. Garbage Collection of Contexts
14. Performance Benchmarks
15. Cancellation Under High Concurrency
16. Cancellation Race Conditions
17. Cross-process Implementations
18. Incident Post-Mortems
19. Patterns That Push the Limits
20. Cheat Sheet for Professionals
21. Summary
22. Further Reading

Scope¶

This file dives into the internals: how context.Context is implemented, what cancellation costs in the Go runtime, the race conditions that production code must defend against, and the lessons from large-scale incidents. The audience is engineers who design infrastructure libraries, debug production cancellation bugs, or optimise services for low-latency shutdown.

The patterns described at junior, middle, and senior level remain correct; this file explains why they work and where they break under pressure.

A note on assertions and cancellation¶

Some code uses assertions to validate invariants. Cancellation may invalidate assertions silently.

func process(ctx context.Context, data Data) {
    intermediate := step1(ctx, data)
    if intermediate == nil {
        panic("invariant: step1 always returns non-nil")
    }
    finalize(ctx, intermediate)
}

If step1 is cancellable and returns nil on cancellation, the panic fires. Either:

• The assertion is wrong (step1 can return nil), and the code is unprepared.
• The assertion is right (step1 should never return nil), and cancellation is the bug.

Better:

func process(ctx context.Context, data Data) error {
    intermediate, err := step1(ctx, data)
    if err != nil {
        return err
    }
    return finalize(ctx, intermediate)
}

Use error returns; assertions are for true invariants that cannot be violated by external events (like cancellation).

Cancellation in distributed counting¶

A subtle case: counting events across many goroutines while supporting cancellation. The naive approach uses a shared counter under a mutex; this works but contends under high write rates.

var counter int64
for _, item := range items {
    item := item
    g.Go(func() error {
        if err := process(ctx, item); err != nil {
            return err
        }
        atomic.AddInt64(&counter, 1)
        return nil
    })
}

On cancellation, the counter reflects partial work — the items processed before cancel. This is usually fine.

For more sophisticated counting (per-tenant, per-status), use per-goroutine counters reduced at the end:

results := make([]int64, len(items))
for i, item := range items {
    i, item := i, item
    g.Go(func() error {
        if err := process(ctx, item); err != nil {
            return err
        }
        results[i] = 1
        return nil
    })
}
// after Wait
total := int64(0)
for _, r := range results {
    total += r
}

Per-index slot avoids contention. The reduce is sequential but fast.

For very large fan-outs, use sharded counters or expvar.Int for atomic-ish counting with low contention.

Reading the runtime source for cancellation¶

The Go runtime source is fast to read once you know where to look. For cancellation:

• src/context/context.go: the package itself.
• src/runtime/chan.go: channel operations, including close.
• src/runtime/proc.go: scheduler, including parking and waking.
• src/runtime/select.go: select implementation.
• src/runtime/sema.go: semaphores used by sync.Mutex.

Reading these gives a deeper understanding of "what happens when cancel fires." The structures are well-named; the comments are extensive.

Notable functions¶

• closechan (chan.go): closes a channel and wakes waiters.
• gopark (proc.go): parks the calling goroutine.
• goready (proc.go): readies a goroutine to be scheduled.
• selectgo (select.go): implements select.

Tracing through cancel -> close -> closechan -> goready -> selectgo wakes up gives a complete picture.

Resources¶

The Go source has docs and design notes in src/runtime/HACKING.md and src/runtime/README.md. The scheduler design doc by Dmitry Vyukov is widely available.

Context package: design history¶

Worth understanding where context.Context came from before diving into internals.

context was originally an internal Google package, used heavily in the net/http and RPC libraries. It was promoted to the standard library in Go 1.7 (2016). The design was driven by:

• Need for cancellation in long-running RPC operations.
• Need to carry per-request values (trace IDs, auth) without polluting every function signature.
• Desire to make cancellation composable across library boundaries.

The choices that shaped it:

• Interface, not concrete type: lets users implement custom contexts (testing, wrapping).
• Immutable by With* API: each derivation returns a new context; the parent is unchanged. Safe for concurrent use.
• Cancellation via channel close: leverages the existing channel primitive rather than introducing a new sync mechanism.
• Optional value bag: useful but easily abused.
• Per-derivation cancel function: explicit ownership of when to release.

The criticisms over time:

• "Why pass context as first parameter instead of last?" Convention; could have gone either way. The first-parameter rule is enforced by linters now.
• "Why is value lookup not type-safe?" Pragmatic — interface{} (now any) for the value, no generics at the time of design.
• "Why no Set after creation?" Immutability is a feature; concurrent safety would require locks otherwise.
• "Why a tree, not a flat list?" Hierarchical cancellation is a feature; cancelling a parent cancels descendants.

Despite the criticisms, no replacement has emerged. The API is stable; the ecosystem is built around it.

The context Package Implementation¶

The context package is implemented in src/context/context.go (go/src/context/). It is roughly 800 lines of Go, surprisingly compact for the role it plays in every modern Go program.

The interface¶

type Context interface {
    Deadline() (deadline time.Time, ok bool)
    Done() <-chan struct{}
    Err() error
    Value(key any) any
}

Four methods. Each context type implements them. The interface is the entire surface; everything else is helper functions.

Concrete types¶

The implementation has a handful of concrete types:

• emptyCtx — the value returned by Background() and TODO(). Always-on, always-empty.
• cancelCtx — what WithCancel returns. Holds the cancel state.
• timerCtx — what WithTimeout and WithDeadline return. Embeds cancelCtx plus a timer.
• valueCtx — what WithValue returns. Holds a key/value pair plus the parent.
• afterFuncCtx — the type registered by AfterFunc. Hidden from the public API.

The hierarchy is:

Context (interface)
├── emptyCtx (background/todo)
├── valueCtx (parent + key/value)
├── cancelCtx (parent + cancel state)
│     └── timerCtx (cancelCtx + timer)
└── withoutCancelCtx (parent values, no cancellation)

Each derived context embeds or composes the parent. Walking up the chain reaches Background.

emptyCtx¶

type emptyCtx struct{}

func (emptyCtx) Deadline() (time.Time, bool) { return time.Time{}, false }
func (emptyCtx) Done() <-chan struct{}        { return nil }
func (emptyCtx) Err() error                   { return nil }
func (emptyCtx) Value(any) any                { return nil }

The methods all return zero values. Done() returning nil is critical: a select case on a nil channel never fires, so case <-ctx.Done(): on Background is effectively a no-op case. The receive blocks forever (but in a select, the case is never chosen because nil-channel cases are never ready).

Background and TODO are pointers to package-level variables:

var (
    background = new(emptyCtx)
    todo       = new(emptyCtx)
)

func Background() Context { return background }
func TODO() Context       { return todo }

Two singleton instances. The difference is convention only: Background for "real root context," TODO for "I have not decided yet." Linters distinguish them.

valueCtx¶

type valueCtx struct {
    Context
    key, val any
}

func (c *valueCtx) Value(key any) any {
    if c.key == key {
        return c.val
    }
    return c.Context.Value(key)
}

Embeds the parent Context; overrides Value to check its own key first, then delegates to the parent. Looking up a value walks the chain until the key is found or the chain ends.

Performance note: Value is O(depth of chain). For deeply nested contexts this can be slow. In practice, depth is small (typically 1-5).

Looking at the runtime trace¶

Go's runtime trace (go tool trace) captures every goroutine event. For cancellation, you see:

• The cancel call.
• Each goroutine waking up from <-ctx.Done().
• The order in which they were scheduled.
• The time spent waiting between wake and run.

A typical cancel trace shows:

• cancel() at time t0.
• 100 goroutines marked "runnable" by t0+5us.
• Goroutines start running on available P's from t0+5us onwards.
• Last goroutine finishes by t0+50us.

This level of detail is invaluable for tuning. If you see goroutines waiting milliseconds between "runnable" and "running," the scheduler is over-subscribed; consider increasing GOMAXPROCS or reducing per-goroutine work.

The trace output is heavy (megabytes per second of recording), but the insights are uniquely detailed.

In-depth: the cancelCtxKey magic¶

The context package uses a sentinel to identify cancel contexts within the value lookup machinery:

var cancelCtxKey int

This unexported variable is used as a key in Value lookups:

func (c *cancelCtx) Value(key any) any {
    if key == &cancelCtxKey {
        return c
    }
    return value(c.Context, key)
}

When someone calls ctx.Value(&cancelCtxKey), the lookup walks the chain. When it hits a cancelCtx, the special case returns the context itself.

This allows parentCancelCtx to find an ancestor cancel context even if there are valueCtx wrappers in between:

parent -> valueCtx{k:"trace"} -> cancelCtx -> Background
                                     ^
              ctx.Value(&cancelCtxKey) finds this one

The clever bit: the key is unexported, so external code cannot accidentally collide with it. The mechanism is internal to the package.

This is also why custom context implementations can't participate in the fast path — they would need to know about cancelCtxKey and respond to it, but it is unexported.

There is a similar trick for WithoutCancel:

func (withoutCancelCtx) Value(key any) any {
    if key == &cancelCtxKey {
        return nil // explicitly mask the parent's cancel context
    }
    return c.c.Value(key)
}

This is how WithoutCancel detaches: it intercepts the cancelCtxKey lookup and returns nil, preventing the cancel propagation logic from finding the ancestor.

These internal details are not API; they are implementation. But understanding them helps decode the source.

A more thorough look at done lazy initialisation¶

The cancelCtx does not allocate its done channel until first call to Done():

func (c *cancelCtx) Done() <-chan struct{} {
    d := c.done.Load()
    if d != nil {
        return d.(chan struct{})
    }
    c.mu.Lock()
    defer c.mu.Unlock()
    d = c.done.Load()
    if d == nil {
        d = make(chan struct{})
        c.done.Store(d)
    }
    return d.(chan struct{})
}

Double-checked locking. The first load is atomic-only (fast path). If nil, take the lock, load again under lock, and create if still nil.

Why lazy? Because most cancelable contexts are never observed via Done(). They are used for value passing, or for Err() checks, but the channel itself is never selected on. Lazy creation avoids allocating channels for unobserved contexts.

The cancel method handles the lazy case:

d, _ := c.done.Load().(chan struct{})
if d == nil {
    c.done.Store(closedchan)
} else {
    close(d)
}

If Done() was never called, the channel is nil. Store the package-level pre-closed channel. Any future Done() call returns the closed channel; any future select on Done() fires immediately.

This is a small but cumulative optimisation. Across millions of contexts, the saved allocations add up.

Anatomy of cancelCtx¶

A more detailed walkthrough of cancelCtx and how cancellation cascades.

The canceler interface¶

The package defines an internal interface:

type canceler interface {
    cancel(removeFromParent bool, err, cause error)
    Done() <-chan struct{}
}

Both *cancelCtx and *timerCtx implement it. The cascade walks this interface; concrete types extend behaviour (e.g. timerCtx.cancel also stops the timer).

The propagateCancel reasoning¶

The function has two paths:

• Parent is a *cancelCtx: register in children map. When parent cancels, it iterates and cancels each child synchronously.
• Parent is not a *cancelCtx: spawn a goroutine that waits on parent's Done and then cancels the child.

The optimisation for the fast path avoids creating a watcher goroutine when one is not needed. For deeply nested WithCancel chains (all standard cancel contexts), no extra goroutines are created.

The slow path matters when:

• You use a custom Context implementation that is not a *cancelCtx.
• You wrap a *cancelCtx in a valueCtx and then call WithCancel again — wait, this case is handled. Let me look at parentCancelCtx:

func parentCancelCtx(parent Context) (*cancelCtx, bool) {
    done := parent.Done()
    if done == closedchan || done == nil {
        return nil, false
    }
    p, ok := parent.Value(&cancelCtxKey).(*cancelCtx)
    if !ok {
        return nil, false
    }
    pdone, _ := p.done.Load().(chan struct{})
    if pdone != done {
        return nil, false
    }
    return p, true
}

It uses Value with a magic key (cancelCtxKey) that cancelCtx.Value returns self for:

func (c *cancelCtx) Value(key any) any {
    if key == &cancelCtxKey {
        return c
    }
    return value(c.Context, key)
}

So even if you wrap a cancelCtx in a valueCtx, the Value(&cancelCtxKey) call finds the underlying cancelCtx and the fast path is taken. This is a clever piece of API design.

Custom Context implementations do not respond to cancelCtxKey, so they take the slow path. If you implement a custom Context, you can opt into the fast path by responding to cancelCtxKey — but the key is unexported, making this impossible from outside the standard library.

Walking the cancel cascade by hand¶

Consider:

root := context.Background()
ctx1, cancel1 := context.WithCancel(root)
ctx2, cancel2 := context.WithTimeout(ctx1, time.Second)
ctx3, cancel3 := context.WithCancel(ctx2)
ctx4, cancel4 := context.WithValue(ctx3, "k", "v") // not cancellable directly

Wait, WithValue does not return a cancel function. Let me fix:

root := context.Background()
ctx1, cancel1 := context.WithCancel(root)
ctx2, cancel2 := context.WithTimeout(ctx1, time.Second)
ctx3, cancel3 := context.WithCancel(ctx2)

The tree:

• root is emptyCtx (singleton, Done() == nil).
• ctx1 is *cancelCtx with parent root. Since root.Done() == nil, propagateCancel returns early; no parent registration.
• ctx2 is *timerCtx with parent ctx1. ctx1 is a *cancelCtx, so ctx2 registers itself in ctx1.children.
• ctx3 is *cancelCtx with parent ctx2. ctx2 is a *cancelCtx (via embedding), so ctx3 registers in ctx2.children.

Calling cancel1:

1. ctx1.cancel runs. Lock. Set ctx1.err = Canceled. Close ctx1.done. Iterate children (ctx2).
2. ctx2.cancel runs. Lock. Set ctx2.err = Canceled (inheriting parent's err). Close ctx2.done. Stop ctx2.timer. Iterate children (ctx3).
3. ctx3.cancel runs. Lock. Set ctx3.err = Canceled. Close ctx3.done. No children.

All three contexts are cancelled. Calling cancel2 or cancel3 after is a no-op (idempotent).

Calling cancel3 first (before cancel1):

1. ctx3.cancel runs. Sets err, closes done. Removes self from ctx2.children.
2. ctx2.cancel and ctx1.cancel are unaffected. The tree partially cancels.

Calling cancel2 later:

1. ctx2.cancel runs. Cancels ctx2. No children (ctx3 already removed). Stops the timer.
2. ctx1 unaffected.

This is "structured concurrency" working: subtree cancellation does not affect siblings or ancestors.

How WithCancel Builds the Tree¶

func WithCancel(parent Context) (ctx Context, cancel CancelFunc) {
    c := withCancel(parent)
    return c, func() { c.cancel(true, Canceled, nil) }
}

func withCancel(parent Context) *cancelCtx {
    if parent == nil {
        panic("cannot create context from nil parent")
    }
    c := &cancelCtx{}
    c.propagateCancel(parent, c)
    return c
}

The cancelCtx struct:

type cancelCtx struct {
    Context

    mu       sync.Mutex            // protects following fields
    done     atomic.Value          // of chan struct{}, created lazily, closed by first cancel call
    children map[canceler]struct{} // set to nil by the first cancel call
    err      error                 // set to non-nil by the first cancel call
    cause    error                 // set to non-nil by the first cancel call
}

Key fields:

• done is an atomic.Value holding a chan struct{}. Lazy: created on first call to Done().
• children is a map of "things that should also be cancelled when this is." Filled by propagateCancel.
• err and cause record the cancellation reason. Set once.
• mu protects the children map and the error field.

propagateCancel¶

func (c *cancelCtx) propagateCancel(parent Context, child canceler) {
    c.Context = parent
    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 {
        // parent is a *cancelCtx, register as its child
        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 not a *cancelCtx, watch it via a goroutine
    goroutines.Add(1)
    go func() {
        select {
        case <-parent.Done():
            child.cancel(false, parent.Err(), Cause(parent))
        case <-child.Done():
        }
    }()
}

Two paths:

1. Parent is a *cancelCtx: register the child in the parent's children map. When the parent cancels, it iterates children and cancels each.
2. Parent is a custom Context (not a *cancelCtx): spawn a goroutine that watches the parent's Done channel and cancels the child when it fires.

The optimisation: known cancel-context parents do not need a watcher goroutine; the cancellation cascades through the map. Unknown parents (custom Context implementations) need the watcher.

This is why mixing in custom contexts can cost more goroutines than you expect.

cancel method¶

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 {
        child.cancel(false, err, cause)
    }
    c.children = nil
    c.mu.Unlock()

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

Walk through:

1. Lock.
2. If already cancelled, return (idempotent).
3. Record err and cause.
4. Close the done channel (or store the package-level pre-closed channel if Done() was never called).
5. Cascade to children.
6. Clear the children map.
7. Unlock.
8. Optionally remove self from parent's children map.

The cascade is synchronous: this cancel invokes each child's cancel, which invokes its grandchildren's, etc. The whole subtree is cancelled before this call returns.

For deep trees, the cascade is sequential and the call stack grows with depth. In practice, depth is small.

closedchan¶

var closedchan = make(chan struct{})

func init() {
    close(closedchan)
}

A package-level pre-closed channel. When cancel fires before Done() was ever called, it stores closedchan instead of allocating a new channel and closing it. This avoids an allocation for the common case "cancelled before anyone observed."

The next call to Done() returns closedchan, which is already closed; any select on it fires immediately.

This is a small optimisation that matters when you create many short-lived cancellable contexts.

timerCtx: the deadline variant¶

WithDeadline (and WithTimeout which wraps it) returns a *timerCtx:

type timerCtx struct {
    cancelCtx
    timer    *time.Timer
    deadline time.Time
}

func WithDeadline(parent Context, d time.Time) (Context, CancelFunc) {
    if parent == nil {
        panic("cannot create context from nil parent")
    }
    if cur, ok := parent.Deadline(); ok && cur.Before(d) {
        // The current deadline is already sooner than the new one.
        return WithCancel(parent)
    }
    c := &timerCtx{
        deadline: d,
    }
    c.cancelCtx.propagateCancel(parent, c)
    dur := time.Until(d)
    if dur <= 0 {
        c.cancel(true, DeadlineExceeded, nil)
        return c, func() { c.cancel(false, Canceled, nil) }
    }
    c.mu.Lock()
    defer c.mu.Unlock()
    if c.err == nil {
        c.timer = time.AfterFunc(dur, func() {
            c.cancel(true, DeadlineExceeded, nil)
        })
    }
    return c, func() { c.cancel(true, Canceled, nil) }
}

Key points:

• If parent's deadline is already sooner, just use WithCancel(parent) — the parent's deadline will fire first anyway.
• If the deadline has already passed, cancel immediately.
• Otherwise, install a time.AfterFunc that cancels when the duration elapses.

The time.AfterFunc is scheduled in the runtime's timer wheel. When it fires, it runs the callback (cancel the context). The cancel cascades to children.

cancel for timerCtx:

func (c *timerCtx) cancel(removeFromParent bool, err, cause error) {
    c.cancelCtx.cancel(false, err, cause)
    if removeFromParent {
        removeChild(c.cancelCtx.Context, c)
    }
    c.mu.Lock()
    if c.timer != nil {
        c.timer.Stop()
        c.timer = nil
    }
    c.mu.Unlock()
}

Stops the timer to free its resources. Without this, the timer wheel would still hold a reference to the (now cancelled) context.

Timer resource costs¶

Each active timer in the wheel costs a small struct plus a slot in the data structure. The Go runtime can handle millions of timers efficiently, but there is a cost. defer cancel() is what releases the timer; without it, the timer survives until it fires.

This is the resource leak go vet flags as "lostcancel".

The Closed-Channel Trick¶

The fundamental primitive of cancellation propagation is "closing a channel broadcasts to every receiver." Let me dig into why this is so cheap.

What close does to a channel¶

A channel is a struct in the runtime (hchan in runtime/chan.go). It has:

• A buffer (for buffered channels).
• A send queue (goroutines blocked on send).
• A receive queue (goroutines blocked on receive).
• A closed flag.
• A lock.

close(ch) acquires the lock, sets the closed flag, drains the receive queue (each waiting goroutine is woken and resumes with the zero value plus ok == false), and unblocks any future receives. Future sends panic.

For a chan struct{} with no buffer and N goroutines blocked on receive, the close wakes all N. The wake is sequential: the goroutines are queued, and the close iterates the queue. Each wake is fast (an enqueue onto the scheduler's run queue), but N wakes still take O(N) time.

For N = 10, this is negligible. For N = 10 000, the close takes a few microseconds. For N = 1 000 000, it can take milliseconds. Most pipelines are far from that scale.

Why receivers see the close immediately¶

After close, any receive on the channel returns immediately. This is implemented by checking the closed flag inside the receive operation. A new receive after close does not block; it returns the zero value and false.

In select, the case <-done becomes "ready" the moment the close completes. The select picks it (or another ready case) on its next evaluation.

Why this matters for ctx.Done()¶

ctx.Done() returns a channel. cancel closes that channel. Every goroutine selecting on ctx.Done() is woken. The wake-up is the broadcast.

Compare to alternatives:

• Atomic boolean: if cancelled { return }. Each goroutine must poll explicitly. No wake-up.
• Condition variable: cond.Broadcast() wakes waiters but requires every waiter to hold a mutex. Not composable with channel operations.
• Per-goroutine notification: each goroutine has its own signal channel. The canceller iterates and signals each. O(N) work for the canceller, but no shared close.

The closed-channel approach is the sweet spot: O(1) canceller work, automatic compatibility with select, and the runtime handles wake-up efficiently.

Channel close: a deeper look at hchan¶

The chan struct{} used by Done() is a runtime.hchan. The relevant structure (simplified from runtime/chan.go):

type hchan struct {
    qcount   uint           // total data in the queue
    dataqsiz uint           // size of the circular queue
    buf      unsafe.Pointer // points to an array of dataqsiz elements
    elemsize uint16
    closed   uint32
    elemtype *_type
    sendx    uint
    recvx    uint
    recvq    waitq // list of recv waiters
    sendq    waitq // list of send waiters
    lock     mutex
}

closed is a flag; recvq is the list of goroutines waiting to receive.

The closechan runtime function (called by close()):

func closechan(c *hchan) {
    if c == nil {
        panic(plainError("close of nil channel"))
    }
    lock(&c.lock)
    if c.closed != 0 {
        unlock(&c.lock)
        panic(plainError("close of closed channel"))
    }
    c.closed = 1
    // wake up all readers
    var glist gList
    for {
        sg := c.recvq.dequeue()
        if sg == nil {
            break
        }
        if sg.elem != nil {
            typedmemclr(c.elemtype, sg.elem)
            sg.elem = nil
        }
        if sg.releasetime != 0 {
            sg.releasetime = cputicks()
        }
        gp := sg.g
        gp.param = unsafe.Pointer(sg)
        sg.success = false
        if raceenabled {
            raceacquireg(gp, c.raceaddr())
        }
        glist.push(gp)
    }
    // wake up all writers (they will panic)
    for {
        sg := c.sendq.dequeue()
        if sg == nil {
            break
        }
        // ... similar handling ...
        glist.push(gp)
    }
    unlock(&c.lock)
    for !glist.empty() {
        gp := glist.pop()
        gp.schedlink = 0
        goready(gp, 3)
    }
}

What we see:

1. Lock the channel.
2. Set closed = 1.
3. Dequeue every waiting receiver; for each, mark as not-successful and add to a wake list.
4. Dequeue every waiting sender (these will panic upon waking — sending to a closed channel panics, but the convention "owner closes" prevents this).
5. Unlock the channel.
6. Wake every goroutine in the list via goready.

The interesting bit: the wake-up is after the unlock. The lock is held only for the dequeue, not for the actual goready calls. This means the close is fast even with many receivers; the wake-up happens off the critical path.

goready adds the goroutine to a P's local run queue (or the global one). The scheduler picks it up on the next iteration.

Latency budget for close-and-wake¶

• Lock: tens of nanoseconds (uncontended) to microseconds (contended).
• Per-receiver dequeue: tens of nanoseconds.
• Wake (goready): tens of nanoseconds per goroutine.
• Receiver running its next instruction: depends on scheduler load.

For 1 receiver: 100 ns total. For 100 receivers: 10 microseconds. For 10 000 receivers: ~1 millisecond.

This is the actual latency budget for "cancellation broadcast." It explains why cancellation is "fast enough" for most pipelines but becomes measurable at very large scales.

Scheduler Interactions¶

When a goroutine is blocked on <-ctx.Done(), it is in the scheduler's "blocked" state. The scheduler removes it from the run queue and parks it on the channel's receive queue.

When close(done) runs, the scheduler walks the receive queue and re-queues each goroutine onto the run queue. They become runnable.

The runtime preempts (or schedules) them on available threads. The wake-up latency is:

• Time to walk the receive queue (microseconds for typical sizes).
• Time for the scheduler to pick the goroutine up on a thread (typically nanoseconds to single-digit microseconds).

The total: sub-millisecond for almost any scenario.

Cancellation during blocking I/O¶

If a goroutine is blocked in a system call (e.g. read on a socket), it is parked by the OS, not the Go scheduler. Closing ctx.Done() does not wake it. The goroutine must be woken some other way:

• The I/O completes naturally.
• The I/O fails (the file descriptor is closed elsewhere).
• A deadline on the I/O fires.

This is why cancellation must be plumbed into the I/O layer (via SetReadDeadline, db.QueryContext, etc.). The ctx.Done() close alone does not wake a goroutine in a syscall.

Cancellation under high goroutine count¶

The Go scheduler scales well. Closing a channel with 100 000 receivers takes a millisecond or so. The bottleneck is the OS scheduling of the runtime threads. On a busy host, the latency can climb.

For a service that needs to cancel 100 000 goroutines in under a second, this is fine. For 1 million goroutines in under a millisecond, you may want to engineer alternatives (per-shard cancellation, hierarchical fan-out).

Cost of select with ctx.Done()¶

A select with N cases has overhead proportional to N. Each iteration:

1. Builds an array of cases.
2. Checks each case for readiness.
3. If any are ready, picks one at random (and executes it).
4. If none are ready, parks the goroutine in each case's queue.
5. On wake-up, removes from the other queues.

For 2-3 cases, the cost is tens of nanoseconds. Negligible for most code.

For tight loops where the select runs millions of times per second, the cost adds up. Optimisations:

• Cache done := ctx.Done() outside the loop.
• Avoid extra cases that are rarely ready.
• Use atomic flags for hot-path checks, with select for the rare slow path.

Micro-benchmarking your specific hot path is the right way to decide.

Benchmark example¶

func BenchmarkSelectCtxDone(b *testing.B) {
    ctx := context.Background()
    in := make(chan int, 1)
    in <- 1
    for i := 0; i < b.N; i++ {
        select {
        case <-in:
        case <-ctx.Done():
        }
        in <- 1
    }
}

On a modern machine: roughly 20-50 ns per iteration. For most pipelines, this is well under the per-item work cost and is invisible.

When the cost matters¶

In CPU-bound inner loops processing millions of items per second per goroutine, even 20 ns adds up to 2% of CPU. If you measure and find select overhead is the bottleneck, options:

• Move the cancel check outside the hot loop. Check ctx.Err() every 1000 iterations.
• Use a buffered channel as the input; let the buffer absorb load and check cancellation between batches.
• Profile to confirm; sometimes the GC or per-item work is the actual culprit.

Go scheduler basics relevant to cancellation¶

The Go scheduler is GMP: G (goroutine), M (OS thread), P (processor / scheduling context). The relevant pieces:

• Each P has a local run queue of runnable goroutines.
• M's run goroutines from their associated P's queue.
• When a goroutine blocks, it is parked off the run queue.
• When unblocked, it is enqueued onto a P's run queue.

For cancellation:

• A goroutine waiting on <-ctx.Done() is parked on the channel's recvq.
• cancel() calls close(done), which iterates recvq and re-queues each goroutine.
• The scheduler picks them up on next iteration.

The wake-up delay is:

• For a goroutine that was on a P's run queue: nanoseconds.
• For a goroutine that needs to be migrated: microseconds.
• Under heavy load (all P's busy): milliseconds while waiting for a slot.

GOMAXPROCS determines the number of P's. Increasing it speeds up cancellation under load (more parallelism for wake-ups) but increases overall scheduler overhead.

Preemption and cancellation¶

Go's async preemption (since 1.14) allows the runtime to interrupt a running goroutine at safe points and reschedule. This means even a CPU-bound goroutine that does not select on ctx.Done() will eventually be preempted and the scheduler will check its status.

But preemption does not by itself cancel the goroutine. The goroutine must check ctx.Err() to know it should exit. Without the check, preemption merely moves the goroutine off-CPU briefly, then resumes it.

So: preemption gives the scheduler control; the goroutine must use that control to check cancellation.

Locking and cancellation¶

A goroutine holding a sync.Mutex cannot be cancelled until it releases the mutex. There is no Mutex.LockContext in the standard library; the operation is uninterruptible.

Workarounds:

• Use a channel-based lock that supports select:

type CtxMutex struct {
    ch chan struct{}
}

func New() *CtxMutex {
    return &CtxMutex{ch: make(chan struct{}, 1)}
}

func (m *CtxMutex) Lock(ctx context.Context) error {
    select {
    case m.ch <- struct{}{}:
        return nil
    case <-ctx.Done():
        return ctx.Err()
    }
}

func (m *CtxMutex) Unlock() {
    <-m.ch
}

A 1-element buffered channel as a mutex. Lock-by-send (blocking until the buffer has room), Unlock-by-receive. The Lock can wait on <-ctx.Done().

The trade-off: this lock is slower than sync.Mutex (no fast path, no spinning) but is cancellable. Use for locks held across long operations.

AfterFunc Internals¶

context.AfterFunc was added in Go 1.21. It registers a callback to run when a context is cancelled.

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

Internally, AfterFunc creates an afterFuncCtx that subscribes to the parent's cancellation. When cancellation fires, the callback runs.

Why use AfterFunc instead of a watcher goroutine?

• No goroutine for the wait. The callback is invoked from the canceller's cascade, not a separate goroutine.
• Built-in unregistration. The stop function detaches the callback.
• Cleaner code. No explicit <-ctx.Done() plus separate cancel() plumbing.

Cost: a small alloc per registration. Use when you have many short-lived "do this on cancel" hooks (e.g. per-request cleanup).

Caveat: the callback runs from the cancelling goroutine. It must be fast and non-blocking, or it will delay other cancellations in the cascade.

WithCancelCause and Cause¶

WithCancelCause (Go 1.20+) returns a context that can be cancelled with a custom error.

func WithCancelCause(parent Context) (ctx Context, cancel CancelCauseFunc) {
    c := withCancel(parent)
    return c, func(cause error) { c.cancel(true, Canceled, cause) }
}

func Cause(c Context) error {
    if cc, ok := c.Value(&cancelCtxKey).(*cancelCtx); ok {
        cc.mu.Lock()
        defer cc.mu.Unlock()
        return cc.cause
    }
    return c.Err()
}

The cause is stored in the cancelCtx.cause field. Cause(ctx) walks up the tree (via Value) to find the nearest cancelCtx and returns its cause.

The reason Cause uses Value traversal: it must work even if the context has been wrapped in WithValue since the cancel was set. The traversal finds the cancelling ancestor.

ctx.Err() still returns Canceled for compatibility. Cause(ctx) returns the rich reason. Both are part of the public API.

Use it for debuggability¶

Logging Cause(ctx) at the cancellation boundary gives "why was this cancelled?" with the actual reason. Logging ctx.Err() gives "Canceled" — useless for diagnosis.

if ctx.Err() != nil {
    log.Printf("operation cancelled: %v", context.Cause(ctx))
    return ctx.Err()
}

The log captures the cause; the return preserves error compatibility.

How Cause traverses the tree¶

context.Cause(ctx) returns the cause associated with the cancellation. The implementation:

func Cause(c Context) error {
    if cc, ok := c.Value(&cancelCtxKey).(*cancelCtx); ok {
        cc.mu.Lock()
        defer cc.mu.Unlock()
        return cc.cause
    }
    return c.Err()
}

It calls c.Value(&cancelCtxKey), which the cancelCtx.Value method special-cases to return self. This walks up the chain through any valueCtxs until it finds a cancelCtx.

If found, it returns the cause field. If not (no cancel context anywhere in the chain), it falls back to c.Err().

Why this design? Because the cause may have been set on a parent context (e.g. via cancel(myErr) on the parent), and any descendant should be able to learn it.

Subtle: if both a parent and a child have causes, which one wins? The nearest cancelled cancelCtx in the chain. So if a child is cancelled with its own cause before the parent, the child's cause is returned. If the parent cancels first (cascading to the child), the parent's cause is propagated through cancel(removeFromParent, err, cause) and stored on each descendant.

The result: Cause(ctx) returns the most specific cause known to that context's subtree.

WithoutCancel¶

WithoutCancel (Go 1.21+) is a context that does not propagate cancellation from its parent.

type withoutCancelCtx struct {
    c Context
}

func (withoutCancelCtx) Deadline() (time.Time, bool) { return time.Time{}, false }
func (withoutCancelCtx) Done() <-chan struct{}        { return nil }
func (withoutCancelCtx) Err() error                   { return nil }
func (c withoutCancelCtx) Value(key any) any           { return c.c.Value(key) }

The parent's values are preserved; cancellation is not. Useful for "this background task should outlive the request that triggered it":

func handler(ctx context.Context) {
    err := work(ctx)
    if err != nil {
        // log the failure even if ctx cancelled
        go logFailure(context.WithoutCancel(ctx), err)
    }
}

logFailure keeps the request's trace ID and other values, but is not affected by the request's cancellation. It runs to completion.

Be careful with this — WithoutCancel is an escape hatch from structured concurrency. Use it only when you specifically need to detach from the parent's cancellation. If the detached work goes wrong, the structure cannot help you find it.

A deep example: implementing a context-aware worker pool from scratch¶

Putting it all together: a production-grade worker pool with all the right cancellation behaviour.

type Pool struct {
    mu      sync.Mutex
    closed  bool
    workers []chan job
    submit  chan job
    ctx     context.Context
    cancel  context.CancelCauseFunc
    wg      sync.WaitGroup
}

type job struct {
    ctx context.Context
    run func(context.Context) error
    res chan error
}

func New(parent context.Context, workers, buf int) *Pool {
    ctx, cancel := context.WithCancelCause(parent)
    p := &Pool{
        submit: make(chan job, buf),
        ctx:    ctx,
        cancel: cancel,
    }
    p.workers = make([]chan job, workers)
    p.wg.Add(workers)
    for i := 0; i < workers; i++ {
        p.workers[i] = make(chan job)
        go p.runWorker(p.workers[i])
    }
    p.wg.Add(1)
    go p.dispatch()
    return p
}

func (p *Pool) runWorker(ch chan job) {
    defer p.wg.Done()
    for {
        select {
        case <-p.ctx.Done():
            return
        case j, ok := <-ch:
            if !ok {
                return
            }
            // Combined context: cancel if either job or pool cancels
            jobCtx, jobCancel := context.WithCancel(j.ctx)
            stop := context.AfterFunc(p.ctx, jobCancel)
            err := j.run(jobCtx)
            stop()
            jobCancel()
            j.res <- err
        }
    }
}

func (p *Pool) dispatch() {
    defer p.wg.Done()
    nextWorker := 0
    for {
        select {
        case <-p.ctx.Done():
            // close all worker channels
            for _, w := range p.workers {
                close(w)
            }
            return
        case j := <-p.submit:
            // round-robin
            target := p.workers[nextWorker]
            nextWorker = (nextWorker + 1) % len(p.workers)
            select {
            case target <- j:
            case <-p.ctx.Done():
                j.res <- p.ctx.Err()
                return
            }
        }
    }
}

func (p *Pool) Submit(ctx context.Context, fn func(context.Context) error) error {
    p.mu.Lock()
    if p.closed {
        p.mu.Unlock()
        return errors.New("pool closed")
    }
    p.mu.Unlock()

    res := make(chan error, 1)
    j := job{ctx: ctx, run: fn, res: res}
    select {
    case p.submit <- j:
    case <-ctx.Done():
        return ctx.Err()
    case <-p.ctx.Done():
        return p.ctx.Err()
    }
    select {
    case err := <-res:
        return err
    case <-ctx.Done():
        return ctx.Err()
    }
}

func (p *Pool) Close() {
    p.mu.Lock()
    if p.closed {
        p.mu.Unlock()
        return
    }
    p.closed = true
    p.mu.Unlock()
    p.cancel(errors.New("pool closed"))
    p.wg.Wait()
}

Features:

• Bounded concurrency via per-worker channels.
• Per-job context combined with pool's context — either cancels the job.
• context.AfterFunc wires the pool's cancellation into the job's context without an extra goroutine.
• Cancellable Submit — respects both the caller's and pool's contexts.
• Cancellable Result — waiting for the result respects the caller's context.
• Graceful Close — cancels everything and joins.

The complexity reflects production realities: every place that can block must be cancellable from multiple directions.

Hidden subtleties of Value¶

context.WithValue is criticised for enabling implicit passing of parameters. But it has real subtleties worth knowing.

Value lookup walks the chain¶

func (c *valueCtx) Value(key any) any {
    if c.key == key {
        return c.val
    }
    return value(c.Context, key)
}

func value(c Context, key any) any {
    for {
        switch ctx := c.(type) {
        case *valueCtx:
            if key == ctx.key {
                return ctx.val
            }
            c = ctx.Context
        case *cancelCtx:
            if key == &cancelCtxKey {
                return ctx
            }
            c = ctx.Context
        case withoutCancelCtx:
            if key == &cancelCtxKey {
                return nil
            }
            c = ctx.c
        case *timerCtx:
            if key == &cancelCtxKey {
                return &ctx.cancelCtx
            }
            c = ctx.Context
        case backgroundCtx, todoCtx:
            return nil
        default:
            return c.Value(key)
        }
    }
}

A type switch over the context tree. Each layer either matches the key or delegates to the parent. Custom types fall through to c.Value(key) which is the interface method.

The cost is O(depth). For a tree of depth 5, the walk is 5 dispatches. For depth 50 (rare but possible), it is 50.

Comparable keys¶

The key in WithValue must be comparable (since the implementation does ==). String keys work but are dangerous because of collisions: two unrelated packages might both use "user_id" and clash.

The idiomatic key is a private unexported type:

type userIDKey struct{}

ctx = context.WithValue(ctx, userIDKey{}, uid)
// elsewhere:
uid, _ := ctx.Value(userIDKey{}).(string)

The struct type is unique to the package; no collision possible.

Performance of Value¶

In a hot path, Value is a measurable cost. The standard library uses it sparingly. If you find yourself doing ctx.Value in inner loops, cache the result outside the loop.

Custom Context Implementations¶

The Context interface is public; you can implement it. Common reasons:

• Test fixtures (fakeContext with controlled Done channel).
• Tracing wrappers that add span IDs.
• Aspect-oriented contexts that record values automatically.

A minimal custom implementation:

type myContext struct {
    parent  context.Context
    done    <-chan struct{}
    err     error
}

func (m *myContext) Deadline() (time.Time, bool) { return m.parent.Deadline() }
func (m *myContext) Done() <-chan struct{}        { return m.done }
func (m *myContext) Err() error                   { return m.err }
func (m *myContext) Value(key any) any            { return m.parent.Value(key) }

The catch: as noted in propagateCancel, if your custom type is not a *cancelCtx, the standard library will spawn a watcher goroutine for every WithCancel(myContext) call. This is correct but wasteful at scale.

For performance-critical code, embedding a cancelCtx (via a type alias trick) lets the standard library treat your type as a normal cancel context. The internal detail of "I am cancellable" is communicated via the Value method returning self for the magic cancelCtxKey. This is non-portable behaviour; prefer not to customise unless necessary.

Cancellation Latency in the Scheduler¶

A measurement: how long from cancel() to a goroutine's first instruction after <-ctx.Done()?

On a modern x86 server:

• cancel() itself: a few hundred nanoseconds (lock + close + iterate children).
• Goroutine wake-up: O(microseconds), depending on scheduler state.
• First instruction: another few hundred nanoseconds.

Total: 1-10 microseconds for a simple cancellation reaching a single waiting goroutine. For N waiters, the time is O(N) for the close itself but parallel for the post-wake-up execution.

Under heavy CPU contention (many goroutines runnable, few CPUs available), the latency can be 100 microseconds to milliseconds. The wake itself is fast; getting CPU time to run is the bottleneck.

Implications¶

For pipelines that cancel rarely (once per request), latency is negligible. For pipelines that re-derive contexts in tight loops (a WithTimeout per item, for example), the allocation and scheduler interaction become measurable.

The optimisation: hoist context creation out of inner loops when possible. Re-use a single context for many iterations; check ctx.Err() inside the loop.

Cancellation in slow-tail systems¶

Some workloads have predictable slow tails: 99% of requests complete in 10 ms, but 1% take 5 seconds. The 1% is the long tail; the 99% is the fast path.

Cancellation is the tool for managing the long tail: cancel slow requests so resources stay available for the fast path.

ctx, cancel := context.WithTimeout(ctx, time.Duration(maxLatencyMs)*time.Millisecond)
defer cancel()

Set maxLatencyMs near the p99 of the fast path. Anything slower is cancelled, freeing the goroutine and resources for the next request.

The trade-off: a small fraction of requests fail with timeout. They are the requests that would have eaten resources from the rest.

This pattern is sometimes called "deadline propagation" or "tail amputation." It is essential for high-throughput services where the long tail can starve everyone.

Cancellation in HTTP middleware chains¶

A typical HTTP server has a chain of middleware: logging, auth, tracing, etc. Each middleware can affect the context.

func handler(w http.ResponseWriter, r *http.Request) {
    // ... handler uses r.Context() ...
}

mux := http.NewServeMux()
mux.HandleFunc("/", handler)

var srv http.Handler = mux
srv = withLogging(srv)
srv = withTracing(srv)
srv = withTimeout(srv, 30*time.Second)
srv = withAuth(srv)

Each middleware wraps the next. The request flows from outermost to innermost; the response flows back.

For cancellation:

• withTimeout derives a new context with a deadline and replaces r.Context().
• withTracing adds a span to the context.
• withAuth may add user info to the context.

By the time the handler runs, r.Context() is a derived context with all the middleware's modifications. Cancellation cascades from the original request context to the deadline-narrowed handler context.

Implementation: withTimeout¶

func withTimeout(next http.Handler, d time.Duration) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        ctx, cancel := context.WithTimeout(r.Context(), d)
        defer cancel()
        next.ServeHTTP(w, r.WithContext(ctx))
    })
}

The new context replaces the request's; downstream sees the tighter deadline. The defer fires after the handler returns.

Implementation: withTracing¶

func withTracing(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        ctx, span := tracer.Start(r.Context(), r.URL.Path)
        defer span.End()
        next.ServeHTTP(w, r.WithContext(ctx))
    })
}

The trace span is added to the context. The span's lifetime is bounded by the handler's execution (via defer).

Cancellation issues in middleware¶

A poorly written middleware can break cancellation:

// BAD: ignores cancellation
func badMiddleware(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        time.Sleep(time.Second) // ignores ctx; blocks for full second
        next.ServeHTTP(w, r)
    })
}

Even if the client disconnects, the middleware sleeps for the full second. Latency budget burned.

// GOOD
func goodMiddleware(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        select {
        case <-time.After(time.Second):
        case <-r.Context().Done():
            return
        }
        next.ServeHTTP(w, r)
    })
}

Cancellable sleep.

Lesson: every middleware should be cancellation-aware, even seemingly innocuous ones.

Cancellation under chaos (Jepsen-like testing)¶

For truly critical systems, treat cancellation paths as you would treat any other behaviour: test them under chaos. Jepsen-style testing introduces network partitions, process kills, and clock jumps to validate that the system handles them gracefully.

For Go pipelines, simpler chaos tests are valuable:

• Inject random delays at network calls.
• Inject random cancellations.
• Kill a random worker periodically.
• Simulate clock jumps (test with time.Now mocking).

func TestChaos(t *testing.T) {
    for i := 0; i < 1000; i++ {
        ctx, cancel := context.WithTimeout(context.Background(),
            time.Duration(rand.Intn(100)+1)*time.Millisecond)
        defer cancel()
        if err := runPipeline(ctx); err != nil {
            // log but continue
            t.Logf("iteration %d: %v", i, err)
        }
    }
    // After all iterations, verify no goroutine leaks
    runtime.GC()
    n := runtime.NumGoroutine()
    if n > 5 {
        t.Errorf("leaked goroutines: %d", n)
    }
}

1000 iterations with random timeouts. Catches a wide variety of timing bugs.

For production systems, run chaos in staging: kill random pods, inject network delays, etc. The system should degrade gracefully and recover quickly. Cancellation paths are heavily exercised by chaos.

Cancellation in transactional pipelines¶

For pipelines that need exactly-once semantics (rare but valuable), cancellation interacts with the transaction protocol.

The pattern: batch a series of changes; commit only when the whole batch succeeds; rollback on any error or cancellation.

func transactionalPipeline(ctx context.Context, items []Item) error {
    tx, err := db.BeginTx(ctx, nil)
    if err != nil {
        return err
    }
    defer tx.Rollback() // no-op if Commit succeeded

    for _, item := range items {
        if err := tx.ExecContext(ctx, "INSERT ...", item); err != nil {
            return err
        }
        if ctx.Err() != nil {
            return ctx.Err()
        }
    }

    return tx.Commit()
}

Cancellation during the loop returns; defer tx.Rollback aborts. No partial state visible.

Cancellation during Commit is tricky. The commit may have been written to the database before the cancel signal arrived. The transaction may be committed even though the function returns context.Canceled.

This is fundamental: distributed commits are not atomic from the client's perspective. The transaction is or is not committed; the cancellation result is ambiguous from the client side.

Mitigation: query the database after a cancelled commit to determine actual state. Or use two-phase commit semantics if the database supports them.

For most pipelines, the simpler approach is good enough: rely on defer Rollback for the common case; accept the ambiguity for the rare race.

Cancellation in connection multiplexing¶

A common pattern: many logical streams over one physical connection. gRPC over HTTP/2 is the classic example. Each stream has its own context; cancellation is per-stream, not per-connection.

The implementation: the framework tracks streams by ID. Cancelling stream N sends RST_STREAM(N); other streams continue.

For Go applications using gRPC, this is automatic — each call has its own context, and cancellation doesn't affect other calls on the same connection.

For custom multiplexed protocols (e.g. a streaming WebSocket-of-streams), you need to implement per-stream context handling:

type Mux struct {
    conn    net.Conn
    streams map[uint32]*Stream
    mu      sync.Mutex
}

type Stream struct {
    id    uint32
    ctx   context.Context
    cancel context.CancelFunc
}

func (m *Mux) NewStream(parent context.Context) *Stream {
    m.mu.Lock()
    defer m.mu.Unlock()
    id := nextID()
    ctx, cancel := context.WithCancel(parent)
    s := &Stream{id: id, ctx: ctx, cancel: cancel}
    m.streams[id] = s
    return s
}

func (m *Mux) CancelStream(id uint32) {
    m.mu.Lock()
    defer m.mu.Unlock()
    if s, ok := m.streams[id]; ok {
        s.cancel()
        delete(m.streams, id)
    }
}