Chapter 8: Data Races and the Memory Model

8.1 What Is a Data Race?

A data race occurs when three conditions are all true simultaneously:

1. Two or more goroutines access the same memory location
2. At least one access is a write
3. The accesses are not synchronized

If any condition is false, there’s no data race. Remove any one, and the race disappears.

  1. Same memory location     ─┐
                                ├──► All three = DATA RACE
  2. At least one write       ─┤
                                │
  3. No synchronization       ─┘

  Remove ANY condition → No data race:

  • Different memory locations  → Independent access (safe)
  • All reads, no writes        → Concurrent reads (safe)
  • Synchronized access         → Ordered operations (safe)

Let’s examine each condition.

Condition 1: Same Memory Location

Two goroutines must access the same variable, struct field, slice element, or map entry:

// Illustrative snippet — not a complete program
var counter int  // Shared variable

go func() {
    counter++  // Access 1: reads and writes counter
}()

go func() {
    counter++  // Access 2: reads and writes counter
}()

Both goroutines access counter—the same memory location.

What counts as “same location”:

Condition 2: At Least One Write

If all accesses are reads, there’s no race—reading doesn’t modify memory, so concurrent reads cannot conflict:

// Illustrative snippet — not a complete program
var config = Config{Timeout: 30}  // Initialized before goroutines start

// Safe: concurrent reads only
go func() { fmt.Println(config.Timeout) }()  // Read
go func() { fmt.Println(config.Timeout) }()  // Read

The danger arises when at least one goroutine writes:

// Illustrative snippet — not a complete program
var config = Config{Timeout: 30}

// DATA RACE: one read, one write
go func() { fmt.Println(config.Timeout) }()  // Read
go func() { config.Timeout = 60 }()          // Write

What counts as a write:

Concurrent reads (safe):

  Memory: [42]
            ↑ ↑
  G1 reads: 42
  G2 reads: 42

  Both see the same value. No conflict.

─────────────────────────────────────────────────────────

Read + write (unsafe):

  Memory: [42] → [??] → [99]
            ↑      ↑
  G1 reads: 42? 99? partial?
  G2 writes: 99

  G1 might see old, new, or corrupted value.

Condition 3: No Synchronization

If accesses are ordered by synchronization primitives, there’s no race—even with concurrent goroutines and writes:

// Illustrative snippet — not a complete program
var (
    counter int
    mu      sync.Mutex
)

// Safe: mutex synchronizes access
go func() {
    mu.Lock()
    counter++
    mu.Unlock()
}()

go func() {
    mu.Lock()
    counter++
    mu.Unlock()
}()

The mutex ensures accesses never overlap. At any moment, exactly one goroutine accesses counter.

Synchronization mechanisms that prevent races:

The Counter Example

Here’s the canonical data race:

package main

import (
    "fmt"
    "sync"
)

func main() {
    counter := 0
    var wg sync.WaitGroup

    for i := 0; i < 1000; i++ {
        wg.Go(func() {
            counter++  // DATA RACE
        })
    }

    wg.Wait()
    fmt.Println("Counter:", counter)
}

Expected: Counter: 1000

Actual (varies each run):

The varying output is a symptom of the data race, but the varying output isn’t the actual problem. The problem is that the program’s behavior is undefined.

The race detector immediately identifies the problem, showing exactly which goroutines accessed the variable and where in the code. We’ll cover the race detector in detail in §8.3.

Why counter++ Races

counter++ looks like one operation but compiles to three:

Source code:    counter++

Actual steps:   1. READ:   temp = counter   (load from memory)
                2. MODIFY: temp = temp + 1  (increment)
                3. WRITE:  counter = temp   (store to memory)

Between any two steps, another goroutine can act.

When two goroutines execute counter++ concurrently, their operations can interleave:

Initial: counter = 0

Time    Goroutine A              Goroutine B         counter
────    ───────────              ───────────         ───────
T1      READ counter (0)                               0
T2                               READ counter (0)      0
T3      temp = 0 + 1 = 1                               0
T4                               temp = 0 + 1 = 1      0
T5      WRITE counter = 1                              1
T6                               WRITE counter = 1     1

Result: counter = 1 (expected: 2)

Both read 0, both compute 1, both write 1.
One increment was lost.

With 1000 goroutines, hundreds of increments can be lost.

This is called a lost update—one of many symptoms of data races. But lost updates are the benign case. Data races cause problems far worse than wrong counts.

What a Data Race Actually Costs You

A program with a data race does not merely produce “wrong answers sometimes.” But Go is more specific than “anything can happen,” and the specifics are worth knowing, because they tell you which races merely corrupt a number and which corrupt memory.

The Go memory model says three things about a program that races. First, an implementation is always allowed to detect the race, report it and halt — which is exactly what -race builds do. Second, for a value no larger than a machine word, a read must observe some value actually written by a preceding or concurrent write; acausal and “out of thin air” values are forbidden. Third — and this is where it gets dangerous — reads of anything larger than a word are only encouraged to behave that way. An implementation may treat them as several word-sized operations in an unspecified order.

The compiler and runtime assume your code is race-free and optimize accordingly—reordering operations, eliminating redundant memory accesses, caching values in registers. When that assumption is violated, these optimizations produce behavior that looks impossible from a reading of the source. The program is broken even when it appears to work.

Torn Reads: Seeing Impossible States

Consider a data race on a struct:

// Illustrative snippet — not a complete program
type Config struct {
    Host string
    Port int
}

var config Config  // Shared, unsynchronized

// Goroutine A: updates config
func updateConfig(host string, port int) {
    config.Host = host
    config.Port = port
}

// Goroutine B: reads config
func connect() {
    addr := fmt.Sprintf("%s:%d", config.Host, config.Port)
    dial(addr)
}

If updateConfig("newhost", 8080) runs while connect() reads, goroutine B might see:

• Host = "newhost", Port = 8080 (fully updated) ✓
• Host = "oldhost", Port = 80 (fully old) ✓
• Host = "newhost", Port = 80 (half old, half new) ✗
• Host = "oldhost", Port = 8080 (half old, half new) ✗

The last two are torn reads—seeing a state that never existed as a complete, coherent value.

Time    Goroutine A (writer)       Goroutine B (reader)
────    ────────────────────       ────────────────────
T1      config.Host = "newhost"
T2                                 host := config.Host → "newhost"
T3                                 port := config.Port → 80
T4      config.Port = 8080

Reader sees: Host="newhost", Port=80
This combination was NEVER a valid state.

Result: connect("newhost:80") — wrong server!

A data race on any of these can produce torn reads where the components are inconsistent with each other—reading a string’s new pointer with its old length, for example.

Pointer and Interface Races: Crashes

Data races on pointers or interfaces can cause crashes:

// Illustrative snippet — not a complete program
var handler http.Handler  // Shared, unsynchronized

// Goroutine A: replaces handler
func updateHandler(h http.Handler) {
    handler = h
}

// Goroutine B: uses handler
func handleRequest(w http.ResponseWriter, r *http.Request) {
    handler.ServeHTTP(w, r)  // May crash
}

In Go, an interface value is two words: a type pointer and a data pointer. Without synchronization, a reader might see a torn value:

Initial:  interface{ Type: *TypeA, Data: *DataA }

Writer updates to: interface{ Type: *TypeB, Data: *DataB }

Reader might see:
  interface{ Type: *TypeB, Data: *DataA }  ← TORN!

Calling a method uses TypeB's method table with DataA → crash

The Race You Can’t See: Reordering

The most dangerous races are the ones that don’t manifest during development:

// Illustrative snippet — not a complete program
var ready bool
var data int

func setup() {
    data = 42      // Write 1
    ready = true   // Write 2
}

func use() {
    if ready {
        fmt.Println(data)  // DATA RACE: may print 0!
    }
}

// Called from separate goroutines:
go setup()
go use()

This looks reasonable: set data, then set ready. But without synchronization:

1. CPU reordering: The CPU may execute or make visible the writes in different order
2. Cache effects: Another CPU core may see ready = true before seeing the updated data
3. Compiler optimization: Independent writes may be reordered for efficiency

What you wrote:                What another core may observe:

  data = 42                      ready = true
  ready = true                   data = 42

Why reordering happens: The compiler and CPU reorder
independent operations to improve performance—instruction
pipelining, cache optimization, register allocation. From
their perspective, these writes have no dependency.

Another goroutine may observe:
  ready == true
  data == 0 (zero value)

Your intended "happens-before" relationship only exists in
your mind—you must make it explicit with synchronization.

