Chapter 13: Context

13.1 Why Context Exists

A done channel cancels a set of goroutines. A request is a tree, and the difference shows up the first time a worker starts a worker.

13.1.1 The Orphaned Work Problem

The handler in this chapter’s opening spawns three searches and waits for all three. When the client disconnects at T1, nothing changes. The handler still blocks, the three searches still run, and the database connection, the cache round trip and the third-party API quota are all still spent on an answer nobody will read.

T0   request arrives
     └─ handler starts 3 searches

T1   client disconnects
     └─ handler still blocked on <-results
        the searches do not know

T2   all 3 finish and send

     buffered channel   → sends succeed, results discarded
                        → connection held, quota spent
     unbuffered channel → sends block forever
                        → 3 goroutines leaked (§2.5)

Nothing here is a data race. -race reports nothing.

The buffered case is the one worth sitting with, because it is not a leak in §2.5's sense — every goroutine exits. It is worse in a way that is harder to see: the program is correct and is spending real money on work it has already decided to throw away.

This is orphaned work: goroutines producing results no one will use. Cancellation is how you stop paying for it.

13.1.2 How Far a Done Channel Gets You

§4.3's pattern handles more than people give it credit for. One goroutine is trivial:

// Illustrative snippet — not a complete program
func worker(id int, done <-chan struct{}) {
    tick := time.NewTicker(500 * time.Millisecond)
    defer tick.Stop()
    for {
        select {
        case <-done:
            return
        case <-tick.C:
            process(id)
        }
    }
}

Many goroutines are no harder, because closing a channel is a broadcast — §3.3's property, and the whole reason this pattern scales at all:

// Illustrative snippet — not a complete program
done := make(chan struct{})
for i := 1; i <= 3; i++ {
    go worker(i, done)
}
close(done) // all three see it

It breaks at the third level. Suppose the coordinator starts four workers, one of which starts two sub-workers, and you need three different cancellation scopes: cancelling main stops everything, cancelling the coordinator stops its workers but not the logger, and cancelling worker 2 stops only its own children.

            main ── done ──┐
                           │
      ┌────────────────────┴─────┐
      │                          │
 coordinator                  logger
      │  needs its own done channel
 ┌────┼────┬────┐
 W1   W2   W3   W4
      │  needs a THIRD done channel
    ┌─┴─┐
    S1  S2

3 scopes ─► 3 channels, wired by hand
cancelling the coordinator means remembering
to close every channel below it, forever

The wiring is the problem, not the channels. Each new scope adds a channel, every cancel site has to know every channel beneath it, and a select that must respect a global deadline, a per-item deadline and a manual stop is now watching three cases before it does any work — a shape §4.6 already warned gets unreadable fast.

Nested deadlines make it worse. “The whole operation gets 30 seconds; each fetch gets 5” is one sentence, and expressing it with timers means every child receives both timers, plus the done channel, plus whatever its own children need.

13.1.3 What Context Adds

Context is the done channel with three things attached: a tree, a clock, and a reason.

The same three-scope program becomes a shape with no wiring in it:

// Illustrative snippet — not a complete program
ctx, cancel := context.WithCancel(context.Background())
defer cancel()

go logger(ctx)

coordCtx, coordCancel := context.WithCancel(ctx)
defer coordCancel()
for i := 1; i <= 4; i++ {
    go worker(i, coordCtx)
}
// cancelling coordCancel stops W1-W4 and their children,
// and leaves logger running

Each derived context is a node. Cancelling a node cancels its whole subtree and nothing above it. No goroutine needs to know how many descendants it has.

13.1.4 When Context Is the Answer

Context is for cancellation, deadlines and request scope. It is not a general-purpose communication channel, and §13.6 spends most of its length on the one place people reach for it wrongly.

13.1.5 Common Mistakes

Summary: Why Context Exists

A done channel broadcasts a stop to a set of goroutines and does it well. What it cannot do is describe a hierarchy: it has no notion of a descendant, so every scope you add is a channel you wire and a select case you remember. It also has no clock and no vocabulary for why the work ended.

Context supplies those three. A derived context is a node in a tree; cancelling it stops that node’s entire subtree and nothing above it. A deadline set anywhere binds everything below and can be narrowed but never widened. And since Go 1.20, the stop can carry a reason.

Self-Check Questions: Why Context Exists

13.2 The Context Interface

Four methods, and every context in every Go program implements exactly these:

// Illustrative snippet — not a complete program
type Context interface {
    Done() <-chan struct{}
    Err() error
    Deadline() (deadline time.Time, ok bool)
    Value(key any) any
}

Two of them are about stopping, one is about time, one is about data. Nothing in the interface cancels anything — cancellation lives in the cancel function a constructor hands back, never in the context you pass around. That split is deliberate and §13.2.7 is about what it buys.

13.2.1 The Fundamental Guarantee

A context makes one promise: once Done() is closed, it stays closed, and Err() is non-nil forever after. There is no reset, no re-arm, no way back. A cancelled context is cancelled for the life of the program.

That is what makes the type safe to share. Any number of goroutines may hold the same context and read it concurrently, because after the single transition there is nothing left to observe.

13.2.2 Done(): The Cancellation Signal

Done() returns a channel that is closed when the context is cancelled. It is never written to — closing is the signal, which is §3.3's close-as-broadcast applied to an arbitrary number of waiters.

// Illustrative snippet — not a complete program
select {
case <-ctx.Done():
    return ctx.Err()
case result := <-work:
    return handle(result)
}

Why a channel rather than a callback or a flag? Because a channel is the only one of the three that composes with select. A flag has to be polled, and a poll cannot wait on anything else at the same time. A callback runs on somebody else’s goroutine and cannot be combined with the receive you actually care about. A channel lets one select wait on cancellation and on real work, which is the shape almost every context-aware function has.

Done() can return nil. For Background() and TODO() it does, because those contexts can never be cancelled:

// Illustrative snippet — not a complete program
ctx := context.Background()
fmt.Println(ctx.Done() == nil) // true

A receive on a nil channel blocks forever, which is exactly right: a context that will never be cancelled should never make the Done() case fire. select handles this correctly with no special casing, so code that treats Done() uniformly is already correct.

13.2.3 Err(): The Reason, and What It Costs

Err() returns nil while the context is live, and after cancellation returns one of exactly two sentinels:

Compare them with errors.Is, never ==, because the error you receive has usually been wrapped on its way up. The same rule applies to net.Error, which DeadlineExceeded implements with Timeout() == true:

// Illustrative snippet — not a complete program
var netErr net.Error
if errors.As(err, &netErr) && netErr.Timeout() {
    // handles both context and network timeouts, wrapped or not
}

Go 1.26’s generic errors.AsType[net.Error](err) returns the value and a bool without the declared variable, and go fix’s errorsastype modernizer performs the rewrite; either form is fine.

A bare err.(net.Error) type assertion is the common version of this and it is wrong for the same reason err == context.Canceled is wrong: one layer of fmt.Errorf("%w", ...) and it stops matching.

The Done/Err invariant. If Done() is closed, Err() is non-nil. If Err() is non-nil, Done() is closed. The two are never observed out of step — but the mechanism is worth knowing, because it is not what “atomic” would suggest. Inside cancel() the error is stored before the channel closes:

// Illustrative snippet — not a complete program
// $GOROOT/src/context/context.go, cancelCtx.cancel
c.err.Store(err)
// ... then
close(d)

Those are two separate operations, so for an instant the error is set while the channel is still open. The invariant holds anyway because Err() closes the gap from the other side:

// Illustrative snippet — not a complete program
// $GOROOT/src/context/context.go, cancelCtx.Err
if err := c.err.Load(); err != nil {
    <-c.Done()          // wait for the close before reporting
    return err.(error)
}
return nil

That extra receive is why Err() costs what it does, and the cost is not flat.

13.2.4 Deadline(): The Time Limit

Deadline() reports when the context will cancel itself, and whether it has such a time at all:

// Illustrative snippet — not a complete program
if deadline, ok := ctx.Deadline(); ok {
    if time.Until(deadline) < 100*time.Millisecond {
        return errNotEnoughTime // don't start what we can't finish
    }
}

The ok result is the whole point: false means no deadline was ever set anywhere in this context’s ancestry, and the returned time.Time is the zero value. Contexts from Background(), WithCancel and WithValue all report false unless something above them set a deadline.

This is the method to use when the work is adaptive — sizing a batch, choosing a retry budget, deciding whether an expensive call is worth starting. It is not how you detect cancellation; that is Done().

13.2.5 Value(): Request-Scoped Data

Value(key) walks up the tree looking for a matching key and returns nil if it reaches the root without finding one. It is the one method that is not about stopping, it is the one people misuse, and §13.6 is entirely about the narrow band where it is correct.

Two things matter here. The key must be an unexported type so no other package can collide with it, and the lookup is a walk, not a map read — §13.6.4 measures what that costs.

13.2.6 The Complete Behavior Table

This table has one row that is wrong in most references, and getting it wrong produces a real bug.

The entry usually written for WithCancel is “context.Canceled”, and it is only true when this context’s own cancel was the thing that fired. A WithCancel child whose ancestor’s deadline expires reports the ancestor’s error:

// Illustrative snippet — not a complete program
bg := context.Background()
parent, pc := context.WithTimeout(bg, 20*time.Millisecond)
defer pc()
child, cc := context.WithCancel(parent) // a plain WithCancel child
defer cc()

<-child.Done()
fmt.Println(child.Err())                    // deadline exceeded
fmt.Println(errors.Is(child.Err(), context.Canceled)) // false

13.2.7 Thread Safety and the Read-Only Contract

The interface has no setters, and that is the design. A context you receive can be observed and derived from, never modified and never cancelled:

creator                  receiver
───────                  ────────
ctx, cancel := ...       func work(ctx context.Context)
      │                        │
      ├─ holds cancel          ├─ reads Done/Err/Deadline/Value
      │  stops the subtree     ├─ derives a narrower child
      │                        └─ cannot cancel what it got
      └─ passes only ctx down

Cancellation authority stays with whoever
created the scope. That is why cancel is a
separate return value and not a method.

All four methods are safe to call from any number of goroutines. Values stored via WithValue are safe only if the values themselves are immutable — the context protects its own structure, not your data (§13.6.7).

13.2.8 Common Mistakes

Summary: The Context Interface

Four methods, one transition. Done() returns a channel that is closed on cancellation — close-as-broadcast, chosen over a flag or a callback because it is the only form that composes with select. It returns nil for contexts that can never be cancelled, and a nil channel blocking forever is the correct behaviour rather than a special case.

Err() is nil until cancellation and then reports one of two sentinels forever. Compare with errors.Is. The transition is not one atomic step: the error is stored before the channel closes, and Err() covers the gap by receiving on Done() before returning a non-nil error — which is why the call is 2.21 ns while live and 19.38 ns afterwards.

Deadline() is for adapting to the time you have, not for detecting the stop. Value() walks the tree. And the sentinel you get names the cause of cancellation, not the constructor that produced the context — the single most consequential row in the behavior table.

Self-Check Questions: The Context Interface

13.3 Creating Contexts

You never construct a Context directly. You start from a root and derive, and every derivation returns a new context — the parent is unchanged.

13.3.1 Roots: Background() and TODO()

Both return a context that is never cancelled, has no deadline, no values, and a nil Done(). They are identical at run time — TODO() exists purely to say something to a human.

TODO() is a marker that survives code review and greps cleanly. Shipping it is the mistake — it means a cancellation path was never wired up, and nothing will ever stop that subtree.

13.3.2 WithCancel(): Manual Cancellation

// Illustrative snippet — not a complete program
ctx, cancel := context.WithCancel(parent)
defer cancel()

cancel is idempotent and safe from any goroutine; calling it twice does nothing the second time. Call it on every path — that is what defer is for.

Cancellation cascades immediately to the whole subtree:

// Illustrative snippet — not a complete program
root, rootCancel := context.WithCancel(context.Background())
a, aCancel := context.WithCancel(root)
defer aCancel()
b, bCancel := context.WithCancel(a)
defer bCancel()

rootCancel()
<-b.Done() // already closed: root -> a -> b

The reverse never happens. bCancel() stops b and anything below it, and a and root do not notice.

13.3.3 WithTimeout() and WithDeadline(): Time-Based

WithTimeout(parent, d) is WithDeadline(parent, time.Now().Add(d)). Use a timeout for “this operation gets 5 seconds” and a deadline when several operations share one absolute budget:

// Illustrative snippet — not a complete program
// one budget, many operations
deadline := time.Now().Add(30 * time.Second)
for _, step := range steps {
    ctx, cancel := context.WithDeadline(parent, deadline)
    err := step(ctx)
    cancel()
    if err != nil {
        return err
    }
}

Note cancel() inside the loop body rather than defer cancel() — §13.3.8 has the version that gets this wrong.

