The Garbage Collector

Concurrent, tricolor, non-moving

Go’s collector is a concurrent tricolor mark-and-sweep GC. “Concurrent” is the headline: it runs mostly alongside your goroutines, so pauses are tiny (typically well under a millisecond) rather than the long stop-the-world halts of older collectors. It is non-generational and non-moving — it doesn’t relocate objects, which keeps interior pointers, unsafe, and cgo straightforward at the cost of not compacting fragmentation.

The collection has two phases:

1. Mark — find everything reachable, concurrently.
2. Sweep — reclaim everything not marked, lazily.

The tricolor invariant

Marking colors every object one of three shades, starting from the roots (globals, and each goroutine’s stack):

• White — not yet proven reachable. At the end, white = garbage.
• Gray — reachable, but its outgoing pointers haven’t been scanned yet.
• Black — reachable and fully scanned.

graph LR
W["WHITE<br/>maybe garbage"] -->|"found from a root<br/>or a gray object"| G["GRAY<br/>reachable, unscanned"]
G -->|"all its pointers scanned"| B["BLACK<br/>reachable, done"]

The collector repeatedly takes a gray object, grays everything it points to, then blackens it. When no gray objects remain, marking is done: every reachable object is black, everything still white is unreachable and can be swept. The safety rule — the tricolor invariant — is that no black object may hold a pointer to a white object.

The write barrier

Here’s the danger of marking concurrently: while the collector works, your program (the mutator) keeps rewriting pointers. If it stores a pointer to a white object into an already-black object, and deletes the only other path to that white object, the collector would never revisit the black object — and would wrongly free a live object.

The fix is a write barrier: a tiny piece of code the compiler inserts on pointer writes during marking. It notices such stores and re-colors the object (greys it), preserving the invariant. The barrier is only active during a GC cycle, so its cost is paid only while collecting.

The knobs: GOGC and GOMEMLIMIT

You rarely tune the GC, but two environment variables (and their runtime/debug equivalents) control the CPU-vs-memory trade-off:

• GOGC (default 100) — the heap-growth target. At 100, the GC aims to run once the live heap has grown ~100% (doubled) since the last cycle. Raise it (GOGC=200) for fewer GCs and more memory use; lower it for the opposite. GOGC=off disables collection entirely.
• GOMEMLIMIT (Go 1.19+) — a soft total-memory ceiling. Because GOGC is relative to live heap, a sudden burst can overshoot a container’s hard limit before the next GC fires. GOMEMLIMIT=512MiB makes the GC work harder as usage approaches the limit, the standard defense against OOM-kills in Kubernetes.

# Watch every GC cycle: pause times, heap sizes, CPU%.
GODEBUG=gctrace=1 ./myprogram
# gc 1 @0.012s 2%: 0.018+0.69+0.005 ms clock, ... 4->4->1 MB, 5 MB goal

# Common production setting: cap memory, let GOGC float.
GOMEMLIMIT=900MiB GOGC=off ./myprogram

Driving the GC from code

You can read GC stats and trigger collection programmatically — useful for understanding behavior (and for tests), though you should almost never force GC in production:

package main

import (
"fmt"
"runtime"
"runtime/debug"
)

func numGC() uint32 {
var m runtime.MemStats
runtime.ReadMemStats(&m)
return m.NumGC
}

func main() {
// Tighten GOGC so collections happen sooner (demo only).
debug.SetGCPercent(20)

start := numGC()
fmt.Println("GC cycles at start:", start)

// Generate garbage: allocate and immediately drop.
for i := 0; i < 200; i++ {
	junk := make([]byte, 64*1024) // 64 KB, becomes unreachable next iteration
	_ = junk
}

runtime.GC() // force one final cycle so the count is stable
fmt.Println("GC cycles after churning garbage:", numGC()-start, "(plus the forced one)")

var m runtime.MemStats
runtime.ReadMemStats(&m)
fmt.Printf("TotalAlloc=%d KB  NumGC=%d  GCCPUFraction=%.4f\n",
	m.TotalAlloc/1024, m.NumGC, m.GCCPUFraction)
}

GCCPUFraction is the share of CPU the GC has used — the single most useful “is the GC a problem?” number. If it’s low (a few percent), the collector isn’t your bottleneck.

Reference

See also

• the memory allocator — produces the spans the GC sweeps.
• the stack & the heap — only heap objects are collected.
• runtime introspection — MemStats, runtime/metrics, and gctrace.
• GC, stacks & escape analysis (concurrency) — the GC from the goroutine-cost angle.

Next: how Go lays values out in memory — memory layout & alignment.

Related topics