Memory Management and Garbage Collection

package main

import "fmt"

type Book struct {
	Title string
	ISBN  string
	Pages int
}

// byValue returns a copy: nothing outlives the call.
//
//go:noinline
func byValue(title string) Book {
	return Book{Title: title, Pages: 100}
}

// byPointer returns the address of a local variable: it must escape.
//
//go:noinline
func byPointer(title string) *Book {
	b := Book{Title: title, Pages: 100}
	return &b
}

// makeBuffer sizes a slice with a variable: the backing array is heap allocated.
//
//go:noinline
func makeBuffer(n int) []byte {
	return make([]byte, n)
}

// fixedBuffer uses a constant size that does not leave the function.
//
//go:noinline
func fixedBuffer() int {
	buf := make([]byte, 64)
	buf[0] = 1
	return len(buf)
}

// describe converts a Book to an interface value to print it.
//
//go:noinline
func describe(b Book) {
	fmt.Println(b)
}

func main() {
	p := byPointer("Dune")
	fmt.Println(p.Title, len(makeBuffer(10)), fixedBuffer())
	describe(byValue("Emma"))
}

go build -gcflags=-m -o /dev/null ./e01

# example.com/shelf/e01
e01/main.go:14:14: leaking param: title to result ~r0 level=0
e01/main.go:21:16: leaking param: title
e01/main.go:22:2: moved to heap: b
e01/main.go:30:13: make([]byte, n) escapes to heap
e01/main.go:37:13: make([]byte, 64) does not escape
e01/main.go:45:15: leaking param: b
e01/main.go:46:13: ... argument does not escape
e01/main.go:46:14: b escapes to heap
e01/main.go:51:13: ... argument does not escape
e01/main.go:51:15: p.Title escapes to heap
e01/main.go:51:26: len(makeBuffer(10)) escapes to heap
e01/main.go:51:55: fixedBuffer() escapes to heap

go run ./e01

Dune 10 64
{Emma  100}

e01/main.go:22:2: b escapes to heap in byPointer:
e01/main.go:22:2:   flow: ~r0 ← &b:
e01/main.go:22:2:     from &b (address-of) at e01/main.go:23:9
e01/main.go:22:2:     from return &b (return) at e01/main.go:23:2
e01/main.go:30:13: make([]byte, n) escapes to heap in makeBuffer:
e01/main.go:30:13:   flow: ~r0 ← &{storage for make([]byte, n)}:
e01/main.go:30:13:     from make([]byte, n) (spill) at e01/main.go:30:13
e01/main.go:30:13:     from return make([]byte, n) (return) at e01/main.go:30:2

// Command e09 shows how goroutine stacks are accounted for.
package main

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

func stackBytes() uint64 {
	s := []metrics.Sample{{Name: "/memory/classes/heap/stacks:bytes"}}
	metrics.Read(s)
	return s[0].Value.Uint64()
}

func deep(n int) int {
	var pad [128]byte
	pad[0] = byte(n)
	if n == 0 {
		return int(pad[0])
	}
	return deep(n-1) + int(pad[0])
}

func startingSize() uint64 {
	s := []metrics.Sample{{Name: "/gc/stack/starting-size:bytes"}}
	metrics.Read(s)
	return s[0].Value.Uint64()
}

func main() {
	const goroutines = 10_000
	fmt.Println("starting stack size:", startingSize(), "bytes")
	before := stackBytes()

	var ready, release, done sync.WaitGroup
	ready.Add(goroutines)
	release.Add(1)
	done.Add(goroutines)
	for range goroutines {
		go func() {
			defer done.Done()
			ready.Done()
			release.Wait()
		}()
	}
	ready.Wait()
	idle := stackBytes()
	fmt.Printf("%d idle goroutines: about %d bytes of stack each\n",
		goroutines, (idle-before)/goroutines)
	release.Done()
	done.Wait()

	var ready2, release2, done2 sync.WaitGroup
	ready2.Add(goroutines)
	release2.Add(1)
	done2.Add(goroutines)
	for range goroutines {
		go func() {
			defer done2.Done()
			deep(200) // forces the stack to grow
			ready2.Done()
			release2.Wait()
		}()
	}
	ready2.Wait()
	grown := stackBytes()
	fmt.Printf("%d goroutines after deep(200): about %d bytes of stack each\n",
		goroutines, (grown-before)/goroutines)
	release2.Done()
	done2.Wait()
}

