With context.WithCancelCause, what do ctx.Err() and context.Cause(ctx) each return after cancellation?

## The problem it solves Plain `context.WithCancel` gives you exactly one bit of information at the receiving end: the context is done, and `ctx.Err()` says `context.Canceled`. In a system where several things can cancel the same work — the caller went away, a sibling attempt already won, a supervisor is shutting the runner down, an input turned out to be corrupt — that single sentinel is the same in all four cases. The goroutine that returns it cannot log a useful reason, and the layer above cannot decide whether to report a failure or a normal shutdown. `context.WithCancelCause` closes that gap by letting the *canceller* attach an error explaining itself. ## The API ``` func WithCancelCause(parent Context) (ctx Context, cancel CancelCauseFunc) type CancelCauseFunc func(cause error) func Cause(c Context) error ``` The derived context is an ordinary `Context` — there is no new interface and no new method. The difference is entirely in the cancel func, which now takes an error, and in the package-level `Cause` function that reads it back. ## What each accessor returns After `cancel(errors.New("source stream went away"))`: - `ctx.Done()` is closed, as with any cancellation. - `ctx.Err()` returns `context.Canceled`. **It does not return your error.** This is deliberate: `Err()` reports the *class* of ending, and every piece of existing code that compares against `context.Canceled` must keep working. Changing `Err()` would have been a breaking change to the whole ecosystem. - `context.Cause(ctx)` returns the error you passed. The other cases: - **Not cancelled yet** — `Cause` returns `nil`, the same way `Err()` does. - **Cancelled with `cancel(nil)`** — `Cause` returns the same value as `Err()`, so you get `context.Canceled` rather than a surprising nil on a done context. - **A plain `WithCancel` context** — `Cause` still works on it and returns whatever `Err()` returns. `Cause` is safe to call on any context, so a generic helper can use it unconditionally. ## First cancellation wins The cause is set once, by the first cancellation that reaches the context, and never overwritten. Two consequences: - Calling `cancel(a)` and then `cancel(b)` on the same context leaves the cause as `a`. The second call is a no-op, exactly as a repeated plain cancel is. - Causes propagate downward. If an ancestor is cancelled with a cause, every descendant's `Cause` reports that ancestor's error, because the ancestor's cancellation is the first one that reached them. A child cancelled by its own cancel func first keeps its own cause. That propagation is what makes it useful across layers: a worker deep in a call chain can ask `context.Cause(ctx)` and learn the reason recorded several frames up, without anyone threading a reason parameter through. ## How you actually use it The pattern is to define sentinel errors for the reasons that matter, cancel with them, and inspect at the point where the decision is made: ``` var errSourceGone = errors.New("source stream disappeared") ctx, cancel := context.WithCancelCause(parent) defer cancel(nil) // still mandatory; nil means no specific reason ... cancel(errSourceGone) ``` and downstream: ``` if err := ctx.Err(); err != nil { return fmt.Errorf("transcode stopped: %w", context.Cause(ctx)) } ``` Note that `defer cancel(nil)` is still required. `WithCancelCause` derives a child exactly as `WithCancel` does, with the same registration in the parent's children set, so an uncalled cancel retains the child in exactly the same way. Passing `nil` is the idiomatic way to say 'this is the ordinary cleanup call, no reason attached'. ## Where it fits and where it does not Use it when several distinct reasons can end the same work and downstream code or your logs need to tell them apart. Do not use it as a general error-return channel: the cause is attached to a *cancellation*, so it is visible only once the context is done, and code that never checks `Done()` will never see it. The function's return value is still how errors travel. Also resist the urge to attach large objects as causes. The cause is retained on the context for as long as the context is, which for a long-lived cancelled parent is the rest of the process. A sentinel error, or a small wrapped error, is the right size. ## Interop Because the cause is an ordinary error, everything in `errors` works on it: `errors.Is(context.Cause(ctx), errSourceGone)` is the normal test, and a wrapped cause unwraps as usual. That is the whole point of using an error value rather than a string.