Partial Cancellation — Middle Level¶

Table of Contents¶

1. Introduction
2. Prerequisites
3. Glossary
4. Scoped Contexts
5. Fan-Out with Per-Branch Cancellation
6. Choosing Between WithoutCancel, WithTimeout, and WithDeadline
7. Detached Subtasks in Larger Orchestrations
8. Cancelling One errgroup Branch Without Cancelling Others
9. Interaction with singleflight, sync.Once, and Caches
10. Pipelines and Partial Cancellation
11. Error Handling in Detached Branches
12. Real-World Architectures
13. Tests for Partial-Cancellation Behaviour
14. Edge Cases at Middle Level
15. Common Anti-Patterns at Middle Level
16. Cheat Sheet
17. Summary
18. Further Reading

Introduction¶

The junior file taught you the single most common use of context.WithoutCancel: detached cleanup at the end of a request. That is one shape of partial cancellation. At middle level, you start to see the general problem: many real workflows are trees of subtasks, and you often want to cancel one subtree without affecting the others.

Examples that motivate this level:

• A request fans out to three downstream services. One is slow. You want to abandon it but keep the other two.
• A pipeline has stages A → B → C. Stage B failed for one item. You want to drop that item but keep the pipeline running.
• An errgroup is running five tasks. One is best-effort and failing — you do not want its failure to cancel the four others.
• A detached audit goroutine itself spawns sub-operations. Some of those should respect the audit's deadline; some should not.

These shapes do not have a single API call that solves them. They are composed of three building blocks:

• context.WithCancel, context.WithTimeout, context.WithDeadline — to give a subtask its own bounded lifetime.
• context.WithoutCancel — to break the chain so an inner subtask is not cancelled by an outer one.
• Manual goroutines that watch multiple cancellation signals at once.

At middle level, you learn to compose these three building blocks into the shapes your application needs. The standard library does not give you "cancel only branch B" out of the box; you build it from primitives.

This file teaches you:

• Scoped contexts: per-subtask cancellation that does not reach back up.
• Fan-out where each branch is independently cancellable.
• The decision matrix for choosing between detach, timeout, deadline, and cancel.
• Cancelling one branch of an errgroup without aborting others.
• Partial cancellation in pipelines.
• The interaction with single-flight, sync.Once, and caches.
• A small but realistic detached-supervisor design.

By the end, you should be able to design a 100-goroutine workflow where you can name, for each goroutine, which lifetime owns it.

Prerequisites¶

• The junior file — you must know context.WithoutCancel cold.
• Comfortable with errgroup.WithContext.
• Familiar with select statements with multiple cases.
• Have written at least one fan-out/fan-in workflow.
• Know what singleflight.Group does, even if you have not used it.
• Comfortable with sync.WaitGroup, sync.Once, sync.Mutex.

If you have ever debugged a "but the other goroutines kept running" surprise, you are ready.

Glossary¶

Scoped Contexts¶

A scoped context is a context that lives only for the duration of one subtask. It is created with WithCancel, WithTimeout, or WithDeadline, and its cancellation does not reach back up to the parent.

The basic pattern¶

func fetchA(parent context.Context) (Result, error) {
    ctx, cancel := context.WithTimeout(parent, 2*time.Second)
    defer cancel()
    return callServiceA(ctx)
}

The cancellation of ctx (whether by cancel(), timeout, or parent cancellation) only affects fetchA. The parent is unaffected by the cancel() call.

This is scope — each function has its own cancellation scope, and the cancellation only flows downward.

When scoped contexts collide with partial cancellation¶

The conventional scoped pattern is fine until you want a sibling of fetchA to keep running even if fetchA's parent is cancelled. That is when WithoutCancel enters.

func handler(parent context.Context) {
    res, _ := fetchA(parent) // scoped to handler; respects parent
    _ = res

    // Side-effect that must outlive handler:
    detached := context.WithoutCancel(parent)
    go writeAudit(detached, res)
}

The first call uses the parent's cancellation; the second does not. Each line is a scope decision.

Scope at every level of the tree¶

A real handler may have many scope decisions:

func handler(parent context.Context) {
    // Scope 1: the whole handler. Inherits parent.
    ctx := parent

    // Scope 2: a quick lookup with its own timeout.
    lookupCtx, lookupCancel := context.WithTimeout(ctx, 500*time.Millisecond)
    user, err := lookupUser(lookupCtx, userID)
    lookupCancel()
    if err != nil {
        return
    }

    // Scope 3: the main work, inheriting parent's cancellation.
    res, err := mainWork(ctx, user)
    if err != nil {
        return
    }

    // Scope 4: detached cleanup with its own bounded lifetime.
    detached := context.WithoutCancel(ctx)
    auditCtx, auditCancel := context.WithTimeout(detached, 5*time.Second)
    go func() {
        defer auditCancel()
        writeAudit(auditCtx, res)
    }()
}

Four distinct scopes:

• Scope 1 inherits the parent's cancellation directly.
• Scope 2 has a tighter timeout but still inherits parent cancellation.
• Scope 3 inherits the parent's cancellation directly.
• Scope 4 is detached from the parent and has its own timeout.

Naming each scope explicitly in your mental model is the difference between writing correct partial-cancellation code and writing code that "mostly works."

Fan-Out with Per-Branch Cancellation¶

