Skip to content

00 — Start here

Level: 101 · read this first

This library is for someone who can read Go — functions, structs, slices, errors — and wants to understand what its concurrency actually does: why a goroutine's output never appeared, why a program hangs, why a count comes out short one run in ten, and what the standard library gives you to prevent each of those. If the syntax itself is new, A Tour of Go ↗ comes first.

The seven to read first

  1. main does not wait — the first surprise, and the WaitGroup that fixes it.
  2. An unbuffered send waits for a receiver — a channel is a meeting as well as a pipe.
  3. select chooses at random — case order is not a priority.
  4. A mutex guards a counter — the lost update, and when a lock beats a channel.
  5. One cancel reaches every goroutine — how a whole tree of work is stopped.
  6. A worker pool — the pattern most programs end up needing.
  7. The race detector — the tool to run before trusting any of the above in your own code.

How to read a page

Each page has the same shape: a one-line claim, an output block from the program in that page's examples/ folder, Reading the output, What to do, In other languages, and Sources. The output blocks are generated, never typed: if a page shows a value, Go printed it, on both CI machines.

A fence titled Real runs is different. It shows something that changes from run to run — how many increments a race lost, the order goroutines finished in — counted on one machine on one date. It is not an answer key; the demo/ script beside the page reproduces it on yours.

Go's concurrency in one paragraph

A goroutine is a function call started with go; it costs a few kilobytes, so starting a hundred thousand is ordinary (Goroutines are cheap). It hands nothing back, so results travel on channels (A goroutine has no handle). Channels synchronize as well as carry (An unbuffered send waits for a receiver), select waits on several of them, and context carries cancellation through all of it (One cancel reaches every goroutine). When sharing memory is simpler, the sync package has the locks (A mutex guards a counter) — and go test -race finds the places where neither was used (The race detector).