Lesson 6: sync, atomic & the Race Detector

Channels Aren't Always the Answer #

Lesson 0005 taught you "share memory by communicating." But Go's philosophy is pragmatic, not dogmatic. Sometimes a mutex is simpler:

// Channel approach: over-engineered for a simple counter
type Counter struct {
    inc  chan struct{}
    read chan chan int
}
// ... need a goroutine to manage the channel loop ...

// Mutex approach: clear, simple, idiomatic for this use case
type Counter struct {
    mu    sync.Mutex
    value int
}

func (c *Counter) Inc() {
    c.mu.Lock()
    c.value++
    c.mu.Unlock()
}

The Kubernetes codebase uses both — channels for controller work queues, mutexes for shared caches. Knowing when to use each is the mark of an experienced Go developer.

sync.Mutex — Mutual Exclusion #

A mutex ensures only one goroutine accesses a critical section at a time:

type SafeMap struct {
    mu   sync.Mutex
    data map[string]int
}

func (m *SafeMap) Set(key string, val int) {
    m.mu.Lock()
    defer m.mu.Unlock()  // always unlock with defer
    m.data[key] = val
}

func (m *SafeMap) Get(key string) (int, bool) {
    m.mu.Lock()
    defer m.mu.Unlock()
    val, ok := m.data[key]
    return val, ok
}

sync.RWMutex — Read/Write Lock #

When reads vastly outnumber writes, use RWMutex. Multiple readers can hold the lock simultaneously, but writers get exclusive access:

type Cache struct {
    mu   sync.RWMutex
    data map[string]string
}

func (c *Cache) Get(key string) (string, bool) {
    c.mu.RLock()          // multiple goroutines can RLock
    defer c.mu.RUnlock()
    val, ok := c.data[key]
    return val, ok
}

func (c *Cache) Set(key, val string) {
    c.mu.Lock()           // exclusive — blocks all readers and writers
    defer c.mu.Unlock()
    c.data[key] = val
}

Don't Copy a Mutex #

sync.WaitGroup — Wait for Goroutines #

A WaitGroup waits for a collection of goroutines to finish:

func main() {
    urls := []string{"url1", "url2", "url3"}
    var wg sync.WaitGroup

    for _, url := range urls {
        wg.Add(1)  // increment counter BEFORE launching goroutine
        go func(u string) {
            defer wg.Done()  // decrement counter when goroutine exits
            fetch(u)
        }(url)
    }

    wg.Wait()  // block until counter reaches zero
    fmt.Println("all done")
}

WaitGroup with Error Collection #

Real pattern from cloud-native code — wait for goroutines and collect their errors:

func fetchAll(urls []string) []error {
    var (
        wg     sync.WaitGroup
        mu     sync.Mutex
        errs   []error
    )

    for _, url := range urls {
        wg.Add(1)
        go func(u string) {
            defer wg.Done()
            if err := fetch(u); err != nil {
                mu.Lock()
                errs = append(errs, err)
                mu.Unlock()
            }
        }(url)
    }

    wg.Wait()
    return errs
}

sync.Once — Run Exactly Once #

Guarantees a function runs exactly once, even when called from multiple goroutines:

type DB struct {
    conn *sql.DB
    once sync.Once
}

func (d *DB) Conn() *sql.DB {
    d.once.Do(func() {
        // This runs exactly once, even if 100 goroutines call Conn()
        var err error
        d.conn, err = sql.Open("postgres", dsn)
        if err != nil {
            panic(err)  // or: log.Fatal — can't return error from Do
        }
    })
    return d.conn
}

sync/atomic — Lock-Free Operations #

For simple counters and flags, atomic operations avoid mutex overhead entirely:

var counter int64

// Concurrent-safe increment without a mutex
atomic.AddInt64(&counter, 1)

// Read the value atomically
val := atomic.LoadInt64(&counter)

// Store atomically
atomic.StoreInt64(&counter, 100)

// Compare-and-swap: set to 200 only if current value is 100
swapped := atomic.CompareAndSwapInt64(&counter, 100, 200)

Atomic Bool for State Flags #

var isReady atomic.Bool
isReady.Store(true)
if isReady.Load() {
    // ...
}

Mutex vs Atomic: When to Use Which #

Use MutexUse Atomic Protecting a section of code (multiple statements)Single integer/boolean read/write Complex data structure updatesHigh-frequency counters Read-write access patterns (RWMutex)Flags and state transitions When correctness > micro-optimizationWhen perf matters and operation is simple

The Race Detector — Go's Superpower #

Run it with -race:

go test -race ./...
go run -race main.go
go build -race -o myapp

What constitutes a data race:

func main() {
    counter := 0

    go func() {
        counter++  // write without synchronization — RACE!
    }()

    fmt.Println(counter)  // read without synchronization — RACE!
}

Output from go run -race:

==================
WARNING: DATA RACE
Read at 0x00c00001a0f8 by main goroutine:
  main.main()
      /tmp/race.go:12 +0x4e

Previous write at 0x00c00001a0f8 by goroutine 7:
  main.main.func1()
      /tmp/race.go:8 +0x38

Goroutine 7 (finished) created at:
  main.main()
      /tmp/race.go:7 +0x47
==================

What the Race Detector Does #

• Instruments every memory access — tracks which goroutine read/wrote which address
• Detects concurrent access where at least one is a write AND no synchronization (lock, channel, atomic) happened between them
• Reports the exact lines where the race occurred

Limitations #

• Only detects races that actually happen during execution — it can't find races in code paths that don't run
• Race-enabled binaries use ~10x more memory and run slower
• Don't deploy race-enabled binaries to production

When to Use What #

ProblemTool Two goroutines need to coordinate (handoff)Unbuffered channel Producer-consumer data flowChannel (buffered for throughput) Multiple goroutines read/write a shared mapsync.Mutex or sync.RWMutex Wait for N goroutines to finishsync.WaitGroup One-time initializationsync.Once Simple counter, high frequencyatomic.AddInt64 State flag shared across goroutinesatomic.Bool Signal cancellation to many goroutinesclose(chan struct{}) Multiplex multiple channelsselect

Practice #

Quick Check #

What's Next? #

You now have the full concurrency toolkit — channels for communication, sync primitives for shared state, and the race detector to verify correctness. Next: Context — cancellation, deadlines, and passing request-scoped values through call chains. Every Kubernetes controller method takes a ctx context.Context.

---

Ask Questions #

Not sure when to use a channel vs a mutex? Paste your scenario and I'll help you decide.