Partial Cancellation — Professional Level¶

Table of Contents¶

1. Introduction
2. Source Walkthrough: withoutCancelCtx
3. The cancelCtxKey Sentinel
4. propagateCancel and the Detach Boundary
5. Cause Propagation Rules
6. AfterFunc Internals
7. WithDeadlineCause and WithTimeoutCause
8. The parentCancelCtx Walk
9. Memory and GC Considerations
10. Timer Multiplexing
11. Race-Detector Behaviour
12. Goroutine Lifecycle Across Detach
13. Comparison With Other Runtimes
14. Designing Custom Context Types
15. Subtle Specification Corners
16. Performance Microbenchmarks
17. Compatibility and Versioning
18. Summary

Introduction¶

At the professional level, partial cancellation is no longer a pattern or an architecture — it is a precise contract enforced by specific lines of code in the standard library. This file walks through those lines.

You should already know:

• Why partial cancellation exists.
• How to use context.WithoutCancel, context.AfterFunc, context.WithCancelCause.
• How to compose detached contexts with timeouts, cancels, and value chains.
• How to design platform layers around detached work.

This file teaches:

• The exact source of withoutCancelCtx in src/context/context.go.
• The role of cancelCtxKey in cancellation propagation.
• The walking algorithm in parentCancelCtx.
• The rules for context.Cause propagation across detach boundaries.
• The AfterFunc mechanism and its memory cost.
• The subtle semantics that distinguish WithoutCancel from naive wrappers.
• The performance characteristics, the GC behaviour, the timer cost.

By the end, you should be able to read the context package source with full understanding, and design custom Context types that participate correctly in cancellation propagation.

Source Walkthrough: withoutCancelCtx¶

The implementation of context.WithoutCancel in src/context/context.go (as of Go 1.22+) is short. Here is the entire implementation, with annotations.

// WithoutCancel returns a copy of parent that is not canceled when parent is canceled.
// The returned context returns no Deadline or Err, and its Done channel is nil.
// Calling [Cause] on the returned context returns nil.
func WithoutCancel(parent Context) Context {
    if parent == nil {
        panic("cannot create context from nil parent")
    }
    return withoutCancelCtx{parent}
}

Three things to note:

1. The function panics on nil parent. This matches the rest of the context package — WithCancel(nil), WithValue(nil, ...), all panic.
2. The return value is a withoutCancelCtx struct, not a pointer. The struct is small (one pointer to the parent) and is heap-allocated by the conversion to Context interface.
3. There is no other state. No cancellation channels, no children, no timers.

The withoutCancelCtx struct itself:

type withoutCancelCtx struct {
    c Context
}

func (withoutCancelCtx) Deadline() (deadline time.Time, ok bool) {
    return
}

func (withoutCancelCtx) Done() <-chan struct{} {
    return nil
}

func (withoutCancelCtx) Err() error {
    return nil
}

func (c withoutCancelCtx) Value(key any) any {
    return value(c, key)
}

func (c withoutCancelCtx) String() string {
    return contextName(c.c) + ".WithoutCancel"
}

Each method:

• Deadline(): returns zero time.Time and false. There is no deadline.
• Done(): returns nil. A receive on nil blocks forever.
• Err(): returns nil. There is no cancellation.
• Value(key): calls the package-level value function, which walks the parent chain.
• String(): returns the parent's name plus ".WithoutCancel" for debugging.

The implementation is deliberately minimal. It does not hold any cancellation state, not register with the parent, not maintain a list of children. It is purely a value-passing wrapper that breaks the cancellation chain.

The cancelCtxKey Sentinel¶

How does the standard library know that a context derives from withoutCancelCtx and should be treated specially in cancellation propagation? Through the cancelCtxKey sentinel.

The sentinel is defined in context.go:

// &cancelCtxKey is the key that a cancelCtx returns itself for.
var cancelCtxKey int

Note the type: it is an int, but the address is the key. Comparing addresses is the standard library's way of getting a unique key without allocating.

The cancelCtx type implements Value to return itself when queried for this key:

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

When some code does ctx.Value(&cancelCtxKey), it gets the nearest cancelCtx ancestor.

For withoutCancelCtx, the Value method does not return self for cancelCtxKey. It delegates to the parent. But it has a special form of value walking that we will see next.

propagateCancel and the Detach Boundary¶

When context.WithCancel(parent) or context.WithTimeout(parent, ...) is called, the new cancelCtx must register with its cancellable ancestor. This is done by propagateCancel:

// propagateCancel arranges for child to be canceled when parent is.
func (c *cancelCtx) propagateCancel(parent Context, child canceler) {
    c.Context = parent

    done := parent.Done()
    if done == nil {
        return // parent is never canceled
    }

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

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

    if a, ok := parent.(afterFuncer); ok {
        c.mu.Lock()
        stop := a.AfterFunc(func() {
            child.cancel(false, parent.Err(), Cause(parent))
        })
        c.Context = stopCtx{Context: parent, stop: stop}
        c.mu.Unlock()
        return
    }

    goroutines.Add(1)
    go func() {
        select {
        case <-parent.Done():
            child.cancel(false, parent.Err(), Cause(parent))
        case <-child.Done():
        }
    }()
}

Trace through what happens when WithCancel(withoutCancelCtx) is called:

1. parent.Done() returns nil (because the parent is a withoutCancelCtx).
2. The if done == nil branch fires.
3. The function returns. The child is not registered with the parent.
4. The child's cancellation chain is broken at the withoutCancelCtx boundary.

This is the magic of WithoutCancel. The cancel propagation walks up until it hits a non-cancellable parent (returning nil from Done()), and stops there.

Why this design is robust¶

There is no special-case for withoutCancelCtx in propagateCancel. The function checks parent.Done() == nil, which is a fact about any context that does not produce a cancellation signal. withoutCancelCtx happens to have this property, but so does context.Background() and context.TODO().

