sync and sync/atomic — Specification¶

1. Introduction¶

The sync package is part of the Go standard library and is governed by the Go 1 compatibility promise. Once a type or function ships in sync it cannot be renamed, removed, or have its signature changed within the Go 1 release line; new behaviour arrives by adding new types (OnceValue, OnceFunc) or new methods, never by altering the existing surface. The package provides the low-level concurrency primitives — mutual exclusion, one-shot initialisation, broadcast signalling, latch-style wait groups, a concurrent map, and a transient object pool — that nearly every other concurrent Go library is built on top of.

The behaviour of these primitives is not defined by their implementations alone. The Go memory model, revised in 2022 to align with the published C/C++ and Java memory models, is the authoritative document for what guarantees sync and sync/atomic provide. The memory model defines a partial order called "happens-before" over events in concurrent goroutines; sync operations are listed as the synchronisation events that establish this order. Reading sync's source without first reading the memory model produces a working but incomplete understanding: the code shows what the primitives do mechanically, the memory model shows what the language promises to user programs that use them.

The companion sync/atomic package provides lock-free primitive operations on integer and pointer types. It is the foundation on which most of sync is implemented internally — Mutex, Once, WaitGroup, and Pool all use atomic operations on their internal state — and it is also the public surface a senior Go programmer reaches for when a mutex would be overkill. Like sync, sync/atomic is governed by Go 1 compatibility, and its types and operations are catalogued in the memory model as synchronisation events.

This specification is the authoritative-source map for senior code reading: which source files define what, which proposals introduced which features, what each contract guarantees and forbids, and where the runtime bridge ties sync into the Go scheduler.

2. The Go memory model and sync¶

The Go memory model defines, for two goroutines g1 and g2, when a read in g2 is guaranteed to observe a write in g1. The model is built around the "synchronised before" relation, which is a strict partial order on synchronising events; "happens-before" is the transitive closure of "synchronised before" combined with sequenced-before (program order within a single goroutine).

The 2022 revision aligned Go with the sequentially consistent atomics model used by C/C++ and Java. Before the revision, the documentation was informal and ambiguous about racing reads; the revision made the guarantees precise and added explicit text for sync/atomic operations.

sync and sync/atomic are the language's synchronisation events. The memory model lists them by name:

These guarantees are the contract sync exists to provide. The implementations in src/sync/*.go realise them on top of the runtime scheduler and sync/atomic operations.

The 2022 revision introduced four important precisions over the original text:

1. Atomic operations are sequentially consistent. The model previously left the ordering of atomic operations across multiple addresses unspecified; the revision pins it down. A Store to address A followed in program order by a Store to address B is observed in that order by any goroutine that sees both.
2. Racy reads of word-sized values may return unrelated values. Before the revision, the documentation hinted that a racy read of an int might tear or might return the old or new value; the revision states explicitly that a data race may produce a value not equal to any prior write — torn reads are permitted, and undefined behaviour is the right mental model.
3. sync primitives are happens-before sources. The revision enumerates Mutex, RWMutex, WaitGroup, Once, channel send/receive, and atomic operations as the synchronisation events; nothing else (e.g., time.Sleep, runtime.Gosched) provides happens-before.
4. Compiler reordering is permitted within the relation's limits. The compiler may reorder reads and writes within a goroutine as long as the observable behaviour respects program order; across goroutines, reordering is constrained only by synchronisation events.

This is the framework against which sync source code should be read: every atomic operation in mutex.go or waitgroup.go exists to produce, or to observe, a synchronisation event listed above.

3. Stable types in sync¶

Source: src/sync/ in the Go repository.

4. The sync/atomic package¶

The sync/atomic package provides lock-free operations on a fixed set of integer, pointer, and boolean types. Operations are guaranteed to be atomic with respect to other goroutines; the memory model promises sequential consistency for these operations across the whole program.

4.1 Wrapper types (Go 1.19+)¶

4.2 Free function operations (legacy, Go 1.0+)¶

The original package surface was free functions on pointer arguments — atomic.AddInt32(addr *int32, delta int32) int32, atomic.LoadInt64(addr *int64) int64, atomic.CompareAndSwapPointer(addr *unsafe.Pointer, old, new unsafe.Pointer) bool, and so on. These remain supported under Go 1 compatibility but the wrapper types (4.1) are the recommended surface for new code; the wrappers eliminate alignment bugs on 32-bit platforms and present a more type-safe API.

4.3 Operations¶

Source: src/sync/atomic/ — doc.go, value.go, type.go, and the architecture-specific asm_*.s files.

4.4 Memory ordering of atomic operations¶

The memory model makes sync/atomic operations sequentially consistent: a total order exists over all atomic operations in the program, consistent with each goroutine's program order, and every goroutine observes that order. This is the strongest possible ordering and is more restrictive than the acquire/release semantics of C/C++ memory_order_acquire and memory_order_release.

The practical consequences:

• A Store is a release operation with respect to all prior writes in the same goroutine; a subsequent Load on the same address from another goroutine that observes the stored value is an acquire operation that sees all those prior writes.
• A CompareAndSwap that succeeds is both an acquire and a release; the failed case is a load that still participates in the total order.
• Add is a read-modify-write that is atomic and ordered with respect to all other atomic operations.

There is no relaxed-ordering form of these operations in sync/atomic. Programs that want weaker ordering have no portable way to express it; the language designers chose the strong default deliberately, on the grounds that the cost of sequential consistency is small in practice and the cognitive cost of weaker ordering is large.

4.5 Alignment on 32-bit platforms¶

The free-function 64-bit operations (AddInt64, LoadInt64, StoreInt64, CompareAndSwapInt64, SwapInt64) require their argument to be 8-byte aligned on 32-bit platforms. The package documentation states: "On ARM, 386, and 32-bit MIPS, it is the caller's responsibility to arrange for 64-bit alignment of 64-bit words accessed atomically. The first word in a variable or in an allocated struct, array, or slice can be relied upon to be 64-bit aligned."

The atomic.Int64 and atomic.Uint64 wrapper types (Go 1.19+) include a no-op field that forces correct alignment, eliminating this footgun for code that adopts the typed wrappers.

5. The Mutex contract¶

sync.Mutex is a non-reentrant mutual-exclusion lock with the following formal contract:

TryLock was added in Go 1.18 (proposal #45435) after a long debate; the documentation notes that "correct use of TryLock exists but is rare" and that most usages indicate a design problem.

Mutex has two implementation phases internally: a fast path written in inline atomic operations and a slow path that parks goroutines via the runtime scheduler. The slow path uses runtime_SemacquireMutex and runtime_Semrelease which are linknamed from sync into the runtime.

The implementation has two operating modes, switched between dynamically since Go 1.9:

These modes are not visible in the public API and are not part of the contract; they are implementation choices that satisfy the documented semantics while preventing pathological tail latency. Source comments in mutex.go discuss the rationale.

6. The RWMutex contract¶

sync.RWMutex distinguishes readers from writers. The contract:

The internal implementation uses a Mutex plus atomic counters; the writer-preferring semantics are realised by incrementing a "writer waiting" counter that subsequent RLock calls observe and respect.

7. The WaitGroup contract¶

sync.WaitGroup provides a counter-based barrier. The contract:

The implementation packs the counter and waiter count into a single 64-bit value, manipulated by atomic.CompareAndSwap. The runtime hooks runtime_Semacquire and runtime_Semrelease park and unpark waiters.

8. The Once contract¶

sync.Once provides exactly-once execution of a function:

The implementation is a tagged atomic — done atomic.Uint32 plus a Mutex for the slow path. The fast path is a single atomic.LoadUint32 followed by an early return when the bit is set.

9. The Map contract¶

sync.Map is a concurrent map optimised for two workloads: read-mostly with stable keys, and disjoint key sets across goroutines:

The internal design is a two-tier structure: a read-only atomic snapshot for cheap reads, and a dirty map protected by a Mutex for writes. When the dirty map accumulates enough writes the read snapshot is promoted. Source: src/sync/map.go.

10. The Pool contract¶

sync.Pool is a per-P transient cache for objects that can be reused:

The internal structure is per-P (one shard per scheduler P) plus a victim cache that survives one GC. Source: src/sync/pool.go and the runtime hook runtime_registerPoolCleanup.

Per-P sharding is what makes Pool scale: a Get on P0 reads from P0's local shard with no contention against goroutines running on P1 through P_n. When the local shard is empty, the implementation steals from another P's shard before falling back to New. The victim cache, added in Go 1.13, holds the previous generation of pool items for one GC cycle; this smooths the cost of GC clearing for workloads with bursty allocation patterns. The Go 1.13 redesign is described in CL 166961 and the accompanying issue #22950.

10a. The Cond contract¶

sync.Cond is a condition variable for goroutine coordination over a shared predicate:

The package documentation notes that "in most cases" channels are a better fit than Cond; the type exists for the cases where a channel cannot express the predicate-and-broadcast pattern cleanly.

10b. The Locker interface¶

sync.Locker is the smallest possible interface for a mutex-like type:

type Locker interface {
    Lock()
    Unlock()
}

It is satisfied by *Mutex and *RWMutex directly, and by the value returned by (*RWMutex).RLocker() which produces a Locker whose Lock calls the underlying RLock. The interface exists primarily as the argument type for sync.NewCond; secondarily, it lets callers parameterise code over the choice of mutex implementation. Custom implementations of Locker are permitted and used by some libraries (timed-out locks, instrumented locks) but are rare.

11. The runtime bridge¶

sync is unusual in the standard library: it reaches into the runtime via go:linkname to use scheduler primitives that are not exported as a stable API. The bridge lives in src/sync/runtime.go and declares function signatures whose bodies live in the runtime package.

These linknames are an internal protocol between sync and the runtime. They are not part of the Go 1 promise to user code — go:linkname to runtime symbols from outside the standard library is unsupported and warned against. The list itself is stable in practice across Go versions but is subject to change at any minor release.

12. Generics additions (Go 1.21+)¶

Go 1.21 (release notes) added typed one-shot helpers built on top of Once:

These functions replace the very common idiom:

var (
    once  sync.Once
    value T
    err   error
)
func get() (T, error) {
    once.Do(func() { value, err = compute() })
    return value, err
}

with:

var get = sync.OnceValues(compute)

The proposal is #56102. The implementation lives in src/sync/oncefunc.go.

13. Authoritative source files¶

The full directory listing for src/sync/ and src/sync/atomic/ is the starting point for any source-reading session.

14. Compatibility scope¶

The Go 1 compatibility document governs what may and may not change:

The package has remained source-compatible since Go 1.0 (March 2012). Notable additions:

• Go 1.3: sync.Pool.
• Go 1.9: sync.Map.
• Go 1.17: atomic.Value.Swap, atomic.Value.CompareAndSwap.
• Go 1.18: Mutex.TryLock, RWMutex.TryLock, RWMutex.TryRLock.
• Go 1.19: atomic.Int32, Int64, Uint32, Uint64, Uintptr, Pointer[T], Bool.
• Go 1.20: Map.Swap, Map.CompareAndSwap, Map.CompareAndDelete.
• Go 1.21: OnceFunc, OnceValue, OnceValues.

15. Notable proposals¶

The historical proposal list for the sync package is at pkgsite proposals view.

16. Bug reporting¶

Bugs in sync or sync/atomic are filed at github.com/golang/go/issues with the label sync (and sync/atomic as a sub-component label where applicable). The issue template asks for:

1. The Go version (go version).
2. The platform (go env GOOS GOARCH).
3. A minimal reproducer.
4. Expected and actual behaviour.

The package's maintainers are listed in CODEOWNERS and historically include members of the runtime team. Security-relevant issues (a hypothetical lock-skipping bug, for example) are reported through security@golang.org rather than the public tracker.

The race detector (go test -race) is the first-line tool for diagnosing suspected sync misuse. The detector instruments memory accesses and reports any pair that are unordered by the memory-model relations defined above; a sync primitive used correctly should produce no race reports, and any report from sync-using code is either a bug in user code or, very rarely, a bug in sync itself.