The sync package and the race detector

A race, found

1package main2 3import (4	"fmt"5	"sync"6)7 8func main() {9	var wg sync.WaitGroup10	var mu sync.Mutex11	racy, safe := 0, 012	for range 1000 {13		wg.Go(func() { // Go 1.25+: Add(1), go, Done() in one call14			racy++ // data race: unsynchronised read-modify-write15			mu.Lock()16			safe++17			mu.Unlock()18		})19	}20	wg.Wait()21	fmt.Println("safe:", safe, "racy:", racy)22}

One run on a 16-core machine printed safe: 1000 racy: 958. With GOMAXPROCS=1 it printed 1000 every time in five runs, and even on 16 cores an occasional run came out right: that is how races survive testing. go run -race . reports the problem regardless (output shortened):

1WARNING: DATA RACE2Read at 0x00c0000120f0 by goroutine 11:3  main.main.func1()4      main.go:14 +0x385Previous write at 0x00c0000120f0 by goroutine 7:6  main.main.func1()7      main.go:14 +0x488...9Found 1 data race(s)10exit status 66

The detector instruments every memory access and tracks which accesses are ordered by synchronisation. It only sees races that actually happen in that run, so its value depends on coverage. It costs roughly 2–20× in time and 5–10× in memory, so it is for tests and staging, not production. Use go test -race ./... in CI.

The tools

• sync.Mutex guards a critical section. Keep the section short and don't call out to unknown code while holding the lock. defer mu.Unlock() right after Lock keeps it correct when the function returns early or panics.
• sync.RWMutex allows many concurrent readers or one writer. It only helps when reads dominate and the critical section is not tiny.
• sync.WaitGroup waits for a group of goroutines. wg.Go(f) (Go 1.25) replaces the Add(1)/go/defer Done() pattern, and the new go vet check waitgroup reports Add called inside the goroutine, where it is too late.
• sync.Once runs initialisation exactly once; sync.OnceValue (Go 1.21) also returns its result.
• sync/atomic types (atomic.Int64, atomic.Bool, atomic.Pointer[T]) do a single read, write, add or compare-and-swap atomically, with the same visibility guarantee as a lock. Good for counters and flags; anything with two related fields needs a mutex.
• sync.Pool reuses temporary objects such as buffers to reduce garbage. Anything in a pool may be removed at any time without notice, so it is a cache, not storage.

All of these must not be copied after first use: copying a struct copies its lock state. Pass such structs by pointer; go vet reports most copies.

The memory model, briefly

If a goroutine writes a variable and another reads it, the read is only guaranteed to see the write if something orders them: a channel send before the matching receive completes, an Unlock before the next Lock, a wg.Done before Wait returns, or an atomic operation. Without such an edge the program has a data race. Go's memory model guarantees much less for racy programs, and a race on a map, slice or interface can corrupt memory and crash the process.