Go GC Source — Practice Tasks¶

Twenty-four exercises that drag you from GODEBUG=gctrace=1 on a hello-world to reading runtime/mgcpacer.go and reproducing a GC death spiral under a tight GOMEMLIMIT. Along the way: runtime.ReadMemStats, runtime/metrics, pprof -alloc_space vs -inuse_space, mark-assist, write-barrier slow paths, finalizers as a leak detector, and the trigger-heap calculation that powers the pacer. Difficulty: Junior, Mid, Senior, Staff.

Each task gives a Goal, Difficulty, Skills, Setup, Steps, Acceptance criteria, and folded Hints + Reference solution. The Go source lives at $(go env GOROOT)/src/runtime/; the GC implementation is mgc.go, mgcmark.go, mgcsweep.go, mgcpacer.go, mgcwork.go, mbarrier.go, plus the design comment block at the top of mgc.go. Read those first when a task says "read the source"; reference solutions cite specific function names and line ranges as of Go 1.22.

The discipline this file builds is not "make GC fast". It is "ask a precise question, run the smallest experiment that answers it, and read the source to confirm what the numbers mean". Most Go programmers stop at gctrace=1. Staff engineers can point at the line in gcControllerState.heapGoalInternal that produced the trigger.

Task 1: gctrace one-liner¶

Goal. Run a small allocating program with GODEBUG=gctrace=1, capture one line of GC trace output, and explain every field by referencing the formatter in runtime/mgc.go.

Difficulty. Junior.

Skills. GODEBUG, basic Go program execution, reading mgc.go comments.

Setup. Go 1.22+. Any terminal. Save the program as gctrace1/main.go.

Steps. 1. Write a program that allocates ~50 MiB across many small slices over ~2 seconds. 2. Run with GODEBUG=gctrace=1 go run ./gctrace1. 3. Copy one full line (starts with gc N). 4. Open runtime/mgc.go, search for gctrace, and read the printf the runtime uses. As of Go 1.22 the format is documented inline; the formatter is in gcMarkTermination writing through printlock/print. 5. Annotate each field of your captured line with what it means.

Acceptance criteria. - You can produce at least one gc N ... line. - You can name each field: gc number, wall-clock time since start, CPU fraction, three pause phases, heap sizes (live before/after, goal), Pscan, goroutine count, etc. - Your annotation matches the source comments, not a blog post.

// gctrace1/main.go
package main

import (
    "fmt"
    "time"
)

func main() {
    // Allocate ~50 MiB in small chunks to force several GCs.
    keep := make([][]byte, 0, 50_000)
    deadline := time.Now().Add(2 * time.Second)
    for time.Now().Before(deadline) {
        b := make([]byte, 1024) // 1 KiB
        for i := range b {
            b[i] = byte(i)
        }
        keep = append(keep, b)
        if len(keep) > 30_000 {
            // Drop half to give the GC something to reclaim.
            keep = keep[len(keep)/2:]
        }
    }
    fmt.Println("retained", len(keep))
}

$ GODEBUG=gctrace=1 go run ./gctrace1 2>&1 | head -5
gc 1 @0.005s 0%: 0.027+0.42+0.005 ms clock, 0.21+0.13/0.41/0.42+0.044 ms cpu, 4->4->2 MB, 5 MB goal, 0 MB stacks, 0 MB globals, 8 P
gc 2 @0.019s 0%: 0.011+0.30+0.004 ms clock, 0.092+0.18/0.30/0.04+0.034 ms cpu, 4->4->2 MB, 5 MB goal, 0 MB stacks, 0 MB globals, 8 P

Extension. Run the same program with GODEBUG=gctrace=1,gcpacertrace=1. The second key dumps the pacer's internal state every cycle: trigger ratio, scan work estimate, assist ratio. Map each pacertrace field to a struct field in gcControllerState (in mgcpacer.go).

Task 2: ReadMemStats before and after allocation¶

Goal. Use runtime.ReadMemStats to measure heap growth across an explicit allocation of one million small objects.

Difficulty. Junior.

Skills. runtime.MemStats, basic benchmarking discipline.

Setup. memstats1/main.go. Standard library only.

Steps. 1. Read MemStats into before. 2. Allocate 1_000_000 items of struct{ A, B int64 } into a slice (keep them live). 3. Read MemStats into after. 4. Print HeapAlloc, HeapInuse, HeapObjects, TotalAlloc, Mallocs differences. 5. Compute and print bytes per allocation: (after.HeapAlloc-before.HeapAlloc) / (after.Mallocs - before.Mallocs).