This race might never trigger on your development machine but fail consistently on a different CPU architecture or under production load. This is why race bugs discovered in production are often impossible to reproduce locally—the reordering that exposes the race only happens under specific CPU, compiler, or load conditions.

Test Your Understanding

Example 1: Shared counter

// Illustrative snippet — not a complete program
var count int
for i := 0; i < 100; i++ {
    go func() { count++ }()
}

Race? Yes—multiple goroutines write count without synchronization.

Example 2: Goroutine-local variables

// Illustrative snippet — not a complete program
for i := 0; i < 10; i++ {
    go func() {
        localCount := 0
        localCount++
        fmt.Println(i, localCount)
    }()
}

Race? No—each goroutine has its own localCount. No shared memory.

Example 3: Read-only shared data

// Illustrative snippet — not a complete program
var config = loadConfig()  // Package level; never modified after

go func() { fmt.Println(config.Timeout) }()  // Read
go func() { fmt.Println(config.Timeout) }()  // Read

Race? No—config is initialized before goroutines start (package-level initialization), and only read afterward. No writes after initialization means no race.

Example 4: Channel communication

// Illustrative snippet — not a complete program
ch := make(chan int)
go func() { ch <- 42 }()
go func() { fmt.Println(<-ch) }()

Race? No—channel operations are synchronized by the runtime.

Example 5: Mutex-protected counter

// Illustrative snippet — not a complete program
var mu sync.Mutex
var count int

go func() { mu.Lock(); count++; mu.Unlock() }()
go func() { mu.Lock(); count++; mu.Unlock() }()

Race? No—mutex ensures only one goroutine accesses count at a time.

Example 6: Map with concurrent writes

// Illustrative snippet — not a complete program
var cache = make(map[string]string)

for i := 0; i < 100; i++ {
    go func() { cache[fmt.Sprint(i)] = "value" }()
}

Race? Yes—this is a data race. Go’s runtime usually detects concurrent map writes and panics with fatal error: concurrent map writes, but detection is not guaranteed.

The Four Questions Connection

Chapter 2 introduced the Four Questions for every goroutine. Question 4—“What data does it access?”—directly addresses race prevention:

When you answer Q4 and find that multiple goroutines access the same data with at least one write, you’ve identified a potential data race. The follow-up question: “How is that access synchronized?”

Common Mistakes

Next: §8.2 distinguishes data races from race conditions—a crucial distinction that even experienced developers often confuse.

8.2 Data Races vs Race Conditions

§8.1 defined data races: concurrent memory access with at least one write and no synchronization. But there’s another term you’ll encounter—race condition—that sounds similar but describes a fundamentally different problem.

These terms are often used interchangeably. This is a mistake. They have different causes, different consequences, and different solutions.

DATA RACE                          RACE CONDITION
─────────────────────────          ─────────────────────────────
Memory safety violation            Logic/correctness bug

Unsynchronized concurrent          Program correctness depends
access with at least               on timing of operations
one write

Causes memory-unsafe results       Causes wrong but defined
(torn values, corruption)          behavior

Detected by:                       Detected by:
race detector                      testing, reasoning, code review
(go run -race)

Fixed by:                          Fixed by:
synchronization                    correct algorithm

──────────────────────────────────────────────────────────────

KEY INSIGHT: You can have one without the other. Adding mutexes
eliminates data races but doesn’t automatically fix race conditions.

Understanding this distinction matters because:

• The race detector finds data races, not race conditions
• Fixing a data race doesn’t automatically fix a race condition
• Code can have one without the other

Definitions

Data race: Two goroutines access the same memory location concurrently, at least one is a write, and there’s no synchronization. The value you read is not predictable, and for anything wider than a machine word it may be a value that was never written — see §8.1.

Race condition: Program correctness depends on the relative timing or ordering of operations. The outcome varies based on which operation “wins the race.” This produces wrong but defined behavior—the program does something predictable, just not what you wanted.

Race Condition Without Data Race

The most important insight: you can have race conditions in perfectly synchronized code.

Consider a bank account with properly synchronized methods:

// Illustrative snippet — not a complete program
type Account struct {
    mu      sync.Mutex
    balance int
}

func (a *Account) Balance() int {
    a.mu.Lock()
    defer a.mu.Unlock()
    return a.balance
}

func (a *Account) Withdraw(amount int) bool {
    a.mu.Lock()
    defer a.mu.Unlock()
    if a.balance >= amount {
        a.balance -= amount
        return true
    }
    return false
}

func (a *Account) Deposit(amount int) {
    a.mu.Lock()
    defer a.mu.Unlock()
    a.balance += amount
}

Each method is properly synchronized. There are no data races—the mutex ensures exclusive access to balance. The race detector will report nothing.

But this code has a race condition when used like this:

// Illustrative snippet — not a complete program
// ✗ WRONG: Check-then-act with gap
func transferUnsafe(from, to *Account, amount int) bool {
    if from.Balance() >= amount {  // Check
        from.Withdraw(amount)       // Act (return value ignored!)
        to.Deposit(amount)
        return true
    }
    return false
}

The bug: Between checking Balance() and calling Withdraw(), another goroutine can withdraw funds:

from.balance: $100, to.balance: $0

Goroutine A                            Goroutine B
(transfer $80)                           (transfer $80)
──────────────────                       ──────────────────
Balance() → $100
(100 >= 80? yes, proceed)
                                         Balance() → $100
                                         (100 >= 80? yes, proceed)
Withdraw($80) → true
(from = $20)
                                         Withdraw($80) → false
                                         ($20 < $80, rejected)
Deposit($80) to “to”
(to = $80)
                                         Deposit($80) to “to”
                                         (to = $160) ← BUG!

Final: from=$20, to=$160 (started with $100 total!)
transferUnsafe ignored Withdraw’s return value — money created.

NO DATA RACE (each method is synchronized)
YES RACE CONDITION (correctness depends on timing)

The race detector won’t catch this because there’s no data race—every memory access is properly synchronized. But the program is still wrong: the check in transferUnsafe became stale before the action occurred.

// Illustrative snippet — not a complete program
if condition() {    // Check
    act()           // Act—condition may have changed!
}

Examples:

• “If file doesn’t exist, create it”
• “If key not in map, insert it”
• “If balance sufficient, withdraw”
• “If seat available, book it”
• “If counter below limit, increment”

Rule: Check-then-act must be atomic. The lock must cover both operations.

Fixing the race condition:

// Illustrative snippet — not a complete program
// ✓ CORRECT: Check and act atomically under same lock
func (a *Account) TransferTo(to *Account, amount int) bool {
    if a == to {
        return true  // Self-transfer is a no-op
    }

    a.mu.Lock()
    defer a.mu.Unlock()

    if a.balance < amount {
        return false
    }

    a.balance -= amount

    to.mu.Lock()
    to.balance += amount
    to.mu.Unlock()

    return true
}

Now the balance check and withdrawal happen while holding the lock—no other goroutine can see or modify the balance in between.

Adding Mutex Alone Isn’t Enough

A common mistake: adding a mutex but releasing it between check and act.

// Illustrative snippet — not a complete program
// ✗ WRONG: Mutex but gap between check and act
func increment() {
    mu.Lock()
    belowLimit := counter < 100
    mu.Unlock()  // Released here!

    if belowLimit {
        mu.Lock()
        counter++  // Another goroutine may have incremented!
        mu.Unlock()
    }
}

// ✓ CORRECT: Check and act under same lock
func increment() {
    mu.Lock()
    defer mu.Unlock()

    if counter < 100 {
        counter++
    }
}

The first version has no data race—every access is protected. But it has a race condition because belowLimit can become stale before we act on it.

Why “Benign” Data Races Aren’t Benign

Can you have a data race where the program logic appears correct? Some developers call these “benign races”—though as we’ll see, they’re anything but benign.

// Illustrative snippet — not a complete program
var done bool  // Unsynchronized

func worker() {
    processData()
    done = true  // DATA RACE: write without synchronization
}

func coordinator() {
    go worker()

    for !done {  // DATA RACE: read without synchronization
        time.Sleep(time.Millisecond)
    }
    fmt.Println("Complete")
}

Data race? Yes—concurrent read and write to done without synchronization.

Race condition? Also yes—due to caching and visibility rules, the coordinator may spin forever, never observing the write. The program’s correctness depends on timing and hardware memory behavior.

Why this specific race breaks:

Scenario 1: Register caching

  // Compiler may optimize to:
  r1 = done                        // Load once into register
  loop:
    if !r1 goto loop               // Checks register, not memory

  Worker writes to memory, but loop never reloads done
  → Infinite loop

Scenario 2: Reordering

  func worker() {
      done = true                  // CPU may make visible first
      processData()                // This runs second
  }

  Coordinator sees done==true, proceeds before
  processData() completes → Uses unprocessed data