go run ./e09

starting stack size: 2048 bytes
10000 idle goroutines: about 2067 bytes of stack each
10000 goroutines after deep(200): about 65925 bytes of stack each

package alloc

import "testing"

var sinkInts []int

// makeSum sizes the slice with a variable. Go 1.25 and later keep a small
// buffer (32 bytes) on the stack when the requested size fits in it.
//
//go:noinline
func makeSum(n int) int {
	buf := make([]int, 0, n)
	for i := range 3 {
		buf = append(buf, i)
	}
	total := 0
	for _, v := range buf {
		total += v
	}
	return total
}

// appendCount grows a slice that never leaves the function and is only
// measured, so the first backing array can live on the stack.
//
//go:noinline
func appendCount(n int) int {
	var s []int
	for i := range n {
		s = append(s, i)
	}
	return len(s)
}

// appendEscaping returns the slice, so its final backing array is on the heap.
//
//go:noinline
func appendEscaping(n int) []int {
	var s []int
	for i := range n {
		s = append(s, i)
	}
	return s
}

func TestAllocs(t *testing.T) {
	run := func(name string, f func()) {
		t.Logf("%-34s %v allocs", name, testing.AllocsPerRun(100, f))
	}
	run("make([]int, 0, n) with n=3", func() { makeSum(3) })
	run("make([]int, 0, n) with n=4", func() { makeSum(4) })
	run("make([]int, 0, n) with n=1000", func() { makeSum(1000) })
	run("append x3, never leaves", func() { appendCount(3) })
	run("append x4, never leaves", func() { appendCount(4) })
	run("append x5, never leaves", func() { appendCount(5) })
	run("append x100, never leaves", func() { appendCount(100) })
	run("append x3, returned", func() { sinkInts = appendEscaping(3) })
	run("append x100, returned", func() { sinkInts = appendEscaping(100) })
}

go test -v -run TestAllocs ./e15

    main_test.go:48: make([]int, 0, n) with n=3         0 allocs
    main_test.go:48: make([]int, 0, n) with n=4         0 allocs
    main_test.go:48: make([]int, 0, n) with n=1000      1 allocs
    main_test.go:48: append x3, never leaves            0 allocs
    main_test.go:48: append x4, never leaves            0 allocs
    main_test.go:48: append x5, never leaves            1 allocs
    main_test.go:48: append x100, never leaves          5 allocs
    main_test.go:48: append x3, returned                1 allocs
    main_test.go:48: append x100, returned              5 allocs
--- PASS: TestAllocs (0.00s)
PASS
ok  	example.com/shelf/e15	0.218s

go test -v -run TestAllocs -gcflags=all=-d=variablemakehash=n ./e15

    main_test.go:48: make([]int, 0, n) with n=3         1 allocs
    main_test.go:48: make([]int, 0, n) with n=4         1 allocs
    main_test.go:48: make([]int, 0, n) with n=1000      1 allocs
    main_test.go:48: append x3, never leaves            3 allocs
    main_test.go:48: append x4, never leaves            3 allocs
    main_test.go:48: append x5, never leaves            4 allocs
    main_test.go:48: append x100, never leaves          8 allocs
    main_test.go:48: append x3, returned                3 allocs
    main_test.go:48: append x100, returned              8 allocs

package smallalloc

import "testing"

type node16 struct {
	next *node16
	v    int
}
type node48 struct {
	a, b, c, d, e *int
	f             int
}
type node80 struct {
	p [9]*int
	n int
}
type big struct{ p [64]*int }

var (
	sink16 *node16
	sink48 *node48
	sink80 *node80
	sinkBg *big
)

func BenchmarkNew(b *testing.B) {
	b.Run("16B", func(b *testing.B) {
		for b.Loop() {
			sink16 = new(node16)
		}
	})
	b.Run("48B", func(b *testing.B) {
		for b.Loop() {
			sink48 = new(node48)
		}
	})
	b.Run("80B", func(b *testing.B) {
		for b.Loop() {
			sink80 = new(node80)
		}
	})
	b.Run("512B", func(b *testing.B) {
		for b.Loop() {
			sinkBg = new(big)
		}
	})
}

