Course 1 · Part 0Go: what are we building?

The final result

A program called antfarm. At the end of the course you will be able to run:

$ antfarm run --ants 50000 --grid 512x512 --food 400 \
      --chaos crash=0.001,drop=0.02,slow=0.005 \
      --metrics :9090 --view web:8080

colony: 50000 ants, 512x512 grid, 400 food sources
tick 1200 | alive 49863 | carrying 8214 | food delivered 31902
           | restarts 137 | dropped msgs 4411 | p99 decide 412µs

while a browser tab shows the grid with pheromone trails intensifying along routes the colony has discovered, a Prometheus-style metrics endpoint exposes counters, and go tool pprof can attach to the running process and tell you where the CPU is going. In the final milestone the colony runs split across several operating-system processes that talk over TCP, and you can kill one of them and watch the rest continue.

Why this project is interesting

Ant colonies are the canonical example of emergent behaviour: no ant knows where the food is, no ant is in charge, and yet the colony reliably finds short paths to food. The algorithm behind it is real (ant colony optimisation is a genuine technique for routing and scheduling problems), and it happens to be an almost perfect Go exercise, because the natural implementation is thousands of independent activities exchanging small messages.

It is also a trap, in a useful way. The obvious first implementation puts the world in a shared data structure and lets every ant touch it. That works until you add concurrency, at which point it corrupts itself in ways that only appear under load. Milestone 4 walks you into that bug deliberately, and Milestone 5 walks you out of it using the idiom Go actually recommends. That sequence is the single most valuable thing in this course.

Why Go in particular

• Goroutines are cheap. A goroutine starts with about 2 KB of stack that grows on demand, so 50,000 of them is unremarkable. 50,000 operating-system threads would be roughly 50 GB of reserved stack and a scheduler in agony. This is what makes "one ant, one goroutine" a reasonable design rather than a joke.
• Channels make ownership explicit. Sending a value on a channel is a statement about who is allowed to touch it next. That turns a concurrency question into a design question you can see in the code.
• The race detector is built in. go test -race and go run -race instrument memory accesses and report exactly which two goroutines touched the same address without synchronisation, with both stack traces. Very few languages hand you this for free.
• Profiling is built in. CPU, memory, blocking and mutex-contention profiles come from the standard library, with a viewer in the toolchain.
• The static binary matters at the end. When we go multi-process, deploying is copying one file.

What is genuinely Go-specific here

Worth separating, so you know what transfers:

Architecture we are building toward

                          ┌──────────────────────────┐
                          │        cmd/antfarm       │  flags, config, wiring
                          └────────────┬─────────────┘
                                       │
        ┌──────────────────────────────┼──────────────────────────────┐
        │                              │                              │
┌───────▼────────┐            ┌────────▼─────────┐          ┌─────────▼────────┐
│   sim engine   │            │   observability  │          │      viewer      │
│                │            │                  │          │                  │
│  world owner   │◄─ queries ─┤  metrics, pprof, │          │  terminal / web  │
│   goroutine    │            │  event log       │          │   (read-only)    │
└───┬────────┬───┘            └──────────────────┘          └─────────▲────────┘
    │        │                                                       │
    │        └───────────── snapshots (channel, buffered) ───────────┘
    │
    │  requests: Move, Sense, PickUp, Drop, Deposit
    │  replies:  per-request reply channel
    │
┌───▼──────────────────────────────────────────────────────────┐
│   ant goroutines  (N = 1..50,000)                            │
│                                                              │
│   ant 1 ──┐                                                  │
│   ant 2 ──┤                                                  │
│    ...    ├──► requests channel ──► world owner ──► replies  │
│   ant N ──┘                                                  │
└───┬──────────────────────────────────────────────────────────┘
    │
┌───▼───────────┐     ┌────────────────┐     ┌──────────────────┐
│  supervisor   │     │  pheromone     │     │  chaos injector  │
│  (restarts    │     │  evaporator    │     │  (crash, drop,   │
│   dead ants)  │     │  (ticker)      │     │   delay)         │
└───────────────┘     └────────────────┘     └──────────────────┘

Do not worry about understanding this yet. It is here so that when Milestone 5 introduces "the world owner goroutine" you can see where it fits. The important structural idea, which you will earn rather than be told, is that exactly one goroutine owns the world state, and everyone else asks it questions.

What you will know afterwards

You will be able to explain, from having done it: why a mutex-per-cell design deadlocks and a single-owner design does not; what the race detector actually detects and what it misses; why an unbuffered channel send is a synchronisation point; how to cancel 50,000 goroutines in under a millisecond; how to tell an allocation problem from a contention problem in a profile; and what "backpressure" means in code rather than in a blog post.

Course 1 · Part 1Install and first program

What the Go toolchain is

Go is a compiled, statically typed language with a garbage collector. "Compiled" means a program is translated ahead of time into machine code for your CPU and operating system, producing a single executable file with no runtime to install alongside it. "Statically typed" means the type of every variable is known at compile time and mismatches are compile errors. "Garbage collected" means you do not free memory by hand.

Unusually, almost everything you need is one command, go. There is no separate package manager (no npm, no pip), no separate build system (no Make required), no separate formatter, no separate test runner. This is deliberate and it is one of the pleasant parts of the language.

Installing

