Channel Close Violations — Senior Level¶

Table of Contents¶

1. Introduction
2. Ownership as a First-Class Concept
3. The Channel State Machine
4. The "Only Sender Closes" Idiom Revisited
5. Multi-Sender Fan-In: The Done-Channel Pattern
6. Coordinator Patterns at Scale
7. sync.Once for Safe-Close
8. Atomic Close-Bit Patterns
9. Double-Close Panic Semantics
10. Send-on-Closed Panic Semantics
11. Quiescent-State Closing
12. Race Window Analysis
13. Library API Design
14. Returning a Closable Channel
15. Cascading Close in Pipelines
16. Errors in the Close Protocol
17. Close vs Context Cancellation
18. Hybrid Close+Context Idiom
19. Testing Close Behaviour
20. Recover as a Last-Resort Tool
21. Anti-Pattern Catalogue
22. Self-Assessment
23. Summary

Introduction¶

At junior level we listed the five rules of close and met the four canonical safe patterns. At middle level we focused on the multi-sender problem and learned five patterns that cover every scenario.

At senior level we stop memorising patterns and start designing them. The questions shift:

• How do I express channel ownership in a type system that has no notion of ownership?
• How do I make "you cannot misuse this API" a compile-time or initialisation-time guarantee, not a comment in a code review?
• When two reasonable patterns disagree, which one is appropriate for the system I am building?
• How do I reason about the race window between "last data" and "close" without writing prose proofs in every change request?
• How does close interact with context.Context, errgroup.Group, sync.Cond, sync.WaitGroup, atomic flags, and the rest of the synchronisation toolkit?

This document gives the answers. It is the level at which you can review an unfamiliar codebase, find the close violations from the structure of the code (not from running the program), and propose a refactor that the on-call team will trust.

What this is not: a guide to the runtime panic itself. That lives in professional.md. Here we stay in the design space.

Ownership as a First-Class Concept¶

In a low-level language, ownership is visible: who allocated this, who frees it, who is allowed to write to it. In Go, the runtime owns memory; you own the lifecycle. For a channel, the lifecycle has three positions:

1. Allocation. make(chan T) or make(chan T, n). Once.
2. Use. Sends, receives, range, select. Any number of times.
3. Close. close(ch). Exactly zero or one time.

Position 3 is where ownership matters. There must be exactly one entity in the program with the authority to call close. We will call that entity the closer.

The closer is not necessarily a goroutine¶

A common misreading of "single closer" is "single goroutine". That is too strict. The closer can be:

• A single goroutine — the simplest case.
• A coordinator goroutine that observes a sync.WaitGroup reach zero and then calls close.
• An object method protected by sync.Once, which guarantees that out of N concurrent calls, exactly one will run the close.
• An object method protected by an atomic compare-and-swap on a state field.
• An object method protected by a mutex and a closed bool flag.

What matters is that the semantics of single-closer hold: exactly one call to close(ch) is ever reachable for that channel, regardless of how many goroutines race through the code.

Closer ≠ Owner¶

The closer is one role; the owner is another. The owner is the goroutine or component that decided when the channel should close. The closer is the entity that physically executes close(ch). They are often the same, but not always:

• In a coordinator pattern, the senders are owners (they know when their work is done). The coordinator is the closer (it knows when all senders are done).
• In a sync.Once wrapper, the caller of Close() is the owner (it decided closure should happen). The Once.Do callback is the closer (it actually runs close).

Splitting these two roles is what makes safe-close patterns possible.

Channel directionality as documented ownership¶

Go's channel direction types — chan<- T and <-chan T — are how you document ownership in the type system. They are not enforcement of correctness; they are enforcement of intent.

type Producer struct {
    out chan<- Event // I own this side: sends + close
}

type Consumer struct {
    in <-chan Event // I do not own this side: I may only read
}

The compiler will refuse close(c.in) because <-chan cannot be closed. That is a real safety property — Rule 4 (the receiver should not close) is enforced at compile time by direction types.

The flip side: once you cast chan T to chan<- T, you have given that recipient the authority to close. Be honest about who you hand the bidirectional reference to.

Anti-pattern: passing chan T because "it is more convenient"¶

// BAD: convenience that destroys the close contract
func startWorker(jobs chan Job) { /* worker may close jobs */ }

If startWorker does not need to close jobs, the parameter must be <-chan Job. If it does need to close, the parameter must be chan<- Job and startWorker becomes the closer — at which point the caller must guarantee no other goroutine sends.

If both sides need to send, you have a multi-sender channel and must use a coordinator. There is no API that lets you pretend you do not.

A note on private channels¶

If a channel never escapes a struct, the channel direction in the type signature is less critical — internal code can be reviewed for correctness. But for any channel that crosses an API boundary, the direction is your only durable contract. Senior code reviews should reject mixed-direction channels at API boundaries with the same severity as interface{} parameters that should be typed.

The Channel State Machine¶

A channel has four observable states. Senior-level reasoning about close requires keeping these states sharply distinguished.

                  +-----+
        +-------->| nil |<--------+
        |         +-----+         |
        |            ^            |
        |  var ch    |  ch = nil  |
        |            |            |
        |       +----+----+       |
        |       |         |       |
        | make  |         |       |
        v       v         v       v
   +-----------------+ +------------------+
   | open  & empty   | | open & non-empty |
   +-----------------+ +------------------+
        ^   |     ^    ^         |
        |   |     |    | recv    | send
        |   |send |    |         v
        |   v     |    +---------+
        | (block) +-->|             |
        |              | sends fill |
        +--------+-----+ to capacity|
                 |     +-----+------+
                 v           |
            +----------------v---------+
            | closed (drainable or empty)
            +--------------------------+
                       |
                       | every receive
                       v
            +--------------------------+
            | closed & empty           |
            | (zero value forever)     |
            +--------------------------+

Important consequences from this state machine:

• The transitions from any open state to closed are via close(ch), and they are one-way. You cannot reopen.
• The transition from nil to open requires assignment from make. Setting ch = nil after closure is a programmer-side convention: the runtime channel object is gone-but-not-deallocated until GC.
• The "closed & empty" state is a black hole for receivers: every receive succeeds immediately with the zero value and ok = false.
• select treats a nil case as "never ready". A closed case is "always ready (zero value)". A nil case is identical to omitting the case altogether.

State queries¶

You cannot directly query whether a channel is closed. The two indirect queries are:

1. Receive with comma-ok. v, ok := <-ch — if ok == false, the channel is closed and drained. But this is destructive: if the channel was open and had data, the receive consumes it.
2. Non-blocking receive in select. select { case v, ok := <-ch: ...; default: } — also destructive if data is available.

There is no IsClosed(ch) because such a function would be a race by construction. The state can flip between your check and your action.

Why no IsClosed¶

Consider the hypothetical:

// HYPOTHETICAL: not in the language
if !runtime.IsClosed(ch) {
    ch <- v // race: another goroutine can close between check and send
}

Even if IsClosed existed, this would panic under a race. So Go simply does not expose the query — you must use one of the safe-close patterns instead.

Buffered channels: extra dimension¶

A buffered channel has an additional dimension: occupancy (0..cap). Close interacts with the buffer:

• close(ch) does not drain the buffer. Buffered values remain available to readers.
• After close, for range ch will deliver every buffered value, then exit.
• After close, a single <-ch returns the next buffered value, or the zero value if empty.
• After close, len(ch) reports the number of buffered values still available.

This is sometimes useful: enqueue N work items, close, then signal workers via "channel closed" — they will still see every queued item. The pattern is called "drainable close".

The "Only Sender Closes" Idiom Revisited¶

The conventional rule "only the sender closes" is correct but underspecified. The fully-stated form:

Only a goroutine that holds the exclusive right to send on this channel may close it. If the right to send is shared, the closer is the unique entity that has aggregated the senders' right.

This is the property that makes single-sender channels easy and multi-sender channels hard. Single-sender: the only sender is also the only valid closer. Multi-sender: no individual sender can safely close without coordination.

Single-sender, single-receiver¶

func produce() <-chan int {
    out := make(chan int)
    go func() {
        defer close(out)
        for i := 0; i < 10; i++ {
            out <- i
        }
    }()
    return out
}

The producer goroutine is the unique sender. It is also the closer. The defer close(out) is correct because no other goroutine can race with it.

Single-sender, multi-receiver (fan-out)¶

func produce() <-chan int {
    out := make(chan int)
    go func() {
        defer close(out)
        for i := 0; i < 10; i++ {
            out <- i
        }
    }()
    return out
}

func main() {
    src := produce()
    for i := 0; i < 5; i++ {
        go func(id int) {
            for v := range src {
                fmt.Println(id, v)
            }
        }(i)
    }
    // ...
}

Still single-sender. The five receivers compete for items via the channel's internal locking. When the producer closes, every receiver exits its range. No close coordination required on the receiver side.

Multi-sender, single-receiver¶

Now the rule breaks. If two senders each try defer close(out), the second will panic. If one sender closes early, the other will panic on send. We need a coordinator (covered next).

Multi-sender, multi-receiver¶

Same problem as above; receivers are not the issue, senders are.

The "right to send" delegation¶

A common pattern: a coordinator goroutine has the right to send, but it delegates that right to N worker goroutines. The right is still single — it is held by the coordinator — but the workers borrow it temporarily.

type Pool struct {
    out chan Result
    wg  sync.WaitGroup
}

func (p *Pool) Start(n int) {
    for i := 0; i < n; i++ {
        p.wg.Add(1)
        go func() {
            defer p.wg.Done()
            for {
                r, ok := compute()
                if !ok {
                    return
                }
                p.out <- r
            }
        }()
    }
    go func() {
        p.wg.Wait()
        close(p.out)
    }()
}

The coordinator (the third goroutine) is the closer. The workers are senders who borrow the right; they relinquish it by calling wg.Done. Only when all rights have been returned does the closer execute close.

This is the canonical idiom for multi-sender close. It works because:

1. The wg.Add is called before spawning each worker, in the parent goroutine, so the coordinator cannot wake up early.
2. The wg.Done is called from defer, so it runs even on panic.
3. The closer is a single goroutine, satisfying single-closer.
4. At the moment of close, every worker has finished or is about to finish its defer wg.Done, so no live send can race the close.

Where this idiom fails¶

The idiom assumes that workers exit eventually. If a worker is stuck on p.out <- r because the receiver stopped reading, wg.Done is never reached, and the closer never wakes up. The whole pipeline leaks.

Sender-side deadlock is the dual of the close problem: just as you must coordinate the close, you must coordinate the unblocking of senders. The fix is to attach a done signal that aborts the send:

go func() {
    defer p.wg.Done()
    for {
        r, ok := compute()
        if !ok {
            return
        }
        select {
        case p.out <- r:
        case <-p.done:
            return
        }
    }
}()

Now if the consumer goes away and closes p.done, every worker sees the cancellation and returns; wg reaches zero; the coordinator closes out. No leak.

Multi-Sender Fan-In: The Done-Channel Pattern¶

Fan-in is the canonical multi-sender case: take N input streams, merge them into one output stream. Multi-sender close violations live here.

func merge(srcs ...<-chan int) <-chan int {
    out := make(chan int)
    var wg sync.WaitGroup
    wg.Add(len(srcs))
    for _, s := range srcs {
        go func(s <-chan int) {
            defer wg.Done()
            for v := range s {
                out <- v
            }
        }(s)
    }
    go func() {
        wg.Wait()
        close(out)
    }()
    return out
}

This is the WaitGroup variant, identical in shape to the previous pool. It is correct under the assumption that every input channel will eventually close. If one input is a long-lived stream that may never close, fan-in must take a done channel for cancellation.

Fan-in with done-channel cancellation¶