A common middle-level shape: one parent goroutine spawns N sibling subtasks. You want to cancel one of them — perhaps because its result is no longer needed — without affecting the others.

Naive approach: one cancel per branch¶

func fanOut(parent context.Context, items []Item) {
    var wg sync.WaitGroup
    cancels := make([]context.CancelFunc, len(items))
    for i, item := range items {
        ctx, cancel := context.WithCancel(parent)
        cancels[i] = cancel
        wg.Add(1)
        go func(i int, it Item) {
            defer wg.Done()
            process(ctx, it)
        }(i, item)
    }
    // To cancel branch 3:
    cancels[3]()
    wg.Wait()
}

Each branch has its own cancel function. Cancelling one branch leaves the others running. Cancelling the parent cancels all.

Why detach is sometimes the right answer¶

If you want a branch to survive the parent being cancelled — because, say, it is a cleanup that must run regardless — start the branch from a detached context:

detached := context.WithoutCancel(parent)
ctx, cancel := context.WithTimeout(detached, 10*time.Second)
go func() { defer cancel(); cleanup(ctx) }()

Now cleanup is unaffected by the parent and has its own 10-second budget.

Combining the two ideas¶

You can have a fan-out where some branches inherit parent cancellation and some are detached:

func handler(parent context.Context) {
    // Primary fan-out: respects parent cancellation.
    g, ctx := errgroup.WithContext(parent)
    g.Go(func() error { return fetchA(ctx) })
    g.Go(func() error { return fetchB(ctx) })
    _ = g.Wait()

    // Detached fan-out: independent of parent cancellation.
    detached := context.WithoutCancel(parent)
    go writeAudit(detached, /* ... */)
    go emitMetric(detached, /* ... */)
}

The errgroup fan-out uses parent cancellation. The post-response fan-out is detached. Each is its own cancellation scope.

Granular per-branch deadlines¶

Sometimes each branch should have its own deadline, derived from the parent but tighter:

func fanOut(parent context.Context, items []Item) {
    var wg sync.WaitGroup
    for _, item := range items {
        wg.Add(1)
        go func(it Item) {
            defer wg.Done()
            ctx, cancel := context.WithTimeout(parent, deadlineFor(it))
            defer cancel()
            process(ctx, it)
        }(item)
    }
    wg.Wait()
}

Each goroutine creates its own WithTimeout. The deadlines vary per item. The parent is the common ancestor.

Fan-out with a "first failure cancels all but one" rule¶

Sometimes you want first-failure-cancels-all behaviour except for one branch (often a logger or a metric emitter) that should keep going. Compose errgroup for the cancellable branches and a separate detached goroutine for the un-cancellable one:

g, ctx := errgroup.WithContext(parent)
g.Go(func() error { return fetchA(ctx) })
g.Go(func() error { return fetchB(ctx) })

// Sibling that should keep running even if A or B fails.
detached := context.WithoutCancel(parent)
go alwaysLog(detached)

err := g.Wait()

The detached logger is not part of the errgroup, so the errgroup's cancellation does not affect it.

Choosing Between WithoutCancel, WithTimeout, and WithDeadline¶

A frequent middle-level confusion: which of these four (WithCancel, WithTimeout, WithDeadline, WithoutCancel) do I want at each node?

The decision is about answers to four orthogonal questions:

1. Should this subtree be cancelled when the parent is? → if not, start with WithoutCancel.
2. Should this subtree have its own bounded lifetime? → if yes, layer WithTimeout or WithDeadline.
3. Should this subtree be cancellable on demand? → if yes, layer WithCancel.
4. Should this subtree carry additional values? → if yes, layer WithValue.

You compose them in any order. The most common compositions are:

• WithCancel(parent) — respects parent, plus its own cancellation.
• WithTimeout(parent, d) — respects parent, plus its own deadline.
• WithTimeout(WithoutCancel(parent), d) — ignores parent cancellation, has its own deadline.
• WithCancel(WithoutCancel(parent)) — ignores parent cancellation, plus its own cancellation.

A complete reference table¶

Memorise the first six rows. The seventh is custom logic, covered later.

When deadlines from the parent should not be inherited¶

A subtle scenario: the parent context has a deadline of 30 seconds (the request budget). You spawn a detached cleanup goroutine that needs to do work for up to 5 minutes (a slow batch write).

If you use parent directly, the cleanup is cancelled at 30 seconds. Bug. If you use WithoutCancel(parent), the cleanup has no deadline. Risk. If you use WithTimeout(WithoutCancel(parent), 5*time.Minute), the cleanup has its own 5-minute budget independent of the parent's 30 seconds. Correct.

The detach + bound pattern is exactly the recipe for "I need a different deadline than the parent."

When the parent deadline should be inherited¶

The opposite case: the parent has a 30-second deadline, and your subtask should never exceed that deadline, but you also want a tighter 10-second internal budget. Use WithTimeout(parent, 10*time.Second). The effective deadline is min(parent, 10s) = 10s. The cancellation propagates both ways: parent timeout fires → child cancelled; child timeout fires → child cancelled (but not parent).

WithTimeout and WithDeadline never extend the parent's deadline. They only tighten it. This is sometimes called "monotonic deadline."

Detached Subtasks in Larger Orchestrations¶

In a microservice, a single user-facing request often triggers a small workflow of database reads, downstream calls, and cleanup operations. Some are bound to the request lifecycle; some are not.