The robustness comes from the fact that the "I have no cancellation signal" check is well-defined and universal.

What if someone subclasses?¶

A user-defined Context that returns nil from Done() is treated the same way as withoutCancelCtx. This is intentional — it gives library authors a clean way to implement detached-like contexts without depending on the standard library's specific type.

Cause Propagation Rules¶

context.Cause returns the error that caused a context to be canceled, or the context's Err() if there is no specific cause.

The function:

// Cause returns a non-nil error explaining why c was canceled.
// The first cancellation of c or one of its parents sets the cause.
// If that cancellation happened via a call to CancelCauseFunc(err),
// then [Cause] returns err.
// Otherwise Cause(c) returns the same value as c.Err().
// Cause returns nil if c has not been canceled yet.
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()
}

Three points:

1. It looks up the nearest cancelCtx ancestor.
2. If found, it returns that ancestor's stored cause.
3. If not found, it returns the context's own Err().

For a withoutCancelCtx, the value lookup for cancelCtxKey is interrupted by the withoutCancelCtx's own Value method, which does not return self for that key. The walk goes to the parent.

Wait — actually no. withoutCancelCtx.Value calls value(c, key), which is the package-level walk. Let's look at that:

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

Crucial line: case withoutCancelCtx: if key == &cancelCtxKey { return nil }. When the walker hits a withoutCancelCtx and is looking for the cancelCtxKey, it returns nil instead of continuing the walk.

This is the explicit mechanism that breaks Cause propagation across the detach boundary. Even if the parent had a cancelCtx ancestor with a stored cause, the walk stops at the withoutCancelCtx and Cause returns the context's own Err() (which is nil for withoutCancelCtx).

So Cause(detached) always returns nil. This matches the documentation:

Calling Cause on the returned context returns nil.

The mechanism is elegant: one sentinel check in the value walk.

Implications¶

If you layer WithCancelCause(detached, cause) on a detached context, then Cause(layered) after the layered context is cancelled returns cause — because the cancelCtx for layered is found in the walk before hitting any boundary.

If the parent had been cancelled with a cause before the detach, and you call Cause(detached), you get nil. The detached context does not propagate the parent's cause.

This is sometimes surprising. The documentation is clear, but the underlying mechanism — the sentinel return in the value walk — is hidden.

AfterFunc Internals¶

context.AfterFunc(ctx, f) registers f to be called in its own goroutine when ctx is cancelled.

The implementation:

// AfterFunc arranges to call f in its own goroutine after ctx is done
// (canceled or timed out).
// If ctx is already done, AfterFunc calls f immediately in its own goroutine.
//
// Multiple calls to AfterFunc on a context operate independently;
// one does not replace another.
//
// Calling the returned stop function stops the association of ctx with f.
// It returns true if the call stopped f from being run.
// If stop returns false,
// either the context is done and f has been started in its own goroutine;
// or f was already stopped.
// The stop function does not wait for f to complete before returning.
// If the caller needs to know whether f is completed,
// it must coordinate with f explicitly.
//
// If ctx has a "AfterFunc(func()) func() bool" method,
// AfterFunc will use it to schedule the call.
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, Canceled, nil)
        }
        return stopped
    }
}

The internal type:

type afterFuncCtx struct {
    cancelCtx
    once sync.Once // either starts running f or stops f from running
    f    func()
}

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

When the context is cancelled:

1. The internal cancelCtx is cancelled.
2. The function f runs in its own goroutine (via sync.Once to ensure single execution).
3. If stop was called first, the sync.Once was already triggered with a no-op, and f does not run.

Interaction with WithoutCancel¶

If you call AfterFunc(detached, f), what happens?

1. propagateCancel(detached, a) is called.
2. detached.Done() returns nil.
3. The "parent is never canceled" branch fires.
4. The function returns. a is never registered.

f will never be called. The stop function still works, but it is a no-op since there is no pending registration.

This is sometimes a bug. If you wrote:

context.AfterFunc(detached, cleanup)

…expecting cleanup to run, it never will. The detached context cannot be cancelled, so the callback never fires.

The fix: layer a cancellation on the detached context first.

ctx, cancel := context.WithCancel(detached)
defer cancel()
context.AfterFunc(ctx, cleanup)
// ... work ...
// When this function returns, cancel() runs, the AfterFunc fires.

AfterFunc memory cost¶

Each AfterFunc registration creates one afterFuncCtx struct, plus an entry in the parent's children map. The sync.Once is one word. The function f is captured by reference.

The cost is small but not zero. In a hot path with many AfterFunc calls, this can add up. Profile if you suspect.

AfterFunc and the afterFuncer interface¶

The propagateCancel function has a special case for contexts that implement afterFuncer:

type afterFuncer interface {
    AfterFunc(func()) func() bool
}

If the parent context has this method, the standard library uses it instead of allocating a goroutine to watch for cancellation. This is an optimisation for high-throughput cases where the propagation goroutine cost matters.

Most application code does not implement this; it is for library authors with special-purpose Context types.

WithDeadlineCause and WithTimeoutCause¶

Go 1.21 also added WithDeadlineCause and WithTimeoutCause. These are variants of WithDeadline and WithTimeout that accept a cause error to attach when the deadline fires.

func WithDeadlineCause(parent Context, d time.Time, cause error) (Context, CancelFunc)
func WithTimeoutCause(parent Context, timeout time.Duration, cause error) (Context, CancelFunc)

When the deadline expires, ctx.Err() returns context.DeadlineExceeded (as before), but Cause(ctx) returns the supplied cause.

This is useful for differentiating "this operation timed out because X" from generic timeouts. For example:

ctx, cancel := context.WithTimeoutCause(parent, time.Second, errors.New("user request limit"))
defer cancel()