go test -bench New -benchtime=500ms -run '^$' ./e17
GOEXPERIMENT=nosizespecializedmalloc go test -bench New -benchtime=500ms -run '^$' ./e17

BenchmarkNew/16B-10         	57477457	        12.12 ns/op
BenchmarkNew/48B-10         	35650534	        17.30 ns/op
BenchmarkNew/80B-10         	25595221	        23.15 ns/op
BenchmarkNew/512B-10        	 4543778	       138.0 ns/op

BenchmarkNew/16B-10         	31283060	        20.08 ns/op
BenchmarkNew/48B-10         	24890756	        24.26 ns/op
BenchmarkNew/80B-10         	19992918	        29.32 ns/op
BenchmarkNew/512B-10        	 5286535	       116.7 ns/op

// Command e07 builds one million small records twice: as a slice of values
// and as a slice of pointers, and times a forced collection for each.
package main

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

type Loan struct {
	BookID   int64
	MemberID int64
	Due      int64
}

func timeGC() time.Duration {
	start := time.Now()
	runtime.GC()
	return time.Since(start)
}

func main() {
	const n = 2_000_000

	values := make([]Loan, n)
	for i := range values {
		values[i] = Loan{BookID: int64(i), MemberID: 1, Due: 2}
	}
	runtime.GC() // settle
	d := timeGC()
	fmt.Printf("[]Loan  (1 object, no pointers): GC took %v\n", d.Round(100*time.Microsecond))
	runtime.KeepAlive(values)
	values = nil

	ptrs := make([]*Loan, n)
	for i := range ptrs {
		ptrs[i] = &Loan{BookID: int64(i), MemberID: 1, Due: 2}
	}
	runtime.GC()
	d = timeGC()
	fmt.Printf("[]*Loan (%d objects, pointers):   GC took %v\n", n, d.Round(100*time.Microsecond))
	runtime.KeepAlive(ptrs)
}

go run ./e07

[]Loan  (1 object, no pointers): GC took 100µs
[]*Loan (2000000 objects, pointers):   GC took 4.2ms

// Command e10 derives a memory limit from the memory the container is
// allowed to use and applies it with runtime/debug.
package main

import (
	"fmt"
	"math"
	"os"
	"runtime/debug"
	"strconv"
)

// limitFromEnv leaves 10% headroom for memory the Go runtime does not manage
// (C allocations, the binary mappings, kernel buffers).
func limitFromEnv(name string) (int64, bool) {
	v, ok := os.LookupEnv(name)
	if !ok {
		return 0, false
	}
	total, err := strconv.ParseInt(v, 10, 64)
	if err != nil || total <= 0 {
		return 0, false
	}
	return total / 10 * 9, true
}

func main() {
	if limit, ok := limitFromEnv("SHELFD_CONTAINER_MEMORY_BYTES"); ok {
		prev := debug.SetMemoryLimit(limit)
		fmt.Printf("memory limit: %d MiB (was %d)\n", limit>>20, prev)
	} else {
		fmt.Println("memory limit: unchanged")
	}
	// SetMemoryLimit(-1) reads the current value without changing it.
	cur := debug.SetMemoryLimit(-1)
	// SetGCPercent returns the previous value; restore it straight away to
	// read the current setting.
	pct := debug.SetGCPercent(100)
	debug.SetGCPercent(pct)
	if cur == math.MaxInt64 {
		fmt.Printf("GOGC=%d, no limit\n", pct)
		return
	}
	fmt.Printf("GOGC=%d, limit=%d MiB\n", pct, cur>>20)
}

go run ./e10
SHELFD_CONTAINER_MEMORY_BYTES=536870912 go run ./e10

$ go run ./e10
memory limit: unchanged
GOGC=100, no limit
$ SHELFD_CONTAINER_MEMORY_BYTES=536870912 go run ./e10
memory limit: 460 MiB (was 9223372036854775807)
GOGC=100, limit=460 MiB