The "outer trunk, inner branches" model¶

Picture the workflow as a tree:

request (lifetime: client connection)
├── load user                 (inherits)
├── load cart                 (inherits)
├── place order               (inherits)
│   ├── reserve inventory     (inherits)
│   ├── charge payment        (inherits)
│   └── write order row       (inherits)
└── DETACH HERE
    ├── write audit row       (detached, own timeout)
    ├── send confirmation email (detached, own timeout)
    └── refresh search index   (detached, own timeout)

Everything above DETACH HERE shares the parent's lifetime. Everything below has been pulled out of the parent's tree and lives independently.

In code:

func (s *Server) placeOrder(ctx context.Context, req PlaceOrderRequest) (*Order, error) {
    user, err := s.users.Load(ctx, req.UserID)
    if err != nil {
        return nil, err
    }
    cart, err := s.carts.Load(ctx, req.UserID)
    if err != nil {
        return nil, err
    }
    order, err := s.orders.Place(ctx, user, cart)
    if err != nil {
        return nil, err
    }

    // DETACH HERE: side-effects that must outlive the request.
    detached := context.WithoutCancel(ctx)
    s.detached.Run(detached, "audit", 5*time.Second, func(c context.Context) error {
        return s.audit.Record(c, order)
    })
    s.detached.Run(detached, "email", 10*time.Second, func(c context.Context) error {
        return s.email.SendConfirmation(c, user.Email, order)
    })
    s.detached.Run(detached, "index", 30*time.Second, func(c context.Context) error {
        return s.search.Reindex(c, order)
    })

    return order, nil
}

The first half of the function uses ctx everywhere. The second half uses detached. The boundary is clear.

Why three separate detached goroutines, not one?¶

You could put all three side-effects into a single detached goroutine that runs them sequentially. Why three?

• Independence. If audit fails, you still want email to run. Sequential coupling would prevent that.
• Different deadlines. Audit must complete in 5 seconds; email may take 10; search may take 30. Sequential coupling would force a single, longest deadline.
• Different retry policies. Audit retries 3 times; email retries 5; search does not retry at all.
• Parallelism. Three independent operations finish faster in parallel.

The cost is three goroutines instead of one. Three goroutines is negligible compared to the network calls they make.

When sequential is right¶

Sometimes the operations do depend on each other:

• Generate a receipt PDF.
• Upload it to S3.
• Email a link to the user.

These must run in order. Wrap them in a single detached goroutine:

s.detached.Run(parent, "post_order", 60*time.Second, func(c context.Context) error {
    pdf, err := generatePDF(c, order)
    if err != nil {
        return err
    }
    url, err := uploadPDF(c, pdf)
    if err != nil {
        return err
    }
    return s.email.SendReceipt(c, user.Email, url)
})

One goroutine, one detached context, sequential operations.

Mixed parallel and sequential¶

A common shape: emit audit and metric in parallel, then send notifications sequentially. Use an inner errgroup:

s.detached.Run(parent, "post_order", 60*time.Second, func(c context.Context) error {
    g, gctx := errgroup.WithContext(c)
    g.Go(func() error { return s.audit.Record(gctx, order) })
    g.Go(func() error { return s.metrics.Emit(gctx, order) })
    if err := g.Wait(); err != nil {
        return err
    }
    return s.notify.Send(c, order)
})

The outer goroutine is detached. The inner errgroup runs two operations in parallel using the detached context. If either fails, the errgroup cancels its inner context and the parallel operations stop. Then the notification runs sequentially.

Cancelling One errgroup Branch Without Cancelling Others¶

errgroup.WithContext propagates first-error cancellation: when any goroutine returns a non-nil error, the shared context is cancelled and the others should bail out. This is the right default for "all-or-nothing" fan-out.

When you want "best-effort" fan-out — where one branch failing should not cancel others — you have three options.

Option 1: Use a plain errgroup.Group without WithContext¶

var g errgroup.Group
g.Go(func() error { return fetchA(parent) })
g.Go(func() error { return fetchB(parent) })
g.Go(func() error { return fetchC(parent) })
err := g.Wait()

Without WithContext, there is no shared cancellation. Each goroutine uses the parent context directly. One failure does not cancel the others.

The trade-off: you lose the "stop everything on first error" behaviour, which is sometimes desired.

Option 2: Wrap the failing branch to swallow its error¶

g, ctx := errgroup.WithContext(parent)
g.Go(func() error { return fetchA(ctx) })
g.Go(func() error { return fetchB(ctx) })
g.Go(func() error {
    err := fetchOptional(ctx)
    if err != nil {
        log.Printf("optional failed: %v", err)
        return nil // not propagated to errgroup
    }
    return nil
})
err := g.Wait()

The optional branch returns nil even on failure. The errgroup never sees its error and does not cancel siblings. The actual failure is logged separately.

Option 3: Detach the best-effort branch¶

g, ctx := errgroup.WithContext(parent)
g.Go(func() error { return fetchA(ctx) })
g.Go(func() error { return fetchB(ctx) })

// Best-effort sibling that should not participate in errgroup cancellation.
detached := context.WithoutCancel(parent)
go func() {
    defer recoverPanic("optional")
    _ = fetchOptional(detached)
}()

err := g.Wait()

The best-effort sibling does not even join the errgroup. It is detached from the errgroup's shared context. If A or B fails, the errgroup cancels its context — the detached sibling is unaffected.