Scenario 3: Cache visibility delay

  On multi-core systems, one CPU’s write may not be visible
  to another CPU for an unbounded time without synchronization

These aren’t theoretical — they happen in production.

Correct implementation:

// Illustrative snippet — not a complete program
var done atomic.Bool

func worker() {
    processData()
    done.Store(true)
}

func coordinator() {
    go worker()

    for !done.Load() {
        time.Sleep(time.Millisecond)
    }
    fmt.Println("Complete")
}

Atomic operations establish happens-before relationships (§ 8.4), so when Load() returns true, the coordinator is guaranteed to see processData()’s side effects. This fixes both the caching and the reordering problems—the compiler cannot move Store(true) before processData().

Both Data Race AND Race Condition

Many real-world bugs combine both problems:

// Illustrative snippet — not a complete program
var counter int  // Unsynchronized

func increment() {
    if counter < 100 {  // DATA RACE: unsynchronized read
        counter++       // DATA RACE: unsynchronized read-modify-write
    }
}

// Multiple goroutines
for i := 0; i < 200; i++ {
    go increment()
}

Data race: Multiple goroutines access counter without synchronization. Undefined behavior.

Race condition: Even with synchronization, the check-then-act pattern would still be buggy if the lock is released between check and act.

Both bugs must be fixed:

// Illustrative snippet — not a complete program
var (
    counter int
    mu      sync.Mutex
)

func increment() {
    mu.Lock()
    defer mu.Unlock()

    // Check and act atomically under same lock
    if counter < 100 {
        counter++
    }
}

Now there’s no data race (mutex protects access) and no race condition (check-then-act is atomic).

The Four Combinations

                    Has Race Condition?
                    No                    Yes
           ┌─────────────────────┬─────────────────────┐
       No  │ ✓ CORRECT           │ ⚠ LOGIC BUG         │
 Has       │                     │ (subtle)            │
 Data      ├─────────────────────┼─────────────────────┤
 Race? Yes │ ✗ MEMORY-UNSAFE     │ ✗✗ BOTH BUGS        │
           │ RESULTS             │ (worst case)        │
           └─────────────────────┴─────────────────────┘

Top-left:     Correct concurrent code (goal)
Top-right:    Synchronized memory, wrong algorithm
              (race detector won’t catch it)
Bottom-left:  Data race despite “correct” logic
              (race detector WILL catch it)
Bottom-right: Both problems (common in buggy code)

TOCTOU: Time-of-Check to Time-of-Use

TOCTOU is the formal name for check-then-act race conditions, particularly common in file operations. The vulnerability exists in the gap between checking a condition and using the result.

// Illustrative snippet — not a complete program
// ✗ TOCTOU: File may change between check and use
func processFile(path string) error {
    info, err := os.Stat(path)
    if err != nil {
        return err
    }
    if info.Size() > maxSize {
        return errors.New("file too large")
    }

    // Gap: file can change here!

    data, err := os.ReadFile(path)  // May read different content
    if err != nil {
        return err
    }
    return process(data)
}

Between Stat and ReadFile:

• The file could grow larger than maxSize
• The file could be replaced with different content
• The file could be deleted

Not a data race (no shared memory between goroutines), but still a race condition—the check becomes stale before use. Race conditions aren’t limited to goroutines; they can occur anywhere timing matters.

Fix: Act atomically, handle errors

// Illustrative snippet — not a complete program
// ✓ No TOCTOU: Open once, use the handle
func processFile(path string) error {
    f, err := os.Open(path)
    if err != nil {
        return err
    }
    defer f.Close()

    info, err := f.Stat()  // Stat the open file, not the path
    if err != nil {
        return err
    }
    if info.Size() > maxSize {
        return errors.New("file too large")
    }

    data, err := io.ReadAll(f)  // Read from same handle
    if err != nil {
        return err
    }
    return process(data)
}

For file creation, use atomic flags:

// Illustrative snippet — not a complete program
// ✗ TOCTOU: File may be created between check and create
if _, err := os.Stat(path); os.IsNotExist(err) {
    os.Create(path)  // Another process might create it first
}

// ✓ Atomic: O_EXCL fails if file exists
f, err := os.OpenFile(path, os.O_CREATE|os.O_EXCL|os.O_WRONLY, 0644)

Test Your Understanding

Example 1: Atomic counter with check

// Illustrative snippet — not a complete program
var counter atomic.Int64

func incrementIfBelow(max int64) bool {
    current := counter.Load()
    if current < max {
        counter.Add(1)
        return true
    }
    return false
}

Data race? No—atomic operations are synchronized.

Race condition? Yes—another goroutine might increment between Load() and Add(), causing counter to exceed max.

Example 2: Map with mutex

// Illustrative snippet — not a complete program
var (
    cache = make(map[string]string)
    mu    sync.Mutex
)

// No defer — intentionally release lock before expensive computation
func getOrCompute(key string) string {
    mu.Lock()
    if val, ok := cache[key]; ok {
        mu.Unlock()
        return val
    }
    mu.Unlock()

    // Expensive; lock released so other callers are not blocked
    computed := expensiveCompute(key)

    mu.Lock()
    cache[key] = computed
    mu.Unlock()
    return computed
}

Data race? No—mutex protects all map access.

Race condition? Yes—two goroutines may both compute for the same key if they both see “not found” before either stores.

Example 3: Channel select

// Illustrative snippet — not a complete program
func queryFirst(ch1, ch2 <-chan int) int {
    select {
    case v := <-ch1:
        return v
    case v := <-ch2:
        return v
    }
}

Data race? No—channels are synchronized by runtime.

Race condition? Depends on intent. If either result is acceptable (first-response-wins pattern), this is correct by design. If a specific channel’s result is required, this is a bug.

Common Mistakes

Summary

Next: §8.3 covers Go’s race detector in depth—how to use it, interpret its output, and integrate it into your development workflow.

8.3 The Race Detector

§§8.1 and 8.2 taught you what data races are and how they differ from race conditions. But recognizing data races in code is hard—they’re timing-dependent, often invisible during development, and can lurk undetected for months. You need a tool.

Go provides one: the race detector. It’s built into the toolchain, requires no setup, and finds data races that would take humans hours to identify.

What it is:
  A dynamic analysis tool built into the Go toolchain
  that detects data races at runtime

How to use it:
  go run -race main.go
  go test -race ./...
  go build -race -o myapp

What it detects:
  ✓ Concurrent unsynchronized memory access
  ✓ Data races (all three conditions from §8.1)

What it does NOT detect:
  ✗ Race conditions (logic bugs in synchronized code)
  ✗ Deadlocks
  ✗ Goroutine leaks
  ✗ Races in code paths not executed during the run

Cost:
  2-20× slower execution (typically ~10×), 5-10× more memory
  Worth it for testing; not for production

Basic Usage

Enable the race detector with the -race flag:

The detector instruments your code at compile time, tracking all memory accesses and synchronization operations. When it detects concurrent access to the same memory location with at least one write and no synchronization, it reports a race.

Your First Race Report

Let’s trigger and examine a race report:

package main

import (
    "fmt"
    "sync"
)

func main() {
    counter := 0
    var wg sync.WaitGroup

    for i := 0; i < 2; i++ {
        wg.Go(func() {
            counter++  // DATA RACE
        })
    }

    wg.Wait()
    fmt.Println("Counter:", counter)
}

Run with -race:

Anatomy of a Race Report

Every race report has the same structure:

==================
WARNING: DATA RACE

┌───────────────────────────────────────────────────────┐
│ Read at 0x00c0000b4010 by goroutine 7:        │
│   main.main.func1()                             │
│       /path/to/main.go:15 +0x3a                  │
│                                                       │
│ This is the CURRENT access that triggered      │
│ the report. Shows: memory address,             │
│ goroutine ID, stack trace.                     │
└───────────────────────────────────────────────────────┘

┌───────────────────────────────────────────────────────┐
│ Previous write at 0x00c0000b4010 by goroutine 6:│
│   main.main.func1()                             │
│       /path/to/main.go:15 +0x52                  │
│                                                       │
│ This is the CONFLICTING access                 │
│ (unsynchronized). At least one must be a       │
│ write—here it's explicit.                     │
└───────────────────────────────────────────────────────┘

┌───────────────────────────────────────────────────────┐
│ Goroutine 7 (running) created at:              │
│   main.main()                                   │
│       /path/to/main.go:12 +0x7a                  │
│                                                       │
│ Where the goroutine was spawned—helps        │
│ trace the bug.                                  │
└───────────────────────────────────────────────────────┘