func merge(done <-chan struct{}, srcs ...<-chan int) <-chan int {
    out := make(chan int)
    var wg sync.WaitGroup
    wg.Add(len(srcs))
    for _, s := range srcs {
        go func(s <-chan int) {
            defer wg.Done()
            for {
                select {
                case v, ok := <-s:
                    if !ok {
                        return
                    }
                    select {
                    case out <- v:
                    case <-done:
                        return
                    }
                case <-done:
                    return
                }
            }
        }(s)
    }
    go func() {
        wg.Wait()
        close(out)
    }()
    return out
}

Two selects, nested. The outer chooses between "receive from s" and "done". The inner chooses between "send to out" and "done". Cancellation reaches the worker whether it is blocked on receive or blocked on send.

A common simplification — merging the inner select into the outer — is wrong:

// BAD: missed cancellation
select {
case v, ok := <-s:
    if !ok { return }
    out <- v // blocks forever if reader gone
case <-done:
    return
}

If done closes after we have received v but before out <- v completes, we are stuck. The nested form prevents this.

Why done is a <-chan struct{} and not chan struct{}¶

The merge function takes done <-chan struct{}. It is a receive-only channel for two reasons:

1. The caller owns the done channel and is the only entity allowed to close it. Caller-side direction is chan<- struct{} (or chan struct{} if it both reads and writes). Callee-side is <-chan struct{}.
2. The compiler enforces that merge cannot accidentally close(done) — that would be Rule 4 (receiver closes). Rule 4 is enforced at the type system level.

Cancellation race: receive vs done¶

What if done and a value-from-s are both ready simultaneously? Go's select picks pseudo-randomly. That is fine: under cancellation we are allowed to deliver-or-drop the value. The contract of merge does not promise "we delivered every input we had a chance to read"; it promises "we eventually exit cleanly".

If you do want "deliver everything you have read", reorder: check done only when there is no work pending. But then a stuck reader can never be cancelled. There is no free lunch; pick a side.

Why we still need the closer goroutine¶

After wg.Wait() returns, every worker has exited. We then call close(out). Could we instead skip the closer goroutine by having the last worker call close(out)?

// SUBTLY BROKEN
go func(s <-chan int) {
    defer func() {
        if last := wg.Done(); last { // wg.Done() doesn't return last!
            close(out)
        }
    }()
    for v := range s { out <- v }
}(s)

wg.Done() is void. It does not tell you if you were the last. The standard library has no public API for "is this the last Done". You can implement one with an atomic counter, but the WaitGroup itself does not expose it:

var pending int32 = int32(len(srcs))
for _, s := range srcs {
    go func(s <-chan int) {
        for v := range s { out <- v }
        if atomic.AddInt32(&pending, -1) == 0 {
            close(out)
        }
    }(s)
}

This is correct but loses the wg semantics. It is fine for small fan-in; for production pipelines, the coordinator-goroutine version is more readable and equally efficient. The atomic version saves one goroutine and a Wait syscall; not usually worth it.

Fan-in with errors¶

If each source can fail, the merge function must propagate failures. The done channel is no longer enough — it conveys "stop" but not "why". Convert to an error channel:

type Item struct {
    Value int
    Err   error
}

func merge(done <-chan struct{}, srcs ...<-chan int) <-chan Item {
    out := make(chan Item)
    var wg sync.WaitGroup
    wg.Add(len(srcs))
    for _, s := range srcs {
        go func(s <-chan int) {
            defer wg.Done()
            for {
                select {
                case v, ok := <-s:
                    if !ok { return }
                    select {
                    case out <- Item{Value: v}:
                    case <-done: return
                    }
                case <-done: return
                }
            }
        }(s)
    }
    go func() { wg.Wait(); close(out) }()
    return out
}

For source-level errors, embed them in the item type. Do not introduce a side-channel for errors — it adds another channel to close and another race window.

Coordinator Patterns at Scale¶

The coordinator-WaitGroup pattern scales linearly with N senders. But there are cases where it is too heavy or too restrictive.

Hierarchical coordinators¶

If you have N producers feeding M intermediate aggregators feeding 1 final output, you have a tree of close protocols. Each aggregator is a coordinator for its inputs; the root aggregator is the coordinator for the whole tree.

func tree(done <-chan struct{}) <-chan int {
    // Three groups of three senders each.
    var groups []<-chan int
    for g := 0; g < 3; g++ {
        var srcs []<-chan int
        for s := 0; s < 3; s++ {
            srcs = append(srcs, gen(done, g*10+s))
        }
        groups = append(groups, merge(done, srcs...))
    }
    return merge(done, groups...)
}

Each layer's merge independently closes its output when its inputs are drained. The cascade is automatic: source closes → tier 1 drains and closes → tier 2 drains and closes → terminal channel closes.

Coordinator on a critical path¶

If the coordinator goroutine becomes a hot path (many merges per second), the wg.Wait's park-unpark cost matters. Two optimisations:

1. Replace the goroutine with an atomic counter as shown above.
2. If the senders themselves can never block on out (because the consumer is fast), share the close via sync.Once:

type Once struct {
    once sync.Once
    out  chan T
}

func (o *Once) Send(v T) {
    select {
    case o.out <- v:
    case <-shutdown:
        o.once.Do(func() { close(o.out) })
    }
}

This is dangerous: now any sender can close, but sync.Once makes it idempotent. The risk is sending after close; that requires a different idiom (covered later).

Generation-based coordinators¶

Long-running services do not close their primary channels — they reuse them across "epochs". An epoch boundary is closer to a checkpoint than a shutdown. For these, the coordinator is a state machine rather than a goroutine:

type Generation struct {
    mu     sync.Mutex
    out    chan Event
    closed bool
}

func (g *Generation) Rotate() (oldOut, newOut chan Event) {
    g.mu.Lock()
    defer g.mu.Unlock()
    oldOut = g.out
    g.out = make(chan Event, cap(g.out))
    g.closed = false
    newOut = g.out
    // Caller now drains oldOut and closes it.
    return
}