If the timeout fires, Cause(ctx) returns the descriptive error, even though ctx.Err() is the generic DeadlineExceeded.

Interaction with WithoutCancel¶

If you layer WithTimeoutCause(WithoutCancel(parent), d, cause) and the timeout fires:

• ctx.Err() = DeadlineExceeded.
• Cause(ctx) = the supplied cause.

If the timeout has not fired and the parent is cancelled:

• ctx.Err() = nil (because the detach broke the propagation).
• Cause(ctx) = nil.

The detached and timeout layers cooperate cleanly.

The parentCancelCtx Walk¶

The function parentCancelCtx walks the parent chain to find the nearest cancelCtx. If it finds one, the new child can register directly. If not, the new child must spawn a goroutine to watch for cancellation.

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
}

The function:

1. Checks if the parent's Done() is the closed sentinel channel or nil — in either case, no parent cancelCtx is useful.
2. Looks up the cancelCtxKey value, which (per the value walk we saw) returns the nearest cancelCtx ancestor unless a withoutCancelCtx interrupts the walk.
3. Verifies that the cancelCtx's done channel matches the parent's Done() — this protects against user code that has overridden Done() on a custom context.

For a withoutCancelCtx, the parent's Done() returns nil, so step 1 returns false immediately. No cancelCtx is found.

For a child of withoutCancelCtx, say WithCancel(detached):

• detached.Done() returns nil.
• The new cancelCtx is created.
• propagateCancel(detached, newChild) is called.
• The "parent is never canceled" branch fires.
• The new cancelCtx is its own root for cancellation purposes.

This is exactly the behaviour we want: cancellation contexts derived from a detached parent become their own roots.

Memory and GC Considerations¶

A detached context holds a pointer to its parent. The parent holds pointers to its values. Therefore the detached context (transitively) holds references to all values in the parent chain.

The garbage collector cannot reclaim:

• The detached context (while any code holds a reference).
• The parent chain of contexts.
• All values stored in any valueCtx in that chain.

This can cause subtle memory pressure. Examples:

1. A handler stores a giant response body in the context (bad practice, but common). The handler spawns a detached goroutine. The detached goroutine holds the context, which holds the response body. Until the goroutine exits, the response body is not collected.

2. A long-running detached operation (say, 30 seconds) holds the context. If 100 such operations are in flight, 100 copies of the parent value chain are alive.

The fix:

• Extract values from the parent at detach time. Pass them as function parameters.
• Do not store large values in the context.
• Bound the duration of detached operations.

For most production services, this is not a practical issue. But at very high throughput or very long durations, it matters.

Children maps and GC¶

A cancelCtx maintains a children map[canceler]struct{}. When children are cancelled (or their cancel function is called), they are removed from the map.

If a child is never cancelled, it stays in the map forever. The map grows. This is a leak.

For withoutCancelCtx, there is no children map — the wrapper does not participate in cancellation propagation. So no leak from this source.

For a cancelCtx whose cancel function is never called (a common bug), the child stays in the parent's map. The fix: always defer cancel().

Closure captures¶

A detached goroutine that captures large values in a closure keeps them alive for as long as the goroutine runs.

func handler(r *http.Request) {
    bigData := loadBig(r) // 100 MB
    detached := context.WithoutCancel(r.Context())
    go func() {
        time.Sleep(time.Minute)
        process(detached, bigData) // captures bigData
    }()
}

bigData is alive for at least a minute. If the handler is called 60 times per second, you have 6 GB of bigData retained.

Fix: only capture what you need.

small := extractSmallPart(bigData)
go func() {
    time.Sleep(time.Minute)
    process(detached, small)
}()

Timer Multiplexing¶

Each WithTimeout allocates a time.Timer. Each timer has some overhead. For many concurrent detached operations, the timers add up.

The Go runtime multiplexes timers efficiently. Internally, all timers share a heap, and the runtime fires them based on wall-clock time. The cost per timer is roughly:

• 64 bytes for the timer structure.
• One entry in the timer heap.
• Some bookkeeping on add/remove.

For 10,000 concurrent timers, expect ~640 KB of memory just for timers. The CPU cost is O(log n) per add/remove.

This is fine for most services. For extreme cases (100,000+ concurrent timers), consider batching multiple operations under a single timer or using a coarser-grained scheduler.

Cancellation timer¶

When you defer cancel() on a WithTimeout, the timer is stopped. If you forget the defer, the timer fires when its deadline elapses; the cancellation runs; nobody is listening; the goroutine eventually exits.

The leak is small but cumulative. Always defer cancel().

Race-Detector Behaviour¶

The Go race detector tracks concurrent accesses to shared memory. Detached contexts share values with their parents.

A scenario:

func handler(r *http.Request) {
    user := &User{Name: "Alice"}
    ctx := context.WithValue(r.Context(), userKey{}, user)
    detached := context.WithoutCancel(ctx)
    go func() {
        u := detached.Value(userKey{}).(*User)
        u.Name = "Bob" // <-- write from goroutine
    }()
    user.Name = "Carol" // <-- write from handler
}

The race detector flags this. The detached context shares the user pointer with the parent; both write to it concurrently.

The fix: contexts should hold immutable values. Mutable values must be guarded by mutexes or copied at detach time.

cancelCtx internal locking¶

Each cancelCtx has a mutex protecting its err, cause, and children fields. The race detector tracks these correctly. Cancellation operations from multiple goroutines are safe.

withoutCancelCtx has no mutex¶

Because it has no mutable state, withoutCancelCtx does not need a mutex. Concurrent calls to its methods are trivially safe.

Goroutine Lifecycle Across Detach¶

A detached goroutine has its own lifecycle:

1. Spawn. The handler does go func() { ... }(). The runtime creates a new goroutine, scheduled to run.
2. Execution. The goroutine runs. It uses the detached context for downstream calls.
3. Termination. The goroutine's function returns or panics. The runtime cleans up the goroutine.