exit status 66  ← what go run prints; go run itself exits 1

Key information in each report:

// Illustrative snippet — not a complete program
- name: Test with race detector
  run: go test -race ./...
  # go test exits 1 on a detected race, which fails the step.
  # Do not match on 66 here: that is the inner binary's code.

Reading Complex Reports

Real-world races often involve deeper call stacks:

// Illustrative snippet — not a complete program
type Cache struct {
    data map[string]string
}

func (c *Cache) Get(key string) string {
    return c.data[key]  // Line 8
}

func (c *Cache) Set(key, value string) {
    c.data[key] = value  // Line 12
}

func main() {
    cache := &Cache{data: make(map[string]string)}
    var wg sync.WaitGroup

    wg.Go(func() {
        cache.Set("foo", "bar")  // Line 22
    })
    wg.Go(func() {
        _ = cache.Get("foo")  // Line 27
    })
    wg.Wait()
}

Those first frames are inside the runtime’s map implementation. Since Go 1.24 that lives in internal/runtime/maps/ (the Swiss-table rewrite); on an older toolchain the same frames point at runtime/map_faststr.go. Either way they are noise — the frames you want are the two below them, in your own package.

Reading strategy:

1. Skip runtime internals. Ignore runtime.mapassign_faststr—that’s the map implementation.
2. Find your code. Look for your package name: main.(*Cache).Set() on line 12.
3. Identify the conflict. Set() writes to the map, Get() reads from it—both without synchronization.
4. Trace goroutine creation. Lines 22 and 27 show where the goroutines were spawned.

Common runtime functions in reports:

These are normal—look at the line above them in your code for the actual source.

Multiple Races in One Run

The detector reports each distinct race it finds:

// Illustrative snippet — not a complete program
var (
    counter1 int
    counter2 int
)

func main() {
    var wg sync.WaitGroup
    for i := 0; i < 100; i++ {
        wg.Go(func() {
            counter1++  // Race 1
            counter2++  // Race 2
        })
    }
    wg.Wait()
}

What the Race Detector Catches

The detector finds races on all Go memory types:

// Illustrative snippet — not a complete program
// ✓ DETECTED: Variables
var count int
go func() { count++ }()
go func() { count++ }()

// ✓ DETECTED: Struct fields
type Data struct{ value int }
var d Data
go func() { d.value = 1 }()
go func() { fmt.Println(d.value) }()

// ✓ DETECTED: Map access
var m = make(map[string]int)
go func() { m["a"] = 1 }()
go func() { _ = m["a"] }()

// ✓ DETECTED: Slice modification
var s []int
go func() { s = append(s, 1) }()
go func() { fmt.Println(len(s)) }()

What the Race Detector Misses

The detector has fundamental limitations. Understanding them prevents false confidence.

1. Races in Unexecuted Code Paths

The detector only finds races that actually occur during execution:

// Illustrative snippet — not a complete program
// Given: var cache map[string]string; var key, value string
func process(useCache bool) {
    if useCache {
        // Race here—but only if useCache is true
        go func() { cache[key] = value }()
        _ = cache[key]
    }
}

func TestProcess(t *testing.T) {
    process(false)  // Race never triggered—not detected!
}

The only way to reduce false negatives is to increase test coverage of concurrent code paths and test with production-like workloads.

2. Race Conditions (Logic Bugs)

From §8.2—synchronized code with timing-dependent correctness:

// Illustrative snippet — not a complete program
// Given: var mu sync.Mutex; var balance int

// ✗ NOT DETECTED: Race condition with proper synchronization
func withdraw(amount int) bool {
    mu.Lock()
    hasEnough := balance >= amount
    mu.Unlock()  // Gap between check and act!

    if hasEnough {
        mu.Lock()
        balance -= amount
        mu.Unlock()
        return true
    }
    return false
}

The race detector sees properly synchronized memory access. It can’t detect that the logic is wrong.

3. Deadlocks and Goroutine Leaks

// Illustrative snippet — not a complete program
// ✗ NOT DETECTED: Deadlock
var mu1, mu2 sync.Mutex
go func() { mu1.Lock(); mu2.Lock() }()
go func() { mu2.Lock(); mu1.Lock() }()

// ✗ NOT DETECTED: Goroutine leak
ch := make(chan int)
go func() { ch <- 1 }()  // Blocks forever, no receiver

Performance Overhead

Race detection isn’t free:

This means:

• Always use in development and testing—the cost is worth finding bugs
• Avoid in production—consider staging/canary environments if runtime detection is needed
• CI/CD should always run -race—automated testing can absorb the cost

CI/CD Integration

Make the race detector part of your continuous integration pipeline:

// Illustrative snippet — not a complete program
# GitHub Actions
name: Test
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-go@v5
        with:
          go-version: 'stable'  # Or pin to your project's version

      - name: Test with race detector
        run: go test -race -timeout 10m ./...

// Illustrative snippet — not a complete program
# GitLab CI
test:
  image: golang:latest  # Or pin to your project's version
  script:
    - go test -race -timeout 10m ./...

Best practices for CI:

Environment Variables

Control race detector behavior with the GORACE environment variable:

Strategies for Better Detection

Since the detector only finds races in executed code, maximize coverage:

1. Write Concurrent Tests

Tests that only use one goroutine won’t detect races:

// Illustrative snippet — not a complete program
// ✗ BAD: No concurrency, won't detect races
func TestCache(t *testing.T) {
    c := NewCache()
    c.Set("key", "value")
    _ = c.Get("key")
}

// ✓ GOOD: Concurrent access exposes races
func TestCacheConcurrent(t *testing.T) {
    c := NewCache()
    var wg sync.WaitGroup

    for i := 0; i < 10; i++ {
        wg.Go(func() {
            for j := 0; j < 100; j++ {
                c.Set(fmt.Sprintf("key-%d", j), "value")
            }
        })
        wg.Go(func() {
            for j := 0; j < 100; j++ {
                _ = c.Get(fmt.Sprintf("key-%d", j))
            }
        })
    }
    wg.Wait()
}

2. Run Tests Multiple Times

Races are non-deterministic. Running tests multiple times increases detection probability:

3. Stress Test Concurrent Code

// Illustrative snippet — not a complete program
func TestCacheStress(t *testing.T) {
    if testing.Short() {
        t.Skip("skipping stress test in short mode")
    }

    c := NewCache()
    var wg sync.WaitGroup

    // 100 concurrent workers, each doing 1000 operations
    for i := 0; i < 100; i++ {
        wg.Go(func() {
            for j := 0; j < 1000; j++ {
                c.Set(fmt.Sprint(i), fmt.Sprint(j))
            }
        })
        wg.Go(func() {
            for j := 0; j < 1000; j++ {
                _ = c.Get(fmt.Sprint(i))
            }
        })
    }
    wg.Wait()
}

Common Patterns and Fixes

Pattern 1: Shared Counter

// Illustrative snippet — not a complete program
// ✗ RACE
var count int
go func() { count++ }()

// ✓ FIX: Use atomic
var count atomic.Int64
go func() { count.Add(1) }()

Pattern 2: Shared Map

// Illustrative snippet — not a complete program
// ✗ RACE: concurrent write + read on map (undefined behavior)
var cache = make(map[string]string)
go func() { cache["a"] = "1" }()
go func() { _ = cache["b"] }()

// ✓ FIX: Use mutex
var (
    cache = make(map[string]string)
    mu    sync.Mutex
)
go func() { mu.Lock(); cache["a"] = "1"; mu.Unlock() }()
go func() { mu.Lock(); _ = cache["b"]; mu.Unlock() }()

Pattern 3: Done Flag

// Illustrative snippet — not a complete program
// ✗ RACE
var done bool
go func() { doWork(); done = true }()
for !done { time.Sleep(time.Millisecond) }

// ✓ FIX: Use channel
done := make(chan struct{})
go func() { doWork(); close(done) }()
<-done

Pattern 4: Lazy Initialization

// Illustrative snippet — not a complete program
// ✗ RACE
var config *Config
func getConfig() *Config {
    if config == nil {
        config = loadConfig()
    }
    return config
}

// ✓ FIX (Go 1.21+): sync.OnceValue owns both the guard and the
// value, so there is no package-level variable left to race on.
var getConfig = sync.OnceValue(loadConfig)

// ✓ Same guarantee the long way, if you need to do more than
// return one value.
var (
    config     *Config
    configOnce sync.Once
)
func getConfigSlow() *Config {
    configOnce.Do(func() { config = loadConfig() })
    return config
}

Debugging Tips

Reproduce Flaky Races

Races are timing-dependent. If a race appears intermittently:

