The Go memory model, data races, and the -race detector

Happens-before: the only ordering that exists

When you review concurrent code and something looks “obviously fine,” ask yourself: what creates the happens-before edge here? If you can’t name it, the compiler can’t see it either — and will act accordingly. The Go memory model (go.dev/ref/mem) defines when a read is guaranteed to observe a write: only when the write happens-before the read. Within one goroutine, program order gives you that for free. Between goroutines, happens-before is created exclusively by synchronization:

• a channel send happens-before the corresponding receive completes (and for unbuffered channels, the receive happens-before the send returns);
• the close of a channel happens-before a receive that returns a zero value because of it;
• an unlock of a sync.Mutex happens-before any later Lock that acquires it;
• sync.WaitGroup.Done happens-before the Wait it releases; sync.Once’s function happens-before any Do returning;
• atomic operations in sync/atomic behave like tiny synchronized accesses — a goroutine that observes an atomic store also observes everything sequenced before that store.

Nothing else creates ordering. Not time.Sleep, not “the write obviously happened seconds earlier,” not a print statement that seems to fix it. Without an edge, the compiler may reorder and cache aggressively (hoisting the Hook’s flag load is legal), and each CPU core may serve reads from its own store buffer. The model is explicit: if two accesses to the same location from different goroutines are not ordered by happens-before and at least one is a write, that is a data race, and the behavior of the whole program is undefined — Go promises sequentially consistent semantics only to race-free programs. Multiword values make “undefined” concrete: an interface value or slice header is two/three words, so a racy write can be observed half-updated — a type pointer from the new value with data from the old — which is memory corruption, not a stale read.

The race detector: how it works and what it costs

Build or test with -race and the compiler instruments every memory access; the runtime (based on ThreadSanitizer) keeps vector clocks per goroutine and shadow memory recording the last accesses to each word. On every access it checks: is there a previous access to this address, from another goroutine, at least one a write, with no happens-before path between them? If yes, it prints both stack traces — the racing read and write, with goroutine creation sites. Two properties matter for how you use it:

• No false positives. It detects actual unsynchronized accesses against the formal model, not heuristics. Every report is a real bug; “we know about that one” is not a triage category.
• Only false negatives. It flags races that executed, not races that could. A race on a code path your test never runs, or an interleaving that never occurred, stays invisible. Coverage and realistic concurrency in tests are what make -race strong.

The price: typically 2–20× slower execution and 5–10× more memory (goroutines also start with bigger stacks). That is too heavy for most production fleets but trivial for CI — go test -race ./... belongs in every pipeline, and a canary instance built with -race in staging traffic is the senior move for catching interleavings tests never produce.

// The Hook's bug, minimally. `go test -race` reports it deterministically
// when both goroutines run; without -race it may "work" for months.
var done bool // shared, unsynchronized

func worker() {
	for !done { // racy read — compiler may hoist, core may cache
		work()
	}
}

func shutdown() { done = true } // racy write

// Fix 1 (atomic flag):   var done atomic.Bool … done.Store(true) / done.Load()
// Fix 2 (channel):       done := make(chan struct{}) … close(done) /
//                        select { case <-done: return; default: }
// Fix 3 (ctx):           pass a context.Context and select on ctx.Done()

Mutexes, RWMutex, atomics: guarding state

sync.Mutex is the workhorse: Lock/Unlock create the happens-before edges that make everything done inside the critical section visible to the next locker. Go mutexes are cheap when uncontended (~tens of nanoseconds, a single atomic CAS) and unfair-but-bounded under contention (a starvation mode kicks in after ~1 ms of waiting, handing the lock to the longest waiter). They are not reentrant — locking twice from one goroutine deadlocks. Keep critical sections tiny and never hold a lock across I/O or a channel operation; the convention is to declare the mutex immediately above the fields it guards.

sync.RWMutex allows concurrent readers and exclusive writers. The honest tradeoff: its bookkeeping is heavier than Mutex, so it wins only when read sections are long or readers are many and writes are rare; for a nanosecond-scale read of a couple of fields, a plain Mutex is usually faster, and a frequently-written RWMutex is slower than Mutex while also letting readers starve writers’ arrival window. For read-mostly data that changes wholesale (config, routing tables), atomic.Pointer[T] — readers load a snapshot pointer, the writer builds a new immutable value and stores it — gives lock-free reads with one allocation per update. sync/atomic types (atomic.Bool, atomic.Int64, atomic.Pointer) cover flags and counters; reaching for atomics to build multi-variable invariants by hand is how lock-free bugs are born — if two fields must change together, that is a mutex’s job.

Channels or mutexes — the slogan, qualified

“Don’t communicate by sharing memory; share memory by communicating” is design advice, not a ban. The honest decision rule: mutexes protect state in place; channels transfer ownership of data or coordinate lifecycles. A counter, a cache, a set of in-place fields — that is mutex territory, and forcing it through a channel-owning goroutine adds latency, an extra goroutine to manage, and an API where every read is a round-trip. A pipeline stage handing off work items, a worker pool, cancellation, “exactly one goroutine may touch this buffer now” — that is channel territory, and emulating it with mutexes and condition variables reinvents what channels already are. The codebase smell test: a struct with a mutex and twelve methods that each lock-mutate-unlock is fine; a channel used as a mutex (buffer 1, send to lock, receive to unlock) is a sign someone applied the slogan instead of the rule. Either way, both tools compile to the same memory-model currency: happens-before edges. Pick the one that makes ownership obvious to the reader.