Crucially, the goroutine's lifecycle is not tied to any context. The context is just data the goroutine carries.

A detached goroutine that loops forever is a leak. The context's lack of cancellation does not cause the leak; the loop does.

Goroutine pinning¶

In some Go versions, goroutines can be "pinned" to OS threads (via runtime.LockOSThread). This is relevant for code that interacts with thread-local state in C libraries.

Detached goroutines have the same pinning behaviour as any other goroutine. Pinning is independent of context.

Goroutine local storage¶

Go has no built-in goroutine-local storage. The closest pattern is the context.Context itself — values stored in the context act like goroutine-locals for the goroutines that hold a reference.

Detached contexts share their value chain with the parent. So a detached goroutine sees the same "goroutine-local-like" values as the parent.

If you want fresh per-detached-goroutine storage, allocate it explicitly:

go func() {
    localState := newState()
    detachedDo(detached, localState)
}()

The localState is not in the context; it is a goroutine-specific variable.

Comparison With Other Runtimes¶

Java's CompletableFuture¶

CompletableFuture does not have a native equivalent of WithoutCancel. Cancellation of a future does not affect its parent. To "detach," you simply do not chain.

Values do not propagate automatically. Java's MDC (mapped diagnostic context) for logging is a thread-local that does not survive across thread boundaries unless explicitly copied.

.NET's CancellationToken¶

CancellationToken is the analog of Done(). There is no built-in way to "detach" — you create a new token.

To preserve values, you would use the IServiceProvider or AsyncLocal<T>. These are not equivalent to context values; they are more like thread-locals.

Rust's tokio¶

tokio::spawn runs a future on the runtime. The future runs independently of its caller. There is no implicit cancellation propagation.

To get Go-like behaviour, you would explicitly check a cancellation token in the future. Detaching means not checking the token.

Kotlin coroutines¶

CoroutineScope is the lifetime boundary. SupervisorJob is the closest equivalent to WithoutCancel — a child of a supervisor scope is cancelled independently of its parent.

The mental model is similar: scopes, supervisors, and detached children. The API differs.

What makes Go's design distinct¶

Three things:

1. Explicit context plumbing. Every operation that wants cancellation takes a Context. There is no thread-local sneakiness.
2. Immutable contexts. Contexts are immutable. Derivations create new contexts. This avoids the mutation bugs that plague thread-local approaches.
3. Composition over inheritance. WithoutCancel, WithCancel, WithTimeout, WithValue are composable. You compose them in any order for any combination of behaviours.

The trade-off: every function signature has an extra parameter. Some find this verbose. Go programmers find the explicit lifetime tracking worth the verbosity.

Designing Custom Context Types¶

Library authors sometimes want custom Context types — for example, a "service context" that bundles a logger, a metrics emitter, and a request ID together.

The pattern:

type Service struct {
    Logger  *log.Logger
    Metrics *Metrics
    ReqID   string
}

type serviceCtx struct {
    context.Context
    svc *Service
}

func WithService(parent context.Context, svc *Service) context.Context {
    return serviceCtx{Context: parent, svc: svc}
}

func ServiceFromCtx(ctx context.Context) *Service {
    if sc, ok := ctx.(serviceCtx); ok {
        return sc.svc
    }
    if v, ok := ctx.Value(serviceKey{}).(*Service); ok {
        return v
    }
    return nil
}

This is a common pattern. The custom context wraps a parent and adds typed accessors.

Custom context and WithoutCancel¶

What happens if you call context.WithoutCancel(serviceCtx{...})?

The withoutCancelCtx wraps the serviceCtx. Value lookups walk through the withoutCancelCtx to the serviceCtx. The serviceCtx's Value method (inherited from the embedded Context) returns whatever the embedded context returns.

Crucially, the type assertion if sc, ok := ctx.(serviceCtx); ok fails on a detached context, because the detached context is a withoutCancelCtx, not a serviceCtx.

The fix: do not rely on type assertions for value extraction. Use the Value method with a key:

type serviceKey struct{}

func WithService(parent context.Context, svc *Service) context.Context {
    return context.WithValue(parent, serviceKey{}, svc)
}

func ServiceFromCtx(ctx context.Context) *Service {
    if v, ok := ctx.Value(serviceKey{}).(*Service); ok {
        return v
    }
    return nil
}

Now ServiceFromCtx(detached) works, because the value lookup walks through the withoutCancelCtx to find the serviceKey in the parent.

Custom context that implements Done()¶

If your custom context implements Done(), you participate in cancellation propagation. Be careful:

• Done() must return the same channel every time, or a nil.
• The channel must close when the context is cancelled.
• Err() must return non-nil after the channel closes.

If you get this wrong, propagateCancel may behave unexpectedly.

A safe pattern: embed a cancelCtx (or use composition).

Custom context that implements afterFuncer¶

A custom context can opt into the afterFuncer interface to optimize AfterFunc. This is rarely useful for application code but is used by some libraries.

Subtle Specification Corners¶

A few corners of the spec that catch even experienced engineers.

Corner 1: Cause on a cancelled cancel-cause context¶

parent, cancel := context.WithCancelCause(context.Background())
cancel(errors.New("boom"))
context.Cause(parent) // "boom"

Cause returns the supplied error.

Corner 2: Cause on a child of cancel-cause context¶

parent, cancel := context.WithCancelCause(context.Background())
child, _ := context.WithCancel(parent)
cancel(errors.New("boom"))
context.Cause(child) // "boom" — walked up

The walk finds the parent cancelCtx and returns its cause.

Corner 3: Cause across WithoutCancel boundary¶

parent, cancel := context.WithCancelCause(context.Background())
detached := context.WithoutCancel(parent)
cancel(errors.New("boom"))
context.Cause(detached) // nil — walk interrupted

