In a worker loop, how do you observe cancellation of a context.Context, and what do you return?

## The two methods that matter A `context.Context` exposes cancellation through two methods: - `Done() <-chan struct{}` — a receive-only channel of empty structs. It is never *sent* to; it is **closed**. A closed channel is permanently ready to receive, which makes it a broadcast: every goroutine selecting on it wakes, not just one. - `Err() error` — `nil` while the context is live, and once done it returns a non-nil sentinel. For a context cancelled through the func from `context.WithCancel`, that sentinel is `context.Canceled`. The empty struct carries no data because no data is needed: the *event* is the closure of the channel. ## The canonical loop ``` for { select { case <-ctx.Done(): return ctx.Err() case job, ok := <-jobs: if !ok { return nil } process(job) } } ``` Three things about this shape are worth stating explicitly. **The Done case sits beside the work, not before it.** `select` blocks until one of its cases is ready and picks uniformly at random among the ready ones. That means a worker that is idle on `jobs` wakes the instant the context is cancelled — but it also means that if both a job and the cancellation are ready simultaneously, either branch may win. If shutdown must be strict, re-check `ctx.Err()` before starting expensive work, or drain deliberately. Do not assume `Done` has priority; it does not. **Return `ctx.Err()`, not `nil` and not a home-made error.** The caller can then compare against `context.Canceled` and distinguish an orderly shutdown from a real failure. Returning `nil` after a cancellation tells the caller the work succeeded, which is a lie that propagates: a job runner will mark a half-transcoded output as complete. **Between iterations is the only place cancellation is observed.** Whatever `process(job)` does, it runs to the end. If a single unit of work is long, pass `ctx` down into it so the inner layers can select too, or check `ctx.Err()` between its phases. ## Cancellation is cooperative This is the point candidates most often get wrong. Cancelling a context does not interrupt a goroutine. There is no thread kill, no injected panic, no unwinding. The runtime can *preempt* a goroutine for scheduling purposes, but that only means another goroutine gets CPU time; the preempted one resumes exactly where it was. So a loop like ``` for i := range n { heavyPureComputation(i) } ``` is untouched by cancellation until you make it look. For CPU-bound work the cheap idiom is a polled check, not a select: ``` for i := range n { if err := ctx.Err(); err != nil { return err } heavyPureComputation(i) } ``` `Err()` is a mutex-guarded field read; checking it once per outer iteration is negligible, checking it a million times in the innermost loop is not free. Pick a granularity that bounds your shutdown latency. ## Non-blocking checks When you want to test cancellation without blocking, the `select`-with-`default` form does it: ``` select { case <-ctx.Done(): return ctx.Err() default: } ``` This is equivalent to the `ctx.Err() != nil` check and is mostly a matter of taste; the `Err()` form is shorter and reads better outside a loop that already selects. ## Details that separate a confident answer - **A nil Done channel is legal.** `context.Background()` and `context.TODO()` can never be cancelled, and their `Done()` returns `nil`. Receiving from a nil channel blocks forever, so `case <-ctx.Done():` is simply never selected. The code compiles and behaves correctly; nothing special is required. - **Done can be called repeatedly and by many goroutines.** It returns the same channel each time and is safe for concurrent use, as every method on `Context` is. - **After the channel closes, receives return immediately, forever.** There is no need to store a flag; re-reading is cheap and always true. - **`Err()` is set before `Done()` is closed.** So a goroutine woken by the closure always sees a non-nil `Err()`; you never observe the ordering the other way round. - **Do not select on Done in order to do cleanup in a parked goroutine.** For a one-shot reaction there is `context.AfterFunc(ctx, f)`, added in Go 1.21, which runs `f` in its own goroutine once the context is done and returns a `stop func() bool` you can call to cancel that registration. It avoids a goroutine sitting in a `select` for the sole purpose of noticing. ## Reporting up Once the worker returns `ctx.Err()`, the layer above generally propagates it rather than retrying: `context.Canceled` means somebody asked for this to stop, so retrying is exactly the wrong reaction. Treating cancellation as a transient failure and retrying is one of the classic ways a shutdown turns into a stampede.