The effective deadline rule. A child’s deadline is the earlier of its own and its parent’s. It can narrow what it inherits; it can never widen it:

// Illustrative snippet — not a complete program
parent, pc := context.WithTimeout(bg, 5*time.Second)
defer pc()

child, cc := context.WithTimeout(parent, 1*time.Hour)
defer cc()

d, _ := child.Deadline() // 5 seconds from now, not an hour

This is enforced by the constructor, which is what makes “the whole request gets 30 seconds” a guarantee rather than a convention. No amount of optimism further down the tree can extend it.

A zero or negative timeout is already expired. It does not mean “no timeout”:

// Illustrative snippet — not a complete program
ctx, cancel := context.WithTimeout(bg, 0)
defer cancel()
fmt.Println(ctx.Err()) // context deadline exceeded

That bites when a duration comes from configuration and the field is missing.

13.3.4 WithCancelCause(): Cancellation with a Reason (Go 1.20+)

Err() tells you that something stopped; it has only two answers. WithCancelCause lets the canceller attach a real error, retrieved with context.Cause:

// Illustrative snippet — not a complete program
ctx, cancel := context.WithCancelCause(parent)

cancel(fmt.Errorf("upstream %s returned 503", host))

fmt.Println(ctx.Err())           // context canceled
fmt.Println(context.Cause(ctx))  // upstream cache-3 returned 503

Err() keeps returning the sentinel — that is deliberate, so existing code that branches on context.Canceled keeps working. Cause is the richer view layered on top.

The cause propagates down: a child of a cause-cancelled parent reports the same cause, so the goroutine that discovers the failure can be many levels below the one that named it. WithTimeoutCause and WithDeadlineCause (Go 1.21) do the same for deadlines.

13.3.5 WithoutCancel(): Detaching from the Parent (Go 1.21+)

Inherits values; drops cancellation and deadline:

// Illustrative snippet — not a complete program
detached := context.WithoutCancel(ctx)

The use is cleanup that must finish even though the request it belongs to is over — while keeping the trace ID that makes the cleanup findable in a log:

// Illustrative snippet — not a complete program
func handle(ctx context.Context) error {
    result, err := doWork(ctx)
    if err != nil {
        return err
    }

    // keep the values, drop the request's cancellation
    bg := context.WithoutCancel(ctx)
    // then give the cleanup a bound of its own
    cleanup, cancel := context.WithTimeout(bg, 5*time.Second)
    defer cancel()

    recordMetrics(cleanup, result)
    return nil
}

The two steps matter in that order. Detaching alone gives you work with no deadline at all, which is how a “quick” cleanup becomes a goroutine that outlives the process it was reporting on. Always re-bound after detaching.

13.3.6 AfterFunc(): Cleanup Callbacks (Go 1.21+)

Registers a function to run when a context is cancelled, and returns a stop you use to unregister it:

// Illustrative snippet — not a complete program
stop := context.AfterFunc(ctx, func() {
    conn.Close()
})
defer stop()

The stop return is not optional. Discarding it is the bug in most examples of this function:

// Illustrative snippet — not a complete program
// ✗ BROKEN: closes twice if the caller closes normally first
func acquire(ctx context.Context) (*Resource, error) {
    res := &Resource{}
    context.AfterFunc(ctx, func() { res.Close() })
    return res, nil
}

Nothing here is a data race, and -race says nothing. The caller closes the resource when it is finished, the request ends a moment later, the callback fires, and res.Close() runs on an already-closed resource. Hand the caller the stop:

// Illustrative snippet — not a complete program
// ✓ the caller can retire the cleanup when it closes normally
func acquire(ctx context.Context) (*Resource, func(), error) {
    res := &Resource{}
    stop := context.AfterFunc(ctx, func() { res.Close() })
    release := func() {
        stop()
        res.Close()
    }
    return res, release, nil
}

AfterFunc is also how you bridge a context to an API that predates it — anything that takes its own done channel or has its own Close.

13.3.7 What cancel() Actually Releases

Almost every explanation of defer cancel() says it stops a leaked goroutine. That is not what happens, and the real answer is a better number.

1000 x WithCancel      ─►  goroutines +0
1000 x WithTimeout     ─►  goroutines +0
───────────────────────────────────────────────
100 000 children of one long-lived parent:

  cancel() not called  ─►  heap +11.55 MB
                           +115 B per child
  cancel() called      ─►  heap  ~0 MB
                           +0 B per child
───────────────────────────────────────────────
In both cases:             goroutines +0

WithCancel adds the child to the parent’s children map — a map insert, no goroutine. WithTimeout arms a runtime timer through time.AfterFunc, which is an entry in the timer heap, not a parked goroutine. A goroutine appears in exactly one case: propagateCancel's fallback path, when the parent is a custom Context implementation that the package cannot inspect, and it must watch parent.Done() itself. That is rare and it is not what happens with the standard constructors.

So the advice is right and the usual reason is wrong. cancel() removes the child from the parent’s map and stops the timer. Skip it under a long-lived parent and you accumulate 115 bytes per orphaned child, held for as long as the parent lives — which for a server whose root context lives for the life of the process means until restart.

13.3.8 Common Mistakes

The loop case is worth seeing, because it looks correct:

// Illustrative snippet — not a complete program
// ✗ BROKEN: 1000 contexts, all released when poll returns
func poll(ctx context.Context, urls []string) {
    for _, u := range urls {
        c, cancel := context.WithTimeout(ctx, time.Second)
        defer cancel()
        get(c, u)
    }
}

// ✓ released at the end of each iteration
func poll(ctx context.Context, urls []string) {
    for _, u := range urls {
        c, cancel := context.WithTimeout(ctx, time.Second)
        get(c, u)
        cancel()
    }
}

If get can panic, put the body in a closure so the defer still runs per iteration. The measured cost of getting this wrong is §13.3.7's 115 bytes times the length of the loop.

Summary: Creating Contexts

Start from Background() and derive. WithCancel gives you a stop you control; WithTimeout and WithDeadline give you one the clock controls, and a child’s deadline is always the earlier of its own and its parent’s — narrowing is allowed, widening is not, and the constructor enforces it.

WithCancelCause (1.20) attaches a real error to the stop while leaving Err()'s two sentinels intact, so existing branches keep working. WithoutCancel (1.21) detaches from cancellation while keeping values, and should always be followed by a fresh bound. AfterFunc (1.21) registers cleanup and hands back a stop that is not optional.

