The sync package in Go: every type, with examples

The sync package holds Go's low-level synchronisation tools. Channels handle passing data between goroutines; sync handles everything around shared state: locking it, waiting for goroutines, doing setup once, and reusing memory. Its sibling sync/atomic handles single values without a lock.

One rule applies to every type here: do not copy it after first use. A copied Mutex is a second, unrelated lock, and a copied WaitGroup counts nothing. Pass pointers, and let go vet (its copylocks check) catch the mistakes.

Lock and Unlock around every access to the shared data, with defer mu.Unlock() straight after Lock so an early return or a panic cannot leave it locked. Keep the mutex next to the data it protects, in the same struct, and keep the locked section short: never hold a lock while making a network call.

TryLock exists (Go 1.18) but its own documentation warns that correct uses are rare. If you are reaching for it, there is usually a design problem. The Go mutex is also fair under pressure: a waiter that has waited more than 1 ms switches the lock into starvation mode, where it is handed over directly in queue order. The full lesson is Mutexes and races.

RLock lets any number of readers in together; Lock waits until there are none and keeps everyone else out. It only beats a plain Mutex when reads clearly outnumber writes and each read holds the lock long enough for readers to overlap. It has one trap that deadlocks real programs: a goroutine must never take RLock twice. Both are covered with benchmarks in Mutex vs RWMutex.

A WaitGroup is a counter. Add(n) raises it, Done() lowers it by one, and Wait() blocks until it reaches zero. Call Add before the go statement; inside the goroutine, Wait can run first and return immediately.

Go 1.25 added wg.Go(f), which does the Add(1), starts f in a goroutine, and calls Done when it returns. Use it whenever your module targets Go 1.25 or later; it removes both classic mistakes. A WaitGroup does not collect errors. For that, use errgroup (Worker pool).

once.Do(f) runs f the first time it is called from any goroutine. Concurrent callers wait until that first call finishes, then return without running f. Use it for lazy setup: parsing a config, compiling a regular expression, creating a shared client.

Go 1.21 added three helpers that are usually what you want. sync.OnceFunc(f) returns a function that runs f once. sync.OnceValue(f) returns a function that runs f once and then returns its result every time. sync.OnceValues(f) does the same for a (value, error) pair.

The trap: "once" means once, even if it failed. If the setup returns an error, every later call gets the same error, and it is never retried. When the setup can fail for a temporary reason, like a network call, use a mutex and a "done" flag instead, so a later call can try again.

A Pool keeps temporary objects for reuse, so a hot path that needs a scratch buffer on every request does not allocate a new one each time. Get returns a pooled object or calls New to make one; Put hands it back.

Two rules. First, the pool may drop anything it holds at any time; in practice objects that sit unused across garbage collections are freed. So it is a cache for memory, never a place to keep state. Second, reset an object before using it again, because it still holds whatever the last user left in it. Do not pool things that need closing, such as connections or files; that is a job for a real pool like *sql.DB.

Measure before adding one. A Pool only pays off when allocation shows up in a profile. The standard library uses it in places like fmt, where buffers are allocated on every call.

A map that is safe for concurrent use without your own lock. Its documentation is specific about when it helps: when each key is written once and then read many times (a cache that only grows), or when different goroutines read and write disjoint sets of keys. For everything else, a plain map guarded by a Mutex or RWMutex is simpler, type-safe and often faster.

Its methods are Load, Store, LoadOrStore, LoadAndDelete, Delete, Range, plus Swap, CompareAndSwap and CompareAndDelete (Go 1.20) and Clear (Go 1.23). Values come back as any, so you need a type assertion on every read.

A condition variable: goroutines Wait until another goroutine changes some state and calls Signal (wake one) or Broadcast (wake all). Wait unlocks the associated mutex while sleeping and locks it again before returning.

Always call Wait inside a for loop that re-checks the condition, because by the time a woken goroutine runs, another may have changed the state again. The package documentation itself says that for many simple cases channels are a better fit. Cond earns its place when many goroutines wait on a condition over shared state, and Broadcast wakes all of them at once, which a channel can only do by being closed (once).

For a single counter, flag or pointer, an atomic operation is cheaper than a lock. Since Go 1.19 the package has typed values (atomic.Int64, atomic.Bool, atomic.Pointer[T] and others) that cannot be accessed non-atomically by accident, which is a real improvement over the older atomic.AddInt64(&n, 1) functions.

Atomics protect one value. As soon as two values must change together (a balance and a history, a count and a total), use a mutex. Every access to an atomic value must be atomic: one plain read next to atomic writes is a data race.

When the problem is about handing data or work from one goroutine to another: a pipeline, a job queue, a result, a timeout with select. Use sync when goroutines share state in place. The Go wiki's advice is to use whichever is simpler, and Mutex vs channel walks through both versions of the same program.