You want Go 1.22 or newer for this course, because we use a few features introduced there (ranging over integers, and the corrected loop-variable semantics). At the time of writing the current release is in the 1.25/1.26 range; my knowledge of releases stops in mid-2026, so check go.dev/dl for what is current and prefer the newest stable version.

macOS

# Option A: Homebrew
brew install go

# Option B: official package
# download the .pkg from https://go.dev/dl/ and double-click it

go version    # should print something like: go version go1.25.1 darwin/arm64

Linux

Distribution packages are often a year or more out of date, so install from the tarball:

# adjust the version and architecture to match what go.dev/dl offers
curl -LO https://go.dev/dl/go1.25.1.linux-amd64.tar.gz
sudo rm -rf /usr/local/go
sudo tar -C /usr/local -xzf go1.25.1.linux-amd64.tar.gz

# add to ~/.bashrc or ~/.zshrc, then restart the shell
export PATH=$PATH:/usr/local/go/bin
export PATH=$PATH:$(go env GOPATH)/bin

go version

The rm -rf /usr/local/go matters: the official instructions require removing the old installation rather than untarring over it, because leftover files from a previous version cause confusing errors.

Windows

:: Option A (PowerShell or cmd)
winget install --id GoLang.Go

:: Option B: download the .msi from https://go.dev/dl/ and run it

go version

The installer edits PATH for you, but you must open a new terminal window afterwards for that to take effect. If you plan to do the Perl and Erlang courses too, consider installing WSL2 (wsl --install in an administrator PowerShell) and doing everything inside Linux instead; the Go experience is good either way, but the other two courses are noticeably smoother on Linux.

Checking the installation

go version        # the compiler version
go env GOPATH     # where downloaded modules and installed binaries live
go env GOROOT     # where Go itself is installed (you rarely touch this)

GOPATH defaults to ~/go on macOS and Linux and %USERPROFILE%\go on Windows. If you read an old tutorial saying your code must live inside GOPATH: that has not been true since 2019. With modules, your code lives wherever you like, and GOPATH is just a cache plus a bin directory.

Creating the project

mkdir antfarm
cd antfarm
go mod init github.com/yourname/antfarm

That last command creates a file called go.mod:

module github.com/yourname/antfarm

go 1.25

Three things to understand here.

A module is a unit of versioning and dependency. It is roughly "one repository". The go.mod file records the module's own name, the minimum Go version, and every dependency with its exact version.

The module path is an identity, not a download instruction. github.com/yourname/antfarm is how other code refers to your packages. It looks like a URL because if you ever publish it, Go will fetch it from there. You do not need a GitHub repository to use this name, and nothing contacts the network because of it. Use your real username if you plan to publish; otherwise example.com/antfarm is fine.

There is no lockfile step. When you add a dependency, Go writes it to go.mod and records cryptographic hashes in go.sum. Both are committed to git.

Directory structure

Go has no enforced project layout, but there is a strong convention that you should follow because every Go programmer reads it instantly:

antfarm/
├── go.mod                  module definition
├── go.sum                  dependency hashes (appears when you add deps)
├── cmd/
│   └── antfarm/
│       └── main.go         the executable: flags, wiring, nothing clever
├── internal/               importable only by this module
│   ├── sim/                the simulation engine
│   ├── world/             the grid, food, pheromones
│   └── metrics/
├── pkg/                    (optional) code you intend others to import
└── README.md

Two rules worth knowing now:

• A directory is a package. All .go files in one directory belong to the same package and can see each other's definitions without imports. Subdirectories are separate packages.
• internal/ is enforced by the compiler. Any package under a directory named internal can only be imported by code rooted in the parent of that internal directory. This is not a convention, it is a compile error. It lets you have public-looking structure without committing to a public API.

Editor setup

Use gopls, the official Go language server. It gives completion, jump-to-definition, inline errors, and automatic import management.

• VS Code: install the extension named "Go" (publisher: Go Team at Google). On first opening a .go file it offers to install tools; accept. Then enable format-on-save, which will also fix your imports as you type.
• Neovim: go install golang.org/x/tools/gopls@latest, then configure gopls in your LSP setup.
• GoLand: works out of the box, no language server needed.
• Anything else: if it speaks LSP, install gopls the same way and point your editor at it.

Turn on format-on-save now rather than later. Go has exactly one formatting style, produced by gofmt, and nobody argues about it. Indentation is tabs, which surprises people coming from Python or JavaScript. Let the tool do it.

Hello, colony

Create cmd/antfarm/main.go:

package main

import "fmt"

func main() {
	fmt.Println("Hello, colony.")
}

Run it:

$ go run ./cmd/antfarm
Hello, colony.

Every line, explained

package main — every Go file starts by declaring which package it belongs to. The name main is special: a package named main that contains a function named main is compiled into an executable program. Every other package name produces a library. Note that the package name here is unrelated to the directory name antfarm; the directory determines the import path, the package line determines the name. For main packages the directory name becomes the binary's name.

import "fmt" — brings in the standard library package fmt (short for "format"), which handles printing and string formatting. The quoted string is an import path. For standard library packages it is just the name; for external ones it is the full module path, for example "github.com/spf13/cobra".