And cancel() releases a map entry and a timer, not a goroutine. The constructors create no goroutines at all under a standard parent. Missing the call costs 115 bytes per child for as long as the parent lives.

Self-Check Questions: Creating Contexts

13.4 The Context Tree

Every derived context is a node with exactly one parent. That single edge is the whole data structure, and everything in this chapter follows from which direction each thing travels along it.

13.4.1 How Trees Form

A tree is built by derivation, top down:

// Illustrative snippet — not a complete program
root := context.Background()
reqCtx := context.WithValue(root, requestIDKey{}, id)
opCtx, cancel := context.WithTimeout(reqCtx, 30*time.Second)
defer cancel()

for _, shard := range shards {
    go query(opCtx, shard) // all three share opCtx
}

              Background()
                   │
            WithValue(id)          ▲  values resolve
                   │               │  UPWARD on lookup
          WithTimeout(30s)         │
                   │               │
       ┌───────────┴──────────┐    │
       │                      │    │
  WithCancel             WithCancel
       │                      │    │  cancellation and
   ┌───┴───┐                  │    ▼  deadlines flow
   │       │                  │       DOWNWARD
 query   query              query

cancel a node ─► its whole subtree stops
cancel a leaf ─► nothing above it notices

Nothing travels upward except a value lookup, and that is a read.

13.4.2 Cancellation Propagates Down

Cancelling a node closes its Done() and every descendant’s, carrying the originating error:

// Illustrative snippet — not a complete program
root, rootCancel := context.WithCancel(bg)
mid, midCancel := context.WithCancel(root)
defer midCancel()
leaf, leafCancel := context.WithCancel(mid)
defer leafCancel()

midCancel()

fmt.Println(root.Err()) // <nil>  — unaffected
fmt.Println(mid.Err())  // context canceled
fmt.Println(leaf.Err()) // context canceled

The propagation is synchronous within cancel(): by the time it returns, every descendant’s Done() is closed. What is not synchronous is the goroutines reacting — they wake when the scheduler gets to them, so cancel() returning does not mean the work has stopped. §13.7.5 is about waiting for that properly.

13.4.3 Deadlines Are Inherited, Never Extended

The rule from §13.3.3, stated as a tree property: a node’s effective deadline is the earliest deadline anywhere on the path from it to the root.

root            no deadline
  └─ A          WithTimeout 30s   ─► fires at 30s
       └─ B     WithTimeout 60s   ─► fires at 30s
            └─ C  WithTimeout 5s  ─► fires at  5s

B asked for 60 and got 30: it cannot widen A.
C asked for 5 and got 5: narrowing is allowed.

This is why a request-level budget is trustworthy. It is also why a slow dependency cannot be given “just a bit more time” by the function that calls it — the only way to get a longer budget is to sit outside the scope, which §13.3.5 makes explicit and deliberate.

13.4.4 Values Resolve Upward

Value(key) starts at the node and walks toward the root, returning the first match:

// Illustrative snippet — not a complete program
ctx := context.WithValue(bg, userKey{}, alice)
child := context.WithValue(ctx, traceKey{}, "abc123")

child.Value(userKey{})  // alice — found two levels up
ctx.Value(traceKey{})   // nil   — the parent cannot see the child

A key set closer to the node shadows the same key set higher up, which is occasionally useful and more often a bug you cannot see. §13.6.4 measures what the walk costs.

13.4.5 Deriving a Child Is O(depth), Not O(1)

This is stated as constant-time nearly everywhere, and it is not. WithCancel has to find the nearest cancellable ancestor to register with, and it does that with a value lookup:

// Illustrative snippet — not a complete program
// $GOROOT/src/context/context.go, parentCancelCtx
p, ok := parent.Value(&cancelCtxKey).(*cancelCtx)

That is the same upward walk as any other Value call, so the cost of creating a child grows with how deep you already are.

The chain has to be rooted at something cancellable for that to be the code doing the work, and it is worth seeing why. propagateCancel gives up before it ever reaches parentCancelCtx if there is nothing above it to register with:

// Illustrative snippet — not a complete program
// $GOROOT/src/context/context.go, cancelCtx.propagateCancel
done := parent.Done()
if done == nil {
    return // parent is never canceled
}

Under a Background() root, Done() is nil and that early return fires, so a benchmark built on WithValue over Background() measures only Done() chaining through each node — the right shape, the wrong mechanism. A real request tree is rooted at something cancellable, where both walks run and the child is inserted into the ancestor’s map.

In practice a request tree is a handful of levels deep and none of this matters. It starts mattering when a chain of middleware adds a WithValue each, a library adds a few more, and something in a loop derives a child per item — which is precisely the shape §13.6.5's “bundle related values” advice exists to prevent.

13.4.6 Designing the Tree

Breaking the chain is the one that hides best:

// Illustrative snippet — not a complete program
// ✗ BROKEN: the caller's cancellation and deadline are discarded
func fetch(ctx context.Context, url string) error {
    c, cancel := context.WithTimeout(bg, 5*time.Second) // not ctx!
    defer cancel()
    return get(c, url)
}

// ✓ derived, so the caller's budget still binds
func fetch(ctx context.Context, url string) error {
    c, cancel := context.WithTimeout(ctx, 5*time.Second)
    defer cancel()
    return get(c, url)
}

The broken version passes every test that checks the 5-second timeout, and quietly ignores a client that hung up 4 seconds ago.

13.4.7 Debugging a Context Tree

Two questions come up in production, and they have different tools.

“What cancelled this?” Err() gives you the kind and Cause gives you the reason, but neither says which node. Build the tree with WithCancelCause at every point where a distinct thing can go wrong, and the answer arrives with the error:

// Illustrative snippet — not a complete program
sub, cancel := context.WithCancelCause(ctx)
// ...
cancel(fmt.Errorf("shard %d: %w", id, err))

// far below, in a worker that only sees sub:
if err := ctx.Err(); err != nil {
    log.Printf("stopping: %v", context.Cause(ctx))
}

Without a cause, every cancellation in a large tree reports the same two words and you are left correlating timestamps.

“Why is the heap growing?” This is §13.3.7's failure, and the important thing is that the usual tool says nothing. A missing cancel() leaks no goroutines, so the dump §10.4 taught you to read looks perfectly healthy:

goroutine dump   ─►  nothing. counts are flat.
-race            ─►  nothing. no data race.
go vet           ─►  nothing. it compiles.
─────────────────────────────────────────────
heap profile     ─►  context.propagateCancel,
                     growing, retained by the
                     parent's children map