When Races Aren’t Reported

If you suspect a race but the detector is silent:

1. Check test coverage. Does the test exercise the racy code path?
2. Run multiple times. Races are probabilistic: go test -race -count=100
3. Widen race windows. Add artificial delays during debugging to increase overlap probability.
4. Check feature flags. Is the racy code behind a flag that’s disabled in tests?

Races in Third-Party Code

If a race report points to library code:

1. Check if you’re using the library correctly (most likely)
2. Check if there’s a known issue in the library
3. Report the bug if it’s genuinely in the library

Common Mistakes

Next: §8.4 covers the Go memory model—the formal rules that define when one goroutine’s writes become visible to another, and why synchronization is necessary for correct concurrent programs.

8.4 The Go Memory Model

§§8.1–8.3 established that data races cause undefined behavior and showed you how to detect them. But why is unsynchronized access so dangerous? Why can’t goroutines just read the latest value written by another goroutine?

The answer lies in Go’s memory model—a set of formal rules that define when a write in one goroutine is guaranteed to be visible to a read in another. Without synchronization, you have no guarantees about what values a goroutine will see. Not “probably correct,” not “eventually consistent”—no guarantees at all.

The memory model answers one question:

  When is a write in goroutine A guaranteed to be
  visible to a read in goroutine B?

The answer: When there’s a HAPPENS-BEFORE relationship
  between the write and the read.

─────────────────────────────────────────────────────────

Without happens-before:
  • Writes may not be visible to other goroutines
  • Reads may see stale, partial, or no values
  • Word-sized reads still see a real write; wider values tear

With happens-before:
  • Writes are guaranteed visible before subsequent reads
  • Program behavior is defined and predictable
  • This is what synchronization establishes

Why Memory Models Exist

You might think: “If I write to a variable, then another goroutine reads it, it should see my write.” This intuition is wrong for three reasons:

1. Compiler Reordering

Recall the reordering example from §8.1—now we can explain why it happens. The compiler optimizes code by reordering operations that appear independent:

// Illustrative snippet — not a complete program
// What you wrote:
data = 42
ready = true

// What the compiler might generate:
ready = true
data = 42  // Reordered—no dependency between them

Within a single goroutine, this reordering is invisible—your code behaves as if operations happened in order. But another goroutine observing these variables might see ready = true before data = 42.

The compiler may also:

• Cache variables in registers (never reading from memory)
• Eliminate “redundant” reads
• Hoist loop-invariant loads outside loops

2. CPU Reordering

Modern CPUs execute instructions out of order for performance. Even if the compiler preserved your order, the CPU might not:

// Illustrative snippet — not a complete program
// Compiled order:
data = 42
ready = true

// CPU execution on a weakly-ordered machine (arm64, ppc64):
Store ready = true
Store data = 42  // Reordered; x86-64 is TSO and will not
                 // do this, which is why the same racy
                 // program can pass on a laptop and fail
                 // on an arm64 server.

3. Cache Visibility

Each CPU core has its own cache. A write might sit in one core’s cache without being visible to other cores:

  Core 1                              Core 2
  ┌──────────┐                        ┌──────────┐
  │ Cache L1 │                        │ Cache L1 │
  │ data=42  │  ← Write here first    │ data=0   │ ← Stale!
  │ ready=T  │                        │ ready=F  │
  └────┬─────┘                        └────┬─────┘
       │                                   │
       └───────────┬───────────────────┘
                    ▼
             ┌────────────┐
             │ Main Memory│
             │  data=?    │  ← May not reflect Core 1’s writes
             │  ready=?   │
             └────────────┘

  Core 2 may read stale values from its cache while
  Core 1’s writes are still in its local cache.

The memory model exists because modern hardware and compilers optimize aggressively. These optimizations are invisible within a single goroutine but become visible—and dangerous—when multiple goroutines share data.

The Happens-Before Relationship

The memory model is built on one core concept: happens-before.

Definition: If event A happens before event B, then A’s memory effects are guaranteed to be visible to B.

Key insight: Happens-before is established by synchronization operations, not by wall-clock time. Two operations can occur at different times but still have no happens-before relationship.

Scenario 1: Happens-before WITHOUT earlier wall-clock time

  T=0: Goroutine A: x = 1
  T=0: Goroutine B: y = 2  (same instant)
  T=1: B sends on channel
  T=2: A receives from channel

  Happens-before: y=2 → send → receive
  A is GUARANTEED to see y=2 after the receive

─────────────────────────────────────────────────────────

Scenario 2: Earlier wall-clock time WITHOUT happens-before

  T=0: Goroutine A: x = 1
  T=1: Goroutine B: print(x)  (one second later!)

  No synchronization → No happens-before
  B might print 0 or 1—DATA RACE
  Wall-clock ordering provides NO guarantee

Key properties of happens-before:

1. Transitive: If A happens-before B, and B happens-before C, then A happens-before C
2. Within a goroutine: Each statement happens-before the next (program order)
3. Across goroutines: Only synchronization creates happens-before edges

What Establishes Happens-Before

Go’s memory model defines exactly which operations create happens-before relationships:

1. Within a Single Goroutine

Statements execute in program order. Each statement happens-before the next:

// Illustrative snippet — not a complete program
func singleGoroutine() {
    x := 1      // A
    y := x + 1  // B: A happens-before B
    z := y + 1  // C: B happens-before C
}

This is the only case where “earlier in code” means “happens before.”

2. Goroutine Creation

The go statement happens before the new goroutine starts:

// Illustrative snippet — not a complete program
x := 42
go func() {
    fmt.Println(x)  // Guaranteed to see x = 42
}()

Happens-before chain: x = 42 → go statement → goroutine’s first instruction.

3. Channel Operations

Send and receive: A send on a channel happens before the corresponding receive completes. This applies to both buffered and unbuffered channels.

// Illustrative snippet — not a complete program
var data int
ch := make(chan struct{})

go func() {
    data = 42         // (1)
    ch <- struct{}{}  // (2) send
}()

<-ch               // (3) receive—happens after (2)
fmt.Println(data)  // (4) guaranteed to see 42

Channel close: Close happens before a receive that returns the zero value due to closure.

// Illustrative snippet — not a complete program
var data int
ch := make(chan struct{})

go func() {
    data = 42
    close(ch)  // Close happens before receive of zero value
}()

<-ch               // Returns immediately (channel closed)
fmt.Println(data)  // Guaranteed to see 42

Unbuffered channels (additional guarantee): For unbuffered channels, send and receive must rendezvous—neither completes until both are ready. This gives an additional guarantee: the receive happens-before the send completes. In practice, this means both sides can observe each other’s prior writes after the rendezvous:

// Illustrative snippet — not a complete program
ch := make(chan int)  // Unbuffered
var data int

go func() {
    data = 42
    <-ch  // (1) Receive happens before send completes
}()

ch <- 1           // (2) Send completes after (1)
fmt.Println(data) // Guaranteed to see 42

This bidirectional synchronization doesn’t apply to buffered channels, where sends complete immediately if buffer space is available.

4. Mutex Operations

Unlock() happens before any subsequent Lock() on the same mutex:

// Illustrative snippet — not a complete program
var (
    mu   sync.Mutex
    data int
)

mu.Lock()           // (1) Main acquires first
go func() {
    mu.Lock()        // (3) Blocks until (2)
    fmt.Println(data) // Guaranteed to see 42
    mu.Unlock()
}()

data = 42           // (1b) Write while holding lock
mu.Unlock()         // (2) Unlock happens-before goroutine's Lock

Time ──────────────────────────────────────────────────────▶

Main:          [Lock]────[write data]────[Unlock]
                                            │
                                            │ happens-before
                                            ▼
Goroutine:                               [Lock]────[read]────

The Unlock-Lock sequence creates the happens-before edge.
All writes before Unlock are visible after the subsequent Lock.

5. sync.Once

The function passed to Do() completes before any Do() call returns:

// Illustrative snippet — not a complete program
var (
    once   sync.Once
    config *Config
)

func getConfig() *Config {
    once.Do(func() {
        config = loadConfig()  // Happens before any Do() returns
    })
    return config  // Guaranteed to see initialized config
}

Since Go 1.21 there is a shorter spelling of exactly this. sync.OnceValue(loadConfig) returns a function with the same happens-before guarantee and no package-level variable to protect — the thing being guarded stops being reachable without going through the guard. sync.OnceFunc does the same for a function that returns nothing. Use the explicit sync.Once when the initializer has to set several things at once; use OnceValue the rest of the time.

6. sync.WaitGroup

Done() happens before Wait() returns:

// Illustrative snippet — not a complete program
var (
    wg   sync.WaitGroup
    data int
)

wg.Add(1)
go func() {
    data = 42
    wg.Done()  // Happens before Wait returns
}()

wg.Wait()
fmt.Println(data)  // Guaranteed to see 42

This example keeps Add and Done visible because they are what the rule is stated in terms of. In your own code, wg.Go(func(){…}) — used everywhere else in this book since Go 1.25 — does the pair for you and carries the identical guarantee: whatever the function writes is visible after Wait returns.

7. Atomic Operations

Operations in sync/atomic establish happens-before. An atomic store happens before any atomic load that observes the stored value:

// Illustrative snippet — not a complete program
var (
    data  int
    ready atomic.Bool
)

go func() {
    data = 42           // (1) Program order within goroutine
    ready.Store(true)   // (2) Atomic store
}()

for !ready.Load() {     // (3) Atomic load—loops until (2) observed
    time.Sleep(time.Microsecond)  // Brief sleep to avoid busy-spinning
}
fmt.Println(data)       // (4) Guaranteed to see 42

Happens-before chain:

• Step 1 → Step 2: Program order within goroutine
• Step 2 → Step 3: Atomic store happens-before the load that observes it
• Step 3 → Step 4: Program order within goroutine
• Therefore: Step 1 → Step 4 (by transitivity)

8. Package Initialization

Package init() functions and variable initialization happen before main() starts:

// Illustrative snippet — not a complete program
var config = loadConfig()  // Happens before main()

func main() {
    use(config)  // Guaranteed to see initialized config
}

Happens-Before Summary

What the Memory Model Does NOT Guarantee

Understanding the limits is as important as understanding the guarantees.

No Guarantee: Time-Based Ordering

// Illustrative snippet — not a complete program
x := 0

go func() {
    time.Sleep(time.Second)
    fmt.Println(x)  // NOT guaranteed to see 1
}()

x = 1
time.Sleep(2 * time.Second)  // "Surely it's visible by now"—WRONG

Sleep is not synchronization. There’s no happens-before relationship.

No Guarantee: Busy-Wait on Regular Variables

// Illustrative snippet — not a complete program
// ✗ BROKEN: Regular bool has no ordering guarantee
var done bool
var result int

go func() {
    result = compute()
    done = true  // DATA RACE
}()

for !done {  // DATA RACE
    // spin
}
fmt.Println(result)

This is undefined behavior. The compiler might:

• Cache done in a register, never seeing the update
• Optimize the loop to if !done { for {} }
• Reorder done = true before result = compute()

Fixes:

// Illustrative snippet — not a complete program
// ✓ FIX 1: Atomic operations
var done atomic.Bool
var result int

go func() {
    result = compute()
    done.Store(true)  // Atomic store establishes happens-before
}()

for !done.Load() {
    time.Sleep(time.Microsecond)  // Brief sleep to avoid busy-spinning
}
fmt.Println(result)  // Guaranteed to see computed result

// Illustrative snippet — not a complete program
// ✓ FIX 2: Channel (preferred—blocking is better than polling)
var result int
done := make(chan struct{})

go func() {
    result = compute()
    close(done)
}()

<-done
fmt.Println(result)  // Guaranteed to see computed result

No Guarantee: Observing Partial Updates

Without synchronization, you might observe writes in a different order than they occurred:

// Illustrative snippet — not a complete program
var a, b int

go func() {
    a = 1
    b = 2
}()

go func() {
    if b == 2 {
        fmt.Println(a)  // Might print 0!
    }
}()

This is a data race—both goroutines access a and b without synchronization. Even observing b == 2 doesn’t guarantee a == 1 is visible:

• Compiler might reorder the writes: b = 2 then a = 1
• Compiler might reorder the reads: read a, then check b == 2
• CPU caches might make b = 2 visible before a = 1

All three scenarios are legal—no synchronization means no happens-before, which means no guarantees.

The Double-Checked Locking Anti-Pattern

A common mistake is attempting “double-checked locking” for lazy initialization:

// Illustrative snippet — not a complete program
// ✗ BROKEN: Double-checked locking
var instance *Singleton
var mu sync.Mutex

func GetInstance() *Singleton {
    if instance == nil {  // First check—no synchronization!
        mu.Lock()
        if instance == nil {
            instance = &Singleton{}
        }
        mu.Unlock()
    }
    return instance
}

The first nil check has no happens-before relationship with the write inside the lock. A goroutine might:

• See a non-nil pointer to a struct whose fields aren’t yet visible
• See stale nil even after initialization completes
• Observe inconsistent values across multiple reads

Fix: Use sync.Once

// Illustrative snippet — not a complete program
// ✓ CORRECT: sync.Once handles all synchronization
var (
    instance *Singleton
    once     sync.Once
)

func GetInstance() *Singleton {
    once.Do(func() {
        instance = &Singleton{}
    })
    return instance
}

Why this works: The function in Do() happens-before Do() returns in any goroutine. All callers see the fully initialized instance.

Connecting the Memory Model to Data Races

Now we can precisely state why data races cause undefined behavior:

§8.1 definition:
  Data race = same memory + write + no synchronization

Memory model definition:
  Data race = same memory + write + no happens-before

These are equivalent:
  “Synchronization” IS “establishing happens-before”

When you add a mutex, channel, or atomic, you’re not just
“protecting” the variable—you’re establishing happens-before
relationships that make writes visible to reads.

─────────────────────────────────────────────────────────

The race detector (§8.3) works by tracking
happens-before relationships:

  1. Track all memory accesses
  2. Track all synchronization operations
  3. Build happens-before graph
  4. If concurrent accesses have no happens-before path → RACE

Why the Compiler Can’t “Just Be Safe”

A common question: “Why doesn’t the compiler insert memory barriers everywhere?”

Answer: Performance. Memory barriers and synchronization are expensive.

// Illustrative snippet — not a complete program
// Hot loop—runs billions of times
for i := 0; i < 1_000_000_000; i++ {
    localSum += data[i]
}
globalSum = localSum

The compiler optimizes this aggressively:

• Keep localSum in a register (never write to memory)
• Reorder and vectorize loads from data[]
• Unroll the loop

If the compiler assumed every operation could be observed by another goroutine, these optimizations would be impossible. Performance would drop by 10–100× for some workloads.

Go’s contract: You mark shared data with synchronization; Go optimizes everything else aggressively. This is why data races cause undefined behavior—the compiler assumes no races exist.

Test Your Understanding

Example 1: Package-level initialization

// Illustrative snippet — not a complete program
var config = loadConfig()

func Handler(w http.ResponseWriter, r *http.Request) {
    use(config)
}

Safe? Yes—package-level variable initialization happens before main() starts, which happens before any HTTP handlers run. The handlers (which run in goroutines spawned by the server) are guaranteed to see the initialized config.

Example 2: Atomic flag guarding data

// Illustrative snippet — not a complete program
var ready atomic.Bool
var data int

go func() {
    data = 42
    ready.Store(true)
}()

for !ready.Load() {
    time.Sleep(time.Microsecond)
}
fmt.Println(data)

Safe? Yes—the atomic store happens before the load that observes true. Since data = 42 happens before the store (program order), it’s visible after the load.

Example 3: Goroutine exit without sync

// Illustrative snippet — not a complete program
var x int

go func() {
    x = 1
}()
time.Sleep(time.Second)
fmt.Println(x)

Safe? No—this is a data race. There’s no happens-before between the write (x = 1) and the read (fmt.Println(x)). Sleep doesn’t establish synchronization, and goroutine completion alone doesn’t create happens-before.

Fixes:

// Illustrative snippet — not a complete program
// ✓ FIX: Use WaitGroup
var x int
var wg sync.WaitGroup

wg.Go(func() {
    x = 1
})
wg.Wait()
fmt.Println(x)  // Guaranteed to see 1

// ✓ FIX: Use channel
var x int
done := make(chan struct{})

go func() {
    x = 1
    close(done)
}()
<-done
fmt.Println(x)  // Guaranteed to see 1

Example 4: Transitive happens-before

// Illustrative snippet — not a complete program
var a, b int
ch1 := make(chan struct{})
ch2 := make(chan struct{})

go func() { a = 1; close(ch1) }()
go func() { <-ch1; b = 2; close(ch2) }()
<-ch2
fmt.Println(a, b)

Safe? Yes—happens-before chains compose through transitivity:

// Illustrative snippet — not a complete program
a=1 → close(ch1) → <-ch1 → b=2 → close(ch2) → <-ch2 → read a,b

Both values are guaranteed visible.

Common Mistakes