containers:
  - name: shelfd
    image: registry.example.com/shelf/shelfd:1.0.0
    resources:
      limits:
        memory: 512Mi
    env:
      - name: GOMEMLIMIT
        value: 450MiB

package e04

import (
	"bytes"
	"strconv"
	"strings"
	"sync"
)

// Book is a trimmed-down catalog.Book.
type Book struct {
	Title string
	Pages int
}

// TitlesGrow lets append discover the final size by doubling.
func TitlesGrow(books []Book) []string {
	var out []string
	for _, b := range books {
		out = append(out, b.Title)
	}
	return out
}

// TitlesPrealloc allocates the final backing array once.
func TitlesPrealloc(books []Book) []string {
	out := make([]string, 0, len(books))
	for _, b := range books {
		out = append(out, b.Title)
	}
	return out
}

// JoinConcat builds a string with += and allocates for every step.
func JoinConcat(titles []string) string {
	s := ""
	for _, t := range titles {
		s += t + ";"
	}
	return s
}

// JoinBuilder reserves the final size and fills it in place.
func JoinBuilder(titles []string) string {
	n := 0
	for _, t := range titles {
		n += len(t) + 1
	}
	var sb strings.Builder
	sb.Grow(n)
	for _, t := range titles {
		sb.WriteString(t)
		sb.WriteByte(';')
	}
	return sb.String()
}

// RenderNew allocates a fresh buffer on every call.
func RenderNew(b Book) int {
	buf := new(bytes.Buffer)
	buf.WriteString(b.Title)
	buf.WriteByte(':')
	buf.WriteString(strconv.Itoa(b.Pages))
	buf.WriteString(padding)
	return buf.Len()
}

// padding makes every rendered record larger than a small buffer.
var padding = strings.Repeat("-", 4096)

var bufPool = sync.Pool{New: func() any { return new(bytes.Buffer) }}

// RenderPooled reuses buffers through a sync.Pool.
func RenderPooled(b Book) int {
	buf := bufPool.Get().(*bytes.Buffer)
	buf.Reset()
	defer bufPool.Put(buf)
	buf.WriteString(b.Title)
	buf.WriteByte(':')
	buf.WriteString(strconv.Itoa(b.Pages))
	buf.WriteString(padding)
	return buf.Len()
}

package e04

import (
	"fmt"
	"testing"
)

func sample(n int) []Book {
	books := make([]Book, n)
	for i := range books {
		books[i] = Book{Title: fmt.Sprintf("Title %04d", i), Pages: 100 + i}
	}
	return books
}

func BenchmarkTitles(b *testing.B) {
	books := sample(1000)
	b.Run("grow", func(b *testing.B) {
		b.ReportAllocs()
		for b.Loop() {
			TitlesGrow(books)
		}
	})
	b.Run("prealloc", func(b *testing.B) {
		b.ReportAllocs()
		for b.Loop() {
			TitlesPrealloc(books)
		}
	})
}

func BenchmarkJoin(b *testing.B) {
	titles := make([]string, 200)
	for i := range titles {
		titles[i] = fmt.Sprintf("Title %04d", i)
	}
	b.Run("concat", func(b *testing.B) {
		b.ReportAllocs()
		for b.Loop() {
			JoinConcat(titles)
		}
	})
	b.Run("builder", func(b *testing.B) {
		b.ReportAllocs()
		for b.Loop() {
			JoinBuilder(titles)
		}
	})
}

func BenchmarkRender(b *testing.B) {
	book := Book{Title: "Dune", Pages: 412}
	b.Run("new", func(b *testing.B) {
		b.ReportAllocs()
		for b.Loop() {
			RenderNew(book)
		}
	})
	b.Run("pooled", func(b *testing.B) {
		b.ReportAllocs()
		for b.Loop() {
			RenderPooled(book)
		}
	})
}

func TestAllocs(t *testing.T) {
	books := sample(1000)
	if got := testing.AllocsPerRun(100, func() { TitlesPrealloc(books) }); got != 1 {
		t.Errorf("TitlesPrealloc allocs = %v, want 1", got)
	}
}

go test -bench . -benchtime=200ms -run '^$' ./e04

