Runtime Source — Specification¶

1. There is no spec; the source is the spec¶

The Go runtime — the body of code in src/runtime/ that implements goroutines, channels, the scheduler, the garbage collector, the memory allocator, panic/recover, defer, the timer wheel, finalizers, signal handling, and the cgo bridge — has no separate specification document. Unlike the Go language, which is pinned by The Go Programming Language Specification (https://go.dev/ref/spec), the runtime's internal behaviour is not formally specified anywhere. The source code itself is the authoritative reference, and the behaviour it exhibits at any given release is what the runtime is at that release.

This is deliberate. The Go team has consistently refused to write a runtime specification because doing so would commit them to implementation choices that they want to revisit. The garbage collector was rewritten twice between 1.5 and 1.8; the scheduler grew async preemption in 1.14; the timer subsystem was sharded per-P in 1.21; maps were rebuilt on top of Swiss tables in 1.24. None of these changes broke a published specification because no specification existed to break.

What does exist is a network of constraining documents — the language spec, the memory model, the Go 1 compatibility promise, the public runtime package godoc, the proposal archive, and a handful of design documents in the golang/go wiki and the go/design directory. Together these constrain what the runtime is allowed to do without constituting a specification of how it does it. A senior reader of the runtime source learns to navigate this network as fluently as the source itself.

The practical consequence: when source reading produces a question of the form "is this behaviour guaranteed?", the answer is found in the language spec or the memory model, not in the runtime source. When the question is "how does this implementation work today?", only the source answers, and the answer may be different in the next release.

The Go team has stated this position explicitly. In the 2018 "Toward Go 2" articulation (https://go.dev/blog/toward-go2) and in periodic responses on the issue tracker, runtime maintainers reject requests to specify scheduler timing, GC pause guarantees, channel performance characteristics, or map iteration costs. The refusal is principled — committing to a specification freezes the implementation — and pragmatic — past commitments (the panic(nil) behaviour before 1.21, the goroutine stack starting size before 1.4) have all become drags on later improvements.

2. Language spec sections that bind the runtime¶

The Go language specification (https://go.dev/ref/spec) does not describe the runtime, but several sections describe behaviour that the runtime must implement. These are the contract surface between language and runtime:

Each of these is a contract the runtime must satisfy. The implementation in chan.go, panic.go, map.go, proc.go is free to change as long as it continues to satisfy the spec's surface behaviour.

The spec deliberately under-specifies. Map iteration order is "not specified and is not guaranteed to be the same from one iteration to the next" — the runtime exploits this by introducing entropy at iteration start so that programs which accidentally depend on order fail loudly. Select's "uniform pseudo-random selection" is a runtime implementation choice that the spec elevated to a guarantee in Go 1.0 and has held ever since.

Two cases worth reading carefully:

• init ordering. The spec mandates that imported package inits run before the importer's inits, that multiple inits within a package run in source-file order (and within a file, in declaration order), and that all inits complete before main. The runtime executes these on a single goroutine (runtime.main in proc.go) before user code starts; the ordering is verified by the linker, not the runtime, but the runtime is responsible for making the linker-emitted init list run in a sequence consistent with the spec. Cross-package init ordering changes between releases when import graphs change, but the rules above hold.
• Defer semantics under panic. The spec promises that deferred functions run during panic unwinding in LIFO order, that a deferred call to recover stops the panic and returns the panic value, and that recover outside a deferred function returns nil. The runtime implements this in panic.go (gopanic, gorecover); the implementation has been rewritten three times (open-coded defers in 1.14, defer ranking changes in 1.18, runtime defer record reuse) without changing the observable semantics.

3. The Go memory model¶

The Go memory model (https://go.dev/ref/mem) is the second constraining document. It defines the happens-before relation across goroutines and pins the synchronization guarantees that the runtime must provide:

The runtime's job is to make these guarantees true at the machine level — write barriers, atomic instructions, memory fences on weakly-ordered architectures (ARM64, RISC-V, PPC64) — without breaking them when adding optimizations. Every change to the scheduler or GC is reviewed against the memory model. The hybrid write barrier (1.8) and the per-P run queue (since 1.1) were designed to preserve happens-before while reducing synchronization cost.

The 2022 revision of the memory model (https://go.dev/blog/compatibility) added explicit guarantees for sync/atomic package operations and a "no thin-air values" rule, codifying behaviour the runtime had already provided informally.

The memory model is intentionally weak in places the runtime exploits:

• Reads and writes of single machine-word values are not guaranteed to be atomic in the absence of explicit sync/atomic use; the runtime assumes torn reads are possible and uses atomics or locks where atomicity matters.
• The goroutine that calls os.Exit may not run any deferred functions and may interleave arbitrarily with other goroutines' final operations; the runtime treats process exit as a hard cut rather than a synchronization point.
• The memory model does not specify when a finalizer runs, only that it runs at some point after the object becomes unreachable; the runtime is therefore free to delay, batch, or skip finalizers (the last under runtime.SetFinalizer(obj, nil) cancellation, never silently).

4. The Go 1 compatibility promise¶

The Go 1 compatibility document (https://go.dev/doc/go1compat) is the third constraining document. It states that Go programs that compile against the Go 1 specification will continue to compile and run correctly across future Go 1.x releases, with limited exceptions for security fixes and bugs.

For the runtime, the compatibility promise has two halves:

This split is the practical license for the runtime team to rewrite internals at will. The exported surface — roughly forty functions and a handful of types in runtime/runtime.go, runtime/debug/, and runtime/pprof/ — is the contract. Everything under those signatures is implementation, and the implementation has changed dramatically across releases without breaking a single program that stayed within the contract.

Programs that used //go:linkname to call unexported runtime functions, or that relied on goroutine stack growth being exactly 8 KB, or that assumed map iteration order was deterministic, are explicitly outside the promise. The 1.24 linkname restriction (see section 6) tightened the boundary further.

Practical reading of the promise:

• A library that calls runtime.NumGoroutine will work in every Go 1.x release; the function name, signature, and documented contract are stable.
• A library that reads unsafe.Sizeof(runtime.G{}) (via linkname shenanigans) is outside the promise and broke when g grew a new field in 1.14, 1.18, 1.21, and 1.24.
• A program that depends on a tight loop blocking GC indefinitely worked through Go 1.13 and broke in 1.14 when async preemption shipped. The "break" was not a compatibility violation because the program was depending on absence of preemption, which the spec never guaranteed.

5. The runtime package public docs¶

The godoc for the runtime package (https://pkg.go.dev/runtime) is the closest thing to a runtime specification that exists. It documents the exported API — what each function does, what its guarantees are, what side effects to expect.

Notable documented contracts:

The godoc for runtime/debug (SetGCPercent, SetMemoryLimit, FreeOSMemory, Stack) and runtime/pprof (StartCPUProfile, WriteHeapProfile) extends this contract surface. Everything in these packages is covered by the Go 1 promise; the internal helpers in runtime/internal/ and unexported identifiers in runtime are not.

A nuance worth flagging: several documented contracts in runtime are aspirational — they describe what callers should expect, not what the runtime literally guarantees. runtime.SetFinalizer documents that "the finalizer is scheduled to run at some arbitrary time after the program can no longer reach the object"; the word "arbitrary" is the runtime's reserved right to never run the finalizer at all if the program exits first. Programs that treat finalizers as a resource-cleanup mechanism are misreading the contract; finalizers are best-effort, not deterministic.

Similarly, runtime.GC is documented to run "a garbage collection". It does not promise that the collection is fully concurrent, that pauses will be below any specific bound, or that the heap will shrink afterwards. A program that calls runtime.GC and then asserts that memory usage dropped is depending on implementation, not contract.

6. The five important //go: pragmas¶

The runtime source uses compiler pragmas to control code generation. Understanding the five most-used pragmas is required to read the source without misreading it:

Other pragmas seen in the source: //go:noinline, //go:noescape, //go:norace, //go:nocheckptr, //go:uintptrescapes. Each has a precise effect on code generation; the runtime uses them deliberately and any reader who treats them as decoration will misread the surrounding code.

The 1.23 release added the //go:linkname restriction proposal (https://go.dev/issue/67401), which limits which packages may link to runtime internals. The runtime team retains the right to rename or remove unexported symbols; the explicit allowlist documents the dependency.

Reading pragma-heavy code requires holding two models at once: what the function does at the Go level, and what the pragma forbids the compiler from doing around the call. A //go:nosplit function calling another //go:nosplit function is fine; calling a normal Go function from a //go:nosplit context risks a stack overflow that the compiler will not catch beyond a small budget (StackLimit, currently 800 bytes). The runtime's CI includes a nosplit analyzer that walks call graphs to enforce this; readers should trust it but understand the rule.

7. The "internals can change" rule, with examples¶

The runtime team exercises the "internals are not stable" provision of the compatibility promise regularly. Each of these changes rewrote core runtime structures without breaking the published API:

Each rewrite passed the compatibility test because the published behaviour — m[k] returns the right value, <-ch blocks correctly, defer runs in LIFO order — was preserved. Tools that scraped goroutine stack dumps, profilers that hardcoded offsets into runtime structures, and debuggers that read mspan fields directly all had to be updated. Programs that stayed inside the public API did not.

The reading consequence: a source file checked out at master may differ substantially from the same file at the most recent release tag. A senior reader always notes the Go version when citing runtime behaviour. "The scheduler does X" is meaningless without "as of Go 1.23"; the next release may do Y. The go version of the toolchain and the source tag of the standard library are the same thing, but only at release boundaries — between releases, master diverges from any tagged version.

8. Authoritative source files map¶

The runtime source lives in src/runtime/ of the Go repository (https://github.com/golang/go/tree/master/src/runtime). The files a senior reader returns to repeatedly:

A first-pass reading touches runtime2.go, then proc.go, then chan.go and panic.go. A second pass goes through the GC stack (mgc.go, mgcmark.go, mgcpacer.go, mbarrier.go). A third pass covers the allocator (malloc.go, mheap.go, mcache.go).

Supporting files less central but worth knowing:

The pre-1.24 map files are still in the tree for legacy build-tags and serve as a study in how a runtime subsystem ages out of relevance gradually.

9. GODEBUG knobs for runtime reading¶

GODEBUG is the environment variable that toggles runtime instrumentation and behavioural switches. The reading-relevant settings:

The full table lives at https://pkg.go.dev/runtime#hdr-Environment_Variables. New knobs are added per release; the GODEBUG history file src/runtime/HACKING.md and the release notes track them.

Two structural points about GODEBUG worth knowing while reading the source:

• Each setting is parsed once at program start by parsedebugvars in runtime1.go; runtime code reads the resulting struct (debug.gctrace, debug.schedtrace) rather than re-parsing the environment. Adding a new knob means adding a field to that struct.
• Since 1.21, GODEBUG also gates behavioural defaults that change between releases. A program built with Go 1.21 honours panicnil=1 (restoring old behaviour); a program built with Go 1.20 ignores it because the new behaviour does not exist there. The go.mod go directive influences which defaults apply, via runtime/internal/godebug.

10. Environment variables¶

The runtime reads a small set of environment variables at process startup:

Beyond these, cgo adds CGO_* variables, and the linker honours GOFLAGS and GO_LDSO. The runtime proper reads only the seven above.

Reading the env-var parsing in runtime/proc.go (schedinit and friends) is short and instructive: the runtime calls gogetenv (its own copy of os.Getenv that does not allocate) at startup, parses each known variable, applies bounds, and stores the result in package-level globals. Any later read by runtime code goes to the global, not the environment. Setting GOGC after startup via os.Setenv has no effect; the supported path is debug.SetGCPercent.

11. Notable proposals as architecture-shaping changes¶

The proposal archive (https://github.com/golang/proposal) is the design record of major runtime changes. The proposals every runtime reader should know:

Each proposal contains the design rationale, the rejected alternatives, and the implementation plan. Reading the proposal for a feature before reading the code that implements it cuts source-reading time roughly in half because the proposal explains why the chosen shape exists.

The proposal archive is also where one finds the design documents that the runtime team treats as more durable than the code. design/17503-eliminate-rescan.md (the hybrid write barrier) and design/24543-non-cooperative-preemption.md (async preemption) are detailed enough to substitute for a textbook chapter on their respective subsystems. The corresponding source files in src/runtime/ are the implementation of these documents; reading them in the reverse order — code first, design after — works, but takes longer and risks confusing implementation choices for fundamental design.

12. Source code conventions¶

The runtime source has internal conventions that differ from idiomatic application Go. A reader who applies application-level expectations will misread the code:

The runtime's HACKING.md (https://github.com/golang/go/blob/master/src/runtime/HACKING.md) documents many of these conventions explicitly and should be read once end-to-end before any sustained source dive.

A consequence worth internalising: most runtime functions are not meant to be called from arbitrary contexts. They expect to be on a specific stack (g0 or a user goroutine), to be running with a specific M state (spinning, idle, syscall), or to be invoked only while holding a specific lock (sched.lock, mheap_.lock). The function's preconditions are documented in the comment above the function, sometimes in a // runtime/HACKING.md cross-reference, sometimes only in the precondition asserted by a throw inside the function body. A reader who skips comments will misread the code; the comments are not decoration but the contract that the body assumes.

13. Reading order recommendation¶

A senior path through the runtime source, in ten steps:

1. Read HACKING.md once. Conventions, state machine vocabulary, the meaning of getg, acquirem, systemstack. https://github.com/golang/go/blob/master/src/runtime/HACKING.md
2. Read runtime2.go cover to cover. Get the data model in your head: g, m, p, sudog, stack, the state enums.
3. Read proc.go's schedule, findrunnable, execute, park_m, goready. This is the scheduler's hot loop.
4. Read chan.go. A small, complete subsystem; chansend, chanrecv, closechan, the sudog-queue dance. Excellent first deep dive.
5. Read panic.go. gopanic, gorecover, defer chain walking, runtime.Goexit.
6. Read the GC entry points. mgc.go gcStart and the phase transitions; mgcpacer.go to understand the trigger.
7. Read the allocator fast path. malloc.go mallocgc; trace one allocation from the mcache through to mheap.
8. Read time.go (with 1.21+ per-P heaps). Smaller than the scheduler, larger than channels; teaches how the runtime composes lock-free per-P state with a global fallback.
9. Read signal_unix.go plus asm_*.s preemption paths. The hardest material; understand how SIGURG becomes a goroutine state transition.
10. Read one cgo path end-to-end. cgocall.go plus the generated _cgo_gotypes.go; this is the boundary between runtime and external code and exercises every previous chapter.

After step 10, the rest of the runtime is variations on themes already encountered.

Two reading aids that pay back tenfold their setup cost:

• Build a local Go tree and tag-switch. git clone https://github.com/golang/go && cd go && git checkout go1.20.14; then compare proc.go against master. Diffing two releases of the same file is the fastest way to learn what changed and why.
• Wire up dlv against a tiny program. A six-line program that creates a goroutine and waits, stepped through under Delve with runtime.* breakpoints, makes the GMP transitions concrete in a way that source alone cannot. The runtime package is optimize=false aware; go build -gcflags 'all=-N -l' makes runtime frames visible to the debugger.

14. Bug reporting and the proposal process¶

Runtime issues are reported at https://github.com/golang/go/issues with the runtime label. The triage workflow:

Behaviour changes — adding a GODEBUG setting, changing default GOGC, modifying scheduler heuristics that affect observable timing — typically require a proposal. The proposal process is documented at https://github.com/golang/proposal/blob/master/README.md:

1. File an issue under the Proposal label with a short problem statement.
2. The proposal review committee (a rotating subset of the Go team) triages weekly; minutes appear in https://github.com/golang/go/issues with the proposal-minutes label.
3. For non-trivial changes, a design document under golang/proposal/design/ is written.
4. After discussion, the committee accepts, declines, or requests revisions.
5. Accepted proposals are implemented under the original issue and linked from the release notes.

Runtime-specific bugs that may be security-sensitive — race detector defeats, memory corruption, signal-handler reentrancy — go through https://go.dev/security/policy rather than the public tracker.

A senior reporter for a runtime issue includes:

Runtime maintainers prioritise reproducers and traces over prose descriptions. A perfect description without a reproducer often languishes; a reproducer without prose is fixed quickly.

15. Glossary¶

The runtime source rewards readers who hold three references open simultaneously: the language spec, the memory model, and the proposal that introduced the subsystem under study. The source itself is precise but terse; the surrounding documents supply the contract and the rationale that make the precision useful.

A final perspective. The runtime is a moving target precisely because it has no specification. Each Go release rewrites some part of it; each rewrite improves performance or simplifies a previously delicate invariant; each is invisible to programs that stay inside the published API. The senior reader internalises this — the source is what the runtime is today; the contract is what the language promises forever — and reads accordingly. Source citations come with version tags. Behavioural claims come with spec or memory-model references. Performance numbers come with the toolchain version that produced them. Without these qualifications, a runtime claim ages out as soon as the next release ships, and the reader who made the claim becomes the source of a subtle bug somewhere downstream.