The walk hits withoutCancelCtx, returns nil for cancelCtxKey, and Cause falls through to detached.Err() which is nil.

Corner 4: Cause after layered cancel on detached¶

parent, _ := context.WithCancelCause(context.Background())
detached := context.WithoutCancel(parent)
inner, innerCancel := context.WithCancelCause(detached)
innerCancel(errors.New("inner"))
context.Cause(inner) // "inner"
context.Cause(detached) // still nil

Each level has its own cause.

Corner 5: Layered WithDeadlineCause on detached¶

detached := context.WithoutCancel(parent)
ctx, _ := context.WithDeadlineCause(detached, time.Now().Add(time.Millisecond), errors.New("budget"))
time.Sleep(10 * time.Millisecond)
ctx.Err() // context.DeadlineExceeded
context.Cause(ctx) // "budget"

Cause carries the supplied error.

Corner 6: AfterFunc on a never-cancelled context¶

detached := context.WithoutCancel(parent)
stop := context.AfterFunc(detached, func() { fmt.Println("never") })
// f never fires; stop() returns false (no registration was made? or true?)

Actually, let's check. AfterFunc calls propagateCancel. If parent.Done() == nil, the propagation returns early without registering. The afterFuncCtx is created but never registered.

Then stop() calls a.once.Do(...). Since the Once has not been triggered, it sets stopped = true and proceeds to call a.cancel(...). The cancel marks the internal cancelCtx as cancelled but does not invoke f (because the once was already used).

Wait — actually looking more carefully at the code, the cancel always calls a.once.Do(...) which would normally schedule f. But if stop was called first, the once already ran the "set stopped" closure, so the cancel's closure never runs. So f never executes.

Return value of stop: true (it set stopped = true).

This is consistent: "stop returns true if the call stopped f from being run."

But the call never had a chance to run anyway because the registration never propagated. The stop returns true even though there was nothing to stop.

This is a slight quirk but not a bug. The contract is "did this stop call prevent f from running?" The answer is yes — vacuously, since f was never going to run.

Corner 7: Concurrent cancel() calls¶

If two goroutines call cancel() simultaneously on a WithCancel context, only one of them "wins" — the cancelCtx uses a mutex internally. The losing call is a no-op.

This is implicit thread-safety in the API. cancel functions are safe to call from any goroutine.

Corner 8: Calling cancel() after a deadline has fired¶

After a deadline-induced cancellation, calling cancel() is a no-op. The mutex is held; the err is set; subsequent calls return without effect.

Performance Microbenchmarks¶

These are illustrative — measure on your hardware.

WithoutCancel allocation¶

func BenchmarkWithoutCancel(b *testing.B) {
    parent := context.Background()
    for i := 0; i < b.N; i++ {
        _ = context.WithoutCancel(parent)
    }
}

Result on a typical laptop: ~10 ns/op, 16 bytes/op, 1 alloc/op.

The cost is minimal.

WithCancel allocation¶

func BenchmarkWithCancel(b *testing.B) {
    parent := context.Background()
    for i := 0; i < b.N; i++ {
        _, cancel := context.WithCancel(parent)
        cancel()
    }
}

Result: ~100 ns/op, ~200 bytes/op, several allocs.

Significantly more than WithoutCancel, but still cheap.

Value lookup through detached¶

func BenchmarkValueLookupDetached(b *testing.B) {
    type k struct{}
    parent := context.WithValue(context.Background(), k{}, "v")
    detached := context.WithoutCancel(parent)
    for i := 0; i < b.N; i++ {
        _ = detached.Value(k{})
    }
}

Result: ~5 ns/op, 0 alloc/op.

The walk has one extra hop compared to direct parent lookup, but it is negligible.

Spawning a detached goroutine with timeout¶

func BenchmarkDetachedGo(b *testing.B) {
    parent := context.Background()
    for i := 0; i < b.N; i++ {
        d := context.WithoutCancel(parent)
        ctx, cancel := context.WithTimeout(d, time.Second)
        go func() { defer cancel() }()
    }
}

Result: ~3 µs/op, ~1 KB/op, several allocs.

Most of the cost is the goroutine, not the context manipulation.

Compatibility and Versioning¶

Go 1.21¶

• Adds WithoutCancel.
• Adds AfterFunc.
• Adds WithDeadlineCause, WithTimeoutCause.

Go 1.20¶

• Adds WithCancelCause.
• Adds Cause.

Go 1.7 (the original)¶

• Context, WithCancel, WithDeadline, WithTimeout, WithValue, Background, TODO.

Backporting¶

If you must support Go 1.20, you can hand-roll a withoutCancelCtx equivalent (as shown in the junior file). The semantics are mostly the same, except that:

• propagateCancel does not know about your wrapper, so children of your wrapper will spawn a watcher goroutine (the slow path).
• Cause propagation across your wrapper is identical to the standard library's behaviour, because the underlying mechanism is the value walk plus the cancelCtxKey sentinel — your wrapper does not interfere with the walk unless you implement Value specially.

For most application code, the hand-rolled wrapper is fine. The slow-path goroutine cost is negligible at typical scale.

Forward compatibility¶

Future Go versions may add more cancellation primitives. The pattern is well-established now; expect more variants (per-deadline cause, per-cancel handlers, etc.) rather than fundamental redesigns.

Summary¶

At the professional level, partial cancellation is no longer about choosing the right API — it is about understanding the contracts those APIs implement.

You now know:

• The exact source of withoutCancelCtx.
• The role of cancelCtxKey in value propagation.
• How propagateCancel detects the detach boundary.
• The rules for Cause propagation and why they break at the boundary.
• The internals of AfterFunc and its interaction with WithoutCancel.
• Memory, GC, and timer considerations.
• The race-detector implications.
• How to design custom Context types that participate correctly.
• The performance characteristics.
• The compatibility story.