Next: §8.5 explores strategies for preventing data races—confinement, immutability, and synchronization—giving you a toolkit for designing race-free concurrent programs.

8.5 Preventing Data Races

§§8.1–8.4 explained what data races are, how they differ from race conditions, how to detect them, and why the memory model makes them dangerous. Now we turn to prevention: how do you design concurrent programs that are race-free by construction?

Recall the three conditions for a data race from §8.1:

1. Two or more goroutines access the same memory location
2. At least one access is a write
3. The accesses are not synchronized

Remove any condition, and there’s no race. This gives us three prevention strategies:

Condition                      Strategy to Eliminate It
──────────────────────────────────────────────────────────────

1. Same memory location        CONFINEMENT
                               Don’t share—one goroutine owns data

2. At least one write          IMMUTABILITY
                               Don’t modify—read-only after init

3. No synchronization          SYNCHRONIZATION
                               Coordinate access with primitives

──────────────────────────────────────────────────────────────

Prefer strategies in this order:
  1. Confinement (simplest, safest, zero runtime cost)
  2. Immutability (simple, safe, minimal cost)
  3. Synchronization (necessary but error-prone)

Confinement and immutability eliminate races by design.
Synchronization requires careful implementation.

Strategy 1: Confinement

Confinement means restricting data access to a single goroutine. If only one goroutine can access a variable, concurrent access is impossible—no race can occur.

Lexical Confinement

Variables scoped to a single goroutine are automatically confined:

// Illustrative snippet — not a complete program
func handler(w http.ResponseWriter, r *http.Request) {
    // Each handler call runs in its own goroutine
    userID := r.URL.Query().Get("user")  // Confined to this goroutine
    data := fetchData(userID)            // Confined to this goroutine
    render(w, data)
}

Variables userID and data are local to each handler invocation. Even though handlers run concurrently, each has its own copy. No shared state = race-free by construction.

Lexical confinement is the default in Go. Unless you explicitly share data via pointers, package variables, or closure captures, data is automatically confined.

// Illustrative snippet — not a complete program
// ✗ WRONG on Go <1.22: one shared loop variable
for _, item := range items {
    go func() {
        process(item)  // DATA RACE on Go <1.22
    }()
}

// ✓ CORRECT on this book's Go 1.25 baseline: item is already
// per-iteration, so the plain closure confines it.
for _, item := range items {
    go func() {
        process(item)
    }()
}

// Also correct, and portable to pre-1.22 toolchains: pass it in.
for _, item := range items {
    go func(it Item) {
        process(it)
    }(item)
}

Which one to write. Go 1.22 made the loop variable per-iteration, so on this book’s baseline the middle form is confined and is what chapters 1–7 use throughout. Reach for the parameter form when you must build on a pre-1.22 toolchain, or when the value you want to confine is not the loop variable — passing it in is still the clearest way to say “this goroutine gets its own copy.”

Ownership Transfer via Channels

Channels naturally implement confinement through ownership transfer. When you send a value on a channel, you transfer ownership to the receiver:

// Illustrative snippet — not a complete program
func producer(out chan<- *Buffer) {
    for {
        buf := &Buffer{}
        buf.Fill()       // Producer owns buf
        out <- buf       // Ownership transfers to receiver
        // Producer must NOT use buf after this point
    }
}

func consumer(in <-chan *Buffer) {
    for buf := range in {
        // Consumer now owns buf exclusively
        buf.Process()
        buf.Clear()
    }
}

Producer              Channel        Consumer

buf := new(Buffer)       │               │
buf.Fill()               │               │
     │                   │               │
     ├─── send ─────────>│               │
     │  (ownership       │               │
     │   transfers)      │<── receive ───┤
     ✗                   │  (ownership   │
(must not                │   acquired)   ▼
 use buf)                │        buf.Process()
                         │        buf.Clear()

At any moment, exactly ONE goroutine owns the buffer.
No concurrent access → No data race.

// Illustrative snippet — not a complete program
// The compiler allows this, but it's a DATA RACE:
buf := &Buffer{}
ch <- buf
buf.Fill()  // Violates ownership—but compiles!

Enforce ownership through code review, clear documentation, and the race detector.

// Illustrative snippet — not a complete program
data := []int{1, 2, 3}

go func() {
    data[0] = 100  // Modifies shared backing array
}()

fmt.Println(data[0])  // DATA RACE

To truly confine, either:

• Copy the slice: go func(d []int) { ... }(append([]int{}, data...))
• Ensure the original is never accessed after spawning the goroutine

Ad-Hoc Confinement

Sometimes confinement is maintained by convention rather than compiler enforcement. In the example below, the channels themselves provide synchronization—the ad-hoc part is the convention about which goroutine sends and which receives:

// Illustrative snippet — not a complete program
type WorkerPool struct {
    // jobs is only written by Submit(), read only by workers
    jobs chan Job

    // results is only written by workers, read only by Collect()
    results chan Result
}

// Illustrative snippet — not a complete program
type Worker struct {
    // stats is confined to the worker goroutine.
    // Do not access from other goroutines.
    stats WorkerStats
}

Strategy 2: Immutability

Immutability means data doesn’t change after initialization. If there are no writes, concurrent reads are always safe.

Initialize-Once Pattern

The most common approach: initialize data before any concurrent access, then only read:

// Illustrative snippet — not a complete program
// Package-level configuration—initialized before main()
var config = loadConfig()  // Happens before any goroutine starts

func Handler(w http.ResponseWriter, r *http.Request) {
    // Safe: config is never modified after init
    timeout := config.Timeout
    endpoint := config.Endpoint
    // ...
}

Package initialization happens before main() (§ 8.4), establishing happens-before with all subsequent code.

Immutable Value Types

Design types that cannot be modified after creation:

// Illustrative snippet — not a complete program
// Point is immutable—all fields are private, no mutating methods
type Point struct {
    x, y float64
}

func NewPoint(x, y float64) Point {
    return Point{x: x, y: y}
}

func (p Point) X() float64 { return p.x }
func (p Point) Y() float64 { return p.y }

// "Mutation" returns a new Point—original unchanged
func (p Point) Translate(dx, dy float64) Point {
    return Point{x: p.x + dx, y: p.y + dy}
}

Mutable (race-prone):

  type Counter struct {
      value int
  }
  func (c *Counter) Increment() { c.value++ }  // Mutates!

Immutable (race-free):

  type Counter struct {
      value int
  }
  func (c Counter) Increment() Counter {  // Returns new
      return Counter{value: c.value + 1}
  }

The immutable version can be shared freely—no mutations, no races.
But you must propagate the new value somehow.

Copy-on-Read for Safe Sharing

When readers need shared data that occasionally changes, return copies:

// Illustrative snippet — not a complete program
type ConfigManager struct {
    mu     sync.RWMutex
    config Config
}

func (cm *ConfigManager) Get() Config {
    cm.mu.RLock()
    defer cm.mu.RUnlock()
    return cm.config  // Returns a copy—caller gets immutable snapshot
}

func (cm *ConfigManager) Update(new Config) {
    cm.mu.Lock()
    defer cm.mu.Unlock()
    cm.config = new
}

Callers receive a copy they own—they can use it freely without synchronization.

// Illustrative snippet — not a complete program
type Config struct {
    Timeout time.Duration  // Safe: value type
    Servers []string       // Danger: backing array shared!
}

For reference types, return defensive copies:

// Illustrative snippet — not a complete program
func (cm *ConfigManager) GetServers() []string {
    cm.mu.RLock()
    defer cm.mu.RUnlock()
    result := make([]string, len(cm.config.Servers))
    copy(result, cm.config.Servers)
    return result
}

Copy-on-Write

For data read frequently but written rarely, copy the entire structure on write:

// Illustrative snippet — not a complete program
type Registry struct {
    mu       sync.RWMutex
    services map[string]Service
}

func (r *Registry) Get(name string) (Service, bool) {
    r.mu.RLock()
    defer r.mu.RUnlock()
    svc, ok := r.services[name]
    return svc, ok
}

func (r *Registry) Register(name string, svc Service) {
    r.mu.Lock()
    defer r.mu.Unlock()

    // Copy-on-write: create new map with added entry
    newServices := make(map[string]Service, len(r.services)+1)
    for k, v := range r.services {
        newServices[k] = v
    }
    newServices[name] = svc
    r.services = newServices
}

// List returns a consistent snapshot—this is the CoW payoff.
// A concurrent Register() replaces the map pointer, but this
// iteration continues safely on the old (immutable) copy.
func (r *Registry) List() []string {
    r.mu.RLock()
    snapshot := r.services
    r.mu.RUnlock()

    names := make([]string, 0, len(snapshot))
    for name := range snapshot {
        names = append(names, name)
    }
    return names
}