Choosing among the three¶

• Option 1: when there is no notion of "primary" vs "optional" — every branch is independent.
• Option 2: when you want to keep the errgroup structure but make one branch lenient.
• Option 3: when the best-effort branch should also be best-effort waiting — i.e., you do not even want the errgroup's Wait to block on it.

Option 3 is the most common at middle level.

Interaction with singleflight, sync.Once, and Caches¶

Partial cancellation interacts with concurrency primitives in subtle ways.

singleflight¶

singleflight.Group deduplicates concurrent calls for the same key. Only one goroutine actually does the work; others wait for the result.

The subtle question: which context is passed to the work function? If two requests A and B both want the same key, only one of them calls the work function. Say A's call wins. The work function uses A's context. Now B is waiting. If A is cancelled, the work function aborts; B sees a context-cancelled error too — even though B was not cancelled.

A common fix: pass a detached context to the work function:

v, err, _ := sf.Do(key, func() (any, error) {
    ctx := context.WithoutCancel(parent)
    ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
    defer cancel()
    return load(ctx, key)
})

The work function is independent of any single caller's cancellation. Whichever caller arrives first triggers it; others wait for the same value. If one caller cancels, the load continues.

The trade-off: if all callers cancel, the load still runs. For very expensive loads, this may be wasteful.

A more refined pattern: count callers; cancel only when the last one disappears. This is more code; we cover it at the senior level.

sync.Once¶

sync.Once ensures a function runs at most once. It is simpler than singleflight and does not return values. Same problem: the first caller's cancellation may affect the work.

Same solution: have the work function use a detached context.

Caches with refresh¶

A cache that supports background refresh has the same shape. The user request triggers a stale-while-revalidate refresh; the request itself returns the stale value; the refresh runs in the background.

func (c *Cache) Get(ctx context.Context, key string) (any, error) {
    if v, ok := c.lookup(key); ok {
        if c.isStale(key) {
            detached := context.WithoutCancel(ctx)
            go c.refresh(detached, key) // background
        }
        return v, nil
    }
    // Cache miss: load synchronously.
    return c.load(ctx, key)
}

The synchronous load uses the request context (so it is cancelled if the request is). The background refresh uses a detached context.

sync.Mutex and detached operations¶

A subtle pitfall: a detached goroutine that holds a mutex blocks other goroutines, including request-bound ones. If the detached goroutine takes a long time, the request-bound goroutines waiting for the mutex effectively inherit the detached goroutine's lifetime.

func (s *Service) update(ctx context.Context) {
    s.mu.Lock()
    defer s.mu.Unlock()
    // ... long work ...
}

// Detached goroutine:
go func() {
    detached := context.WithoutCancel(parent)
    s.service.update(detached) // holds the mutex for a long time
}()

// Request-bound goroutine:
s.service.update(ctx) // waits for the mutex

The request-bound goroutine waits in Lock(). Its context cancellation does not unlock the mutex. If the detached goroutine takes 30 seconds, the request goroutine waits 30 seconds — even if its own context was cancelled at 1 second.

The fix is to make the mutex-protected operations short, or to use a context-aware lock primitive (e.g., a channel-based semaphore).

Pipelines and Partial Cancellation¶

A pipeline is a chain of stages connected by channels. Each stage is one or more goroutines. Cancellation in pipelines is usually all-or-nothing: cancelling the head stops everything downstream.

Partial cancellation in pipelines is useful for two things:

1. Dropping a single item without stopping the pipeline.
2. Letting one stage shut down independently of others.

Dropping a single item¶

In a pipeline like A → B → C, suppose B fails for one item. The item should be dropped, but A should keep producing and C should keep consuming.

Item-level cancellation is not a context concern — it is a control-flow concern. The stage simply does not forward the item:

func stageB(in <-chan Item, out chan<- Result) {
    for it := range in {
        res, err := process(it)
        if err != nil {
            log.Printf("dropped %v: %v", it.ID, err)
            continue
        }
        out <- res
    }
}

But each item processing call may need a per-item context with a deadline:

func stageB(parent context.Context, in <-chan Item, out chan<- Result) {
    for it := range in {
        ctx, cancel := context.WithTimeout(parent, 2*time.Second)
        res, err := process(ctx, it)
        cancel()
        if err != nil {
            continue
        }
        out <- res
    }
}

If the parent is cancelled, all per-item contexts are cancelled. If only one item times out, only that item is dropped.

Stage-level partial cancellation¶

Sometimes a stage needs to be shut down independently. For example, a metrics-emission stage that you want to drain even if the data stages have stopped.

Each stage owns its own context:

type Pipeline struct {
    dataCtx    context.Context
    metricsCtx context.Context
}

func (p *Pipeline) Start() {
    go dataStage(p.dataCtx)
    go metricsStage(p.metricsCtx)
}

Cancelling dataCtx stops the data stages. The metrics stage continues until metricsCtx is cancelled. Each stage has its own bulkhead.

Combining the two¶

Within a single stage, items may have per-item contexts derived from the stage's context. Cancelling the stage cancels all in-flight items.

func dataStage(stageCtx context.Context, in <-chan Item, out chan<- Result) {
    for it := range in {
        select {
        case <-stageCtx.Done():
            return // stage cancelled
        default:
        }
        ctx, cancel := context.WithTimeout(stageCtx, 2*time.Second)
        res, err := process(ctx, it)
        cancel()
        if err != nil {
            continue
        }
        out <- res
    }
}

