go-perf-data-oriented-layout

name	go-perf-data-oriented-layout
description	Guides data-oriented memory layout in Go — Struct-of-Arrays vs Array-of-Structs and when SoA wins (scan one field over many records, fewer cache lines), why []T beats []*T (a pointer slice scatters objects and adds GC scan work; []T is contiguous and noscan), replacing pointer-chasing lists/trees with int32 indices. Fires on cache-friendly layout, struct of arrays, slice of pointers is slow, data-oriented design. Routes field packing to go-perf-struct-layout, GC-scan to go-perf-allocator-internals, SIMD to go-perf-simd.
allowed-tools	Read, Glob, Grep
compatibility	Claude Code, Codex CLI, Gemini CLI

Go Performance: Data-Oriented Layout

"Data dominates. If you've chosen the right data structures and organized things well, the algorithms will almost always be self-evident." — Rob Pike, Notes on Programming in C

This skill owns one lever: lay data out so the hot loop touches the fewest cache lines and the GC scans the fewest pointers. It is the cache-and-access-pattern peer of go-perf-struct-layout (which owns field ordering and padding within one struct). Correctness of slices/maps routes to go-slices-and-maps; the should-I-even-bother gate routes to go-perf-methodology — these are big wins only in hot, data-parallel loops a profile has already proven dominant, and they trade type-safety and readability for speed.

All Go below builds clean under gofmt and go vet on Go 1.26.

---

1. The mental model: the cache, not the CPU, is the bottleneck

A modern core can do dozens of arithmetic ops in the time one DRAM miss costs. So the layout question is "how many cache lines does this loop drag in, and how predictably?" — not "how many instructions." go-perfbook puts the access-pattern rule plainly: "caches prefer the predictable access of scanning a slice to the effectively random access of chasing a pointer" (go-perfbook). Two consequences drive everything below:

• Contiguous + sequential lets the hardware prefetcher run ahead; scattered + pointer-chased stalls on every miss.
• Pointers cost the GC. "More pointers means more GC work, because at minimum the GC needs to visit all the pointers in the program" (GC Guide). Pointer-free data lands in noscan spans the collector never walks (depth → go-perf-allocator-internals).

---

2. Struct-of-Arrays vs Array-of-Structs

When a loop reads one field across many elements, Array-of-Structs ([]Particle) drags every cold field of each element through cache; Struct-of-Arrays packs the hot field contiguously so the loop streams only what it uses. go-perfbook frames it as "SOA vs AOS layouts: row-major vs. column major" and asks the decisive question: "when you have an X, do you need another X or do you need a Y?" (go-perfbook). Iterating one field over many records → you need the next X, so pack the X's together.

// AoS: 48 bytes/elem. A one-field sum still pulls every cold field
// (Y, Z, velocities) through cache — wasted bandwidth.
type Particle struct {
	X, Y, Z    float64
	VX, VY, VZ float64
}

func sumXAoS(ps []Particle) float64 {
	var s float64
	for i := range ps {
		s += ps[i].X
	}
	return s
}

// SoA: X is packed contiguously. The loop streams one tight []float64,
// touches the minimum cache lines, and autovectorizes cleanly (→ go-perf-simd).
type Particles struct {
	X, Y, Z    []float64
	VX, VY, VZ []float64
}

func sumXSoA(p Particles) float64 {
	var s float64
	for _, x := range p.X {
		s += x
	}
	return s
}

Measured (Go 1.26, Ryzen 5950X, summing one field over 2²⁰ elements): for the 48-byte Particle above, SoA ran ~2.83 ms vs AoS ~3.5 ms (~1.2×). Widen the struct to 128 bytes (one hot field + 15 cold) and the gap opens to ~1.7× (AoS ~4.9 ms → SoA ~2.85 ms). The tell is in the shape: SoA's time is flat (~2.85 ms) regardless of struct width because it always streams the same packed array; AoS gets slower the more cold data each element carries. SoA wins exactly in proportion to the cold bytes you stop dragging — so it's worth it for wide records iterated field-wise, and pointless when the loop reads most fields of each element anyway.

---

3. []T vs []*T — a slice of pointers is two penalties

[]*Account stores contiguous headers, but each element is a separate heap object reached by an indirection. That is random access (cache misses on every dereference) and a slice full of pointers the GC must scan. []Account lays the values out contiguously, prefetches predictably, and — if Account is pointer-free — the whole backing array is noscan.

type Account struct {
	Balance int64
	ID      int64 // pointer-free → []Account is a noscan span
}

func totalPtr(as []*Account) int64 { // scattered heap objects + GC scans every *Account
	var t int64
	for _, a := range as {
		t += a.Balance
	}
	return t
}

func totalVal(as []Account) int64 { // contiguous, prefetch-friendly, noscan
	var t int64
	for i := range as {
		t += as[i].Balance
	}
	return t
}

The GC Guide makes the scan cost explicit: "Pointer-free values are segregated from other values. As a result, it may be advantageous to eliminate pointers from data structures that do not strictly need them, as this reduces the cache pressure the GC exerts on the program" (GC Guide). Prefer []T of values; reach for []*T only when elements are large, individually mutated through shared aliases, or genuinely polymorphic.

---

4. Replace pointer-chasing structures with indices-into-a-slice