T0: [Map v1: {a:1, b:2}]
     ¦
     ¦—> Reader 1 gets reference to v1
     ¦—> Reader 2 gets reference to v1
     ¦
T1: Writer calls Register("c", svc)
     Creates [Map v2: {a:1, b:2, c:svc}] (copy + update)
     Swaps r.services to point to v2
     ¦
     ¦—> Reader 1 still using v1 (consistent snapshot)
     ¦—> Reader 2 still using v1 (consistent snapshot)
     ¦—> Reader 3 gets reference to v2
     ¦
T2: Readers 1&2 finish, release v1
     v1 eventually garbage collected

Readers always see complete, consistent snapshots.

Atomic Pointer Swap for Lock-Free Reads

The mutex-protected copy-on-write above requires acquiring a read lock for every access. For extremely read-heavy workloads (thousands of reads per write), you can eliminate read-side locking entirely using atomic pointer swap:

// Illustrative snippet — not a complete program
type Server struct {
    config atomic.Pointer[Config]
}

func NewServer(cfg *Config) *Server {
    s := &Server{}
    s.config.Store(cfg)
    return s
}

func (s *Server) Config() *Config {
    return s.config.Load()  // Lock-free read
}

func (s *Server) UpdateConfig(new *Config) {
    s.config.Store(new)  // Atomic swap
}

func (s *Server) handleRequest(w http.ResponseWriter, r *http.Request) {
    cfg := s.Config()  // Get immutable snapshot
    // Use cfg freely—even if UpdateConfig is called, our pointer
    // still points to the old config which remains valid
    timeout := cfg.Timeout
    // ...
}

// Illustrative snippet — not a complete program
cfg := server.Config()
cfg.Timeout = 100  // DATA RACE if another goroutine reads cfg

Make T immutable by design: unexported fields, no setter methods, no mutable reference-type fields.

Strategy 3: Synchronization

When data must be shared and mutable, use synchronization primitives to coordinate access. This establishes the happens-before relationships covered in §8.4.

Choosing the Right Primitive

Brief Examples

// Illustrative snippet — not a complete program
// Channels: Communication and ownership transfer
results := make(chan Result)
go func() { results <- process(item) }()
result := <-results

// Mutex: Complex shared state
var mu sync.Mutex
var balance int

mu.Lock()
balance += 100
mu.Unlock()

// Atomic: Simple counters (lower overhead than mutex)
var counter atomic.Int64
counter.Add(1)

// Once: Lazy initialization
var once sync.Once
var instance *Service

once.Do(func() { instance = newService() })

// Illustrative snippet — not a complete program
// ✗ BAD: Holding lock during slow I/O
func (c *Cache) GetOrLoad(key string) string {
    c.mu.Lock()
    defer c.mu.Unlock()
    if val, ok := c.data[key]; ok {
        return val
    }
    val := loadFromDatabase(key)  // Slow! Lock held entire time
    c.data[key] = val
    return val
}

// ✓ GOOD: Only lock for map access
// Note: Two goroutines may both miss the cache and load the same key.
// This is a race condition (duplicate work), not a data race.
// For most caches, duplicate loads are acceptable.
func (c *Cache) GetOrLoad(key string) string {
    c.mu.Lock()
    val, ok := c.data[key]
    c.mu.Unlock()

    if ok {
        return val
    }

    val = loadFromDatabase(key)  // No lock during I/O

    c.mu.Lock()
    c.data[key] = val
    c.mu.Unlock()
    return val
}

Detailed synchronization patterns are covered in Chapters 9–12.

Choosing a Strategy

Can data be confined to one goroutine?
  ¦
  ¦—> YES: Use CONFINEMENT
  ¦        • Goroutine-local variables
  ¦        • Ownership transfer via channels
  ¦        • Lexical scoping
  ¦
  ¦—> NO:  Is the data read-only after initialization?
             ¦
             ¦—> YES: Use IMMUTABILITY
             ¦        • Initialize before goroutines start
             ¦        • Copy-on-read for snapshots
             ¦        • Atomic pointer swap for updates
             ¦
             ¦—> NO:  Use SYNCHRONIZATION
                      ¦
                      ¦—> Communication  → Channels
                      ¦—> Complex state  → Mutex
                      ¦—> Read-heavy     → RWMutex
                      ¦—> Simple values  → Atomic
                      ¦—> One-time init  → sync.Once

Combining Strategies

Real programs combine all three strategies, choosing the right approach for each piece of data:

// Illustrative snippet — not a complete program
type Server struct {
    config     *Config             // IMMUTABLE after construction
    addr       string              // IMMUTABLE after construction
    shutdownCh chan struct{}       // SYNCHRONIZED via channel ops
    totalReqs  atomic.Int64        // SYNCHRONIZED with atomics
    mu         sync.RWMutex        // Protects sessions below
    sessions   map[string]*Session // SYNCHRONIZED with mutex
}

func (s *Server) HandleRequest(w http.ResponseWriter, r *http.Request) {
    // Atomic: simple increment
    s.totalReqs.Add(1)

    // Immutable: config never changes after construction
    timeout := s.config.Timeout

    // Confined: request data is local to this handler
    ctx, cancel := context.WithTimeout(r.Context(), timeout)
    defer cancel()

    // Synchronized: session map requires mutex
    s.mu.RLock()
    session := s.sessions[getSessionID(r)]
    s.mu.RUnlock()

    // Process request...
}

                         ┌─────────────────┐
                         │     Server      │
                         └─────────────────┘
                                  ¦
         ┌────────────────────┼────────────────────┐
         ¦                    ¦                    ¦
         ↓                    ↓                    ↓
  ┌─────────────┐      ┌─────────────┐      ┌─────────────┐
  │   config    │      │  totalReqs  │      │  sessions   │
  │ (immutable) │      │  (atomic)   │      │   (mutex)   │
  └─────────────┘      └─────────────┘      └─────────────┘

Each component uses the strategy best suited to its access pattern.
The strategies compose cleanly.

The Four Questions Revisited

Chapter 2 introduced the Four Questions for every goroutine. Question 4—“What data does it access?”—now has a complete framework:

If you can’t answer how shared mutable data is protected, you have a potential race.

Anti-Patterns to Avoid

Shared-state signaling: As we saw in §8.4, polling a regular bool variable is a data race—use a channel or atomic.Bool instead.

Common Mistakes

Verify Your Strategy

After implementing any of these strategies, run your tests with -race to verify there are no hidden races:

The race detector (§8.3) is your safety net—use it to confirm your design is correct.

Test Your Understanding

Example 1

// Illustrative snippet — not a complete program
func handleConnection(conn net.Conn) {
    defer conn.Close()
    buffer := make([]byte, 4096)
    for {
        n, err := conn.Read(buffer)
        if err != nil {
            return
        }
        process(buffer[:n])
    }
}

Example 2

// Illustrative snippet — not a complete program
var config = &Config{Timeout: 30 * time.Second}

func getTimeout() time.Duration {
    return config.Timeout
}

Example 3

// Illustrative snippet — not a complete program
type RateLimiter struct {
    mu     sync.Mutex
    tokens int
}

func (r *RateLimiter) Allow() bool {
    r.mu.Lock()
    defer r.mu.Unlock()
    if r.tokens > 0 {
        r.tokens--
        return true
    }
    return false
}

Example 4

// Illustrative snippet — not a complete program
var totalProcessed int

func worker(items <-chan Item) {
    for item := range items {
        process(item)
        totalProcessed++
    }
}

// Launch 10 workers
for i := 0; i < 10; i++ {
    go worker(items)
}

// Illustrative snippet — not a complete program
var totalProcessed atomic.Int64

func worker(items <-chan Item) {
    for item := range items {
        process(item)
        totalProcessed.Add(1)
    }
}

Summary

Next: Test your understanding with the chapter self-check below.

Chapter 8 Self-Check

Test your understanding of the complete chapter with these questions. Click each question to reveal the answer.

4. You see this pattern in code review. What’s wrong, and how would you fix it?

// Illustrative snippet — not a complete program
var ready bool
var data int

go func() {
    data = 42
    ready = true
}()

for !ready {}
fmt.Println(data)

6. Which of these establishes a happens-before relationship?

• a) time.Sleep(time.Second)
• b) Channel send/receive
• c) Earlier wall-clock time
• d) sync.Mutex Lock/Unlock

10. For each scenario, identify the best prevention strategy (confinement, immutability, or synchronization):

• a) Request-scoped variables in an HTTP handler
• b) Application version string set at startup
• c) Active user session count