Look for a live parent holding a map that only
ever grows: 115 bytes per orphaned child.

go tool pprof -inuse_space on a heap profile is the tool. The retaining path runs back to whichever long-lived context is the parent — usually the one created in main.

13.4.8 Common Mistakes

Summary: The Context Tree

One parent per node, and direction is everything. Cancellation and deadlines flow down; a value lookup is the only thing that travels up, and it is a read. Cancelling a node stops its whole subtree synchronously — every descendant’s Done() is closed by the time cancel() returns — and touches nothing above it.

A node’s effective deadline is the earliest one on its path to the root, which is what makes an outer budget a guarantee rather than a suggestion. Deriving a child is O(depth) rather than O(1), because WithCancel finds its nearest cancellable ancestor with the same upward walk that Value uses: 237 ns at depth 0 against 1,171 ns at depth 50.

Self-Check Questions: The Context Tree

13.5 Checking for Cancellation

A context that nobody checks cancels nothing. This section is about where the checks go and what they cost.

13.5.1 The Three Ways to Check

The first is the one you want almost always, because it is the only one that lets a goroutine wait on cancellation and on something useful at the same time:

// Illustrative snippet — not a complete program
select {
case <-ctx.Done():
    return ctx.Err()
case job := <-jobs:
    return process(job)
}

The other two are point checks. Use them between chunks of CPU work, where there is no channel to wait on:

// Illustrative snippet — not a complete program
for i, item := range items {
    if i%1000 == 0 {
        if err := ctx.Err(); err != nil {
            return err
        }
    }
    process(item)
}

13.5.2 Telling Cancellation from Timeout

This is the branch that §13.2.6's table exists to get right:

// Illustrative snippet — not a complete program
if err := doWork(ctx); err != nil {
    switch {
    case errors.Is(err, context.Canceled):
        // the caller gave up — usually not our problem to log loudly
        return err
    case errors.Is(err, context.DeadlineExceeded):
        // we ran out of time — this is a signal about our own latency
        metrics.Timeouts.Inc()
        return err
    default:
        return fmt.Errorf("work failed: %w", err)
    }
}

Both cases must be present on every context, whatever constructor produced it. A WithCancel child under an expired WithTimeout ancestor arrives here as DeadlineExceeded; a WithTimeout context whose parent was cancelled arrives as Canceled. Writing only the Canceled case sends every ancestor timeout to default, where it is reported as a generic failure and the timeout metric never moves.

context.Cause for the richer answer. When the tree was built with WithCancelCause, Cause gives you what actually went wrong while Err() keeps its two sentinels:

// Illustrative snippet — not a complete program
if err := doWork(ctx); err != nil {
    if cause := context.Cause(ctx); cause != nil && cause != err {
        return fmt.Errorf("work failed (%v): %w", cause, err)
    }
    return err
}

Cause costs more than Err — §13.5.7 has the number — so call it once on the failure path, not in a loop.

13.5.3 Select Patterns

Wait for work or cancellation. The default shape:

// Illustrative snippet — not a complete program
for {
    select {
    case <-ctx.Done():
        return ctx.Err()
    case job, ok := <-jobs:
        if !ok {
            return nil
        }
        if err := handle(ctx, job); err != nil {
            return err
        }
    }
}

Send with cancellation. A send blocks just as a receive does, and needs the same guard:

// Illustrative snippet — not a complete program
select {
case <-ctx.Done():
    return ctx.Err()
case results <- value:
}

Forgetting this is the most common way a worker leaks: it finishes, tries to publish, and blocks forever on a channel nobody is reading because the consumer already returned.

First result wins. Cancel the losers as soon as one replica answers, and keep the real error when they all fail:

// Illustrative snippet — not a complete program
func first(ctx context.Context, hosts []string) (Result, error) {
    ctx, cancel := context.WithCancel(ctx)
    defer cancel() // stops the losers

    type outcome struct {
        res Result
        err error
    }
    ch := make(chan outcome, len(hosts))

    var wg sync.WaitGroup
    for _, h := range hosts {
        wg.Go(func() {
            r, err := query(ctx, h)
            select {
            case ch <- outcome{r, err}:
            case <-ctx.Done():
            }
        })
    }

    var lastErr error
    for range hosts {
        select {
        case o := <-ch:
            if o.err == nil {
                return o.res, nil
            }
            lastErr = o.err
        case <-ctx.Done():
            return Result{}, ctx.Err()
        }
    }
    return Result{}, fmt.Errorf("all %d hosts failed: %w",
        len(hosts), lastErr)
}

The buffered channel matters: with an unbuffered one, a loser that finishes after the winner returns would block on the send forever. The wg.Go form is Go 1.25's (§2.3) — it replaces Add(1) plus defer Done(), and the closure must not call wg.Done itself.

Returning lastErr wrapped, rather than a fresh “all hosts failed” string, is the difference between a caller that can act on the failure and one that gets a sentence.

13.5.4 Checking Inside Loops

A CPU-bound loop has no channel to wait on, so the check is a point check and the only question is how often.

At 7.30 ns for a select with default (§13.5.7), the check is nearly free relative to almost any real work:

The old advice to avoid checking above “10,000 iterations per second” is wrong by about three orders of magnitude. At 7.3 ns a check, ten thousand checks per second is 0.007% of one core. The threshold where it becomes worth batching is in the millions per second.

Time-based checking when iteration cost varies wildly:

// Illustrative snippet — not a complete program
next := time.Now().Add(10 * time.Millisecond)
for _, item := range items {
    if time.Now().After(next) {
        if err := ctx.Err(); err != nil {
            return err
        }
        next = time.Now().Add(10 * time.Millisecond)
    }
    process(item)
}

This is only worth it when the work per item is genuinely unpredictable — time.Now() costs 60.89 ns, roughly eight times a Done() check, so a fixed iteration count is cheaper whenever you can estimate one.

// Illustrative snippet — not a complete program
// allocates a timer per iteration
for _, item := range items {
    select {
    case <-ctx.Done():
        return ctx.Err()
    case <-time.After(time.Second):
    }
    process(item)
}

// one timer, reset after each fire
t := time.NewTimer(time.Second)
defer t.Stop()
for _, item := range items {
    select {
    case <-ctx.Done():
        return ctx.Err()
    case <-t.C:
        process(item)
        t.Reset(time.Second)
    }
}

13.5.5 Blocking Operations

The standard library already takes contexts wherever it blocks, and using those entry points is better than any wrapper you write:

// Illustrative snippet — not a complete program
req, err := http.NewRequestWithContext(ctx, http.MethodGet, url, nil)
if err != nil {
    return err
}
resp, err := http.DefaultClient.Do(req) // cancels mid-flight

For an API that predates contexts and cannot be changed, the honest wrapper returns early and lets the underlying work finish on its own:

// Illustrative snippet — not a complete program
func withContext(ctx context.Context, f func() error) error {
    done := make(chan error, 1) // buffered: f must not block
    go func() { done <- f() }()

    select {
    case err := <-done:
        return err
    case <-ctx.Done():
        return ctx.Err() // f keeps running; we stop waiting
    }
}

13.5.6 Retrying Inside a Budget

A retry loop that ignores its context is the purest form of orphaned work: it keeps trying on behalf of a caller who left. Two things make it correct — the wait between attempts must be interruptible, and the loop must stop when the budget is gone.

// Illustrative snippet — not a complete program
func withRetry(ctx context.Context, attempts int,
    f func(context.Context) error) error {

    var lastErr error
    backoff := 100 * time.Millisecond

    for i := 0; i < attempts; i++ {
        if i > 0 {
            t := time.NewTimer(backoff)
            select {
            case <-ctx.Done():
                // no drain needed: timer channels are synchronous
                // (Go 1.23+, unconditional since Go 1.27)
                t.Stop()
                return ctx.Err()
            case <-t.C:
            }
            backoff *= 2
        }

        lastErr = f(ctx)
        if lastErr == nil {
            return nil
        }
        // A cancelled context will not succeed on retry.
        if ctx.Err() != nil {
            return ctx.Err()
        }
    }
    return fmt.Errorf("after %d attempts: %w", attempts, lastErr)
}

The second check is the one people leave out. Without it, a context that expired during f still costs you every remaining attempt — each one starting, immediately failing on the dead context, and sleeping before the next.

Spending the budget deliberately. Deadline() lets a caller divide the time it has rather than guessing:

// Illustrative snippet — not a complete program
func fetchAndProcess(ctx context.Context) error {
    // Give the network call at most half of whatever is left,
    // so processing always has room.
    budget := 2 * time.Second
    if deadline, ok := ctx.Deadline(); ok {
        if half := time.Until(deadline) / 2; half < budget {
            budget = half
        }
    }

    netCtx, cancel := context.WithTimeout(ctx, budget)
    defer cancel()

    data, err := fetch(netCtx)
    if err != nil {
        return err
    }
    return process(ctx, data) // the rest of the budget
}

13.5.7 Performance Characteristics

13.5.8 Common Mistakes

Summary: Checking for Cancellation

select on ctx.Done() whenever there is something else to wait on; a point check with ctx.Err() between chunks of CPU work when there is not. Guard sends as carefully as receives — a worker blocked publishing a result nobody will read is the most common context-shaped leak.

Branch on both sentinels, always. The error names the cause rather than the constructor, so a WithCancel context can hand you DeadlineExceeded and code that only tests for Canceled loses every ancestor timeout to its default branch.

The checks are cheap: 2.21 ns live, 7.30 ns for a select with default. Cause is the exception at 32.72 ns once cancelled, because it walks the value tree and takes a mutex. And since Go 1.23, time.After in a loop is an allocation problem, not a leak.

Self-Check Questions: Checking for Cancellation

// Illustrative snippet — not a complete program
select {
case results <- value:
case <-ctx.Done():
    return ctx.Err()
}

13.6 Context Values

WithValue is the part of the package people reach for wrongly, and the package documentation says so itself: it is for request-scoped data that crosses API boundaries, and nothing else. This section is about where that line actually falls.

13.6.1 The Litmus Test

Ask one question: would this value be a parameter if every function between here and there were yours to change?

If yes, it is a parameter. Context values are for data that has to cross code you do not own — middleware, an interface you must satisfy, a handler signature fixed by a framework.

The test rules out dependency injection cleanly. A *sql.DB would be a parameter if you controlled every signature, so it is a parameter.

13.6.2 The Key Collision Problem

Value compares keys with == across the whole tree, so two packages using the same key value collide silently:

// Illustrative snippet — not a complete program
// ✗ BROKEN: any package using "user" overwrites this
ctx = context.WithValue(ctx, "user", currentUser)

A string key is shared by everyone who types the same string, and the failure is a wrong value rather than an error. Exported types are no better — another package can construct one.

The rule is an unexported key type:

// Illustrative snippet — not a complete program
type userKey struct{}

ctx = context.WithValue(ctx, userKey{}, currentUser)

No other package can name userKey, so no other package can produce a key that compares equal. A zero-size struct also costs nothing to store.

13.6.3 Type-Safe Accessors

Never export the key. Export a pair of functions and keep every type assertion in one place:

package auth

type userKey struct{}

type User struct {
    ID    string
    Email string
}

// WithUser returns a context carrying u.
func WithUser(ctx context.Context, u *User) context.Context {
    if u == nil {
        return ctx // never store nil; see §13.6.7
    }
    return context.WithValue(ctx, userKey{}, u)
}

// UserFromContext reports the user, if one was set.
func UserFromContext(ctx context.Context) (*User, bool) {
    u, ok := ctx.Value(userKey{}).(*User)
    return u, ok
}

The comma-ok form is the default because “no user” is usually a real case. Where absence is a programming error rather than a runtime condition — code that runs only behind authentication middleware — a Must variant that panics documents the invariant:

// Illustrative snippet — not a complete program
func MustUser(ctx context.Context) *User {
    u, ok := UserFromContext(ctx)
    if !ok {
        panic("auth: no user in context")
    }
    return u
}

13.6.4 How Lookup Works, and What It Costs

valueCtx stores exactly one key and one value and delegates everything else to its parent. A lookup walks up until it matches or reaches the root:

Background()
   └─ valueCtx{traceKey, "abc"}
      └─ valueCtx{userKey, alice}
          └─ valueCtx{tenantKey, 42}  ◄── lookup starts

Value(tenantKey) ─► 1 hop
Value(userKey)   ─► 2 hops
Value(traceKey)  ─► 3 hops
Value(missing)   ─► walks to the root, returns nil

There is no map and no index. Four WithValue calls make four nodes, and the miss case always costs the full depth.

The 48 bytes is exactly valueCtx's size — a Context interface plus a key interface plus a value interface, three two-word headers — and it is the number to trust: it reproduced identically on three separate machines, while the nanosecond figures drifted between sessions by up to 50% because the call is allocator-bound.