goos: darwin
goarch: arm64
pkg: example.com/shelf/e04
cpu: Apple M5
BenchmarkTitles/grow-10         	   53587	      4624 ns/op	   35184 B/op	      11 allocs/op
BenchmarkTitles/prealloc-10     	  101347	      2329 ns/op	   16384 B/op	       1 allocs/op
BenchmarkJoin/concat-10         	    5263	     44027 ns/op	  235274 B/op	     200 allocs/op
BenchmarkJoin/builder-10        	  120019	      2201 ns/op	    2304 B/op	       1 allocs/op
BenchmarkRender/new-10          	  374056	       699.9 ns/op	    4931 B/op	       3 allocs/op
BenchmarkRender/pooled-10       	 2235078	       107.0 ns/op	       3 B/op	       1 allocs/op
PASS
ok  	example.com/shelf/e04	1.552s

// Command e11 shows that sync.Pool is emptied by the garbage collector.
package main

import (
	"fmt"
	"runtime"
	"sync"
)

func main() {
	// One P keeps the example deterministic: a Pool keeps a separate cache
	// for every P, and a goroutine that migrates would miss its own items.
	runtime.GOMAXPROCS(1)

	created := 0
	pool := sync.Pool{New: func() any {
		created++
		return new([4096]byte)
	}}

	b := pool.Get().(*[4096]byte)
	pool.Put(b)
	fmt.Println("created after first Get:", created)

	b = pool.Get().(*[4096]byte) // reused
	pool.Put(b)
	fmt.Println("created after reuse:", created)

	runtime.GC() // moves items to the victim cache
	b = pool.Get().(*[4096]byte)
	pool.Put(b)
	fmt.Println("created after one GC:", created)

	runtime.GC()
	runtime.GC() // victim cache dropped
	b = pool.Get().(*[4096]byte)
	fmt.Println("created after more GCs:", created)
	_ = b
}

go run ./e11

created after first Get: 1
created after reuse: 1
created after one GC: 1
created after more GCs: 2

package main

import (
	"bytes"
	"fmt"
	"runtime"
)

// heapMiB forces a collection and reports the live heap in MiB.
func heapMiB() uint64 {
	runtime.GC()
	var ms runtime.MemStats
	runtime.ReadMemStats(&ms)
	return ms.HeapAlloc >> 20
}

// load pretends to read a 1 MiB record and returns it.
func load(i int) []byte {
	rec := make([]byte, 1<<20)
	copy(rec, fmt.Sprintf("REC%04d", i))
	return rec
}

func main() {
	base := heapMiB()

	// Keeps only the 7-byte header, but the slice still points into the
	// 1 MiB backing array, so the whole record stays reachable.
	var headers [][]byte
	for i := range 50 {
		rec := load(i)
		headers = append(headers, rec[:7])
	}
	fmt.Printf("sub-slices of records:  +%d MiB\n", heapMiB()-base)
	runtime.KeepAlive(headers) // headers is live up to this point

	headers = nil
	fmt.Printf("after dropping them:    +%d MiB\n", heapMiB()-base)

	// Copies the header: the record can be collected.
	for i := range 50 {
		rec := load(i)
		headers = append(headers, bytes.Clone(rec[:7]))
	}
	fmt.Printf("cloned headers:         +%d MiB\n", heapMiB()-base)
	runtime.KeepAlive(headers)
}

go run ./e05

sub-slices of records:  +50 MiB
after dropping them:    +0 MiB
cloned headers:         +0 MiB

package main

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

func main() {
	var keep [][]byte
	for i := range 40 {
		keep = append(keep, make([]byte, 1<<20))
		keep[i][0] = 1
	}
	runtime.GC()

	names := []string{
		"/gc/gogc:percent",
		"/gc/gomemlimit:bytes",
		"/gc/cycles/total:gc-cycles",
		"/gc/heap/live:bytes",
		"/gc/heap/goal:bytes",
		"/gc/heap/allocs:objects",
		"/memory/classes/total:bytes",
		"/memory/classes/heap/released:bytes",
		"/cpu/classes/gc/total:cpu-seconds",
	}
	samples := make([]metrics.Sample, len(names))
	for i, n := range names {
		samples[i].Name = n
	}
	metrics.Read(samples)

	for _, s := range samples {
		switch s.Value.Kind() {
		case metrics.KindUint64:
			fmt.Printf("%-40s %d\n", s.Name, s.Value.Uint64())
		case metrics.KindFloat64:
			fmt.Printf("%-40s %.4f\n", s.Name, s.Value.Float64())
		case metrics.KindBad:
			fmt.Printf("%-40s not supported\n", s.Name)
		}
	}

	for _, d := range metrics.All() {
		if strings.HasPrefix(d.Name, "/sched/pauses/") {
			fmt.Println(d.Name)
		}
	}
	runtime.KeepAlive(keep)
}