The standard library is small. Each piece has a precise contract. Knowing the contracts and the implementation lets you debug subtle bugs, design custom primitives, and reason about edge cases with confidence.

Closing¶

This file completes the partial-cancellation curriculum. Junior taught the API. Middle taught the patterns. Senior taught the architecture. Professional taught the internals.

You should now be able to answer:

• Why does Done() return nil on a detached context?
• Why does Cause not propagate across the detach boundary?
• How does propagateCancel know to stop at the detach?
• What is the memory cost of a long-running detached goroutine?
• How would I implement a custom Context type that behaves like WithoutCancel?

If any of those questions feel unclear, re-read the relevant section. If they all feel obvious, you are done with this topic.

Move on to the next chapter in the cancellation curriculum: cleanup ordering, which builds on the partial-cancellation foundation.

Deep Source Tour: The Full context.go Cancellation Path¶

Let us walk through the entire source path for cancellation propagation, line by line where relevant.

The Context interface¶

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

Four methods. The minimum surface area for a context.

The package-level helpers¶

Background() and TODO() return singletons:

type backgroundCtx struct{ emptyCtx }
type todoCtx struct{ emptyCtx }

type emptyCtx struct{}

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

func Background() Context { return backgroundCtx{} }
func TODO() Context       { return todoCtx{} }

Notice that backgroundCtx and todoCtx are zero-size structs with no fields. The runtime allocates each as a singleton via the type, not the value. Each call returns the same value.

Their Done() returns nil, just like withoutCancelCtx. This is the universal "never cancelled" sentinel.

The cancelCtx type¶

The workhorse:

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 created lazily on first call to Done(). This avoids allocating a channel for contexts that never use it.
• children is a map of registered children that should be cancelled when this context is cancelled.
• err and cause are set atomically by cancel().

The Done() method¶

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. Optimised for the common case where done has already been allocated.

The Err() method¶

func (c *cancelCtx) Err() error {
    c.mu.Lock()
    defer c.mu.Unlock()
    return c.err
}

Returns the stored error. Nil if not cancelled.

The 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 canceled
    }
    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)
    }
}

The cancel:

1. Acquires the mutex.
2. Returns early if already cancelled.
3. Sets err and cause.
4. Closes (or substitutes a pre-closed) done channel.
5. Recursively cancels all children.
6. Releases the mutex.
7. Removes this context from its parent's children map.

The recursion is the cancellation propagation. A single root cancellation flows through the entire subtree.

The removeChild function¶

func removeChild(parent Context, child canceler) {
    p, ok := parentCancelCtx(parent)
    if !ok {
        return
    }
    p.mu.Lock()
    if p.children != nil {
        delete(p.children, child)
    }
    p.mu.Unlock()
}

When a child is cancelled (or its cancel function is called by the user), it removes itself from the parent's children map. This prevents the map from growing unboundedly.

The closedchan sentinel¶

var closedchan = make(chan struct{})

func init() {
    close(closedchan)
}

A pre-closed channel. Used as the done value for contexts that were never queried for Done() before being cancelled. Avoids allocating a channel that will be immediately closed.

Cancellation propagation flow¶

When cancel() is called on a root context:

1. The root marks itself cancelled.
2. The root closes its done channel.
3. The root iterates its children: a. For each child, the root calls child.cancel(false, err, cause). b. The child marks itself cancelled. c. The child closes its done channel. d. The child iterates its children.
4. The recursion bottoms out at leaves.
5. The original root removes itself from its parent (if any).

This is the classic tree cancellation. Now consider where withoutCancelCtx fits in.

Where withoutCancelCtx breaks the chain¶

A withoutCancelCtx has no cancel method. It is not a canceler. When propagateCancel is called for a child of withoutCancelCtx, the function checks parent.Done() == nil, sees true, and returns without registering the child anywhere.

So the parent's children map never gains the child. When the parent's lineage is cancelled, the cancellation propagation never reaches the child.

This is the mechanism of partial cancellation. Not a special case, not a flag, just the absence of a registration.

Deep Source Tour: The Value Walk¶

The package-level value function:

func value(c Context, key any) any {
    for {
        switch ctx := c.(type) {
        case *cancelCtx:
            if key == &cancelCtxKey {
                return c
            }
            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 *valueCtx:
            if key == ctx.key {
                return ctx.val
            }
            c = ctx.Context
        case backgroundCtx, todoCtx:
            return nil
        default:
            return c.Value(key)
        }
    }
}

The walk:

• For *cancelCtx: return self if asked for cancelCtxKey; else walk to parent.
• For withoutCancelCtx: return nil if asked for cancelCtxKey; else walk to parent.
• For *timerCtx: return the embedded cancelCtx if asked for cancelCtxKey; else walk to parent.
• For *valueCtx: return the stored value if the key matches; else walk to parent.
• For root contexts (backgroundCtx, todoCtx): return nil.
• For custom contexts (default case): delegate to the user's Value method.

This is the heart of value resolution.

The cancelCtxKey special case in withoutCancelCtx¶

The line:

case withoutCancelCtx:
    if key == &cancelCtxKey {
        return nil
    }
    c = ctx.c

This is the explicit mechanism that prevents Cause from finding the parent's cancelCtx when crossing a detach boundary. Without this line, Cause(detached) would walk through and find the parent's cancelCtx, returning the parent's cause.

The behaviour is intentional and documented. The implementation is a single sentinel check.

The valueCtx type¶

type valueCtx struct {
    Context
    key, val any
}

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

A WithValue context is a small wrapper holding one key-value pair and a parent. Lookups check the local pair first, then walk.

For deeply nested WithValue chains, the lookup cost is O(depth). For typical contexts (depth 3-10), this is negligible.

Deep Source Tour: WithCancel and WithCancelCause¶

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

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

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