Acceptance criteria. - HeapObjects increases by approximately 1,000,000 (give or take internal allocations). - (HeapAlloc delta) / Mallocs is approximately 16 bytes (two int64s) or 32 bytes (Go's tiny block padding for small composites). - Program prints all five deltas clearly.

// memstats1/main.go
package main

import (
    "fmt"
    "runtime"
)

type pair struct {
    A, B int64
}

func main() {
    var before, after runtime.MemStats
    runtime.GC()                 // start from a known state
    runtime.ReadMemStats(&before)

    n := 1_000_000
    items := make([]*pair, 0, n)
    for i := 0; i < n; i++ {
        items = append(items, &pair{A: int64(i), B: int64(i)})
    }

    runtime.ReadMemStats(&after)
    // Use items so the compiler can't elide the allocation.
    runtime.KeepAlive(items)

    fmt.Printf("HeapAlloc:    %+d bytes\n", int64(after.HeapAlloc)-int64(before.HeapAlloc))
    fmt.Printf("HeapInuse:    %+d bytes\n", int64(after.HeapInuse)-int64(before.HeapInuse))
    fmt.Printf("HeapObjects:  %+d\n", int64(after.HeapObjects)-int64(before.HeapObjects))
    fmt.Printf("TotalAlloc:   %+d bytes\n", int64(after.TotalAlloc)-int64(before.TotalAlloc))
    fmt.Printf("Mallocs:      %+d\n", int64(after.Mallocs)-int64(before.Mallocs))

    bytesPerAlloc := (after.HeapAlloc - before.HeapAlloc) /
        (after.Mallocs - before.Mallocs)
    fmt.Printf("bytes/alloc:  %d\n", bytesPerAlloc)
}

HeapAlloc:    +24000000 bytes
HeapInuse:    +24010752 bytes
HeapObjects:  +1000007
TotalAlloc:   +24000000 bytes
Mallocs:      +1000008
bytes/alloc:  23

Extension. Add runtime/metrics reading of /memory/classes/heap/objects:bytes and compare to MemStats.HeapAlloc. They should be equal within a few hundred bytes; if not, you've found a measurement skew worth investigating.

Task 3: runtime.GC and NumGC¶

Goal. Demonstrate that calling runtime.GC() triggers a collection by reading NumGC before and after.

Difficulty. Junior.

Skills. runtime.GC, runtime.MemStats.NumGC.

Setup. forcegc/main.go.

Steps. 1. Read NumGC into before. 2. Call runtime.GC(). 3. Read NumGC into after. 4. Assert after.NumGC == before.NumGC + 1. 5. Repeat in a loop ten times and confirm linear growth.

Acceptance criteria. - NumGC increments by exactly one per runtime.GC() call. - Program produces ten lines, each showing NumGC incremented by 1.

// forcegc/main.go
package main

import (
    "fmt"
    "runtime"
)

func main() {
    var m runtime.MemStats
    runtime.ReadMemStats(&m)
    base := m.NumGC

    for i := 0; i < 10; i++ {
        runtime.GC()
        runtime.ReadMemStats(&m)
        delta := m.NumGC - base
        fmt.Printf("after call %2d: NumGC=%d (delta=%d)\n", i+1, m.NumGC, delta)
        if int(delta) != i+1 {
            fmt.Printf("UNEXPECTED: expected delta %d, got %d\n", i+1, delta)
        }
    }
}

runtime.GC() -> gcStart(gcTrigger{kind: gcTriggerCycle, n: n+1}) -> ... -> gcMarkTermination()

Extension. Time runtime.GC() calls under different live-heap sizes. Plot wall time vs heap size. The slope tells you the marker's throughput in MB/sec on your hardware — typically ~1 GB/s/core for pointer-heavy heaps.

Task 4: GOGC sensitivity¶

Goal. Set GOGC=50 and GOGC=200 and measure the difference in NumGC over a fixed workload.

Difficulty. Junior.

Skills. GOGC, runtime.MemStats, comparative measurement.

Setup. gogcsense/main.go. Same program runs twice with different env values.

Steps. 1. Write a program that runs for ~2 seconds of allocation, then prints NumGC and HeapInuse. 2. Run with GOGC=50 go run . — record output. 3. Run with GOGC=200 go run . — record output. 4. Document the ratio: GOGC=50 should produce ~3-4x as many GCs as GOGC=200 for the same workload, with a smaller peak HeapInuse.

Acceptance criteria. - GOGC=50 produces strictly more NumGC than GOGC=200. - GOGC=200 shows higher peak HeapInuse. - You can articulate why: GOGC=N means "trigger GC when heap is N% larger than last live size".

// gogcsense/main.go
package main

import (
    "fmt"
    "os"
    "runtime"
    "time"
)

func main() {
    keep := make([][]byte, 0, 1_000_000)
    deadline := time.Now().Add(2 * time.Second)
    var peak uint64
    for time.Now().Before(deadline) {
        keep = append(keep, make([]byte, 4096))
        if len(keep) > 5000 {
            keep = keep[len(keep)/2:]
        }
        var m runtime.MemStats
        runtime.ReadMemStats(&m)
        if m.HeapInuse > peak {
            peak = m.HeapInuse
        }
    }
    var m runtime.MemStats
    runtime.ReadMemStats(&m)
    fmt.Fprintf(os.Stdout, "GOGC=%s NumGC=%d peak_HeapInuse=%d retained=%d\n",
        os.Getenv("GOGC"), m.NumGC, peak, len(keep))
    runtime.KeepAlive(keep)
}

$ GOGC=50 go run ./gogcsense
GOGC=50 NumGC=312 peak_HeapInuse=23232512 retained=5000

$ GOGC=200 go run ./gogcsense
GOGC=200 NumGC=87 peak_HeapInuse=52166656 retained=5000

Extension. Run a sweep: GOGC in {25, 50, 100, 200, 400, 800}. Plot NumGC and peak HeapInuse. The trade-off curve is hyperbolic-ish; identify the knee for your workload. Task 14 will turn this into a proper tuning exercise.

Task 5: GOMEMLIMIT enforcement¶

Goal. Set GOMEMLIMIT=100MiB and demonstrate that Go obeys it: total RSS plateaus near the limit, GC frequency rises as allocations approach it, and the program does not OOM-kill.

Difficulty. Mid.

Skills. GOMEMLIMIT, runtime/metrics, OS RSS observation.

Setup. memlimit/main.go. Need access to a process-monitoring tool (/usr/bin/time -l on macOS, /usr/bin/time -v on Linux, or ps).

Steps. 1. Write a program that allocates ~200 MiB worth of small slices over 5 seconds, retaining half. 2. Run with no GOMEMLIMIT: observe peak RSS and NumGC. 3. Run with GOMEMLIMIT=100MiB: observe peak RSS and NumGC. 4. Confirm peak RSS stays below ~120 MiB (limit + small overhead) and NumGC is at least 2x higher. 5. Read the comment block at the top of runtime/mgcpacer.go describing the soft memory limit.

Acceptance criteria. - Peak RSS under GOMEMLIMIT=100MiB is within ~20% of 100 MiB. - NumGC is meaningfully higher under the limit. - Program completes without OOM kill even if working set exceeds the limit briefly.

// memlimit/main.go
package main

import (
    "fmt"
    "runtime"
    "time"
)

func main() {
    keep := make([][]byte, 0, 100_000)
    deadline := time.Now().Add(5 * time.Second)
    for time.Now().Before(deadline) {
        keep = append(keep, make([]byte, 8192))
        if len(keep) > 12_000 {
            keep = keep[len(keep)/2:]
        }
    }
    var m runtime.MemStats
    runtime.ReadMemStats(&m)
    fmt.Printf("NumGC=%d HeapInuse=%d MB Sys=%d MB retained=%d\n",
        m.NumGC, m.HeapInuse>>20, m.Sys>>20, len(keep))
    runtime.KeepAlive(keep)
}

# No limit
$ /usr/bin/time -l go run ./memlimit
NumGC=12 HeapInuse=180 MB Sys=210 MB retained=6000
        220463104  maximum resident set size

# With limit
$ GOMEMLIMIT=100MiB /usr/bin/time -l go run ./memlimit
NumGC=78 HeapInuse=78 MB Sys=110 MB retained=6000
        118259712  maximum resident set size

// Pseudo-code mirroring mgcpacer.go.
goal := liveHeap + (GOGC/100) * (liveHeap + stacks + globals)
if memLimit > 0 {
    headroom := totalMappedSpace - liveHeap
    memBased := memLimit - headroom
    if memBased < goal {
        goal = memBased   // trigger sooner to respect limit
    }
}

Extension. Set GOMEMLIMIT=50MiB for the same workload. Note what happens to throughput — the program slows noticeably as mark-assist kicks in. This is the "death spiral" zone (Task 19).

Task 6: pprof alloc_space¶

Goal. Use pprof -alloc_space to identify the biggest cumulative allocator in a small program.

Difficulty. Mid.

Skills. runtime/pprof, go tool pprof, reading flame graphs.

Setup. allocspace/main.go plus go.mod. Need go tool pprof (bundled with Go).

Steps. 1. Write a program with two allocating functions: tiny() allocates []byte of length 64 in a tight loop; huge() allocates []byte of length 16384 less often. Tune so they end up with comparable byte totals. 2. Wrap the program in pprof.StartCPUProfile and pprof.WriteHeapProfile — but actually you want a memory profile from runtime/pprof.Lookup("allocs"). 3. Run, save to mem.prof. 4. Run go tool pprof -alloc_space mem.prof, type top10. The top entry should be huge or tiny depending on totals.

Acceptance criteria. - You can produce a heap profile. - top10 -cum shows your allocating functions ranked by cumulative bytes. - You can explain why the ranking matches (or doesn't match) your intuition.

// allocspace/main.go
package main

import (
    "log"
    "os"
    "runtime/pprof"
)

func tiny(n int) {
    bag := make([][]byte, 0, n)
    for i := 0; i < n; i++ {
        bag = append(bag, make([]byte, 64))
    }
    _ = bag
}

func huge(n int) {
    bag := make([][]byte, 0, n)
    for i := 0; i < n; i++ {
        bag = append(bag, make([]byte, 16384))
    }
    _ = bag
}

func main() {
    // Force MemProfileRate=1 so the profile is exact, not sampled.
    // For real programs leave the default (512 KiB) — it's fast and accurate.
    // runtime.MemProfileRate = 1

    tiny(100_000) // ~6.4 MiB total
    huge(1_000)   // ~16 MiB total

    f, err := os.Create("mem.prof")
    if err != nil {
        log.Fatal(err)
    }
    defer f.Close()
    if err := pprof.Lookup("allocs").WriteTo(f, 0); err != nil {
        log.Fatal(err)
    }
}

$ go run ./allocspace
$ go tool pprof -alloc_space mem.prof
(pprof) top10
Showing nodes accounting for 22.40MB, 100% of 22.40MB total
      flat  flat%   sum%        cum   cum%
   16.00MB 71.43% 71.43%    16.00MB 71.43%  main.huge
    6.40MB 28.57%   100%     6.40MB 28.57%  main.tiny
(pprof) list main.huge
ROUTINE ======================== main.huge
   16.00MB    16.00MB (flat, cum) 71.43% of Total
         .          .     19:func huge(n int) {
         .          .     20:    bag := make([][]byte, 0, n)
         .          .     21:    for i := 0; i < n; i++ {
   16.00MB    16.00MB     22:        bag = append(bag, make([]byte, 16384))
         .          .     23:    }

Extension. Add -source_path=$(go env GOROOT) and disasm main.huge in pprof. You'll see the actual mallocgc call site — useful when the alloc is buried inside a library you control.

Task 7: alloc_space versus inuse_space¶

Goal. Take both -alloc_space and -inuse_space profiles of a program where a hot allocator produces short-lived objects and a cold path produces long-lived objects. Explain the difference in pprof output.

Difficulty. Mid.

Skills. Distinguishing cumulative vs live profiles, building intuition about lifetimes.

Setup. allocvinuse/main.go.

Steps. 1. churn() allocates 10,000 64-byte slices in a loop, dropping each (short-lived). 2. retain() allocates 100 64-KiB slices and keeps them in a package-level slice (long-lived). 3. Save heap profile to mem.prof. 4. Run both go tool pprof -alloc_space mem.prof and go tool pprof -inuse_space mem.prof. 5. Compare top10 outputs.

Acceptance criteria. - -alloc_space ranks churn higher than retain. - -inuse_space ranks retain higher than churn. - You can explain: alloc_space counts all bytes ever allocated; inuse_space counts only bytes still reachable at profile capture time.

// allocvinuse/main.go
package main

import (
    "log"
    "os"
    "runtime"
    "runtime/pprof"
)

var retained [][]byte // package-level keeps this live

func churn() {
    for i := 0; i < 10_000; i++ {
        b := make([]byte, 64)
        _ = b
    }
}

func retain() {
    for i := 0; i < 100; i++ {
        retained = append(retained, make([]byte, 64<<10))
    }
}

func main() {
    churn()
    retain()
    // Force GC so heap profile reflects live data only.
    runtime.GC()

    f, err := os.Create("mem.prof")
    if err != nil {
        log.Fatal(err)
    }
    defer f.Close()
    if err := pprof.Lookup("heap").WriteTo(f, 0); err != nil {
        log.Fatal(err)
    }
}

$ go run ./allocvinuse
$ go tool pprof -alloc_space mem.prof
(pprof) top
      flat  flat%   sum%        cum   cum%
    6.40MB 51.61% 51.61%     6.40MB 51.61%  main.retain   (~6.4 MB live - matches what we kept)
    0.62MB 5.00%  56.61%     0.62MB 5.00%   main.churn    (sampled subset of the 10K allocs)

$ go tool pprof -inuse_space mem.prof
(pprof) top
      flat  flat%   sum%        cum   cum%
    6.40MB   100%   100%     6.40MB   100%  main.retain
         0     0%   100%          0     0%  main.churn   (all churned bytes were collected)

Extension. Capture a profile without calling runtime.GC() first. The inuse_space numbers will include not-yet-collected objects from churn. The implicit "you must GC before sampling for accurate live data" is pprof.WriteHeapProfile's old behaviour; modern code uses Lookup("heap").WriteTo and decides GC explicitly.

Task 8: pointer fields versus value fields¶

Goal. Build two structs of identical logical contents — one with pointer fields, one with value fields. Show that the pointer version has higher GC scan cost.

Difficulty. Mid.

Skills. Heap layout, GC scanning model, microbenchmarks.

Setup. pointersvalues/ with bench_test.go and a small main.go.

Steps. 1. Define type WithPtrs struct { A, B, C, D *int64 } and type WithVals struct { A, B, C, D int64 }. 2. Allocate 1,000,000 of each into separate slices. 3. Force a GC with runtime.GC() and time each via runtime/metrics /gc/heap/scan:bytes or MemStats.PauseNs[(NumGC-1)%256]. 4. Confirm WithPtrs causes more bytes scanned than WithVals.

Acceptance criteria. - The bytes-scanned metric for the pointer version is meaningfully higher (often 2-4x). - You can explain: GC scans pointer fields; value-typed fields are skipped using the type's pointer bitmap.

// pointersvalues/main.go
package main

import (
    "fmt"
    "runtime"
    "runtime/metrics"
)

type WithPtrs struct {
    A, B, C, D *int64
}

type WithVals struct {
    A, B, C, D int64
}

func newPtrs(n int) []WithPtrs {
    out := make([]WithPtrs, n)
    for i := range out {
        a, b, c, d := int64(i), int64(i+1), int64(i+2), int64(i+3)
        out[i] = WithPtrs{&a, &b, &c, &d}
    }
    return out
}

func newVals(n int) []WithVals {
    out := make([]WithVals, n)
    for i := range out {
        out[i] = WithVals{int64(i), int64(i + 1), int64(i + 2), int64(i + 3)}
    }
    return out
}

func scanBytes() uint64 {
    s := []metrics.Sample{{Name: "/gc/scan/heap:bytes"}}
    metrics.Read(s)
    return s[0].Value.Uint64()
}

func main() {
    const n = 1_000_000

    // Pointer version
    runtime.GC()
    before := scanBytes()
    ps := newPtrs(n)
    runtime.GC()
    after := scanBytes()
    fmt.Printf("WithPtrs: scanned %d bytes\n", after-before)
    runtime.KeepAlive(ps)

    // Value version
    runtime.GC()
    before = scanBytes()
    vs := newVals(n)
    runtime.GC()
    after = scanBytes()
    fmt.Printf("WithVals: scanned %d bytes\n", after-before)
    runtime.KeepAlive(vs)
}

WithPtrs: scanned 41943040 bytes
WithVals: scanned 16777216 bytes

Extension. Repeat with a struct containing 16 fields. The advantage of values grows: scan work scales with pointer count, value fields are essentially free.

Task 9: sync.Pool to cut allocations¶

Goal. Replace a hot allocation with sync.Pool. Benchmark before and after; aim for >10x reduction in allocations per op.

Difficulty. Mid.

Skills. sync.Pool, testing.B, b.ReportAllocs().

Setup. poolbench/buffer_test.go. A function that processes data using a temporary []byte scratch buffer.

Steps. 1. Write Process(data []byte) []byte that allocates a 4 KiB scratch buffer per call, does some work, returns a copy of the result. 2. Benchmark with go test -bench=. -benchmem. 3. Refactor to use sync.Pool for the scratch buffer. 4. Benchmark again. Compare allocations and ns/op.

Acceptance criteria. - Pooled version has roughly 1 alloc/op (just the returned copy) vs ~2 for the naive version. - ns/op is lower for the pooled version under contention. - You correctly Reset the pooled buffer before returning it to the pool.

// poolbench/buffer_test.go
package poolbench

import (
    "sync"
    "testing"
)

var pool = sync.Pool{
    New: func() any {
        b := make([]byte, 0, 4096)
        return &b
    },
}

// Naive: allocates a 4 KiB buffer every call.
func ProcessNaive(data []byte) []byte {
    buf := make([]byte, 0, 4096)
    for _, b := range data {
        buf = append(buf, b^0x55)
    }
    out := make([]byte, len(buf))
    copy(out, buf)
    return out
}

// Pooled: borrows from sync.Pool, resets, returns it.
func ProcessPool(data []byte) []byte {
    bufp := pool.Get().(*[]byte)
    buf := (*bufp)[:0] // reset, keep capacity
    defer func() {
        *bufp = buf[:0] // store back with capacity, length 0
        pool.Put(bufp)
    }()
    for _, b := range data {
        buf = append(buf, b^0x55)
    }
    out := make([]byte, len(buf))
    copy(out, buf)
    return out
}

var input = make([]byte, 2048)

func BenchmarkNaive(b *testing.B) {
    b.ReportAllocs()
    for i := 0; i < b.N; i++ {
        _ = ProcessNaive(input)
    }
}

func BenchmarkPool(b *testing.B) {
    b.ReportAllocs()
    for i := 0; i < b.N; i++ {
        _ = ProcessPool(input)
    }
}

$ go test -bench=. -benchmem
BenchmarkNaive-8     350000      3421 ns/op    6144 B/op    2 allocs/op
BenchmarkPool-8      720000      1612 ns/op    2048 B/op    1 allocs/op

Extension. Run with -cpu=1,2,4,8. The pool's benefit per-core grows with contention because the lock-free deque keeps Get/Put on the same P most of the time. Compare with a naive sync.Mutex-protected free list at high parallelism — the standard pool wins by an order of magnitude.

Task 10: force a leak with retained references¶

Goal. Build a "leaking" service where each request adds to a global map without removal. Confirm HeapInuse grows monotonically.

Difficulty. Mid.

Skills. Leak diagnosis, runtime.ReadMemStats over time, distinguishing "growth" from "leak".

Setup. leak1/main.go. A loop that simulates incoming requests, each adding to a global structure.

Steps. 1. Define var sessions = map[string]*Session{}. 2. In a loop, generate a unique session key and store a 1 KiB *Session value. 3. Every 1000 iterations, read MemStats and print HeapAlloc and HeapInuse. 4. Run for ~30 seconds. Confirm both grow without bound. 5. Add removal logic; confirm the growth stops.

Acceptance criteria. - Initial version: HeapInuse grows monotonically until you stop the program. - Fixed version: HeapInuse reaches a plateau, oscillates around it. - You can articulate the difference between "leak" (unbounded growth of reachable objects) and "high memory use" (bounded but large).

// leak1/main.go
package main

import (
    "fmt"
    "runtime"
    "strconv"
    "time"
)

type Session struct {
    UserID    string
    Data      [1024]byte
    CreatedAt time.Time
}

var sessions = map[string]*Session{}

func main() {
    start := time.Now()
    for i := 0; ; i++ {
        key := strconv.Itoa(i)
        sessions[key] = &Session{
            UserID:    key,
            CreatedAt: time.Now(),
        }

        if i%1000 == 0 {
            var m runtime.MemStats
            runtime.ReadMemStats(&m)
            fmt.Printf("[%5.1fs] i=%d HeapAlloc=%d MB HeapInuse=%d MB len(sessions)=%d\n",
                time.Since(start).Seconds(), i, m.HeapAlloc>>20, m.HeapInuse>>20, len(sessions))
        }

        if time.Since(start) > 30*time.Second {
            return
        }
    }
}

// At the top of the loop, after writing, evict anything older than 5 seconds.
if i%1000 == 0 {
    cutoff := time.Now().Add(-5 * time.Second)
    for k, s := range sessions {
        if s.CreatedAt.Before(cutoff) {
            delete(sessions, k)
        }
    }
}

Extension. Replace the global map with sync.Map. Repeat the leak; observe similar growth. Now replace with a fixed-size LRU. The leak goes away because eviction is structural, not dependent on the caller remembering to delete.

Task 11: read mgc.go and find gcStart¶

Goal. Open runtime/mgc.go, identify the entry function for starting a GC cycle, and trace through one call's first ~30 lines.

Difficulty. Senior.

Skills. Reading runtime source, navigating Go's internal package layout.

Setup. Local Go install. cd $(go env GOROOT)/src/runtime.

Steps. 1. Open mgc.go. Find the function gcStart. 2. Read its docstring and the assertions at the top. 3. Trace what happens when the trigger is gcTriggerCycle (the kind used by runtime.GC()). 4. Identify where mutators are put into mark-assist mode (in gcMarkRootPrepare and gcAssistAlloc). 5. Write a short summary: which function STWs the world, where the write barrier is enabled, where concurrent mark workers spawn.

Acceptance criteria. - You can quote the signature of gcStart. - You can name three functions it calls in order: stopTheWorldWithSema, setGCPhase(_GCmark), startTheWorldWithSema. - You can locate where gcphase transitions to _GCmark.

// gcStart starts the GC. It transitions from _GCoff to _GCmark (if
// debug.gcstoptheworld == 0) or performs all of GC (if
// debug.gcstoptheworld > 0).
//
// This may return without performing this transition in some cases,
// such as when called on a system stack or with locks held.
func gcStart(trigger gcTrigger) {
    // Since this is called from malloc and malloc is called in
    // the guts of a number of libraries that might be holding
    // locks, don't attempt to start GC in non-preemptible or
    // potentially unstable situations.
    mp := acquirem()
    if gp := getg(); gp == mp.g0 || mp.locks > 1 || mp.preemptoff != "" {
        releasem(mp)
        return
    }
    releasem(mp)
    mp = nil

    // ... lots of preconditions and sema acquire ...

    // Pick up the remaining unswept/not being swept spans concurrently
    for atomic.Load(&work.cycles) == n+1 && sweepone() != ^uintptr(0) {
        sweep.nbgsweep++
    }

    // ...

    // Enter mark phase, enabling write barriers.
    setGCPhase(_GCmark)

    // ...

    // Start concurrent mark workers (one per P).
    // gcBgMarkStartWorkers spawns runtime goroutines named "GC worker"
    // that loop calling gcBgMarkWorker.
    gcBgMarkStartWorkers()

    // ...

    // Start the world. Mutators now run concurrently with mark workers.
    startTheWorldWithSema(0, stw)
}

Extension. Find the place in gcStart where forcegcperiod matters — the periodic GC trigger. It's around the trigger evaluation; identify how the runtime decides "no allocations happened, but it's been 2 minutes, GC anyway".

Task 12: GC pause histogram via runtime/metrics¶

Goal. Use the runtime/metrics package to read the /gc/pauses:seconds histogram. Compute and print p50, p95, p99 over a workload.

Difficulty. Senior.

Skills. runtime/metrics, histogram bucket math, runtime instrumentation.

Setup. gcpauses/main.go.

Steps. 1. Run a workload that triggers many GCs (e.g., the program from Task 4 with GOGC=50). 2. After completion, read /gc/pauses:seconds into a metrics.Sample. 3. Walk the histogram buckets to compute percentile pauses. 4. Print p50, p95, p99 in microseconds. 5. Compare with runtime.MemStats.PauseNs (a circular buffer of the last 256 pauses).

Acceptance criteria. - Program outputs three percentile values. - p99 is meaningfully larger than p50 (long-tail behaviour). - You can explain the difference between the metrics-package histogram (cumulative all-time) and the PauseNs circular buffer (last 256).

// gcpauses/main.go
package main

import (
    "fmt"
    "runtime"
    "runtime/metrics"
    "time"
)

func percentile(h *metrics.Float64Histogram, p float64) float64 {
    var total uint64
    for _, c := range h.Counts {
        total += c
    }
    if total == 0 {
        return 0
    }
    target := uint64(float64(total) * p / 100.0)
    var seen uint64
    for i, c := range h.Counts {
        seen += c
        if seen >= target {
            return h.Buckets[i+1] // right edge of bucket
        }
    }
    return h.Buckets[len(h.Buckets)-1]
}

func main() {
    // Generate some GC pressure.
    keep := make([][]byte, 0, 100_000)
    deadline := time.Now().Add(3 * time.Second)
    for time.Now().Before(deadline) {
        keep = append(keep, make([]byte, 4096))
        if len(keep) > 10_000 {
            keep = keep[len(keep)/2:]
        }
    }
    runtime.KeepAlive(keep)

    // Read the histogram.
    s := []metrics.Sample{{Name: "/gc/pauses:seconds"}}
    metrics.Read(s)
    if s[0].Value.Kind() != metrics.KindFloat64Histogram {
        fmt.Println("wrong kind:", s[0].Value.Kind())
        return
    }
    h := s[0].Value.Float64Histogram()

    fmt.Printf("p50 GC pause: %6.1f us\n", percentile(h, 50)*1e6)
    fmt.Printf("p95 GC pause: %6.1f us\n", percentile(h, 95)*1e6)
    fmt.Printf("p99 GC pause: %6.1f us\n", percentile(h, 99)*1e6)

    var m runtime.MemStats
    runtime.ReadMemStats(&m)
    fmt.Printf("NumGC: %d, total PauseNs: %d (avg %d us)\n",
        m.NumGC, m.PauseTotalNs, m.PauseTotalNs/uint64(m.NumGC)/1000)
}

p50 GC pause:   24.0 us
p95 GC pause:  128.0 us
p99 GC pause:  512.0 us
NumGC: 187, total PauseNs: 7423000 (avg 39 us)

Extension. Plot the histogram over time: read it at 1-second intervals, diff bucket counts, and graph p99 vs wall time. Sudden spikes correlate with allocation bursts.

Task 13: mark-assist under tight allocation¶

Goal. Build a workload where mark-assist becomes the dominant cost. Read the assist field in gctrace output. Read the assist source in mgc.go.

Difficulty. Senior.

Skills. Mark-assist semantics, allocation pressure tuning, source reading.

Setup. markassist/main.go. Combined with GODEBUG=gctrace=1.

Steps. 1. Write a program with one tight-allocating goroutine that does make([]byte, 64) in a hot loop, billions of times. 2. Run with GODEBUG=gctrace=1. 3. Identify the "assist" field in the CPU breakdown (a/b/c where a is assist, b is dedicated, c is idle). 4. Increase allocation pressure (smaller GOGC); confirm the a term grows. 5. Read runtime/mgc.go: gcAssistAlloc to see how mutators are charged.

Acceptance criteria. - You can identify the "assist" field in a gctrace line. - With aggressive GOGC=25, mark-assist visibly dominates GC CPU. - You can explain: when a goroutine allocates faster than mark workers can keep up, it gets taxed — it must do mark work itself before proceeding.

// markassist/main.go
package main

import (
    "fmt"
    "runtime"
    "time"
)

func main() {
    keep := make([][]byte, 0, 1_000_000)
    deadline := time.Now().Add(3 * time.Second)
    for time.Now().Before(deadline) {
        for i := 0; i < 1000; i++ {
            keep = append(keep, make([]byte, 64))
        }
        // Drop most of them; we want allocation pressure, not retention.
        if len(keep) > 5000 {
            keep = keep[len(keep)/2:]
        }
    }
    var m runtime.MemStats
    runtime.ReadMemStats(&m)
    fmt.Printf("NumGC=%d totalPause=%dms retained=%d\n",
        m.NumGC, m.PauseTotalNs/1e6, len(keep))
    runtime.KeepAlive(keep)
}

$ GODEBUG=gctrace=1 GOGC=100 go run ./markassist 2>&1 | head -3
gc 1 @0.011s 3%: 0.05+0.42+0.012 ms clock, 0.41+0.21/0.33/0.12+0.097 ms cpu, 4->4->2 MB, 5 MB goal, 0 MB stacks, 0 MB globals, 8 P
...

$ GODEBUG=gctrace=1 GOGC=10 go run ./markassist 2>&1 | head -3
gc 1 @0.005s 14%: 0.04+0.31+0.008 ms clock, 0.32+2.41/0.29/0.04+0.064 ms cpu, ...

// gcAssistAlloc performs GC work to make up for a recent allocation
// that exceeded the assist credit. assistAlloc returns true if the
// mutator has done enough work to satisfy its current debt; false if
// further work is needed.
func gcAssistAlloc(gp *g) {
    // Check this goroutine's assist debt.
    debtBytes := -gp.gcAssistBytes
    // Compute the work to do: debt × assistWorkPerByte.
    scanWork := int64(assistWorkPerByte * float64(debtBytes))
    // ... do the work, possibly preempting back to the runtime to
    // help if more is needed ...
}

Extension. Set GODEBUG=gctrace=1,gcassiststack=1 and grep for "assist on stack". The runtime prints when a mutator's assist crossed a threshold worth noting.

Task 14: GOGC trade-off curve¶

Goal. For a synthetic workload, sweep GOGC across {25, 50, 100, 200, 400, 800} and plot GC CPU% vs peak HeapInuse. Identify the knee.

Difficulty. Senior.

Skills. Systematic benchmarking, trade-off visualisation, choosing a tuning parameter from data.

Setup. gogcsweep/. A program that runs a fixed workload and reports timing + memory. A shell script to drive the sweep.

Steps. 1. Write a deterministic workload (compute factorial-of-binomials, or any CPU-bound thing that allocates a known amount). 2. The program reports: total wall time, MemStats.GCCPUFraction, peak HeapInuse. 3. Loop: for g in {25 50 100 200 400 800}, run GOGC=$g ./prog, capture output. 4. Plot or table: x = GOGC, y1 = GCCPUFraction, y2 = peak HeapInuse. 5. Identify the knee — where doubling GOGC stops meaningfully reducing GC CPU.

Acceptance criteria. - You have data for all six GOGC values. - GCCPUFraction monotonically decreases with GOGC; peak heap monotonically increases. - You can identify the knee for your workload (often near GOGC=200 for allocation-heavy ones).

// gogcsweep/main.go
package main

import (
    "fmt"
    "os"
    "runtime"
    "time"
)

func work() {
    keep := make([][]byte, 0, 100_000)
    for i := 0; i < 50_000; i++ {
        keep = append(keep, make([]byte, 1024))
        // Half-drop pattern to keep heap interesting.
        if len(keep) > 20_000 {
            keep = keep[len(keep)/2:]
        }
    }
    runtime.KeepAlive(keep)
}

func main() {
    runtime.GC()
    var peak uint64
    start := time.Now()
    done := make(chan struct{})
    go func() {
        for {
            select {
            case <-done:
                return
            default:
                var m runtime.MemStats
                runtime.ReadMemStats(&m)
                if m.HeapInuse > peak {
                    peak = m.HeapInuse
                }
            }
        }
    }()

    work()
    close(done)

    elapsed := time.Since(start)
    var m runtime.MemStats
    runtime.ReadMemStats(&m)
    fmt.Printf("GOGC=%s elapsed=%dms gc_cpu=%.4f peak_inuse=%d MB\n",
        os.Getenv("GOGC"), elapsed.Milliseconds(), m.GCCPUFraction, peak>>20)
}

#!/bin/bash
for g in 25 50 100 200 400 800; do
    for trial in 1 2 3; do
        GOGC=$g go run ./gogcsweep
    done
done

GOGC=25  elapsed=890ms gc_cpu=0.198 peak_inuse=18 MB
GOGC=50  elapsed=720ms gc_cpu=0.115 peak_inuse=24 MB
GOGC=100 elapsed=640ms gc_cpu=0.068 peak_inuse=37 MB
GOGC=200 elapsed=610ms gc_cpu=0.041 peak_inuse=58 MB
GOGC=400 elapsed=595ms gc_cpu=0.024 peak_inuse=92 MB
GOGC=800 elapsed=590ms gc_cpu=0.015 peak_inuse=140 MB

Extension. Repeat with GOMEMLIMIT=80MiB. Watch how the pacer behaves: low GOGC is now redundant (the memory limit triggers); high GOGC is capped by the limit. The two knobs interact non-trivially — that's by design.

Task 15: finalizer-based leak detector¶

Goal. Use runtime.SetFinalizer to detect a class of leaks: objects that should have been closed/released but weren't. Build a small helper that logs unfreed objects.

Difficulty. Senior.

Skills. Finalizers, weak references via finalizer pattern, leak diagnosis tooling.

Setup. finalizeleak/main.go. A Resource type that should be Close()d.

Steps. 1. Define Resource with id, Open(), Close(). In Open, set a finalizer that logs "LEAK: %d never closed". 2. In Close, clear the finalizer via runtime.SetFinalizer(r, nil) so closed resources are silent. 3. Write a program that opens 10 resources, closes 7, drops references to all. 4. Call runtime.GC() twice (finalizers run on a separate goroutine; two GCs ensure their queue drains). 5. Sleep briefly to let finalizer goroutine run; confirm exactly 3 "LEAK" lines.

Acceptance criteria. - The unclosed resources are logged; the closed ones are not. - You correctly clear the finalizer in Close so successful closures don't log. - You can articulate the danger: finalizers run on a runtime goroutine, can block GC progress, and aren't guaranteed to run.

// finalizeleak/main.go
package main

import (
    "fmt"
    "runtime"
    "sync/atomic"
    "time"
)

type Resource struct {
    id     int
    closed atomic.Bool
}

var nextID atomic.Int64

func Open() *Resource {
    r := &Resource{id: int(nextID.Add(1))}
    runtime.SetFinalizer(r, func(r *Resource) {
        if !r.closed.Load() {
            fmt.Printf("LEAK: Resource %d was never closed\n", r.id)
        }
    })
    return r
}

func (r *Resource) Close() {
    r.closed.Store(true)
    // Clear the finalizer so closed resources are silent on GC.
    runtime.SetFinalizer(r, nil)
}

func main() {
    for i := 0; i < 10; i++ {
        r := Open()
        if i%10 < 7 {
            r.Close()
        }
        // Drop the reference (in real code, this happens at scope exit).
    }
    runtime.GC()
    // Finalizers run on a separate goroutine; give them a moment.
    time.Sleep(50 * time.Millisecond)
    runtime.GC()
    time.Sleep(50 * time.Millisecond)
    fmt.Println("done")
}

LEAK: Resource 10 was never closed
LEAK: Resource 9 was never closed
LEAK: Resource 8 was never closed
done

Extension. Use runtime.AddCleanup (Go 1.24+) instead of SetFinalizer. AddCleanup is the modern replacement: cleaner semantics (no resurrection), better composability. Compare ergonomics.

Task 16: write barrier slow path in CPU profile¶

Goal. Build a write-heavy workload that surfaces the write-barrier slow path in a CPU profile. Identify it by function name.

Difficulty. Senior.

Skills. CPU profiling, write barrier semantics, source navigation.

Setup. writebarrier/main.go plus profile capture.

Steps. 1. Build a program that repeatedly writes pointers into long-lived heap-allocated slices during an active GC mark phase. 2. Capture a CPU profile while it runs. 3. Open the profile in go tool pprof, type top and look for gcWriteBarrier or wbBufFlush. 4. Read runtime/mbarrier.go and runtime/mwbbuf.go to understand the slow path.

Acceptance criteria. - CPU profile shows runtime.gcWriteBarrier (or one of its variants) consuming non-trivial CPU. - You can explain the role of wbBuf and why it exists (per-P amortization of barrier work). - You can identify when the slow path runs vs the fast path.

// writebarrier/main.go
package main

import (
    "log"
    "os"
    "runtime"
    "runtime/pprof"
    "time"
)

type Node struct {
    Next *Node
    Data [64]byte
}

func main() {
    f, err := os.Create("cpu.prof")
    if err != nil {
        log.Fatal(err)
    }
    defer f.Close()
    pprof.StartCPUProfile(f)
    defer pprof.StopCPUProfile()

    // Long-lived linked-list nodes; many heap pointer writes follow.
    head := &Node{}
    cur := head
    for i := 0; i < 100_000; i++ {
        cur.Next = &Node{}
        cur = cur.Next
    }
    runtime.KeepAlive(head)

    // Now shuffle pointers around to provoke write-barrier work
    // during the next GC mark phases.
    deadline := time.Now().Add(3 * time.Second)
    for time.Now().Before(deadline) {
        // Walk the list, swap pointers, allocate to keep GC active.
        a := head
        for a != nil && a.Next != nil {
            tmp := a.Next.Next
            a.Next = tmp
            a = tmp
        }
        // Reallocate the tail to force GC churn.
        for j := 0; j < 1000; j++ {
            _ = make([]byte, 1024)
        }
    }
    runtime.KeepAlive(head)
}

$ go run ./writebarrier
$ go tool pprof cpu.prof
(pprof) top10
Showing nodes accounting for 2540ms, 100% of 2540ms total
      flat  flat%   sum%        cum   cum%
     680ms 26.77% 26.77%      680ms 26.77%  runtime.gcWriteBarrier
     310ms 12.20% 38.98%      310ms 12.20%  runtime.wbBufFlush1
     240ms 9.45% 48.43%       240ms 9.45%   main.main
     ...

Extension. Run the same workload with GOGC=off. The write barrier should never engage (mark phase doesn't run). Confirm gcWriteBarrier drops to ~0 in the profile.

Task 17: many small structs vs one large struct¶

Goal. Compare GC cost between (a) a slice of one million pointer-to-struct, and (b) a slice of one million inline structs. Show the cost difference.

Difficulty. Senior.

Skills. Heap layout, indirect-vs-direct allocation, cache effects.

Setup. manysmall/main.go with two configurations.

Steps. 1. Allocate []*Small of length 1M, each pointing to a freshly-allocated Small. 2. Allocate []Small of length 1M, all inline (no pointers). 3. For each, time runtime.GC() and measure MemStats.PauseNs[i] and runtime/metrics /gc/scan/heap:bytes delta. 4. Print scan bytes and pause times.

Acceptance criteria. - The slice-of-pointers version causes more bytes scanned (one million extra objects to walk). - The slice-of-values version is faster to GC and uses slightly less total heap. - You can explain: the slice of *Small is itself a million-pointer array — the GC walks each one even though the targets contain no further pointers.

// manysmall/main.go
package main

import (
    "fmt"
    "runtime"
    "runtime/metrics"
    "time"
)

type Small struct {
    A, B int64
    C    [16]byte
}

func scanBytes() uint64 {
    s := []metrics.Sample{{Name: "/gc/scan/heap:bytes"}}
    metrics.Read(s)
    return s[0].Value.Uint64()
}

func measure(name string, build func() any) {
    runtime.GC()
    before := scanBytes()
    start := time.Now()
    x := build()
    runtime.GC()
    elapsed := time.Since(start)
    after := scanBytes()
    var m runtime.MemStats
    runtime.ReadMemStats(&m)
    fmt.Printf("%-12s scan=%d MB heapObjects=%d gcTime=%dus\n",
        name, (after-before)>>20, m.HeapObjects, elapsed.Microseconds())
    runtime.KeepAlive(x)
}

func main() {
    const n = 1_000_000
    measure("PointerSlice", func() any {
        out := make([]*Small, n)
        for i := range out {
            out[i] = &Small{A: int64(i), B: int64(i)}
        }
        return out
    })
    measure("ValueSlice", func() any {
        out := make([]Small, n)
        for i := range out {
            out[i] = Small{A: int64(i), B: int64(i)}
        }
        return out
    })
}

PointerSlice scan=64 MB heapObjects=1000007 gcTime=8200us
ValueSlice   scan=40 MB heapObjects=8       gcTime=3100us

Extension. Bench the iteration too. for _, s := range valueSlice versus for _, s := range pointerSlice. The value version is roughly 2-3x faster on modern CPUs because of contiguous memory access.

Task 18: read mgcpacer.go and explain heapGoalInternal¶

Goal. Open runtime/mgcpacer.go, find gcControllerState.heapGoalInternal, read it, and write a one-paragraph explanation of how it computes the next trigger.

Difficulty. Staff.

Skills. Reading pacer source, understanding feedback loops.

Setup. Local Go source.

Steps. 1. Open mgcpacer.go. 2. Find the struct gcControllerState. Read the field comments. 3. Find func (c *gcControllerState) heapGoalInternal(). Read it. 4. Identify the three terms: GOGC-based goal, GOMEMLIMIT-based goal, runway adjustment. 5. Write a paragraph summary in your own words.

Acceptance criteria. - You can quote the function signature. - You can describe the three constraints that compete to set the goal. - You can explain why the goal is "internal" — there's a separate heapGoal() that returns the published goal after rounding.

// heapGoalInternal is the implementation of heapGoal which returns
// internal details about the goal.
func (c *gcControllerState) heapGoalInternal() (goal, minTrigger uint64) {
    // Start with the goal calculated for memoryLimit.
    goal = c.memoryLimitHeapGoal()

    // Check if the goal from GOGC is more restrictive. If not, the goal
    // is set by the memory limit.
    if newGoal := c.heapGoalGOGC(); newGoal < goal {
        goal = newGoal
    }

    // ...minTrigger logic for runway smoothing...

    return goal, minTrigger
}

Extension. Find the gcController.revise function. This is called periodically to update the assist ratio mid-cycle as the pacer observes actual scan progress. Read it; it's the heart of "the GC adapts in real-time".

Task 19: reproduce a GC death spiral¶

Goal. Combine high allocation pressure with tight GOMEMLIMIT to produce a "GC death spiral" — a state where the program spends most of its time in GC and makes no progress. Analyze using gctrace.

Difficulty. Staff.

Skills. Pathological tuning, gctrace interpretation, mark-assist saturation diagnosis.

Setup. deathspiral/main.go. Allocates heavily; combined with very low GOMEMLIMIT.

Steps. 1. Write a program that allocates 100 MiB worth of live data in a tight loop. 2. Run with GOMEMLIMIT=80MiB GODEBUG=gctrace=1. 3. Observe: the GC fires constantly, mark-assist dominates, throughput collapses. 4. Read GCCPUFraction — should be >50%. 5. Increase the limit; observe recovery.

Acceptance criteria. - You can produce a run where GCCPUFraction > 0.5 (more than half the CPU is in GC). - gctrace lines show high assist (a/b/c where a is many ms). - You can explain: with the limit below live-heap-plus-headroom, the pacer demands the impossible — collection at a rate exceeding the marker's throughput.

// deathspiral/main.go
package main

import (
    "fmt"
    "os"
    "runtime"
    "time"
)

func main() {
    // Build a live heap close to the GOMEMLIMIT.
    live := make([][]byte, 0, 100_000)
    for i := 0; i < 70_000; i++ {
        live = append(live, make([]byte, 1024)) // ~70 MiB live
    }

    // Now allocate hot; the heap is full, the limit is near.
    start := time.Now()
    var allocOps int
    for time.Since(start) < 5*time.Second {
        _ = make([]byte, 4096) // pure garbage; allocated and dropped
        allocOps++
    }

    var m runtime.MemStats
    runtime.ReadMemStats(&m)
    fmt.Fprintf(os.Stdout, "GOMEMLIMIT=%s allocs=%d NumGC=%d GCCPUFraction=%.4f totalPauseMs=%d\n",
        os.Getenv("GOMEMLIMIT"), allocOps, m.NumGC, m.GCCPUFraction, m.PauseTotalNs/1e6)
    runtime.KeepAlive(live)
}

$ /usr/bin/time go run ./deathspiral
GOMEMLIMIT= allocs=82000000 NumGC=44 GCCPUFraction=0.0421 totalPauseMs=18
        5.21 real    5.18 user    0.10 sys

$ GOMEMLIMIT=80MiB GODEBUG=gctrace=1 /usr/bin/time go run ./deathspiral 2>&1 | tail -10
gc 312 @4.78s 73%: 0.04+3.2+0.008 ms clock, 0.32+15.4/2.1/0.04+0.064 ms cpu, 76->77->75 MB, 80 MB goal, ...
gc 313 @4.82s 73%: 0.04+3.4+0.008 ms clock, 0.32+16.2/2.0/0.04+0.064 ms cpu, 76->77->75 MB, 80 MB goal, ...
GOMEMLIMIT=80MiB allocs=2400000 NumGC=313 GCCPUFraction=0.7321 totalPauseMs=2120
        5.34 real    5.30 user    0.12 sys

Extension. Add debug.SetGCPercent(-1) (disable percent-based trigger) and run with the tight limit. The limit alone now drives GC. Observe behaviour: similar spiral, slightly different shape.

Task 20: read proposal 48409 (GOMEMLIMIT)¶

Goal. Read the Go proposal for GOMEMLIMIT (issue 48409, also Design/48409-soft-memory-limit.md in the proposal repo). Summarize the four design decisions.

Difficulty. Staff.

Skills. Reading design proposals, distinguishing trade-offs.

Setup. Browser or local clone of golang/proposal.

Steps. 1. Open https://github.com/golang/proposal/blob/master/design/48409-soft-memory-limit.md 2. Read the "Background", "Goals", "Design", and "Implementation" sections. 3. Identify four design decisions: soft vs hard limit, interaction with GOGC, behaviour at exhaustion, units/parsing. 4. Write a one-sentence explanation of each.

Acceptance criteria. - You produce four design-decision summaries. - Each captures the trade-off (what was rejected and why). - You can articulate the anti-goal (what GOMEMLIMIT is not).

Extension. Compare with Java's -Xmx (hard heap cap) and -XX:MaxRAMPercentage (soft cap as fraction of container memory). Note how GOMEMLIMIT's "soft" semantics differ from both — closer to G1's "max heap occupancy after concurrent cycle" hint.

Task 21: custom allocation tracker via runtime/metrics¶

Goal. Build a small custom tracker that polls runtime/metrics once per second, computes deltas, and graphs live heap, allocation rate, and GC pause p99 over time.

Difficulty. Staff.

Skills. runtime/metrics, time series, building a Grafana-like view in a single binary.

Setup. alloctrack/main.go. Output to stdout (text graph) or to a file (CSV).

Steps. 1. Discover relevant metric names with metrics.All(). 2. Subscribe to: /memory/classes/heap/objects:bytes, /gc/heap/allocs:bytes, /gc/heap/frees:bytes, /gc/pauses:seconds, /cpu/classes/gc/total:cpu-seconds. 3. Sample every second; compute deltas. 4. Emit CSV with timestamp, live_mb, alloc_rate_mbps, free_rate_mbps, gc_pause_p99_us, gc_cpu_pct. 5. Run the workload from Task 4 or Task 5 alongside; observe the output.

Acceptance criteria. - Program runs continuously, producing one row per second. - Allocation rate is computed correctly (delta bytes / delta seconds). - p99 pause is taken from the histogram bucket walk (Task 12). - Output can be plotted in any tool (gnuplot, Excel, paste into a Grafana panel).

// alloctrack/main.go
package main

import (
    "fmt"
    "os"
    "runtime/metrics"
    "time"
)

type sampler struct {
    samples []metrics.Sample
}

func newSampler() *sampler {
    names := []string{
        "/memory/classes/heap/objects:bytes",
        "/gc/heap/allocs:bytes",
        "/gc/heap/frees:bytes",
        "/gc/pauses:seconds",
        "/cpu/classes/gc/total:cpu-seconds",
        "/cpu/classes/total:cpu-seconds",
    }
    s := &sampler{samples: make([]metrics.Sample, len(names))}
    for i, n := range names {
        s.samples[i].Name = n
    }
    return s
}

func (s *sampler) read() {
    metrics.Read(s.samples)
}

func (s *sampler) live() uint64       { return s.samples[0].Value.Uint64() }
func (s *sampler) allocs() uint64     { return s.samples[1].Value.Uint64() }
func (s *sampler) frees() uint64      { return s.samples[2].Value.Uint64() }
func (s *sampler) gcCPU() float64     { return s.samples[4].Value.Float64() }
func (s *sampler) totalCPU() float64  { return s.samples[5].Value.Float64() }

func (s *sampler) pauseP99us() float64 {
    h := s.samples[3].Value.Float64Histogram()
    var total uint64
    for _, c := range h.Counts {
        total += c
    }
    if total == 0 {
        return 0
    }
    target := uint64(float64(total) * 0.99)
    var seen uint64
    for i, c := range h.Counts {
        seen += c
        if seen >= target {
            return h.Buckets[i+1] * 1e6
        }
    }
    return h.Buckets[len(h.Buckets)-1] * 1e6
}

func main() {
    out := os.Stdout
    fmt.Fprintln(out, "ts,live_mb,alloc_rate_mbps,free_rate_mbps,gc_pause_p99_us,gc_cpu_pct")

    prev := newSampler()
    prev.read()
    prevTime := time.Now()

    ticker := time.NewTicker(time.Second)
    defer ticker.Stop()

    // Background workload (move to a goroutine or run as separate process).
    go workload()

    for now := range ticker.C {
        cur := newSampler()
        cur.read()
        dt := now.Sub(prevTime).Seconds()
        allocRate := float64(cur.allocs()-prev.allocs()) / dt / (1 << 20)
        freeRate := float64(cur.frees()-prev.frees()) / dt / (1 << 20)
        gcCPUPct := 100 * (cur.gcCPU() - prev.gcCPU()) / (cur.totalCPU() - prev.totalCPU())
        fmt.Fprintf(out, "%d,%d,%.2f,%.2f,%.1f,%.2f\n",
            now.Unix(),
            cur.live()>>20,
            allocRate,
            freeRate,
            cur.pauseP99us(),
            gcCPUPct,
        )
        prev = cur
        prevTime = now
    }
}

func workload() {
    keep := make([][]byte, 0, 100_000)
    for {
        keep = append(keep, make([]byte, 4096))
        if len(keep) > 20_000 {
            keep = keep[len(keep)/2:]
        }
    }
}