The stage checks its own context before processing each item.

Error Handling in Detached Branches¶

At middle level, error handling for detached branches needs more structure than the junior-level "log and continue."

Pattern: errors channel¶

A central errors channel collected by a supervisor:

type Supervisor struct {
    errs chan error
}

func (s *Supervisor) Go(parent context.Context, name string, fn func(context.Context) error) {
    ctx := context.WithoutCancel(parent)
    go func() {
        defer recoverPanic(name)
        if err := fn(ctx); err != nil {
            s.errs <- fmt.Errorf("%s: %w", name, err)
        }
    }()
}

func (s *Supervisor) Errors() <-chan error { return s.errs }

A separate goroutine reads from s.Errors() and logs, alerts, or otherwise handles the errors.

Pattern: dead-letter queue¶

Failed events go to a durable buffer that a separate worker drains:

func auditDetached(parent context.Context, ev Event, dlq DLQ) {
    ctx := context.WithoutCancel(parent)
    ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
    defer cancel()
    if err := db.InsertAudit(ctx, ev); err != nil {
        log.Printf("audit failed, enqueuing to DLQ: %v", err)
        dlq.Enqueue(ev)
    }
}

The DLQ ensures eventual consistency. The request itself returns immediately.

Pattern: structured logging¶

Every detached failure is logged with the trace ID for correlation:

func auditDetached(parent context.Context, ev Event) {
    ctx := context.WithoutCancel(parent)
    ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
    defer cancel()
    if err := db.InsertAudit(ctx, ev); err != nil {
        traceID := traceIDFromCtx(ctx)
        log.Printf("audit failed trace=%s err=%v", traceID, err)
    }
}

Since WithoutCancel preserves values, the trace ID is still available. This is essential for debugging — a failed audit in production should be traceable back to the original request.

Pattern: per-event metrics¶

Track success/failure rates per detached operation:

func auditDetached(parent context.Context, ev Event) {
    ctx := context.WithoutCancel(parent)
    ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
    defer cancel()
    if err := db.InsertAudit(ctx, ev); err != nil {
        metrics.Inc("audit_failed")
        return
    }
    metrics.Inc("audit_succeeded")
}

A dashboard can show audit success rate over time. A regression in this rate signals a problem.

Real-World Architectures¶

Three small but realistic architectures that use partial cancellation as a core design element.

Architecture 1: Audit-Logging Service¶

A service that wraps an underlying business service and adds audit logging.

type AuditLogger interface {
    Log(ctx context.Context, ev Event) error
}

type WrappedService struct {
    inner Service
    audit AuditLogger
    pool  *DetachedPool
}

func (s *WrappedService) DoThing(ctx context.Context, req Req) (Resp, error) {
    resp, err := s.inner.DoThing(ctx, req)
    s.pool.Run(ctx, "audit", 5*time.Second, func(c context.Context) error {
        return s.audit.Log(c, Event{Req: req, Resp: resp, Err: err})
    })
    return resp, err
}

The audit fires regardless of whether the inner call succeeded. The audit is detached, so it survives request cancellation. The audit has its own deadline.

Architecture 2: Search Index Updater¶

A service that, after every write to the primary database, updates the search index in the background.

type SearchUpdater struct {
    pool *DetachedPool
}

func (s *Service) Save(ctx context.Context, doc Document) error {
    if err := s.db.Save(ctx, doc); err != nil {
        return err
    }
    s.searchUpdater.pool.Run(ctx, "index", 30*time.Second, func(c context.Context) error {
        return s.search.Index(c, doc)
    })
    return nil
}

If the primary write fails, the index update is not attempted. If the primary write succeeds, the index update runs detached. The user does not wait for the index update.

Architecture 3: Email Confirmation Service¶

A signup endpoint sends a confirmation email asynchronously.

type SignupService struct {
    pool *DetachedPool
}

func (s *SignupService) Signup(ctx context.Context, req SignupReq) (User, error) {
    user, err := s.users.Create(ctx, req)
    if err != nil {
        return User{}, err
    }
    s.pool.Run(ctx, "email_confirmation", 10*time.Second, func(c context.Context) error {
        return s.email.SendConfirmation(c, user.Email)
    })
    return user, nil
}

The user gets back a User object immediately. The email arrives a few hundred milliseconds later.

Tests for Partial-Cancellation Behaviour¶

Testing partial cancellation requires three kinds of test.

Test 1: Verify the detach actually detaches¶

func TestDetachSurvivesParentCancel(t *testing.T) {
    parent, cancel := context.WithCancel(context.Background())
    detached := context.WithoutCancel(parent)
    cancel()
    if detached.Err() != nil {
        t.Fatal("detached should not be cancelled when parent is")
    }
}

This is trivial but worth having as a regression test for refactors.

Test 2: Verify detached work completes after parent cancel¶

func TestDetachedWorkCompletes(t *testing.T) {
    var ran atomic.Bool
    parent, cancel := context.WithCancel(context.Background())
    detached := context.WithoutCancel(parent)
    done := make(chan struct{})
    go func() {
        defer close(done)
        time.Sleep(50 * time.Millisecond)
        if detached.Err() == nil {
            ran.Store(true)
        }
    }()
    cancel()
    <-done
    if !ran.Load() {
        t.Fatal("detached work did not complete")
    }
}

