Mutexes, Data Races & the Race Detector

• Goroutine A reads value and sees 7.
• Goroutine B reads value and also sees 7.
• A adds one and writes 8.
• B adds one and writes 8.

Two increments happened, but the counter only moved by one. An update was lost because both goroutines read the same starting number. If you run 100 goroutines like this, the final total will land somewhere below 100, and the exact number will vary from run to run. There is no bug in the arithmetic. The bug is that nothing stopped the two goroutines from overlapping.

Protecting shared state with sync.Mutex

The fix is to ensure only one goroutine runs the read-modify-write cycle at a time. A mutex (short for mutual exclusion) is a lock that does exactly this. One goroutine calls Lock and enters the protected section of code. Any other goroutine that calls Lock must wait until the first one calls Unlock. Only one gets through at a time, so the overlap that loses updates can no longer happen.

Here is SafeCounter from concurrency.go. It bundles an integer value together with the mutex that guards it:

Inc locks the mutex, increments the value, and unlocks it. Because the lock wraps the entire value++ operation, no other goroutine can read or write value while one is in the middle of updating it. The read-modify-write now happens as one indivisible step. No increments are lost.

Using defer c.mu.Unlock() is an important habit. Putting the unlock in a defer guarantees it runs when the method returns, no matter how it returns. If you unlock by hand at the end of a function, and that function returns early or panics before reaching the unlock line, the lock is never released. Every other goroutine will wait for it forever. This is called a deadlock. Using defer removes the chance of forgetting.

Notice that Value locks too, even though it only reads. Reading is still an access. If one goroutine reads value while another writes to it, you have a data race. The rule is simple: every goroutine that touches the shared field, whether reading or writing, must hold the lock first.

Common confusion: A mutex does not belong to any specific method, nor does it magically protect the variable value by name. It simply protects whatever code runs between Lock and Unlock. Keeping the sync.Mutex field right next to the data it guards, as SafeCounter does, is a Go convention. It makes it obvious which lock covers which state.

Running the demo

The mutexCounterDemo function fires 100 goroutines at a single SafeCounter. It uses a sync.WaitGroup from Chapter 14 to wait for all of them to finish:

Each goroutine calls Inc once, meaning 100 increments happen concurrently. Because every single one goes through the lock, the total is always exactly 100:

If you took the lock away, this same loop would print a different number on almost every run. It would usually be less than 100, and it would never be predictable. The mutex is the only reason the answer is stable.

Catching races with the race detector

You will not always spot a missing lock just by reading code, and a race can hide for a long time before it misbehaves. Go ships with a tool that finds these bugs for you: the race detector. When you add the -race flag, Go instruments your program to watch every memory access at runtime and report any two that conflict.

You turn it on when you run or test your code:

If the program has a data race, the detector prints a DATA RACE report. It is worth learning to read these reports because they point straight to the problem.

The report pairs up the two accesses that conflicted. Each block tells you what happened (a read or a write), the memory address, which goroutine did it, and the exact file and line number. Once you see two goroutines touching the same address with at least one write, you have found your race. You now know exactly where to add a lock. The finish branch is clean under -race. Because SafeCounter locks every access, the detector has nothing to report.

The detector adds performance overhead, so you usually would not ship a production binary built with -race. Instead, you run it during development and in your Continuous Integration (CI) pipeline. This way, every push runs the test suite under -race, and a new race fails the build instead of reaching your users. Make using it a habit.

Where this pays off

This is not a toy pattern. The in-memory task store you will build in Chapter 22 wraps a map[int]Task with a sync.Mutex. It locks the map on every read and every write, exactly like SafeCounter. This is what keeps the store correct once your server is live. Because Go's HTTP server runs each incoming request in its own goroutine, two requests creating tasks at the exact same moment are just two goroutines writing to the same map. This is precisely the situation a mutex is built for.

Shared maps are a classic beginner trap, and they are much less forgiving than a plain counter. When two goroutines write to a Go map at the same time, the runtime usually detects it and aborts the entire program with a fatal concurrent map writes error, rather than quietly corrupting the data. Placing a lock around every map access keeps this from happening.

What's Next

This closes the Go language foundations: you now have the types, structs, interfaces, errors, and concurrency tools to build real programs. Section 3 builds the HTTP server, where per-request goroutines make everything you just learned about shared state matter in practice.