This is generation-based ownership: at any moment, exactly one channel is the current one; the previous one is held only by goroutines that already had a reference and will eventually exit.

sync.Once for Safe-Close¶

sync.Once is the smallest possible safe-close primitive when you do not care which goroutine closes — only that exactly one of them does.

type SafeCh struct {
    ch   chan int
    once sync.Once
}

func New() *SafeCh             { return &SafeCh{ch: make(chan int)} }
func (s *SafeCh) Send(v int)   { s.ch <- v } // BAD: can panic
func (s *SafeCh) Close()       { s.once.Do(func() { close(s.ch) }) }
func (s *SafeCh) Recv() (int, bool) { v, ok := <-s.ch; return v, ok }

This is the minimum safe-close. Multiple callers of Close() are safe; subsequent calls become no-ops.

But this implementation has the send-after-close hole: a sender calling Send(v) after another goroutine calls Close() will panic. The minimal SafeCh is not actually safe for sending.

Full safe-send via select on done¶

type SafeCh struct {
    ch   chan int
    done chan struct{}
    once sync.Once
}

func New() *SafeCh {
    return &SafeCh{ch: make(chan int), done: make(chan struct{})}
}

func (s *SafeCh) Send(v int) (ok bool) {
    select {
    case <-s.done:
        return false
    default:
    }
    select {
    case s.ch <- v:
        return true
    case <-s.done:
        return false
    }
}

func (s *SafeCh) Close() {
    s.once.Do(func() { close(s.done) })
}

func (s *SafeCh) Recv() (int, bool) {
    select {
    case v := <-s.ch:
        return v, true
    case <-s.done:
        return 0, false
    }
}

Now Send cannot panic, regardless of how many goroutines call Close concurrently. The trick: we never close s.ch. We close s.done. The data channel remains open forever (until GC); the cancellation channel is what flips state.

This is the single most important safe-close idiom in production Go. It is the basis of context.WithCancel, errgroup.Group, and every well-designed concurrent library.

Cost of sync.Once¶

sync.Once is two fields (one uint32 flag, one sync.Mutex). The fast path is a single atomic load. The slow path acquires the mutex and runs the function exactly once.

For the safe-close pattern, the slow path runs once per channel lifetime. The cost is negligible compared to the channel itself.

sync.Once is not magic¶

You can implement the same thing with atomic.CompareAndSwapUint32:

type SafeCh struct {
    ch     chan int
    done   chan struct{}
    closed uint32
}

func (s *SafeCh) Close() {
    if atomic.CompareAndSwapUint32(&s.closed, 0, 1) {
        close(s.done)
    }
}

This is equivalent. sync.Once is more readable; the atomic version is microseconds faster on uncontended paths. For library code, choose readability unless profiling demands otherwise.

Atomic Close-Bit Patterns¶

When the channel is part of a larger state machine, using sync.Once may not be enough — the close transition needs to be coupled with other state. Use a single atomic word to encode all the states.

const (
    stateOpen   = 0
    stateDraining = 1
    stateClosed = 2
)

type Channel struct {
    state atomic.Uint32
    ch    chan Item
}

func (c *Channel) Send(it Item) error {
    if c.state.Load() != stateOpen {
        return ErrClosed
    }
    select {
    case c.ch <- it:
        return nil
    default:
        return ErrFull
    }
}

func (c *Channel) BeginDrain() {
    if c.state.CompareAndSwap(stateOpen, stateDraining) {
        close(c.ch)
    }
}

There is a race here: a sender that passed the state.Load() check can still race the close. Atomic-bit alone is insufficient; you must combine it with the done-channel trick or with a mutex. We will return to this in the race-window section.

When pure-atomic is enough¶

If senders never block — they always use non-blocking sends with default — then a closed channel does not cause send-on-closed panics. Why? Because the panic happens only when runtime.chansend proceeds past the closed check, which requires either a waiting receiver or a slot in the buffer. A default arm in select cancels the send before the runtime is committed.

Actually — that is not quite right. Even the non-blocking send checks the closed bit first; if it sees closed, it panics regardless of the default arm. The default arm is only chosen if the send cannot proceed (e.g., buffer full, no waiter). Closed-channel panics happen during the chansend setup phase, before considering the default.

So even non-blocking sends to closed channels panic. The correct pattern is always to gate sends behind a separate "shutdown" channel.

Double-Close Panic Semantics¶

The Go runtime detects double-close inside runtime.closechan and panics with "close of closed channel".

ch := make(chan int)
close(ch)
close(ch) // panic: close of closed channel

The detection is via the channel's internal closed flag (a uint32 member of runtime.hchan). The flag is read and written under the channel's lock. Once it is non-zero, a second closechan raises the panic.

Why the panic and not a return value¶

In other languages (Erlang, Rust mpsc), close-on-closed is a no-op. Why does Go panic?

The Go authors chose strict failure because double-close almost always indicates a design bug: two goroutines both believe they are the closer. Silent tolerance would hide the bug. The panic forces you to think about ownership.

It also makes the spec simpler: the rule is "close exactly once", not "close at most once". No tolerance, no ambiguity.

Where double-close arises¶

The vast majority of production double-closes I have seen fall into these patterns:

1. defer close(ch) in multiple producers. Each producer goroutine has its own defer. As they finish in any order, the second triggers panic.
2. Cleanup in both defer and explicit Stop(). A struct's Close calls close(ch), and a defer close(ch) somewhere else is "just in case".
3. Wrapper functions called more than once. A Drain() helper that closes the underlying channel, called by both the producer and the orchestrator.
4. Tests that close the channel manually for "cleanup" after the SUT already closed it.
5. Retry loops that re-enter Close() after an error.

Each is a symptom of "I do not know who owns the close". The fix is always the same: identify the unique closer and remove the redundant close.

Defensive: catch double-close with recover¶

You can wrap close in a recover:

func safeClose(ch chan int) (closed bool) {
    defer func() {
        if r := recover(); r != nil {
            closed = false
        }
    }()
    close(ch)
    return true
}

This works but is bad style. Recovering a panic to fix a design bug means you are deciding to ignore a runtime invariant. Use sync.Once instead — same effect, no panic, no recover overhead.

Send-on-Closed Panic Semantics¶

ch := make(chan int, 1)
close(ch)
ch <- 1 // panic: send on closed channel

The detection is in runtime.chansend. After taking the channel lock, the runtime reads c.closed. If non-zero, it releases the lock and panics.

Why send-on-closed cannot be made safe by buffering¶

Beginners sometimes hope that a buffered channel will absorb a send after close. It does not. The buffer is for blocking-vs-non-blocking; it is not for after-close semantics. Once c.closed is set, every send panics regardless of buffer state.

Receive after close: zero value, ok=false¶

The dual is benign: receives from a closed channel succeed forever, returning the zero value with ok == false. This asymmetry — sends panic, receives do not — is what makes close usable as a broadcast signal.

A senior question: why this asymmetry? Why does the runtime not deliver an error to the sender instead of panicking?

The answer is that delivering an error would make ch <- v have a runtime type signature error, but it does not — it is a statement, not an expression. The language can either silently drop the send (bad: lost data) or panic (good: loud failure). Panic is the right choice given the syntax.

Recover-around-send¶

func trySend(ch chan int, v int) (sent bool) {
    defer func() {
        if r := recover(); r != nil {
            sent = false
        }
    }()
    ch <- v
    return true
}

This is a deliberate use of recover. It is acceptable in narrow cases (e.g., a logging subsystem where dropping a log line is preferable to panicking the producer), but in general avoid it: the panic indicates that the design is wrong, and recover-around-send hides the symptom while leaving the bug.

Better: use the done-channel idiom and check shutdown before send:

func trySend(ch chan<- int, done <-chan struct{}, v int) bool {
    select {
    case <-done:
        return false
    case ch <- v:
        return true
    }
}

This requires ch to remain open, with done carrying the cancellation. The pattern eliminates the panic by construction.

Quiescent-State Closing¶

A "quiescent" close happens when the closer waits until the system reaches a state where no sender can possibly be in progress. WaitGroup-based close is quiescent-state close: by the time wg.Wait() returns, every sender has finished or never started.

Properties of quiescent close¶

1. No panic possible. No sender is live, so send-on-closed cannot happen.
2. No drop possible. Every send the senders intended has either completed or has been signalled to skip.
3. Deterministic. The closer's wakeup is causally after all sender exits.
4. Composable. Multiple quiescent closes nest — close the inner pipeline, observe its closure, then close the outer.

The downside: quiescent close requires that senders cooperate (return when signalled). Misbehaving senders (e.g., stuck on an unrelated network call) prevent quiescence indefinitely.

Non-quiescent close: snapping the channel¶

Sometimes you cannot wait for quiescence — the consumer has crashed, the timeout has fired, the user pressed Ctrl-C. You want to close now, accept the risk that some senders may still be in flight, and use the safe-send idiom to avoid panics.

The snap-close form:

type Channel struct {
    ch   chan Item
    done chan struct{}
    once sync.Once
}

func (c *Channel) Send(v Item) bool {
    select {
    case <-c.done:
        return false
    case c.ch <- v:
        return true
    }
}

func (c *Channel) Shutdown() {
    c.once.Do(func() {
        close(c.done)
        // Note: we do NOT close c.ch
    })
}

After Shutdown, c.ch remains open. Senders learn from c.done and stop. The data channel is GC'd when both Sender and Receiver references are released.

This is exactly the pattern in context.WithCancel: cancel() closes the done channel, not the channel of values.

Trade-off: leaked values¶

Snap-close may drop values: a sender that was mid-construction of v and about to call Send will skip the send entirely. This is acceptable for cancellation but unacceptable for "graceful shutdown with no data loss". Graceful shutdown must be quiescent.

Race Window Analysis¶

The race window of a close pattern is the interval during which a sender's "is it safe to send?" check is no longer accurate. Patterns differ in how they shrink this window.

Pattern 1: bare defer close¶

go func() {
    defer close(ch)
    for v := range src { ch <- v }
}()

// Elsewhere:
go func() {
    for v := range src2 { ch <- v }
}()

Race window: the entire lifetime of the second sender. The first sender's defer close can fire at any moment, including while the second sender is in the middle of ch <- v. This is "no synchronisation"; the program is broken.

Pattern 2: WaitGroup coordinator¶

wg.Add(2)
go func() { defer wg.Done(); for v := range src { ch <- v } }()
go func() { defer wg.Done(); for v := range src2 { ch <- v } }()
go func() { wg.Wait(); close(ch) }()

Race window: zero. By the time wg.Wait returns, both senders have completed their last send and executed wg.Done. The close fires causally after both sends.

The "causal after" claim depends on the memory model: wg.Done happens-before the wg.Wait return, which happens-before the close(ch). The senders' last ch <- v happens-before their wg.Done. Transitive: last send happens-before close. Safe.

Pattern 3: sync.Once + done-channel¶

type C struct {
    ch   chan int
    done chan struct{}
    once sync.Once
}
func (c *C) Send(v int) bool {
    select {
    case <-c.done: return false
    case c.ch <- v: return true
    }
}
func (c *C) Close() { c.once.Do(func() { close(c.done) }) }

Race window: zero, but for a different reason. The data channel is never closed, so send-on-closed cannot happen. Instead, the done-channel select forms a race-free choice: either the send completes (no concurrent close because the data channel does not close), or the done-channel signals and the send is abandoned.

Pattern 4: mutex + closed flag¶

type C struct {
    mu     sync.Mutex
    ch     chan int
    closed bool
}
func (c *C) Send(v int) bool {
    c.mu.Lock()
    defer c.mu.Unlock()
    if c.closed { return false }
    c.ch <- v  // BAD: blocks while holding lock; deadlock if buffer full
    return true
}