This is more realistic — it asserts that a goroutine using a detached context runs to completion even when the parent is cancelled mid-flight.

Test 3: Verify the supervisor drains correctly¶

func TestSupervisorDrains(t *testing.T) {
    var counter atomic.Int32
    s := NewSupervisor(context.Background())
    for i := 0; i < 100; i++ {
        s.Run(context.Background(), "test", time.Second, func(c context.Context) error {
            counter.Add(1)
            return nil
        })
    }
    drainCtx, cancel := context.WithTimeout(context.Background(), 2*time.Second)
    defer cancel()
    if err := s.Drain(drainCtx); err != nil {
        t.Fatal("drain failed:", err)
    }
    if counter.Load() != 100 {
        t.Fatalf("expected 100 runs, got %d", counter.Load())
    }
}

This verifies that the supervisor's Drain waits for all in-flight detached goroutines.

Test 4: Verify error counting¶

func TestSupervisorCountsErrors(t *testing.T) {
    var errs atomic.Int32
    s := NewSupervisorWithErrHook(context.Background(), func(err error) {
        errs.Add(1)
    })
    for i := 0; i < 10; i++ {
        s.Run(context.Background(), "fail", time.Second, func(c context.Context) error {
            return errors.New("nope")
        })
    }
    drainCtx, cancel := context.WithTimeout(context.Background(), time.Second)
    defer cancel()
    _ = s.Drain(drainCtx)
    if errs.Load() != 10 {
        t.Fatalf("expected 10 errors, got %d", errs.Load())
    }
}

Test 5: Verify panic recovery¶

func TestSupervisorRecoversPanics(t *testing.T) {
    s := NewSupervisor(context.Background())
    s.Run(context.Background(), "panic", time.Second, func(c context.Context) error {
        panic("oops")
    })
    drainCtx, cancel := context.WithTimeout(context.Background(), time.Second)
    defer cancel()
    if err := s.Drain(drainCtx); err != nil {
        t.Fatal("drain failed:", err)
    }
    // If we get here, the panic was recovered.
}

Edge Cases at Middle Level¶

• Detached context whose parent is cancelled before detach. Works fine. The detach reads the parent's value chain, which is still intact. Cancellation state of the parent does not affect the detached context.
• Nested detaches. WithoutCancel(WithoutCancel(parent)) is legal but semantically pointless. The double-detach is identical to a single detach.
• Detached context wrapped in another detached context wrapped in a timeout. The timeout fires; the detached lifetime in between is irrelevant.
• Detached context used as a parent of an errgroup. The errgroup's cancellation flows down into its goroutines but does not flow up into the detached parent. This is sometimes useful — the errgroup is internally cancellable while the outer detached context is not.
• Detached context used in an AfterFunc. AfterFunc on a detached context never fires, because the detached context is never cancelled. To get a "fires after delay" behaviour, layer WithTimeout on the detached context.
• Detached context that crosses a goroutine pool. If you submit work to a worker pool, the worker's context is not the detached context unless you arrange it. Always pass the detached context as a value into the work, not as the worker's loop context.

Common Anti-Patterns at Middle Level¶

Anti-pattern: detaching too late¶

go func() {
    detached := context.WithoutCancel(parent)
    // ... but the parent was already cancelled before we got here ...
    work(detached)
}()

Detaching after the parent is cancelled still works (the values are preserved). But if the work depends on values that are themselves time-sensitive (a short-lived per-request token), the values may be stale.

The fix: detach at the call site of go, not inside the goroutine.

Anti-pattern: detaching the inner errgroup context¶

g, ctx := errgroup.WithContext(parent)
g.Go(func() error {
    detached := context.WithoutCancel(ctx)
    return work(detached) // ignores errgroup cancellation
})

The errgroup's cancellation is meant to coordinate the group. Detaching from it defeats the coordination. If you want this goroutine to not respect the errgroup, do not put it in the errgroup in the first place.

Anti-pattern: chaining WithoutCancel and WithCancel¶

ctx, cancel := context.WithCancel(context.WithoutCancel(parent))
// ... cancel() is the only way to cancel this ...

This is sometimes correct — you want a manually-cancellable detached subtree. But the cancel function is now the only way to cancel. If the goroutine forgets to call it, you have a leak.

Anti-pattern: passing a detached context through middleware¶

func middleware(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        ctx := context.WithoutCancel(r.Context()) // <-- bad
        r = r.WithContext(ctx)
        next.ServeHTTP(w, r)
    })
}

The downstream handler no longer respects client disconnect. Every database call, every downstream HTTP call, every cache lookup will keep running after the client gives up. This is almost never what you want.

The fix is to only detach at the spawning point of a detached goroutine, never at the level of the entire request.

Anti-pattern: pretending detached work is free¶

A handler that detaches three operations is, from the handler's perspective, fast — the response goes out immediately. But the three detached goroutines are using CPU and database connections. If the handler is called a thousand times per second, you have three thousand detached goroutines outstanding. Each one needs a database connection. The connection pool exhausts. The system grinds to a halt.

Detached does not mean free. Account for the resource cost.

Cheat Sheet¶

