Running Two at Once

Goroutine tick loop

worldd does one thing, finishes, and exits, which is a fine description of a batch job and a poor one for a server. The rule for making it a server is narrow: the tick loop runs on its own goroutine, and main reaches it only through a channel.

Two chapters ago the server grew a heartbeat, and one chapter ago it grew a memory: a fixed tick advancing the world in equal steps, and one JSON line appended to world.jsonl the moment anything happened.

Both of them ended up in the same place. The loop sits inside main, counting up to a fixed number of ticks, and while it runs there is no other code in this program.

A world that never resets cannot be a batch job. It has to keep ticking while something else is going on: drawing a frame, accepting a request, or noticing a Ctrl-C.

Chapter 8 already made the log durable, so the orderly-stop rule is not about rescuing lost bytes. An orderly stop means the world's last recorded event belongs to a tick that finished.

The log file is closed by the code that was writing to it, not abandoned by a dying process. When main prints its final report, the numbers in it describe a world that has actually stopped moving.

Not a shared variable. Not a flag one side writes and the other side reads. A channel, for a reason the end of this chapter proves with a tool instead of asserting.

The go keyword

Go spells concurrent work with a single keyword. Write go f(x) and Go calls f with x without waiting for it to return. The argument is evaluated right away, in the goroutine doing the calling; the body runs somewhere else, whenever the runtime gets to it. The statement produces no value at all, because by the time there could be one the caller has moved on to its next line.

A goroutine is not an operating-system thread. The Go runtime keeps a small pool of threads and multiplexes goroutines onto them, and each goroutine starts with a stack of a few kilobytes that grows when it needs to, so starting one costs closer to a function call than to a thread. A server can hold thousands. Today the world needs exactly one.

// cmd/worldd/main.go — chapter 8's setup, then chapter 7's loop with
// one new word in front of it
	w := sim.NewWorld(sim.Generate(12, 8, seed), seed)
	w.Record(lg)
	// ... the shrub and two walkers spawn here, as they did last chapter ...

	go func() {
		ticker := time.NewTicker(sim.TickDuration)
		defer ticker.Stop()
		for range ticker.C {
			must(w.Step())
			must(w.Faulted())
		}
	}()

	fmt.Println("worldd", version, "seed", seed, "ticking")
}

$ go run ./cmd/worldd
worldd 0.0.1 seed 5 ticking

$ cat world.jsonl
{"t":0,"ev":"start","what":"seed 5"}
{"t":0,"ev":"spawn","id":1,"to":{"x":2,"y":5},"what":"shrub"}
{"t":0,"ev":"spawn","id":2,"to":{"x":10,"y":6},"what":"walker"}
{"t":0,"ev":"spawn","id":3,"to":{"x":2,"y":2},"what":"walker"}

The bill for concurrency arrives with the very first goroutine. main needs a reason to stay alive while the world ticks, a way to tell the loop to stop, and proof that the loop finished stopping. One mechanism covers the bill.

make, close and select

A channel is a typed pipe between goroutines, built with make(chan T), and one rule does most of the work: a receive blocks until a value is there, and a send on an unbuffered channel blocks until somebody receives it. Blocking sounds like a cost and is really the coordination. A goroutine parked on a receive burns no CPU, holds no lock, and wakes the moment a value lands.

Closing supplies the second property. close(ch) announces that no value will ever be sent on it again, and from then on every receive returns instantly, forever, with the zero value of the channel's type. One close reaches every receiver and none of them have to be counted, so a shutdown channel is normally closed and never sent on. The third piece is select, which waits on several channels at once and runs the branch belonging to whichever becomes ready first; if two are ready together it picks between them at random. Those three ideas are the whole concurrency vocabulary this volume needs.

// internal/sim/loop.go
package sim

import "time"

// Run ticks the world at the fixed rate until stop is closed. However
// this loop ends, it closes the event log on its way out.
func Run(w *World, lg *Log, stop <-chan struct{}) error {
	ticker := time.NewTicker(TickDuration)
	defer ticker.Stop()

	for {
		select {
		case <-stop:
			return lg.Close()
		case <-ticker.C:
			if err := w.Step(); err != nil {
				lg.Close()
				return err
			}
			if err := w.Faulted(); err != nil {
				lg.Close()
				return err
			}
		}
	}
}

// cmd/worldd/main.go — main starts the world, then goes back to its own job
	stop := make(chan struct{})
	done := make(chan error)

	go func() {
		done <- sim.Run(w, lg, stop)
	}()

	fmt.Println("worldd", version, "seed", seed, "ticking at", sim.TickRate, "Hz; ^C to stop")

	sigs := make(chan os.Signal, 1)
	signal.Notify(sigs, os.Interrupt)
	<-sigs
	fmt.Println("\nstop requested")
	close(stop)
	must(<-done)

	fmt.Print(w.Render())
	fmt.Println("ticks:", w.Tick(), " events written:", lg.Count())