go run ./e03

/gc/gogc:percent                         100
/gc/gomemlimit:bytes                     9223372036854775807
/gc/cycles/total:gc-cycles               5
/gc/heap/live:bytes                      42167440
/gc/heap/goal:bytes                      84523018
/gc/heap/allocs:objects                  347
/memory/classes/total:bytes              55007512
/memory/classes/heap/released:bytes      7110656
/cpu/classes/gc/total:cpu-seconds        0.0010
/sched/pauses/stopping/gc:seconds
/sched/pauses/stopping/other:seconds
/sched/pauses/total/gc:seconds
/sched/pauses/total/other:seconds

// Command e13 serves a few runtime/metrics values as JSON, the way a
// diagnostics endpoint of cmd/shelfd could.
package main

import (
	"encoding/json"
	"fmt"
	"io"
	"net/http"
	"net/http/httptest"
	"runtime"
	"runtime/metrics"
)

var names = []string{
	"/gc/heap/live:bytes",
	"/gc/heap/goal:bytes",
	"/gc/cycles/total:gc-cycles",
	"/memory/classes/total:bytes",
	"/sched/goroutines:goroutines",
}

func metricsHandler(w http.ResponseWriter, _ *http.Request) {
	samples := make([]metrics.Sample, len(names))
	for i, n := range names {
		samples[i].Name = n
	}
	metrics.Read(samples)

	out := make(map[string]uint64, len(samples))
	for _, s := range samples {
		if s.Value.Kind() == metrics.KindUint64 {
			out[s.Name] = s.Value.Uint64()
		}
	}
	w.Header().Set("Content-Type", "application/json")
	json.NewEncoder(w).Encode(out)
}

func main() {
	keep := make([]byte, 8<<20)
	runtime.GC()
	defer runtime.KeepAlive(keep)

	srv := httptest.NewServer(http.HandlerFunc(metricsHandler))
	defer srv.Close()

	resp, err := http.Get(srv.URL)
	if err != nil {
		fmt.Println(err)
		return
	}
	defer resp.Body.Close()
	body, _ := io.ReadAll(resp.Body)
	fmt.Print(string(body))
}

go run ./e13

{"/gc/cycles/total:gc-cycles":2,"/gc/heap/goal:bytes":17547114,"/gc/heap/live:bytes":8655248,"/memory/classes/total:bytes":21907720,"/sched/goroutines:goroutines":22}

go test -run '^$' -bench Join -benchtime=100ms -memprofile mem.out -memprofilerate=1 ./e04
go tool pprof -sample_index=alloc_space -top -nodecount=6 e04.test mem.out

File: e04.test
Type: alloc_space
Time: 2026-10-18 03:20:39 CEST
Showing nodes accounting for 283500.10kB, 99.92% of 283726.79kB total
Dropped 162 nodes (cum <= 1418.63kB)
Showing top 6 nodes out of 9
      flat  flat%   sum%        cum   cum%
164276.84kB 57.90% 57.90% 164276.84kB 57.90%  example.com/shelf/e04.JoinConcat (inline)
  119223kB 42.02% 99.92%   119223kB 42.02%  internal/bytealg.MakeNoZero
    0.27kB 9.4e-05% 99.92% 283633.72kB   100%  testing.(*B).runN
         0     0% 99.92% 164276.84kB 57.90%  example.com/shelf/e04.BenchmarkJoin.func1
         0     0% 99.92%   119223kB 42.02%  example.com/shelf/e04.BenchmarkJoin.func2
         0     0% 99.92%   119223kB 42.02%  example.com/shelf/e04.JoinBuilder