Both functions create a cancelCtx and propagate cancellation registration. The difference is only in the returned cancel function — WithCancel returns a parameterless function; WithCancelCause returns one that accepts a cause.

The cancelCtx itself stores both err and cause. The cancel function is the only difference between the two APIs.

Deep Source Tour: WithDeadline and WithTimeout¶

func WithDeadline(parent Context, d time.Time) (Context, CancelFunc) {
    return WithDeadlineCause(parent, d, nil)
}

func WithDeadlineCause(parent Context, d time.Time, cause error) (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, cause)
        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, cause)
        })
    }
    return c, func() { c.cancel(true, Canceled, nil) }
}

func WithTimeout(parent Context, timeout time.Duration) (Context, CancelFunc) {
    return WithDeadline(parent, time.Now().Add(timeout))
}

func WithTimeoutCause(parent Context, timeout time.Duration, cause error) (Context, CancelFunc) {
    return WithDeadlineCause(parent, time.Now().Add(timeout), cause)
}

Several important details:

• If the parent's deadline is already sooner, WithDeadline degenerates to WithCancel. There is no point creating a timer for a deadline that the parent will hit first.
• The timerCtx embeds a cancelCtx. The timer fires cancel on the embedded cancelCtx.
• If the duration is non-positive, the cancel is fired immediately.
• The cancel function returned by WithDeadlineCause does not propagate the cause — calling cancel() is a "manual cancel," semantically distinct from a deadline-fire. The cause field is reserved for the deadline expiration.

The timerCtx type¶

type timerCtx struct {
    cancelCtx
    timer *time.Timer

    deadline time.Time
}

func (c *timerCtx) Deadline() (deadline time.Time, ok bool) {
    return c.deadline, true
}

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()
}

The cancel stops the timer. This is essential for resource management — without Stop(), the timer fires later (with no effect, since the context is already cancelled) but the runtime still tracks it.

Deep Source Tour: propagateCancel in Depth¶

Let us look at propagateCancel again, line by line:

func (c *cancelCtx) propagateCancel(parent Context, child canceler) {
    c.Context = parent

    done := parent.Done()
    if done == nil {
        return // parent is never canceled
    }

The c.Context = parent line records the parent for later use. Then parent.Done() is queried. If nil, the parent never fires cancellation, so we are done — the child is its own root.

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

If the parent is already cancelled, fire the child immediately. This handles the race where the parent was cancelled between the caller's check and our check.

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

If we can find an ancestor cancelCtx, register with it. The double-check under the mutex handles concurrent cancellation.

    if a, ok := parent.(afterFuncer); ok {
        c.mu.Lock()
        stop := a.AfterFunc(func() {
            child.cancel(false, parent.Err(), Cause(parent))
        })
        c.Context = stopCtx{Context: parent, stop: stop}
        c.mu.Unlock()
        return
    }

If the parent has an AfterFunc method (the afterFuncer interface), use it. This avoids allocating a goroutine.

    goroutines.Add(1)
    go func() {
        select {
        case <-parent.Done():
            child.cancel(false, parent.Err(), Cause(parent))
        case <-child.Done():
        }
    }()
}

The fallback: spawn a goroutine that watches both signals. This is the slow path, used for custom Context types that do not implement afterFuncer and are not derived from cancelCtx.

The goroutines.Add(1) is a debug counter used by the context package's tests to verify that the slow path is exercised correctly.

Why the multiple branches¶

The function has four paths because performance matters:

1. Never-cancelled parent. Zero-cost.
2. Already-cancelled parent. Immediate cancellation, no registration.
3. Standard cancelCtx ancestor. Register in the children map. Constant cost.
4. AfterFunc-supporting ancestor. Use the user-provided hook. Avoids goroutine.
5. Generic Context. Spawn a watcher goroutine. Most expensive.

The standard library cares about each of these. For 99% of real usage, paths 1-3 are taken. Path 4 is for libraries with custom contexts. Path 5 is rare but supported.

Deep Source Tour: 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
}

Three checks:

1. done must not be closedchan or nil. Either indicates "no useful cancellation."
2. The value walk must find a cancelCtx.
3. The cancelCtx's done must match the parent's done. This protects against a custom context that overrides Done().

For withoutCancelCtx, step 1 fails (Done is nil), and the function returns false.

For a child of withoutCancelCtx (a fresh cancelCtx created by WithCancel(detached)), step 1 succeeds (the new cancelCtx has its own done channel), but step 2 finds the new cancelCtx itself — and step 3 verifies it. So parentCancelCtx(WithCancel(detached)) returns the new cancelCtx as its own parent. But that is fine; the function is called from inside propagateCancel which is about registering with the parent, and at that point the new cancelCtx is registering with detached, which has no useful parent.

Wait, let's re-read. propagateCancel is called on the new child with the parent as argument. So when WithCancel(detached) is called:

1. A new cancelCtx c is allocated.
2. c.propagateCancel(detached, c) is called.
3. Inside, done := detached.Done() is nil.
4. The function returns at the if done == nil check.

So parentCancelCtx is never called in this scenario. The new cancelCtx is its own root for cancellation purposes.

Deep Source Tour: The Cause Function¶

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 function:

1. Looks up cancelCtxKey.
2. If found, returns the stored cause (under mutex).
3. Otherwise, returns the context's own Err().

For a detached context, the value walk returns nil for cancelCtxKey. So the function falls through to detached.Err(), which is nil. So Cause(detached) is nil.

For a child of detached (after layered cancel), the value walk finds the child's own cancelCtx. So Cause(child) returns the child's cause.

This is the precise mechanism. Every word in the documented behaviour maps to a specific line of code.

Deep Source Tour: AfterFunc Source¶

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, Canceled, nil)
        }
        return stopped
    }
}

The function:

1. Allocates an afterFuncCtx.
2. Calls propagateCancel to register for cancellation.
3. Returns a stop function.

The stop function uses sync.Once:

• If the once has not run, it sets stopped = true.
• If stopped is true, the cancel is called (cancelling the internal cancelCtx).

The cancel method of afterFuncCtx:

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

The cancel:

1. Cancels the internal cancelCtx.
2. Removes from parent's children map.
3. Uses once.Do to either run f or be a no-op (if stop was called first).

The clever design: a single sync.Once arbitrates between "stop won the race" and "cancellation won the race." Whoever runs first wins; the other becomes a no-op.

Subtle: ordering of removeFromParent vs once.Do¶

If the parent has already cancelled, the propagation has already happened (the child's cancel was called). Subsequent calls to the same child's cancel (e.g., from the stop function) are no-ops because once.Do has already run.

The removeFromParent arg distinguishes between "parent is cancelling me, so don't remove myself from parent's map" and "I'm being cancelled directly via stop, so remove myself." The parent's iteration over its children would not see the entry being removed concurrently, but removeFromParent = false saves the work.

Memory cost¶

Each AfterFunc registration allocates:

• One afterFuncCtx struct (~64 bytes).
• One entry in the parent's children map (~16 bytes amortised).
• One captured closure of f (size depends on f).

For thousands of concurrent AfterFunc registrations, expect KB-scale memory. Negligible for most uses.

Deep Source Tour: goroutines Debug Counter¶

var goroutines atomic.Int32

Used to count goroutines spawned for cancellation propagation (the slow path). Tests check that the counter behaves as expected.

This is internal; application code does not see it. But it is a good example of how the standard library carefully measures the cost of its less-optimal paths.

Deep Topic: Why Done() Returns a Channel¶

The Done() method returns <-chan struct{}, not a function or other primitive. Why a channel?

Channels integrate with select. The select statement is Go's built-in way to wait for multiple events. A channel that closes when an event happens is the idiomatic signal.

A function-based API (like IsDone() bool) would require polling. A condition variable would require a different vocabulary. A channel fits the language.

The cost: every cancelCtx that is queried for Done() must allocate a channel. The lazy allocation in cancelCtx.Done() defers this cost until first use.

For withoutCancelCtx, returning nil avoids the cost entirely. A receive on nil blocks forever, which is the correct semantics for "never cancelled."

This is a deliberate design choice. The nil return is not a sentinel; it is the same value as the zero value of a channel type, which Go specifies as a blocking-forever channel.

Deep Topic: Channel vs Atomic Bool¶

A common alternative is to use an atomic.Bool instead of a channel. The advantages:

• Cheaper to check (a single atomic load).
• No allocation.

The disadvantages:

• Cannot be used with select. Code that wants to wait on cancellation OR something else must poll.

Go chose the channel because select is too useful to give up. The cost of the channel allocation is paid once per Done() call, not per cancellation check.

For very-high-throughput code that wants to check cancellation in a hot loop, the standard pattern is:

if err := ctx.Err(); err != nil {
    return err
}

Err() is just a mutex-protected read; it does not involve the channel at all. Use it for fast polling.

Deep Topic: The string() Method¶

Each context type has a String() method for debugging:

func (c *cancelCtx) String() string {
    return contextName(c.Context) + ".WithCancel"
}

func (c *timerCtx) String() string {
    return contextName(c.cancelCtx.Context) + ".WithDeadline(" + c.deadline.String() + " [" + time.Until(c.deadline).String() + "])"
}

func (c *valueCtx) String() string {
    return contextName(c.Context) + ".WithValue(type " + reflectlite.TypeOf(c.key).String() + ", val " + stringify(c.val) + ")"
}

func (c withoutCancelCtx) String() string {
    return contextName(c.c) + ".WithoutCancel"
}

Each String includes the parent's name plus a description of this layer. For a deep chain, the output is informative:

context.Background.WithValue(type main.userKey, val alice).WithCancel.WithoutCancel

This is useful for log lines and error messages.

contextName helper¶

func contextName(c Context) string {
    if s, ok := c.(stringer); ok {
        return s.String()
    }
    return reflectlite.TypeOf(c).String()
}

Uses the context's String method if available; otherwise falls back to reflection.

Deep Topic: stopCtx for afterFuncer¶

type stopCtx struct {
    Context
    stop func() bool
}

When propagateCancel registers via the afterFuncer interface, it wraps the parent in a stopCtx to remember the stop function. When the child is later cancelled or removed, the stop function is called to release the registration.

This is internal plumbing; application code does not see stopCtx.

Deep Topic: Atomic operations on done¶

The done field of cancelCtx is an atomic.Value. Why atomic?

• Done() reads it without holding the mutex (for performance).
• cancel() writes it.
• propagateCancel may read it via parentCancelCtx.

Concurrent reads and writes to a regular field would be a data race. atomic.Value provides safe concurrent access.

The performance win: Done() is called frequently (especially in select statements); avoiding the mutex makes it fast.

Deep Topic: The canceler interface¶

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

Both *cancelCtx and *timerCtx implement this. afterFuncCtx also implements it (via embedded cancelCtx).

The interface is used internally for propagation. It is not exported.

A custom Context type can implement canceler and participate in propagation more efficiently. This is an advanced library-author technique; most code does not need it.

Deep Topic: Reflectlite¶

The context package uses reflectlite instead of reflect. This is the runtime's lightweight reflection package. It avoids pulling in the full reflect package and its dependencies.

For application code, this is invisible. For the standard library's bootstrap, it matters because context is imported by net/http and other low-level packages.

Deep Topic: Error Handling in cancel¶

func (c *cancelCtx) cancel(removeFromParent bool, err, cause error) {
    if err == nil {
        panic("context: internal error: missing cancel error")
    }
    if cause == nil {
        cause = err
    }
    ...
}