This deadlocks under load: a slow receiver will block Send, which holds the mutex; Close cannot acquire the mutex; the system stalls. Pattern 4 is acceptable only for buffered channels with select default:

func (c *C) Send(v int) bool {
    c.mu.Lock()
    defer c.mu.Unlock()
    if c.closed { return false }
    select {
    case c.ch <- v:
        return true
    default:
        return false // buffer full, drop
    }
}

Now Send never blocks. The race window is zero: c.closed and c.ch <- v happen under the same mutex; close-after-send-started is impossible because they cannot interleave.

The trade-off: any send that could block is lost.

Comparison table¶

The atomic-flag-without-done pattern is unsafe because of the read-then-act race we covered earlier. Avoid it.

Library API Design¶

When you design a library that exposes a channel, you are making an ownership decision that the caller cannot override. Get it wrong and your users will have close-violation panics that they cannot fix without forking your code.

Three-channel choices for library APIs¶

For each channel a library exposes, you choose:

1. Who closes it — library or caller?
2. Who sends — library or caller?
3. Who receives — library or caller?

If library sends and caller receives, the library is the closer. The library returns <-chan T. Caller cannot accidentally close.

If caller sends and library receives, the caller is the closer. The library returns chan<- T. Library cannot accidentally close.

If both send (a bidirectional pipe), the close ownership is contested. Use a Close() method on the library object, not direct close on the channel. The channel itself should be hidden behind methods.

The "I expose the channel" mistake¶

// BAD: library returns chan T (bidirectional)
func (s *Streamer) Out() chan Event {
    return s.out
}

Now the caller can close s.out. The library cannot defend itself. Two production bugs from this pattern in our codebase:

1. A test did defer close(stream.Out()) for cleanup. The library's own close routine then double-closed. Panic in test, found in CI.
2. A consumer wanted to "stop listening" and called close(stream.Out()). The library was still sending. Panic in production.

The fix is to expose the channel only as receive-only:

func (s *Streamer) Out() <-chan Event { return s.out }
func (s *Streamer) Close() { s.once.Do(func() { close(s.out) }) }

Now the caller cannot close. The library's Close() is idempotent.

Avoid exposing the channel at all¶

Better: expose only methods. The channel becomes an implementation detail.

func (s *Streamer) Next() (Event, bool) { v, ok := <-s.out; return v, ok }
func (s *Streamer) Close()              { /* idempotent */ }

This is more verbose but ironclad: the caller cannot misuse a channel they cannot see.

The downside: callers can no longer use range, select, or len. For simple iteration use cases, that is a real loss.

A middle ground: expose a for-range-compatible interface via Go 1.23 range-over-func:

func (s *Streamer) All(yield func(Event) bool) {
    for v := range s.out {
        if !yield(v) { return }
    }
}

// caller:
for v := range streamer.All { ... }

The library still owns the channel; the caller gets iteration. This is the modern idiom.

Returning a Closable Channel¶

If your API really must let the caller close the channel — for example, because the channel represents work the caller submits — design carefully.

Pattern: return chan<- T¶

func (s *Submitter) Submit() chan<- Job {
    return s.jobs
}

The caller can send and close. The library is the receiver. The library's receiver loop should:

for j := range s.jobs {
    s.handle(j)
}

When the caller closes, the receiver exits cleanly. Note that the caller is now responsible for not double-closing — and we cannot help them.

Wrapper struct with documented Close¶

The friendlier pattern is a wrapper:

type Submitter struct {
    jobs chan Job
    once sync.Once
}

func (s *Submitter) Submit(j Job) error {
    defer func() { _ = recover() }() // catch send-on-closed
    s.jobs <- j
    return nil
}

func (s *Submitter) Close() {
    s.once.Do(func() { close(s.jobs) })
}

The wrapper:

• Has idempotent Close (sync.Once).
• Has safe Submit (catches the panic if someone closes between check and send — though this still loses the value).

The recover-on-send is a deliberate concession to robust APIs: callers will call Submit and Close concurrently no matter what your docs say.

Cleaner: refuse send after close via select+done¶

type Submitter struct {
    jobs chan Job
    done chan struct{}
    once sync.Once
}

func (s *Submitter) Submit(j Job) error {
    select {
    case <-s.done:
        return ErrClosed
    case s.jobs <- j:
        return nil
    }
}

func (s *Submitter) Close() {
    s.once.Do(func() { close(s.done) })
}

Now Submit returns an error rather than panicking. The library can decide whether to close s.jobs itself (after observing s.done, to release the receiver) or to leave it for GC.

If the receiver also reads from s.done first, the library can simply stop reading and let GC reclaim the channel:

func (s *Submitter) loop() {
    for {
        select {
        case <-s.done:
            return
        case j := <-s.jobs:
            s.handle(j)
        }
    }
}

After Close, the loop exits, references to s.jobs are dropped, and GC frees it. No close on s.jobs required.

Cascading Close in Pipelines¶

A pipeline is a sequence of stages connected by channels. Close cascades from one stage to the next.

gen → filter → transform → sink

The producer (gen) closes its output when done. filter ranges over gen's output and closes its own output when the range exits. transform does the same. Finally sink consumes from transform's output and exits when the range closes.

func gen(n int) <-chan int {
    out := make(chan int)
    go func() {
        defer close(out)
        for i := 0; i < n; i++ { out <- i }
    }()
    return out
}

func filter(in <-chan int, p func(int) bool) <-chan int {
    out := make(chan int)
    go func() {
        defer close(out)
        for v := range in {
            if p(v) { out <- v }
        }
    }()
    return out
}

func transform(in <-chan int, f func(int) int) <-chan int {
    out := make(chan int)
    go func() {
        defer close(out)
        for v := range in {
            out <- f(v)
        }
    }()
    return out
}

Each stage is a single-sender to a single output channel. defer close(out) is correct. The cascade is automatic.