// Compose for any combination of (parent-cancel) × (own-deadline) × (own-cancel)
ctx = context.WithCancel(parent)              // inherits parent + own cancel
ctx = context.WithTimeout(parent, d)          // inherits parent + own deadline
ctx = context.WithoutCancel(parent)           // ignores parent, no deadline
ctx = context.WithTimeout(
        context.WithoutCancel(parent), d)     // ignores parent + own deadline

// Common patterns
detached := context.WithoutCancel(parent)
ctx, cancel := context.WithTimeout(detached, 5*time.Second)
go func() { defer cancel(); work(ctx) }()

// Best-effort errgroup branch: detach to escape the group
g, gctx := errgroup.WithContext(parent)
detached := context.WithoutCancel(parent)
go bestEffort(detached) // not part of the group

// singleflight: use detached inside the work
sf.Do(key, func() (any, error) {
    ctx := context.WithoutCancel(parent)
    return load(ctx, key)
})

Summary¶

At middle level, partial cancellation stops being about a single API call and becomes about composition. You learn to make scope decisions per subtask, to compose WithoutCancel, WithCancel, WithTimeout, and WithDeadline into the shapes you need, and to coordinate detached and request-bound branches in the same workflow.

Three skills define this level:

1. Naming, for each subtask, what owns its lifetime.
2. Choosing the right composition of cancellation derivations.
3. Designing fan-out, errgroup, and pipeline patterns with selective cancellation.

The senior level moves to architecture: how detached subtasks integrate with graceful shutdown, distributed tracing, and the broader service lifecycle.

Further Reading¶

• golang.org/x/sync/errgroup — pay particular attention to WithContext.
• golang.org/x/sync/singleflight — and the issue about cancellation between callers.
• context.AfterFunc (Go 1.21) — its interaction with WithoutCancel.
• The Go runtime's source for WithCancel and WithCancelCause (src/context/context.go).
• The OpenTelemetry Go SDK's span lifecycle code — they wrestle with exactly these problems.

Deeper Patterns¶

Pattern: The Coordinator Goroutine¶

Some workflows need a long-running coordinator that orchestrates many detached operations. The coordinator owns the supervisor and the process context. Handlers submit work to it.

type Coordinator struct {
    process context.Context
    work    chan Work
    wg      sync.WaitGroup
}

type Work struct {
    Parent context.Context
    Name   string
    Timeout time.Duration
    Fn     func(context.Context) error
}

func NewCoordinator(processCtx context.Context, workers int) *Coordinator {
    c := &Coordinator{
        process: processCtx,
        work:    make(chan Work, workers*4),
    }
    for i := 0; i < workers; i++ {
        c.wg.Add(1)
        go c.run()
    }
    return c
}

func (c *Coordinator) run() {
    defer c.wg.Done()
    for {
        select {
        case w := <-c.work:
            c.do(w)
        case <-c.process.Done():
            return
        }
    }
}

func (c *Coordinator) do(w Work) {
    ctx := context.WithoutCancel(w.Parent)
    ctx, cancel := context.WithTimeout(ctx, w.Timeout)
    defer cancel()
    defer recoverPanic(w.Name)
    if err := w.Fn(ctx); err != nil {
        log.Printf("%s: %v", w.Name, err)
    }
}

func (c *Coordinator) Submit(parent context.Context, name string, timeout time.Duration, fn func(context.Context) error) {
    select {
    case c.work <- Work{Parent: parent, Name: name, Timeout: timeout, Fn: fn}:
    case <-c.process.Done():
    }
}

func (c *Coordinator) Drain(ctx context.Context) error {
    close(c.work)
    done := make(chan struct{})
    go func() { c.wg.Wait(); close(done) }()
    select {
    case <-done:
        return nil
    case <-ctx.Done():
        return ctx.Err()
    }
}

func recoverPanic(name string) {
    if r := recover(); r != nil {
        log.Printf("%s panic: %v", name, r)
    }
}

This is the seed of an internal "detached work" service. Handlers submit; the coordinator processes; the process owns the lifecycle.

Pattern: Per-Operation Lifetime Tracking¶

For debugging or capacity planning, track every in-flight detached operation:

type TrackedSupervisor struct {
    *Coordinator
    inflight sync.Map // map[opID]Info
}

type Info struct {
    Name      string
    Start     time.Time
    TraceID   string
}

func (s *TrackedSupervisor) Submit(parent context.Context, name string, timeout time.Duration, fn func(context.Context) error) {
    id := newOpID()
    s.inflight.Store(id, Info{
        Name: name, Start: time.Now(),
        TraceID: traceIDFromCtx(parent),
    })
    s.Coordinator.Submit(parent, name, timeout, func(ctx context.Context) error {
        defer s.inflight.Delete(id)
        return fn(ctx)
    })
}

func (s *TrackedSupervisor) Inflight() []Info {
    var out []Info
    s.inflight.Range(func(_, v any) bool {
        out = append(out, v.(Info))
        return true
    })
    return out
}

An admin endpoint can show what is currently in flight. Useful when a deployment is stuck on draining.

Pattern: Capacity-Bounded Detached Pool¶

A naive detached pool spawns one goroutine per submission. At high throughput, this can overwhelm the database (each goroutine opens a connection) or the network (each goroutine creates a request).

The fix is a bounded worker pool:

type BoundedPool struct {
    work    chan Work
    process context.Context
    wg      sync.WaitGroup
}

