go-concurrency

Go Concurrency

A quick-reference for writing and reviewing concurrent Go. Reach for the table that fits the problem, copy the nearest pattern, then check it against the gotchas. Verify everything with go test -race.

Don't communicate by sharing memory; share memory by communicating. Use channels to pass ownership of data, distribute work, and signal. Use a mutex for in-place shared state (caches, counters, registries).

Pick your tool

Need	Use
Hand off / stream values between goroutines	chan
Protect shared state in place	sync.Mutex / sync.RWMutex (read-heavy)
Wait for N goroutines to finish	sync.WaitGroup
Run exactly once (lazy init)	sync.Once
Reuse expensive allocations, cut GC pressure	sync.Pool
Wake goroutines on a condition	sync.Cond (rare; a channel is usually clearer)
Lock-free counters / flags	sync/atomic
Cancellation, deadlines, request-scoped values	context.Context

Always defer mu.Unlock() right after mu.Lock() so a panic can't leave the lock held.

In this repo: the streaming task path (StreamableTaskHandler, server/agent_streamable.go) is channel-based - RunWithStream returns a <-chan cloudevents.Event the caller ranges over. The producer owns and closes that channel; consumers only receive. The done-channel / context patterns below are exactly how a streaming handler should honor cancellation.

Channel states

Behaviour is defined by the operation × the channel's state. Memorize this:

Operation	nil channel	open channel	closed channel
receive v := <-c	blocks forever	a value (or blocks if empty)	zero value, ok==false (drains buffer first)
send c <- v	blocks forever	sends (or blocks if full)	panic
close(c)	panic	closes it	panic

• Unbuffered (make(chan T)): send and receive rendezvous - each blocks until the other is ready. This is the synchronization.
• Buffered (make(chan T, n)): send blocks only when full, receive only when empty. A buffer decouples timing; it does not remove backpressure.
• Ownership rule: exactly one goroutine owns a channel - it creates, writes, and closes it, then hands consumers a receive-only <-chan T. This makes the panics above structurally impossible. Receivers never close.
• range c reads until the channel is closed; v, ok := <-c detects closure.