Cancellation in pipelines¶

If the consumer stops early, every stage upstream blocks on its send. Goroutine leak. Fix: every stage takes a done channel.

func filter(done <-chan struct{}, in <-chan int, p func(int) bool) <-chan int {
    out := make(chan int)
    go func() {
        defer close(out)
        for v := range in {
            if !p(v) { continue }
            select {
            case out <- v:
            case <-done:
                return
            }
        }
    }()
    return out
}

If done closes, every stage exits. The defer close(out) cascades.

Why every stage needs the done channel¶

Imagine gen does not take done. The consumer cancels, but gen is mid-send on a full buffer. Backpressure: every upstream stage is blocked because no one is receiving. gen never sees the cancellation. The pipeline stalls forever.

Putting done only at the source is insufficient: source can produce indefinitely. Putting done only at the sink is insufficient: source still blocks on full buffers upstream. Every stage needs cancellation.

context.Context as the done channel¶

Modern pipelines use context.Context instead of a bare <-chan struct{}:

func filter(ctx context.Context, in <-chan int, p func(int) bool) <-chan int {
    out := make(chan int)
    go func() {
        defer close(out)
        for v := range in {
            if !p(v) { continue }
            select {
            case out <- v:
            case <-ctx.Done():
                return
            }
        }
    }()
    return out
}

Context propagates deadline and cause information; it is the strictly more capable choice. Use <-chan struct{} only when context is unavailable or overkill (e.g., a tiny library that does not want a context dependency).

Cascading errors¶

Errors are not part of close. If a stage encounters an error mid-pipeline, it must somehow signal failure to all other stages. Two patterns:

1. Embed errors in the data type. chan Result where Result has both value and error fields.
2. Use errgroup. Each stage's goroutine is registered with the errgroup; the first error cancels the errgroup's context, which all stages observe via ctx.Done().

The second pattern is cleaner because it unifies the close cascade with the error cascade.

func pipeline(ctx context.Context) error {
    g, ctx := errgroup.WithContext(ctx)
    src := gen(ctx, 100)
    filt := filter(ctx, src, isEven)
    xform := transform(ctx, filt, square)
    g.Go(func() error {
        for v := range xform {
            if err := store(v); err != nil { return err }
        }
        return nil
    })
    return g.Wait()
}

If store returns an error, errgroup cancels ctx, every upstream stage observes ctx.Done(), the cascade closes everything. g.Wait() returns the first error.

Errors in the Close Protocol¶

Close is silent: there is no "I am closing because of an error" channel. Three integration patterns:

1. Side-channel error¶

Add an errCh chan error parallel to the data channel. The sender writes its terminal error there before closing the data channel.

func gen() (<-chan int, <-chan error) {
    out := make(chan int)
    errCh := make(chan error, 1)
    go func() {
        defer close(out)
        defer close(errCh)
        for {
            v, err := readNext()
            if err != nil {
                errCh <- err
                return
            }
            out <- v
        }
    }()
    return out, errCh
}

Caller:

out, errs := gen()
for v := range out { use(v) }
if err := <-errs; err != nil { return err }

Order matters: drain out first, then read errs. If you read errs first, you may deadlock — the sender writes to errs after closing out, so you cannot block on errs until you have drained out.

2. Embedded error in result¶

Replace chan int with chan Result:

type Result struct {
    Value int
    Err   error
}

func gen() <-chan Result {
    out := make(chan Result)
    go func() {
        defer close(out)
        for {
            v, err := readNext()
            if err != nil {
                out <- Result{Err: err}
                return
            }
            out <- Result{Value: v}
        }
    }()
    return out
}

Caller:

for r := range gen() {
    if r.Err != nil { return r.Err }
    use(r.Value)
}

Cleaner. One channel, one close. Error is just another value.

3. errgroup context cancellation¶

The errgroup pattern from the previous section folds errors and cancellation into one mechanism. The data channels do not carry errors — the cancellation context does. After g.Wait() returns the error, the caller knows what happened.

This is the most idiomatic modern style.

Close vs Context Cancellation¶

A common senior-level question: when do I close a channel as a signal, vs use ctx.Done()?

Close is for "I produced everything"¶

close(out) semantically says: "I have nothing more to send. You may stop reading."

It is a natural-end signal, not a please-stop signal. The producer is done; the consumer should finish.

context.Done is for "stop, abort"¶

<-ctx.Done() semantically says: "the consumer (or its parent) wants you to abort. Drop what you are doing."

It is a please-stop signal, originating outside the producer.

Both are needed¶

A robust system uses both:

• Producer closes its output when it has produced everything.
• Consumer cancels the context when it wants to abort.
• Producer's send loop selects on ctx.Done() to abandon mid-send.
• Consumer's receive loop selects on ctx.Done() and on the data channel (with ok).

func produce(ctx context.Context) <-chan int {
    out := make(chan int)
    go func() {
        defer close(out)
        for i := 0; ; i++ {
            select {
            case <-ctx.Done():
                return
            case out <- i:
            }
        }
    }()
    return out
}

func consume(ctx context.Context, in <-chan int) {
    for {
        select {
        case <-ctx.Done():
            return
        case v, ok := <-in:
            if !ok { return }
            use(v)
        }
    }
}

Cancellation closes ctx.Done(). Natural completion closes in. Both lead the consumer to return.

Why not just close?¶

Why not use close instead of context? Because close is one-directional: producer signals consumer. Context is hierarchical: any parent can signal any descendant, including across many channels and goroutines simultaneously.

Context also carries deadline and value (cause), which close cannot.

Why not just context?¶

Why not use context instead of close? Because context cannot deliver values. It is a signal only. You still need a data channel; close on that data channel signals "I produced all I will". Context handles the abort case; close handles the natural-end case.

A pipeline that only uses context can leak buffered data: the consumer may not know how many items the producer had queued before cancellation. Using close + context together gives the consumer "drain remaining" semantics:

case v, ok := <-in:
    if !ok { return } // producer ended cleanly
    use(v)