Read once, then pass it down. A value read in a loop pays the walk every iteration for a value that cannot change:

// Illustrative snippet — not a complete program
// ✗ walks the tree per item
for _, item := range items {
    log.Printf("%s: %v", TraceIDFromContext(ctx), item)
}

// ✓ one walk
traceID := TraceIDFromContext(ctx)
for _, item := range items {
    log.Printf("%s: %v", traceID, item)
}

13.6.5 Bundling Related Values

Values that arrive together and are read together should be one node, not four:

// Illustrative snippet — not a complete program
type reqInfo struct {
    TraceID string
    User    *User
    Tenant  string
    Locale  string
}

// Illustrative snippet — not a complete program
// ✗ four nodes, four hops to reach the deepest
ctx = context.WithValue(ctx, traceKey{}, traceID)
ctx = context.WithValue(ctx, userKey{}, user)
ctx = context.WithValue(ctx, tenantKey{}, tenant)
ctx = context.WithValue(ctx, localeKey{}, locale)

// ✓ one node, one hop, one allocation
info := &reqInfo{
    TraceID: traceID,
    User:    user,
    Tenant:  tenant,
    Locale:  locale,
}
ctx = context.WithValue(ctx, reqInfoKey{}, info)

Bundle when the values are set at the same place and read at the same places. Keep them separate when they come from different layers or have different lifetimes — an auth middleware and a tracing middleware should not have to share a struct.

The bundle must be treated as immutable once stored (§13.6.7). Storing a pointer is fine; mutating what it points at is not.

13.6.6 Patterns That Earn Their Place

Request ID propagation, the canonical case — generated once at the edge, read anywhere:

// Illustrative snippet — not a complete program
func RequestIDMiddleware(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter,
        r *http.Request) {
        id := r.Header.Get("X-Request-ID")
        if id == "" {
            id = uuid.New().String()
        }
        ctx := WithRequestID(r.Context(), id)
        w.Header().Set("X-Request-ID", id)
        next.ServeHTTP(w, r.WithContext(ctx))
    })
}

uuid here is Go 1.27’s standard-library package (NewV7 if you want time-sortable IDs) — no third-party module needed.

r.WithContext(ctx) is the required step: it returns a copy of the request carrying the new context. Mutating r in place is not an option, and forgetting the copy means the value never reaches the handler.

Distributed tracing, which is the case the package documentation had in mind. A span is created at the edge and every layer below adds to the same trace without any of them taking a span parameter:

// Illustrative snippet — not a complete program
func Handler(w http.ResponseWriter, r *http.Request) {
    ctx, span := tracer.Start(r.Context(), "handler")
    defer span.End()

    // db.Query starts a child span from ctx; the signature
    // says nothing about tracing
    if err := db.Query(ctx, sql); err != nil {
        span.RecordError(err)
    }
}

This passes the litmus test cleanly: the span identifies this request, every layer needs it, and no layer’s signature should mention it. Note that tracer.Start returns a new context — forgetting to reassign it is how a trace silently loses half its spans.

A request-scoped logger, which is the same pattern with the fields pre-bound:

// Illustrative snippet — not a complete program
func LoggerFromContext(ctx context.Context) *slog.Logger {
    if l, ok := ctx.Value(loggerKey{}).(*slog.Logger); ok {
        return l
    }
    return slog.Default() // always usable, never nil
}

Returning a working default rather than nil is what makes this safe to call from anywhere, including code paths that run outside a request.

13.6.7 Common Mistakes

Mutable state is the one that produces the strangest bugs:

// Illustrative snippet — not a complete program
// ✗ BROKEN: every holder of ctx shares this map, unsynchronised
ctx = context.WithValue(ctx, tagsKey{}, map[string]string{})

// ✓ store what is already immutable
ctx = context.WithValue(ctx, tagsKey{}, tags) // a value copy

The map is shared by every goroutine that receives the context, and nothing in context synchronises it. This is a data race and -race will find it — the only bug in this chapter that it does.

Summary: Context Values

WithValue is for request-scoped data crossing code you do not own. The litmus test — would this be a parameter if you controlled every signature? — settles almost every case, and rules out dependency injection immediately.

Keys must be an unexported type so no other package can construct one, and the key should never be exported: export WithX and XFromContext and keep the assertion in one place.

Lookup is a walk up a chain of one-value nodes, about 1.6 ns per hop, with no map and no index. WithValue allocates exactly 48 bytes and one object. So depth is the cost that matters: bundle values that arrive together, read once outside loops, and remember that the same walk is what makes deriving a child O(depth).

Self-Check Questions: Context Values

13.7 Context in Practice

The rules in this section are conventions rather than compiler-enforced requirements, which is exactly why they are worth stating: nothing will stop you breaking them, and the breakage shows up in production.

13.7.1 The First-Parameter Convention

Context goes first, is named ctx, and is never optional:

// Illustrative snippet — not a complete program
func Fetch(ctx context.Context, url string) (*Response, error)
func (s *Store) Get(ctx context.Context, id string) (*Item, error)

The convention is worth more than its aesthetics. A uniform position makes “is this cancellable?” answerable at a glance across a whole codebase, it makes the mechanical addition of contexts to an existing API a predictable edit, and it means a wrapper can forward ctx without thinking. The standard library follows it without exception.

Accept a context when the function does I/O, blocks, spawns goroutines, may run long enough to be worth abandoning, or calls anything that does. Do not accept one for pure computation, constructors that do no work, getters and setters, or String() — a context there is noise that suggests a cancellation point which does not exist.

13.7.2 Never Store a Context in a Struct

// Illustrative snippet — not a complete program
// ✗ BROKEN: one context, many calls, unrelated lifetimes
type Client struct {
    ctx  context.Context
    http *http.Client
}

func (c *Client) Get(url string) error {
    return do(c.ctx, url) // whose deadline is this?
}

A context describes the lifetime of one operation. A struct usually outlives many, so a stored context is either stale — cancelled by the first request that finished, breaking every later call — or immortal, silently discarding every caller’s deadline. Neither is discoverable from the call site, because the signature no longer mentions a context at all.

// Illustrative snippet — not a complete program
// ✓ the caller's scope reaches the work
type Client struct {
    http *http.Client
}

func (c *Client) Get(ctx context.Context, url string) error {
    return do(ctx, url)
}

The one exception is a type whose whole purpose is a lifetime — a server, a worker pool, a subscription. There the stored context is the object’s lifetime, and the honest form stores the cancel function too:

// Illustrative snippet — not a complete program
type Worker struct {
    ctx    context.Context
    cancel context.CancelFunc
    wg     sync.WaitGroup
}

func NewWorker(parent context.Context) *Worker {
    ctx, cancel := context.WithCancel(parent)
    return &Worker{ctx: ctx, cancel: cancel}
}

func (w *Worker) Stop() {
    w.cancel()
    w.wg.Wait() // cancel means "stop soon"; this means "stopped"
}

Note that per-operation methods on such a type still take their own ctx. The stored one governs the worker’s life, not each request’s.

13.7.3 Designing Context-Aware APIs

The duplicate-timeout rule catches people mid-migration:

// Illustrative snippet — not a complete program
// ✗ which one wins?
func Query(ctx context.Context, sql string, timeout time.Duration) error

// ✓ the caller expresses the bound in the context
func Query(ctx context.Context, sql string) error

If callers need a per-call bound, they have one: context.WithTimeout before the call. A second parameter can only agree with the context or contradict it.

Adding a context to an existing API without breaking callers is a two-signature move — keep the old name delegating to a new one:

// Illustrative snippet — not a complete program
func Fetch(url string) (*Response, error) {
    return FetchContext(context.Background(), url)
}

func FetchContext(ctx context.Context, url string) (*Response, error) {
    // real implementation
}

That is what the standard library did for database/sql and net/http, and the Context suffix is the recognised signal.

13.7.4 Propagation Across Boundaries

In HTTP handlers, the request already carries a context that is cancelled when the client disconnects:

// Illustrative snippet — not a complete program
func handler(w http.ResponseWriter, r *http.Request) {
    ctx := r.Context() // cancelled when the client goes away

    ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
    defer cancel()

    if err := doWork(ctx); err != nil {
        if errors.Is(err, context.DeadlineExceeded) {
            http.Error(w, "timeout", http.StatusGatewayTimeout)
            return
        }
        http.Error(w, "error", http.StatusInternalServerError)
        return
    }
}

// Illustrative snippet — not a complete program
// ✗ BROKEN: cancelled the instant the handler returns
go audit(r.Context(), event)

// ✗ ALSO BROKEN: survives, but drops the trace ID and every other value
go audit(context.Background(), event)

// ✓ keeps the values, drops the cancellation, sets a fresh bound
bg := context.WithoutCancel(r.Context())
ctx, cancel := context.WithTimeout(bg, 30*time.Second)
go func() {
    defer cancel()
    audit(ctx, event)
}()

If the background work needs the body, read it before responding — r.Body is not valid after the handler returns, whatever context you hand the goroutine.

Through a database, where the context bounds the query and the transaction both:

// Illustrative snippet — not a complete program
tx, err := db.BeginTx(ctx, nil)
if err != nil {
    return err
}
defer tx.Rollback() // no-op once Commit succeeds

if _, err := tx.ExecContext(ctx, q, args...); err != nil {
    return err
}
return tx.Commit()

Cancelling ctx here rolls the transaction back — database/sql watches the context for the life of the Tx. That is a good default and a sharp edge: a transaction started from a request context dies with the request, which is correct for a query and wrong for a commit you wanted to finish. If it must complete, it needs §13.3.5's detachment and a bound of its own.

Across a network boundary, the context does not travel — only its values can, and only if something serialises them. gRPC turns metadata into context values on the way in and back out; HTTP needs you to do it by hand, which is what the X-Request-ID header in §13.6.6 is doing. Deadlines are the exception worth knowing: gRPC propagates them, so a server sees a deadline derived from its caller’s, while a plain HTTP call does not unless you send one explicitly.

Into goroutines, always pass the context explicitly rather than capturing an outer one, so each goroutine’s scope is visible at the call site:

// Illustrative snippet — not a complete program
var wg sync.WaitGroup
for _, shard := range shards {
    wg.Go(func() {
        // a per-shard bound under the caller's budget
        c, cancel := context.WithTimeout(ctx, 2*time.Second)
        defer cancel()
        query(c, shard)
    })
}
wg.Wait()

13.7.5 Testing with Context

Since Go 1.24, t.Context() gives a test a context that is cancelled just before cleanup runs — the right default, and often miscited as a 1.21 feature:

// Illustrative snippet — not a complete program
func TestFetch(t *testing.T) {
    ctx := t.Context() // Go 1.24; cancelled before Cleanup
    if _, err := Fetch(ctx, testURL); err != nil {
        t.Fatal(err)
    }
}

Test that cancellation is honoured, which means asserting the work actually stopped rather than that cancel() returned:

// Illustrative snippet — not a complete program
func TestWorkerStopsOnCancel(t *testing.T) {
    ctx, cancel := context.WithCancel(t.Context())
    stopped := make(chan struct{})

    go func() {
        defer close(stopped)
        Worker(ctx)
    }()

    cancel()

    select {
    case <-stopped:
    case <-time.After(time.Second):
        t.Fatal("worker still running 1s after cancel")
    }
}

The timeout arm is the test. Without it the goroutine leaks and the test passes anyway — the failure mode §2.5 describes, reproduced in a test suite.

Test the timeout path with an already-expired context, which needs no sleeping:

// Illustrative snippet — not a complete program
ctx, cancel := context.WithTimeout(t.Context(), 0)
defer cancel()

err := Fetch(ctx, testURL)
if !errors.Is(err, context.DeadlineExceeded) {
    t.Fatalf("got %v, want DeadlineExceeded", err)
}

13.7.6 Common Mistakes

Summary: Context in Practice

Context is the first parameter, named ctx, never optional, never stored in a struct — with the single exception of a type whose purpose is a lifetime, where the cancel function belongs beside it and Stop waits for the work to end.

Accept a context, never create one mid-tree; put it on methods rather than constructors; never pair it with a timeout parameter. Return ctx.Err() so callers can tell a cancellation from a failure.

Across boundaries, r.Context() is cancelled the moment the handler returns, so background work needs WithoutCancel plus a fresh bound — not Background(), which throws away the trace ID that makes the work findable. And in tests, t.Context() (Go 1.24) is the right default, with the real assertion being that the work stopped, not that cancel() returned.

Self-Check Questions: Context in Practice

// Illustrative snippet — not a complete program
bg := context.WithoutCancel(r.Context())
ctx, cancel := context.WithTimeout(bg, 30*time.Second)
go func() { defer cancel(); audit(ctx, event) }()

// Illustrative snippet — not a complete program
select {
case <-stopped:
case <-time.After(time.Second):
    t.Fatal("worker still running 1s after cancel")
}