func main() { — declares a function called main taking no parameters and returning nothing. Go requires the opening brace on the same line as the declaration. This is not a style preference; the compiler inserts semicolons at line ends, so a brace on the next line produces a syntax error. In a main package, this function is where execution starts, and when it returns the program exits.

fmt.Println("Hello, colony.") — calls the Println function from the fmt package. The capital P is load-bearing: in Go, an identifier that starts with an uppercase letter is exported (visible to other packages), and lowercase means package-private. There is no public or private keyword. Println prints its arguments and appends a newline.

Building, testing, documenting

# compile and run in one step (binary goes to a temp dir)
go run ./cmd/antfarm

# compile to a named file
go build -o bin/antfarm ./cmd/antfarm
./bin/antfarm

# compile and install into $(go env GOPATH)/bin, so it is on your PATH
go install ./cmd/antfarm

# format every file in the tree
gofmt -w .

# the built-in correctness checker: finds real bugs, not style nits
go vet ./...

# run all tests in all packages
go test ./...

# read documentation without a browser
go doc fmt.Println
go doc -all strings | less

The ./... pattern means "this directory and every package beneath it". You will type it constantly.

For documentation, pkg.go.dev hosts rendered docs for the standard library and for every public module. go doc gives you the same content offline. go help and go help mod explain the toolchain itself.

package main

import (
	"fmt"
	"runtime"
)

func main() {
	fmt.Println("go version:", runtime.Version())
	fmt.Println("os:        ", runtime.GOOS)
	fmt.Println("cpus:      ", runtime.NumCPU())
}

$ go build -o bin/antfarm ./cmd/antfarm
$ ./bin/antfarm
go version: go1.25.1
os:         darwin
cpus:       10

Checkpoint

1. What makes a package produce an executable rather than a library?
2. Where does the name github.com/yourname/antfarm come from and what is it used for?
3. Why can code outside your module never import yourmodule/internal/sim?
4. Your colleague's file has an import they are not using. Will it compile?
5. What is the difference between go build, go run, and go install?

Course 1 · Part 2Language crash course

This part teaches only what the ant colony needs. Go is a small language and this is most of it, but I am deliberately skipping generics (until Milestone 11), reflection, struct tags, and embedding beyond one mention. Each concept follows the same rhythm: the idea, a small example, a line-by-line reading, and the mistakes people make. Exercises appear after every group of related concepts, with the solution folded away underneath.

Work through this with a scratch project open. Make a directory scratch, run go mod init scratch, and put experiments in main.go. Type the examples rather than reading them.

2.1 Variables, types, and zero values

The idea

Every variable has a type fixed at compile time. You can write the type explicitly, or let Go infer it from the initial value. A variable declared without a value is not undefined or null; it holds its type's zero value, which is a real, usable value.

package main

import "fmt"

func main() {
	var ticks int = 10          // explicit type, explicit value
	var grid = "512x512"        // type inferred: string
	var alive bool              // no value: zero value, which is false
	name := "worker-7"          // short declaration, only inside functions

	const maxAnts = 50000       // compile-time constant

	fmt.Println(ticks, grid, alive, name, maxAnts)
}

Line by line

• var ticks int = 10 — the full form. Reading order is name, then type, then value, which is backwards from C and Java and matches the way you say it out loud ("ticks is an int").
• var grid = "512x512" — omit the type and it is inferred.
• var alive bool — omit the value and you get the zero value. For bool that is false; for numbers 0; for strings ""; for pointers, slices, maps, channels, functions and interfaces it is nil. There is no uninitialised memory in Go and no undefined.
• name := "worker-7" — the short declaration operator. It declares and assigns in one step, inferring the type. It only works inside a function, and it requires at least one variable on the left to be new.
• const maxAnts = 50000 — constants are computed at compile time and have no address. An untyped constant like this adapts to the context it is used in, so maxAnts can be used where an int, int64, or float64 is wanted.

func zeroReport() string {
	var n int
	var s string
	var b bool
	var xs []int
	return fmt.Sprintf("%d %q %v %v", n, s, b, xs)
}
// "0 \"\" false []"

2.2 Functions, multiple returns, and defer

The idea

Functions can return more than one value, and this is how Go handles errors: a function returns its result and an error side by side. defer schedules a call to run when the surrounding function returns, no matter how it returns.

func divide(a, b int) (int, error) {
	if b == 0 {
		return 0, fmt.Errorf("divide %d by zero", a)
	}
	return a / b, nil
}

func report(name string) {
	defer fmt.Println("done:", name)   // runs last, whatever happens
	fmt.Println("start:", name)
	if name == "" {
		return                          // the deferred call still runs
	}
	fmt.Println("working:", name)
}

Line by line

• func divide(a, b int) (int, error) — two parameters of the same type share one type annotation. The return types are in parentheses because there are two of them.
• fmt.Errorf(...) — builds an error value with a formatted message. %d substitutes an integer, exactly like printf.
• return 0, nil — you must return a value for every declared return, so the "unused" one gets a zero value. The convention is that when error is non-nil, the other results are meaningless.
• defer fmt.Println(...) — the arguments are evaluated now but the call happens when report returns. Deferred calls run in last-in-first-out order. This is how Go does cleanup: defer file.Close(), defer mu.Unlock(), defer cancel().

func firstAndRest(xs []int) (first int, rest []int, ok bool) {
	if len(xs) == 0 {
		return 0, nil, false
	}
	return xs[0], xs[1:], true
}

func logged(name string, f func()) {
	defer fmt.Println("done:", name)
	fmt.Println("start:", name)
	f()
}

2.3 Control flow: if, for, switch

The idea

Go has one loop keyword, for, which covers every loop shape. if can declare a variable scoped to the statement. switch does not fall through by default.

// classic three-part loop
for i := 0; i < 5; i++ {
	fmt.Println(i)
}

// while loop
n := 10
for n > 0 {
	n--
}

// infinite loop
for {
	break
}

// range over a slice: index and value
ants := []string{"a1", "a2", "a3"}
for i, name := range ants {
	fmt.Println(i, name)
}

// range over an integer (Go 1.22+)
for i := range 3 {
	fmt.Println(i)     // 0 1 2
}

// if with an initialiser: err exists only inside the if/else
if q, err := divide(10, 2); err != nil {
	fmt.Println("failed:", err)
} else {
	fmt.Println("got", q)
}

// switch on a value, no break needed
switch state {
case "searching":
	fmt.Println("looking for food")
case "carrying", "returning":     // multiple values in one case
	fmt.Println("heading home")
default:
	fmt.Println("idle")
}

// switch with no expression: a tidy if/else chain
switch {
case energy < 10:
	fmt.Println("starving")
case energy < 50:
	fmt.Println("hungry")
default:
	fmt.Println("fine")
}

Notes on the pieces

• No parentheses around conditions, and braces are always required even for one-line bodies.
• for i, name := range ants — range yields index and element for slices and arrays, key and value for maps, and values for channels. If you only want the index, write for i := range ants. If you only want the value, write for _, name := range ants, where _ is the blank identifier meaning "discard this".
• if q, err := ...; err != nil — the initialiser before the semicolon runs first, and any variables it declares are scoped to the whole if/else chain. This is the idiomatic way to handle errors without leaking names.
• switch cases do not fall through. If you actually want fallthrough, there is a fallthrough keyword, which is rare.

package main

import (
	"errors"
	"fmt"
)

var ErrEmpty = errors.New("summary: empty slice")

func summary(values []int) (min int, max int, err error) {
	if len(values) == 0 {
		return 0, 0, ErrEmpty
	}
	min, max = values[0], values[0]
	for _, v := range values[1:] {
		if v < min {
			min = v
		}
		if v > max {
			max = v
		}
	}
	return min, max, nil
}

func main() {
	if lo, hi, err := summary([]int{4, 9, 1, 7}); err != nil {
		fmt.Println("error:", err)
	} else {
		fmt.Println("min", lo, "max", hi)
	}

	if _, _, err := summary(nil); err != nil {
		fmt.Println("error:", err)   // error: summary: empty slice
	}
}

2.4 Slices

The idea

A slice is Go's growable list. Under the hood it is a three-word value: a pointer to an underlying array, a length, and a capacity. Understanding that is not optional, because it explains the behaviour that surprises everyone.

positions := []int{10, 20, 30}      // literal, len 3, cap 3
positions = append(positions, 40)   // append returns a NEW slice value
fmt.Println(len(positions), cap(positions))

grid := make([]int, 0, 1000)        // len 0, capacity 1000: no reallocation
                                    // for the first 1000 appends

view := positions[1:3]              // len 2, shares memory with positions
view[0] = 99                        // this modifies positions[1] too!
fmt.Println(positions)              // [10 99 30 40]

Line by line

• []int{10, 20, 30} — a slice literal. []int is the type "slice of int". ([3]int, with a number, is a fixed-size array, which is a different and much less used type.)
• append(positions, 40) — appends and returns the result. If the underlying array has spare capacity it writes in place; if not, it allocates a bigger array and copies. Because it might reallocate, you must use the return value. append(positions, 40) on its own line is a bug that go vet will not always catch.
• make([]int, 0, 1000) — make creates slices, maps, and channels. The arguments are type, length, capacity. Preallocating capacity when you know the size is the single easiest Go performance win, and we will use it for the ant list.
• positions[1:3] — a view, not a copy. It shares the same backing array. Writing through the view is visible through the original. To copy, use copy(dst, src) or slices.Clone.

2.5 Maps

The idea

A hash table with typed keys and values. Reading a missing key gives the zero value rather than an error, and there is a special two-value form to tell "missing" from "present but zero".

pheromone := make(map[string]float64)
pheromone["12,7"] = 0.8

v := pheromone["99,99"]              // 0, no error, no panic
v, ok := pheromone["99,99"]          // v = 0, ok = false

if strength, ok := pheromone["12,7"]; ok {
	fmt.Println("found", strength)
}

delete(pheromone, "12,7")
fmt.Println(len(pheromone))

for cell, strength := range pheromone {   // order is randomised on purpose
	fmt.Println(cell, strength)
}

Notes

• make(map[K]V) creates an empty, usable map. A map declared with var m map[string]int is nil: reading from it is fine and returns zero values, but writing to it panics. This asymmetry catches everyone once.
• The value, ok := m[key] form is called the "comma ok" idiom and appears again with type assertions and channel receives.
• Keys must be comparable: numbers, strings, booleans, pointers, channels, interfaces, and structs or arrays of those. Slices, maps and functions cannot be keys.
• Maps are not safe for concurrent use. Concurrent reads are fine; a concurrent write with anything else causes the runtime to deliberately crash with fatal error: concurrent map writes. That crash is a feature, and you will meet it.

func countByFirstLetter(words []string) map[byte]int {
	counts := make(map[byte]int)
	for _, w := range words {
		if len(w) == 0 {
			continue
		}
		counts[w[0]]++
	}
	return counts
}

func printSorted(counts map[byte]int) {
	keys := make([]byte, 0, len(counts))
	for k := range counts {
		keys = append(keys, k)
	}
	sort.Slice(keys, func(i, j int) bool { return keys[i] < keys[j] })
	for _, k := range keys {
		fmt.Printf("%c: %d\n", k, counts[k])
	}
}

2.6 Structs, pointers, and methods

The idea

A struct is a fixed collection of named fields. A pointer holds the address of a value. A method is a function with a receiver, which is the value it is attached to. Go has no classes and no inheritance.

type Position struct {
	X, Y int
}

type Ant struct {
	ID       int
	Pos      Position
	Energy   int
	Carrying bool
}

// value receiver: operates on a copy
func (a Ant) Describe() string {
	return fmt.Sprintf("ant %d at (%d,%d)", a.ID, a.Pos.X, a.Pos.Y)
}

// pointer receiver: can modify the original
func (a *Ant) Move(dx, dy int) {
	a.Pos.X += dx
	a.Pos.Y += dy
	a.Energy--
}

func main() {
	a := Ant{ID: 1, Pos: Position{X: 5, Y: 5}, Energy: 100}
	a.Move(1, 0)                 // Go automatically takes &a
	fmt.Println(a.Describe())    // ant 1 at (6,5)

	p := &a                      // p is a *Ant
	p.Move(0, 1)                 // no need to write (*p).Move
	fmt.Println(a.Pos)           // {6 6} — the original changed
}

Line by line

• type Ant struct { ... } — declares a new named type. Fields with uppercase names are visible outside the package.
• Ant{ID: 1, Pos: ...} — a composite literal with field names. Always use field names; the positional form breaks when someone adds a field.
• func (a Ant) Describe() string — the part in parentheses before the name is the receiver. Here it is a value, so a is a copy and modifications would be discarded.
• func (a *Ant) Move(...) — a pointer receiver. a points at the original, so the mutation sticks. Note that you write a.Pos.X, not (*a).Pos.X; Go dereferences pointers automatically for field access and method calls.
• a.Move(1, 0) where a is a value and Move needs a pointer — Go inserts &a for you, because a is addressable. This convenience has one important exception: values stored in a map are not addressable, so ants["x"].Move(1,0) will not compile. Store pointers in the map instead.

The rule for choosing a receiver: use a pointer receiver if the method modifies the receiver, or if the struct is large enough that copying it matters, or if any other method on the type needs a pointer. Mixing value and pointer receivers on one type is a smell. For Ant, which we will mutate constantly, everything will be a pointer receiver.

2.7 Interfaces

The idea

An interface is a set of method signatures. A type satisfies an interface simply by having those methods. There is no implements keyword and no declaration of intent, which means you can define an interface after the fact, in the package that consumes it.

type Behaviour interface {
	Decide(a *Ant, w *World) Action
	Name() string
}

type Forager struct{}

func (Forager) Name() string { return "forager" }
func (Forager) Decide(a *Ant, w *World) Action {
	if a.Carrying {
		return Action{Kind: ReturnHome}
	}
	return Action{Kind: SearchFood}
}

// anything with Decide and Name can be passed here
func step(b Behaviour, a *Ant, w *World) {
	act := b.Decide(a, w)
	w.Apply(a, act)
}

Notes

• type Behaviour interface { ... } — just method signatures. Forager never mentions Behaviour, yet satisfies it.
• func (Forager) Name() string — the receiver has no name because the method does not use it. Legal and common for stateless implementations.
• An interface value is two words: the concrete type and a pointer to the data. A nil interface is different from an interface holding a nil pointer, which is a famous Go trap covered in Milestone 3.
• any (an alias for interface{}) is the empty interface, satisfied by everything. Use it rarely.
• To recover the concrete type: f, ok := b.(Forager) is a type assertion, and a switch v := x.(type) is a type switch.

type Grid struct {
	W, H  int
	cells []int
}

func NewGrid(w, h int) *Grid {
	return &Grid{W: w, H: h, cells: make([]int, w*h)}
}

func (g *Grid) inBounds(x, y int) bool {
	return x >= 0 && y >= 0 && x < g.W && y < g.H
}

func (g *Grid) At(x, y int) int {
	if !g.inBounds(x, y) {
		return 0
	}
	return g.cells[y*g.W+x]
}

func (g *Grid) Set(x, y, v int) {
	if !g.inBounds(x, y) {
		return
	}
	g.cells[y*g.W+x] = v
}

2.8 Errors

The idea

An error is a value implementing one method. You return it, you check it, you wrap it with context as it travels up. Go has panics too, but they are for programmer mistakes and truly unrecoverable situations, not for control flow.

// the entire definition, from the standard library:
// type error interface { Error() string }

var ErrNoFood = errors.New("no food available")     // a sentinel error

func (w *World) TakeFood(p Position) (int, error) {
	amount := w.food.At(p.X, p.Y)
	if amount == 0 {
		return 0, fmt.Errorf("take at (%d,%d): %w", p.X, p.Y, ErrNoFood)
	}
	w.food.Set(p.X, p.Y, amount-1)
	return 1, nil
}

func forage(w *World, p Position) {
	got, err := w.TakeFood(p)
	if errors.Is(err, ErrNoFood) {      // unwraps through %w
		// expected: move elsewhere
		return
	}
	if err != nil {
		log.Printf("unexpected: %v", err)
		return
	}
	_ = got
}

// a custom error type, when callers need structured detail
type OutOfBounds struct{ X, Y int }

func (e *OutOfBounds) Error() string {
	return fmt.Sprintf("position (%d,%d) is outside the grid", e.X, e.Y)
}

// retrieving it:
var oob *OutOfBounds
if errors.As(err, &oob) {
	fmt.Println("bad x was", oob.X)
}

Notes

• errors.New creates a simple error. A package-level Err... variable is called a sentinel, and callers compare against it.
• %w in fmt.Errorf wraps: the new error contains the old one, so context accumulates while identity is preserved. Use %v instead if you deliberately want to hide the cause.
• errors.Is(err, target) walks the wrap chain comparing identity. errors.As(err, &target) walks it looking for a specific type. Never compare error strings.
• panic unwinds the stack running deferred functions and then crashes the program, printing a stack trace. recover, called inside a deferred function, stops the unwinding. We will use exactly one recover in the whole project, in Milestone 8, at the top of each ant goroutine, and I will argue about whether that is a good idea.

2.9 Goroutines

The idea

Put go in front of a function call and it runs concurrently. A goroutine is not an operating-system thread; it is a much cheaper thing that the Go runtime multiplexes onto a small pool of threads.

func main() {
	go fmt.Println("from a goroutine")     // may never print!
	fmt.Println("from main")
	time.Sleep(10 * time.Millisecond)      // crude, but proves the point
}

Two facts to absorb immediately:

• When main returns, the program exits, killing every goroutine still running, with no cleanup and no warning. Half of all beginner "my goroutine didn't run" reports are this.
• Goroutine start order is not defined. The runtime schedules them; do not assume anything about ordering without synchronisation.

time.Sleep is never the answer. The real tool for "wait for a group of goroutines" is sync.WaitGroup:

var wg sync.WaitGroup

for i := range 5 {
	wg.Add(1)                    // register one pending goroutine, BEFORE go
	go func() {
		defer wg.Done()          // signal completion, even on panic
		fmt.Println("ant", i, "reporting")
	}()
}

wg.Wait()                        // blocks until the counter reaches zero
fmt.Println("all ants reported")

Notes

• wg.Add(1) must happen before the go statement. If you put it inside the goroutine, Wait can return before the goroutine has even started.
• defer wg.Done() as the first line of the goroutine guarantees the counter is decremented on every exit path.
• The closure captures i. Since Go 1.22 each loop iteration gets its own i, so this prints 0 through 4 in some order. In Go 1.21 and earlier the loop variable was shared and this printed "5" five times, which was the most notorious Go gotcha. Older tutorials pass i as an argument to work around it; that is still correct, just no longer necessary.
• Recent Go versions add wg.Go(func(){ ... }), which does the Add and Done for you. If your compiler rejects it, your version is older; the classic form above always works.

Traditional threads                 Goroutines
───────────────────                 ──────────
~1-8 MB stack reserved each         ~2 KB stack, grows on demand
created by the OS, expensive        created by the runtime, ~1µs
scheduled by the OS kernel          scheduled by the Go runtime onto
                                      GOMAXPROCS OS threads
blocking syscall blocks a thread    runtime moves other goroutines to
                                      another thread automatically
10,000 is a lot                     1,000,000 is fine
you coordinate with locks           you coordinate with channels
                                      (locks also available)

var counter atomic.Int64
var wg sync.WaitGroup

for i := 0; i < 10; i++ {
	wg.Add(1)
	go func() {
		defer wg.Done()
		for j := 0; j < 1000; j++ {
			counter.Add(1)
		}
	}()
}

wg.Wait()
fmt.Println(counter.Load())   // always 10000

2.10 Channels

The idea

A channel is a typed pipe that also synchronises. One goroutine sends, another receives, and the channel handles the handover safely. The slogan is: do not communicate by sharing memory; share memory by communicating.

ch := make(chan int)            // unbuffered
buf := make(chan int, 100)      // buffered, holds 100 before blocking

go func() {
	ch <- 42                    // send: blocks until someone receives
}()

v := <-ch                       // receive: blocks until someone sends
fmt.Println(v)                  // 42

close(ch)                       // no more values will be sent
v, ok := <-ch                   // ok is false once drained and closed

// range over a channel until it is closed
results := make(chan string, 3)
go func() {
	defer close(results)        // the sender closes, always
	results <- "found food"
	results <- "laid pheromone"
}()
for msg := range results {
	fmt.Println(msg)
}

Semantics you must know

• Unbuffered channels are a rendezvous. The send does not complete until a receiver takes the value. That makes an unbuffered send a synchronisation point between two goroutines, which is often what you want for correctness and sometimes a performance problem.
• Buffered channels decouple sender and receiver up to the buffer size. The buffer size is a policy decision about how much lag you tolerate, and in Milestone 11 it becomes our backpressure knob.
• Closing is a broadcast. Every receiver sees it. That makes a closed channel the standard "everyone stop now" signal, which is exactly how context works internally.
• Only the sender closes, and only when there is exactly one sender, otherwise you risk the "send on closed channel" panic. With multiple senders, use a separate done channel or a WaitGroup.
• Channel direction can be part of a type: func consume(in <-chan int) accepts a receive-only channel and func produce(out chan<- int) a send-only one. The arrow points the way data flows. Use these in signatures; they document intent and the compiler enforces it.

func sum(nums []int) int {
	const chunkSize = 4
	partial := make(chan int, (len(nums)+chunkSize-1)/chunkSize)

	chunks := 0
	for i := 0; i < len(nums); i += chunkSize {
		end := min(i+chunkSize, len(nums))
		chunks++
		go func(chunk []int) {
			s := 0
			for _, v := range chunk {
				s += v
			}
			partial <- s
		}(nums[i:end])
	}

	total := 0
	for i := 0; i < chunks; i++ {
		total += <-partial
	}
	return total
}

2.11 select

The idea

select waits on several channel operations at once and proceeds with whichever is ready. It is the control structure that makes channels composable.

func worker(jobs <-chan int, done <-chan struct{}) {
	timeout := time.After(5 * time.Second)

	for {
		select {
		case job, ok := <-jobs:
			if !ok {
				fmt.Println("jobs channel closed")
				return
			}
			fmt.Println("working on", job)

		case <-done:
			fmt.Println("asked to stop")
			return

		case <-timeout:
			fmt.Println("took too long")
			return
		}
	}
}

// non-blocking variants
select {
case v := <-ch:
	fmt.Println("got", v)
default:
	fmt.Println("nothing waiting")     // never blocks
}

select {
case out <- value:
	// sent
default:
	// receiver is busy: drop the value rather than block.
	// This is load shedding, and it is a real strategy.
}

Notes

• If several cases are ready, select picks one at random, which prevents starvation.
• With no default, select blocks until some case is ready. With a default, it never blocks.
• chan struct{} is the idiomatic "signal only, no data" channel; an empty struct occupies zero bytes.
• time.After(d) returns a channel that delivers a value after d. Convenient, but it allocates a timer each time through a hot loop, so in performance-sensitive loops use time.NewTimer and reset it.
• A nil channel in a select case blocks forever, so setting a channel variable to nil is how you dynamically disable a case. This trick appears in Milestone 11.

func firstOf(a, b <-chan int) int {
	select {
	case v := <-a:
		return v
	case v := <-b:
		return v
	}
}

2.12 Mutexes and atomics

The idea

Channels are not always the right answer. When several goroutines genuinely need to read and write one piece of shared state, a mutex is simpler and faster. Go provides both and expects you to choose.

type Counters struct {
	mu       sync.Mutex
	delivered int
	byAnt    map[int]int
}

func (c *Counters) Record(antID int) {
	c.mu.Lock()
	defer c.mu.Unlock()
	c.delivered++
	c.byAnt[antID]++
}

// for a single number, an atomic is cheaper than a mutex
var ticks atomic.Int64

func tick() {
	ticks.Add(1)
}

func report() int64 {
	return ticks.Load()
}

Notes

• The zero value of sync.Mutex is an unlocked mutex, so no initialisation is needed. Put it next to the data it protects, and add a comment saying what it protects.
• defer c.mu.Unlock() immediately after Lock is the safe habit. It costs a few nanoseconds and eliminates a class of bug.
• Never copy a struct containing a mutex after first use. go vet catches this and it is a genuine bug: the copy has its own independent lock. This is why methods on mutex-containing types take pointer receivers.
• sync.RWMutex allows many concurrent readers or one writer. It is slower than Mutex under write-heavy load, so measure before assuming it helps.
• atomic.Int64, atomic.Bool and friends are lock-free and appropriate for counters and flags, but they do not compose: two atomic operations are not one atomic operation.

type Counters struct {
	mu        sync.Mutex
	delivered int
	byAnt     map[int]int
	Errors    int
}

func (c *Counters) IncError() {
	c.mu.Lock()
	defer c.mu.Unlock()
	c.Errors++
}

func (c *Counters) RecordUnsafe(antID int) {
	c.mu.Lock()
	c.delivered++
	c.byAnt[antID]++
	c.mu.Unlock()
}

2.13 context

The idea

context.Context carries a cancellation signal and a deadline down through a call tree. Every long-running operation in modern Go accepts one as its first parameter. It is the standard answer to "how do I stop 50,000 goroutines at once".

func run(ctx context.Context, id int) error {
	ticker := time.NewTicker(100 * time.Millisecond)
	defer ticker.Stop()

	for {
		select {
		case <-ctx.Done():                  // closed when cancelled
			return ctx.Err()                // context.Canceled or DeadlineExceeded
		case <-ticker.C:
			// do one unit of work
		}
	}
}

func main() {
	ctx, cancel := context.WithCancel(context.Background())
	defer cancel()                          // always; releases resources

	for i := range 1000 {
		go run(ctx, i)
	}

	time.Sleep(time.Second)
	cancel()                                // all 1000 goroutines see this
}

Notes

• context.Background() is the empty root context, created in main. context.TODO() is the same thing with a note to yourself.
• WithCancel, WithTimeout, and WithDeadline derive children. Cancelling a parent cancels every descendant. That tree structure is why one cancel() can stop a whole subsystem.
• ctx.Done() returns a channel that is closed on cancellation. Closing is a broadcast, which is how one call reaches thousands of waiters instantly.
• Always defer cancel(), even for a timeout context that will expire on its own, or you leak a timer and a goroutine.
• Pass context as the first argument, named ctx. Do not store it in a struct. Do not pass nil.
• Cancellation is cooperative. A goroutine in a tight computational loop that never checks ctx.Done() will not stop. Go cannot kill a goroutine, and there is no equivalent of Erlang's exit(Pid, kill). This limitation shapes Milestone 8.

func afterN(ctx context.Context, n int, work func()) error {
	for i := 0; i < n; i++ {
		select {
		case <-ctx.Done():
			return ctx.Err()
		default:
		}
		work()
		if i < n-1 {
			select {
			case <-ctx.Done():
				return ctx.Err()
			case <-time.After(10 * time.Millisecond):
			}
		}
	}
	return nil
}

2.14 Testing

The idea

Testing is in the standard library and requires no dependencies. A test is a function named TestXxx taking *testing.T, in a file ending _test.go, in the same package as the code.

internal/world/grid.go with tests in internal/world/grid_test.go:

package world

import "testing"

func TestGridSetAndAt(t *testing.T) {
	g := NewGrid(4, 3)
	g.Set(2, 1, 7)

	if got := g.At(2, 1); got != 7 {
		t.Errorf("At(2,1) = %d, want 7", got)
	}
}

// table-driven tests: the dominant Go style
func TestGridBounds(t *testing.T) {
	g := NewGrid(4, 3)

	cases := []struct {
		name string
		x, y int
		want int
	}{
		{"inside", 0, 0, 0},
		{"negative x", -1, 0, 0},
		{"beyond width", 4, 0, 0},
		{"beyond height", 0, 3, 0},
	}

	for _, tc := range cases {
		t.Run(tc.name, func(t *testing.T) {
			if got := g.At(tc.x, tc.y); got != tc.want {
				t.Errorf("At(%d,%d) = %d, want %d", tc.x, tc.y, got, tc.want)
			}
		})
	}
}

go test ./...              # everything
go test -v ./internal/world # verbose, one line per test
go test -run TestGridBounds/negative ./internal/world   # one subtest
go test -race ./...        # with the race detector (slower, essential)
go test -cover ./...       # coverage percentage
go test -bench=. ./...     # run benchmarks

Notes

• t.Errorf records a failure and continues; t.Fatalf records and stops that test immediately. Use Fatalf when continuing would panic.
• The message convention is got X, want Y. Follow it; every Go reviewer expects it.
• t.Run creates subtests with their own names, which makes failures pinpoint-able and lets you run one case.
• Tests in package world can see unexported identifiers. A file declaring package world_test sees only the public API, which is a useful way to test that your API is usable.
• There is no built-in assertion library and none is expected. If you want one, testify is common, but plain if statements are the default and are fine.

package main

import (
	"context"
	"fmt"
	"math/rand"
	"sync"
	"time"
)

type Report struct {
	AntID int
	Found bool
}

func ant(ctx context.Context, id int, out chan<- Report) {
	ticker := time.NewTicker(50 * time.Millisecond)
	defer ticker.Stop()

	for {
		select {
		case <-ctx.Done():
			return
		case <-ticker.C:
			r := Report{AntID: id, Found: rand.IntN(4) == 0}
			select {
			case out <- r:            // delivered
			case <-ctx.Done():        // cancelled while waiting to send
				return
			default:                  // collector is behind: drop it
			}
		}
	}
}

func main() {
	ctx, cancel := context.WithCancel(context.Background())
	defer cancel()

	out := make(chan Report, 1024)

	var wg sync.WaitGroup
	for i := range 100 {
		wg.Add(1)
		go func() {
			defer wg.Done()
			ant(ctx, i, out)
		}()
	}

	// close out only after every sender has returned
	go func() {
		wg.Wait()
		close(out)
	}()

	var total, finds int
	done := time.After(500 * time.Millisecond)

collect:
	for {
		select {
		case r, ok := <-out:
			if !ok {
				break collect
			}
			total++
			if r.Found {
				finds++
			}
		case <-done:
			cancel()          // tell the ants to stop; keep draining
		}
	}

	fmt.Printf("reports=%d finds=%d\n", total, finds)
}

Part 2 checkpoint

1. Why does append return a value instead of modifying in place?
2. You have var m map[string]int. Which of reading, writing, and len works?
3. What is the difference between a nil channel and a closed channel when used in a select?
4. Why must wg.Add be called before go rather than inside the goroutine?
5. A function takes ctx context.Context but runs a tight arithmetic loop for ten seconds. Does cancel() stop it? Why not?
6. Your struct has some methods with value receivers and some with pointer receivers. Name one concrete problem this causes.
7. What is the difference between errors.Is and errors.As, and when does == on errors fail?

NextWhere we go from here

The next instalment starts building. Milestone 1 creates the module properly, defines World, Grid and Ant, and runs a single ant through a deterministic tick loop with a seeded random source, a command-line flag or two, and the first real tests. It is intentionally not concurrent, because the whole point of Milestone 4 is to break it.

Before then, two things worth doing:

1. Finish exercise 2.C and run it under -race. If you have not seen race detector output yet, deliberately introduce a shared counter incremented by all 100 goroutines without synchronisation, and read what it tells you.
2. Create the antfarm module and commit the empty skeleton. Milestone 1 assumes it exists.