case <-ctx.Done():
    // optional: drain remaining buffered items
    for {
        select {
        case v, ok := <-in:
            if !ok { return }
            use(v)
        default:
            return
        }
    }

Hybrid Close+Context Idiom¶

The canonical senior-level pipeline uses three concurrent signals:

1. Data channel out. Producer→consumer values. Closed by producer when done.
2. Context ctx. Consumer→producer abort. Closed by consumer or parent.
3. Sync structure (WaitGroup or errgroup). Closer wait for producer goroutines.

func pipeline(ctx context.Context) error {
    out := make(chan Result)
    g, gctx := errgroup.WithContext(ctx)

    g.Go(func() error {
        defer close(out)
        for i := 0; i < 1000; i++ {
            select {
            case <-gctx.Done():
                return gctx.Err()
            case out <- compute(i):
            }
        }
        return nil
    })

    g.Go(func() error {
        for r := range out {
            if err := consume(gctx, r); err != nil {
                return err
            }
        }
        return nil
    })

    return g.Wait()
}

errgroup.WithContext returns a derived context that cancels on first error. Producer observes gctx.Done(). Producer closes out on its way out (via defer). Consumer ranges over out; range exits when out is closed.

This pattern is the right answer to almost every "design a pipeline" interview question.

Testing Close Behaviour¶

Close races are notoriously hard to test because they are timing-dependent. Three strategies:

1. Channel close is observable¶

Tests can call <-ch after a Close() and assert that ok is false. This catches "did the library close the channel" but not race conditions.

func TestClose(t *testing.T) {
    s := New()
    s.Close()
    if _, ok := s.Recv(); ok {
        t.Fatal("expected closed")
    }
}

2. Stress with -race¶

The race detector catches send-on-closed and double-close in many cases. Drive the SUT from many goroutines simultaneously.

func TestConcurrentClose(t *testing.T) {
    s := New()
    var wg sync.WaitGroup
    for i := 0; i < 100; i++ {
        wg.Add(1)
        go func() { defer wg.Done(); s.Close() }()
    }
    wg.Wait()
}

If Close is not idempotent, this panics on a Go runtime check (not race detector, but panic: close of closed channel). Run with go test -race -count=100 to catch sporadic ordering.

3. Inject ordering via channels¶

For deterministic race window tests, inject a synchronisation point:

type spyChannel struct {
    *Channel
    beforeClose chan struct{}
}

func (s *spyChannel) Close() {
    <-s.beforeClose
    s.Channel.Close()
}

The test can now control exactly when Close proceeds, ensuring it interleaves with a sender at a chosen point.

This is overkill for most cases. Prefer pure stress tests with the race detector, plus careful design review.

4. Property tests¶

For libraries with rich close semantics (error propagation, ordering of drains, etc.), property-based tests are valuable. Generate random sequences of "send" and "close" operations; assert invariants like "no panic", "every accepted send appears at the receiver", "after close, no more sends accepted".

The testing/quick package or third-party gopter work. The investment is high; reserve it for foundational libraries.

Recover as a Last-Resort Tool¶

recover() can catch close-related panics. It is the wrong tool for almost all cases, but there are a few where it is appropriate.

Appropriate: legacy API integration¶

You receive a chan T from external code that you cannot modify, and there is no documented close protocol. You want to send safely.

func sendBestEffort(ch chan<- T, v T) (sent bool) {
    defer func() {
        if r := recover(); r != nil {
            sent = false
        }
    }()
    ch <- v
    return true
}

This is a defensive bridge. Mark it clearly as such. The first opportunity, refactor the external API to use a safe-close pattern.

Appropriate: panic-tolerant logger¶

Loggers should never panic the application. If the log channel is closed for some reason (perhaps during shutdown), the log call should be a no-op, not a fatal error.

func (l *Logger) Log(msg string) {
    defer func() { _ = recover() }()
    select {
    case l.ch <- msg:
    default:
        // log buffer full, drop
    }
}

Note: even in this case, select default doesn't help against close-panic. We still need the recover.

Inappropriate: covering up design bugs¶

If your code panics on close in normal operation, recover is not the fix. The fix is to identify why the close protocol is wrong and rebuild it.

Performance cost of recover¶

defer ... recover costs a few hundred nanoseconds per send, even when no panic occurs (deferred function setup). For hot paths, this matters; for cold paths or library APIs, it does not.

If you must use recover but care about performance, hoist the recover to a single outer goroutine. Senders inside that goroutine inherit its recovery without per-send defer overhead.

Anti-Pattern Catalogue¶

A reference list of the close-related anti-patterns reviewers should reject on sight.

1. defer close in every producer¶

go func() { defer close(ch); /* send */ }()
go func() { defer close(ch); /* send */ }()

Double-close in flight. Use a coordinator.

2. Receiver closes the channel¶

for v := range ch {
    if shouldStop(v) { close(ch) }
}

Send-on-closed in any in-flight sender. Use a done-channel separate from the data channel.

3. Atomic flag without done channel¶

if atomic.LoadInt32(&c.closed) == 0 {
    ch <- v
}

Race between check and send. Add a done channel.

4. close to "free resources"¶

defer close(ch) // for cleanup

If the goroutine is not the closer, this is wrong. Resources are not freed by close; the channel is reclaimed by GC when all references drop.

5. Closing a channel passed in¶

func work(ch chan int) { close(ch); /* ... */ }

You do not own a channel given to you. The caller may have other plans for it.

6. Close in select default¶

select {
case ch <- v:
default:
    close(ch) // ???
}

Closing because the channel is full is nonsense. The buffer being full is unrelated to closure.

7. Close-and-recreate¶

close(ch)
ch = make(chan int)

Re-assignment doesn't bring old senders forward. They are still sending on the closed channel. Use a new variable name (and a new struct field), or rotate channels with proper coordination.

8. Conditional defer close¶

defer func() {
    if shouldClose { close(ch) }
}()