func NewBoundedPool(processCtx context.Context, n int) *BoundedPool {
    p := &BoundedPool{
        work:    make(chan Work, n*8),
        process: processCtx,
    }
    for i := 0; i < n; i++ {
        p.wg.Add(1)
        go p.loop()
    }
    return p
}

func (p *BoundedPool) loop() {
    defer p.wg.Done()
    for w := range p.work {
        p.do(w)
    }
}

func (p *BoundedPool) do(w Work) {
    ctx := context.WithoutCancel(w.Parent)
    ctx, cancel := context.WithTimeout(ctx, w.Timeout)
    defer cancel()
    defer recoverPanic(w.Name)
    _ = w.Fn(ctx)
}

func (p *BoundedPool) Submit(parent context.Context, name string, timeout time.Duration, fn func(context.Context) error) error {
    w := Work{Parent: parent, Name: name, Timeout: timeout, Fn: fn}
    select {
    case p.work <- w:
        return nil
    case <-p.process.Done():
        return p.process.Err()
    default:
        return errors.New("pool full")
    }
}

Submit returns an error when the pool is saturated. The handler can decide what to do — drop the event, write to a DLQ, or backpressure.

Pattern: Detached With Shutdown Hook¶

A detached operation that should run, with the option to "speed up" or "shut down" when the process exits:

func (p *Pool) detachedWithShutdown(parent context.Context, fn func(context.Context, <-chan struct{})) {
    ctx := context.WithoutCancel(parent)
    p.wg.Add(1)
    go func() {
        defer p.wg.Done()
        defer recoverPanic("detached")
        fn(ctx, p.process.Done())
    }()
}

The function receives both a context and a separate "stop hint" channel. Long operations can check the stop channel and abort gracefully:

p.detachedWithShutdown(parent, func(ctx context.Context, stop <-chan struct{}) {
    for i := 0; i < 1000; i++ {
        select {
        case <-stop:
            return
        default:
        }
        processItem(ctx, i)
    }
})

Three Worked Architectures¶

Architecture A: A High-Throughput Webhook Sender¶

A service that receives webhook delivery requests and sends them asynchronously. Must survive client disconnect, must be drained at shutdown, must have bounded retries.

type WebhookSender struct {
    pool    *BoundedPool
    client  *http.Client
}

func NewWebhookSender(processCtx context.Context) *WebhookSender {
    return &WebhookSender{
        pool: NewBoundedPool(processCtx, 100),
        client: &http.Client{Timeout: 10 * time.Second},
    }
}

func (s *WebhookSender) Send(parent context.Context, w Webhook) error {
    return s.pool.Submit(parent, "webhook", 60*time.Second, func(ctx context.Context) error {
        return s.deliver(ctx, w)
    })
}

func (s *WebhookSender) deliver(ctx context.Context, w Webhook) error {
    delays := []time.Duration{0, time.Second, 5 * time.Second, 30 * time.Second}
    for i, d := range delays {
        if d > 0 {
            select {
            case <-time.After(d):
            case <-ctx.Done():
                return ctx.Err()
            }
        }
        if err := s.attempt(ctx, w); err == nil {
            return nil
        } else if i == len(delays)-1 {
            return err
        }
    }
    return nil
}

func (s *WebhookSender) attempt(ctx context.Context, w Webhook) error {
    req, err := http.NewRequestWithContext(ctx, "POST", w.URL, bytes.NewReader(w.Body))
    if err != nil {
        return err
    }
    resp, err := s.client.Do(req)
    if err != nil {
        return err
    }
    resp.Body.Close()
    if resp.StatusCode >= 500 {
        return fmt.Errorf("server %d", resp.StatusCode)
    }
    return nil
}

The handler enqueues; the pool processes; the operation has its own 60-second budget; retries are bounded; the pool has 100 workers; on shutdown, the pool drains.

Architecture B: A Metric Aggregator¶

A service that emits metrics. To avoid one network call per metric, it buffers and flushes in batches.

type MetricEmitter struct {
    in      chan Metric
    out     chan []Metric
    process context.Context
}

func NewMetricEmitter(processCtx context.Context) *MetricEmitter {
    e := &MetricEmitter{
        in:      make(chan Metric, 1000),
        out:     make(chan []Metric, 10),
        process: processCtx,
    }
    go e.batcher()
    go e.flusher()
    return e
}

func (e *MetricEmitter) Emit(parent context.Context, m Metric) {
    select {
    case e.in <- m:
    case <-e.process.Done():
    default: // drop on overflow
    }
}

func (e *MetricEmitter) batcher() {
    ticker := time.NewTicker(time.Second)
    defer ticker.Stop()
    var batch []Metric
    for {
        select {
        case m := <-e.in:
            batch = append(batch, m)
            if len(batch) >= 100 {
                e.out <- batch
                batch = nil
            }
        case <-ticker.C:
            if len(batch) > 0 {
                e.out <- batch
                batch = nil
            }
        case <-e.process.Done():
            if len(batch) > 0 {
                e.out <- batch
            }
            close(e.out)
            return
        }
    }
}

func (e *MetricEmitter) flusher() {
    for batch := range e.out {
        ctx, cancel := context.WithTimeout(e.process, 5*time.Second)
        _ = pushMetrics(ctx, batch)
        cancel()
    }
}

func pushMetrics(ctx context.Context, batch []Metric) error { return nil }
type Metric struct{ Name string; Value float64 }