Linked lists and pointer trees are the worst case: every node is a separate heap allocation, every link is a GC-scanned pointer, and traversal is a chain of cache misses. The fix is indices as pointers — keep all nodes in one contiguous []Node and link them by int32 offset. The slice is pointer-free (noscan), dense, and prefetch-friendly. The GC Guide endorses exactly this: "the GC must interact with nearly every pointer it sees, so using indices into a[n] slice, for example, instead of pointers, can aid in reducing GC costs," and "data structures that rely on indices over pointer values, while less well-typed, may perform better" (GC Guide).

// Pointer tree: each child is a heap object and a scanned pointer; random-access misses.
type NodeP struct {
	Val         int64
	Left, Right *NodeP
}

// Index tree: all nodes in one noscan []Node; -1 is the nil sentinel.
type Node struct {
	Val         int64
	Left, Right int32 // index into the backing slice; -1 == none
}

type Tree struct{ nodes []Node }

func (t *Tree) add(val int64) int32 {
	t.nodes = append(t.nodes, Node{Val: val, Left: -1, Right: -1})
	return int32(len(t.nodes) - 1)
}

int32 handles also halve the link size versus 64-bit pointers, packing more nodes per cache line. Measured framing matters here — the same guide warns this "is only worth doing if it's clear that the object graph is complex and the GC is spending a lot of time marking and scanning" (GC Guide). Confirm with a heap profile / GC trace before trading away *T type-safety; route the judgment to go-perf-methodology.

---

5. Ring buffers and arena-style index slabs

The same idea generalizes to allocation-free reuse:

• Ring buffer over a fixed []T instead of container/list (which allocates a node and stores interface-boxed pointers per element). Contiguous, pointer-free, zero per-op allocation.
• Arena / slab: append nodes into one []T and hand out int32 handles instead of *T. The slab is dense and noscan; freeing a whole short-lived graph is one s.buf = s.buf[:0] that keeps the capacity — no per-node GC churn (slice reuse mechanics → go-perf-slices).

// Slab: int32 handles, not *Node. Dense, noscan, freed en masse by reslicing.
type Slab struct{ buf []Node }

func (s *Slab) alloc(n Node) int32 {
	s.buf = append(s.buf, n)
	return int32(len(s.buf) - 1)
}

func (s *Slab) get(h int32) *Node { return &s.buf[h] }
func (s *Slab) reset()            { s.buf = s.buf[:0] } // reuse capacity, no GC work

One caveat the index model buys you: a handle stays valid across a growslice, whereas a *Node into s.buf dangles after the backing array moves — so don't hold *Node across an alloc.

---

6. Batch work to stay in cache

When several passes each touch the same large dataset, fuse them: do all the work on a block while it is resident in L1/L2 before moving on, instead of streaming the whole array once per pass. go-perfbook notes "iterating in batches over data structures can be much faster" (go-perfbook). The flip side is the lookup-table trap — precomputed tables can lose to recomputation: "It's very easy for lookup tables to be 'far away' in memory (and therefore expensive to access) making it faster to just recompute a value every time it's needed" (go-perfbook). A cache miss costs more than a handful of ALU ops, so a "fast" table that lives in cold memory can be slower than the arithmetic it replaced.

---

7. Don't

• Don't reorganize layout without a profile. These wins live in hot, data-parallel loops only; a cold path pays the readability cost for nothing (Amdahl) — gate it through go-perf-methodology.
• Don't default to []*T for a collection of small values you iterate — it scatters the heap and adds GC scan work; use []T (GC Guide).
• Don't reach for SoA when the loop reads most fields of each element — you gain nothing and lose the natural struct grouping. SoA pays off in proportion to the cold bytes skipped (§2).
• Don't index-encode a pointer graph "to be fast" absent evidence the GC is mark/scan-bound — the guide gates it on a complex graph and measured GC time (GC Guide).
• Don't keep *T into a slab/slice across an append — a growslice moves the backing array and dangles the pointer; hold the int32 handle instead (§5).
• Don't use container/list/container/ring on a hot path — per-node allocation and interface boxing; a slice-backed ring buffer is contiguous and allocation-free (§5).
• Don't assume a precomputed lookup table is free — if it sits in cold memory, recomputation can win (go-perfbook).

---

8. Routing to Related Skills

This plugin (go-perf-* depth):

• go-perf-struct-layout — field ordering, alignment, and padding within a single struct; fieldalignment; pointer-free structs.
• go-perf-allocator-internals — noscan vs scan spans, size classes, and what makes a span GC-free; the allocator path behind "noscan."
• go-perf-slices — growslice, make([]T, 0, n) prealloc, s = s[:0] reuse, slice-backed ring buffers as a throughput lever.
• go-perf-simd — vectorizing the tight SoA loop SoA makes possible (GOEXPERIMENT=simd, 1.26).
• go-perf-bounds-check-elimination — dropping the per-iteration bounds check in the hot index loop.
• go-perf-false-sharing — when concurrent per-shard fields share a cache line (a different cache problem).
• go-perf-methodology — the measure-first gate: is this loop actually the bottleneck, and did the relayout measurably help?

Parent / sibling marketplace (go-* correctness):

• go-slices-and-maps — slice aliasing, append semantics, 3-index slices, Clone/Clip, nil maps — the correctness layer under the perf depth here.

---

9. Reference Files

Data-layout anti-patterns in LLM-generated Go, each with a wrong/right contrast and citations:

${CLAUDE_SKILL_DIR}/references/common-mistakes.md

Source provenance for every claim in this skill:

${CLAUDE_SKILL_DIR}/references/sources.yaml