$ go run ./cmd/worldd
worldd 0.0.1 seed 5 ticking at 10 Hz; ^C to stop
^C
stop requested
#@##########
#..........#
#...~......#
#.~~~~~....#
#.~~~~~~.@.#
#.o.~~~~...#
#...~......#
############
ticks: 40  events written: 77

77 lines at tick 40

Those last two printed lines are a claim about a file, so check them against the file. main said the world reached tick 40 and the log accepted 77 events.

$ wc -l world.jsonl
77 world.jsonl

$ tail -1 world.jsonl
{"t":40,"ev":"move","id":3,"from":{"x":0,"y":0},"to":{"x":1,"y":0}}

Trace the chain once: every link in it is a channel operation waiting on the link before. close(stop) makes the stop branch ready. The loop's next trip through select takes that branch, so it is never mid-tick when it leaves, and calls lg.Close(). Run returns whatever that reported. done <- err blocks until main receives, and main has been sitting at <-done waiting for it. Only then does main render the map, read the counters, and return, ending the process. Nothing overlaps, and nothing had to be timed.

Delete the <-done and the printed report becomes fiction of a specific kind: main would be reading terrain and entity positions out of a world that is still being stepped by another goroutine, and the map it drew might show a walker in a cell the log never recorded it entering. Exercise 3 makes the tool say so out loud. The shutdown signal alone was never the point; the acknowledgement is.

Channel ordering

A channel operation does two jobs, and the second one is invisible in the code. The obvious job is delivery: a value, or the news that a channel is closed, moves from one goroutine to another. The quiet job is ordering. Go's memory model guarantees that everything a goroutine did before it sent on a channel is visible to the goroutine that receives, once the receive completes. The send and the matching receive are one event both goroutines agree on, and it cuts time into a before and an after.

That guarantee is the whole reason main can call w.Render() straight after <-done with no lock in sight. The tick loop moved the walkers, appended their lines, closed the file, and then sent on done; main read the world after receiving. Same memory, two goroutines, no race, because a channel stands between the writing and the reading.

Take that event away and two goroutines touching the same variable is a data race, which is a worse thing than an occasional stale value. A compiler with no reason to expect another goroutine may load a variable into a register once and reuse it for the rest of a loop; processors reorder loads and stores for their own reasons; and Go's memory model declines to define what a racing program does at all. "It printed the right answer" is not evidence of correctness under those terms, only evidence that the luck held for one run.

// cmd/worldd/main.go — the stop a boolean seemed able to serve
var stopped bool

func main() {
	// ... the same log, the same world, the same three entities ...

	done := make(chan error)
	go func() {
		ticker := time.NewTicker(sim.TickDuration)
		defer ticker.Stop()
		for range ticker.C {
			if stopped {
				done <- lg.Close()
				return
			}
			must(w.Step())
		}
	}()

	// ... wait for Ctrl-C, then raise the flag ...
	<-sigs
	fmt.Println("\nstop requested")
	stopped = true
	must(<-done)

	fmt.Println("ticks:", w.Tick(), " events written:", lg.Count())
}

$ go run -race ./cmd/worldd
worldd 0.0.1 seed 5 ticking at 10 Hz; ^C to stop
^C
stop requested
==================
WARNING: DATA RACE
Read at 0x0000006a8448 by goroutine 8:
  main.main.func1()
      /home/you/theworld/cmd/worldd/main.go:38 +0x130

Previous write at 0x0000006a8448 by main goroutine:
  main.main()
      /home/you/theworld/cmd/worldd/main.go:52 +0x7ec

Goroutine 8 (running) created at:
  main.main()
      /home/you/theworld/cmd/worldd/main.go:34 +0x524
==================
ticks: 38  events written: 72
Found 1 data race(s)
exit status 66

Checkpoint

$ go run -race ./cmd/worldd
WARNING: DATA RACE
Read at 0x00c0000201f8 by main goroutine:
  theworld/internal/sim.(*World).Render()
      /home/you/theworld/internal/sim/world.go:110 +0x11b
  main.main()
      /home/you/theworld/cmd/worldd/main.go:44 +0x7b7

Previous write at 0x00c0000201f8 by goroutine 8:
  theworld/internal/sim.(*World).Move()
      /home/you/theworld/internal/sim/world.go:82 +0x290
  theworld/internal/sim.(*World).driftWalkers()
      /home/you/theworld/internal/sim/tick.go:75 +0x1ac