Memory Management

Advanced ~50 min read

Understanding Go's memory management is crucial for writing high-performance applications. This lesson covers stack vs heap allocation, garbage collection, memory profiling with pprof, and optimization techniques to minimize allocations and reduce GC pressure.

Figure: Go Memory Management - Stack, Heap, and Garbage Collection

Stack vs Heap Allocation

Go automatically decides where to allocate memory based on escape analysis:

package main

import (
	"fmt"
	"runtime"
)

// Stack allocation - value stays on stack
func stackAllocation() int {
	x := 42 // Allocated on stack
	return x
}

// Heap allocation - value escapes to heap
func heapAllocation() *int {
	x := 42 // Escapes to heap (returned pointer)
	return &x
}

// Large struct on stack
type SmallStruct struct {
	a, b int
}

func smallOnStack() SmallStruct {
	s := SmallStruct{a: 1, b: 2}
	return s // Returned by value, stays on stack
}

// Large struct escapes to heap
type LargeStruct struct {
	data [1000]int
}

func largeOnHeap() *LargeStruct {
	s := &LargeStruct{} // Large allocation, goes to heap
	return s
}

func printMemStats() {
	var m runtime.MemStats
	runtime.ReadMemStats(&m)
	fmt.Printf("Alloc = %v MB", m.Alloc/1024/1024)
	fmt.Printf("\tTotalAlloc = %v MB", m.TotalAlloc/1024/1024)
	fmt.Printf("\tSys = %v MB", m.Sys/1024/1024)
	fmt.Printf("\tNumGC = %v\n", m.NumGC)
}

func main() {
	fmt.Println("Stack vs Heap Allocation Demo")
	fmt.Println("==============================\n")

// Stack allocation
	fmt.Println("Stack allocation:")
	val := stackAllocation()
	fmt.Printf("Value: %d (on stack)\n\n", val)

// Heap allocation
	fmt.Println("Heap allocation:")
	ptr := heapAllocation()
	fmt.Printf("Value: %d (on heap, pointer: %p)\n\n", *ptr, ptr)

// Small struct on stack
	fmt.Println("Small struct (stack):")
	small := smallOnStack()
	fmt.Printf("Struct: %+v\n\n", small)

// Large struct on heap
	fmt.Println("Large struct (heap):")
	large := largeOnHeap()
	fmt.Printf("Struct pointer: %p\n\n", large)

// Memory stats
	fmt.Println("Memory Statistics:")
	printMemStats()
}

Output

Click Run to execute your code

Aspect	Stack	Heap
Speed	✅ Very fast	⚠️ Slower
Management	✅ Automatic (function scope)	⚠️ Garbage collected
Size	⚠️ Limited (per goroutine)	✅ Large, flexible
Lifetime	⚠️ Function scope only	✅ Until GC collects

Garbage Collection

Go uses a concurrent, tri-color mark-and-sweep garbage collector:

package main

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

func allocateMemory() {
	// Allocate many small objects
	for i := 0; i < 1000000; i++ {
		_ = make([]byte, 100)
	}
}

func printGCStats() {
	var m runtime.MemStats
	runtime.ReadMemStats(&m)

fmt.Printf("GC Stats:\n")
	fmt.Printf("  NumGC: %d\n", m.NumGC)
	fmt.Printf("  PauseTotal: %v ms\n", float64(m.PauseTotalNs)/1e6)
	fmt.Printf("  HeapAlloc: %v MB\n", m.HeapAlloc/1024/1024)
	fmt.Printf("  HeapSys: %v MB\n", m.HeapSys/1024/1024)
	fmt.Printf("  HeapIdle: %v MB\n", m.HeapIdle/1024/1024)
	fmt.Printf("  HeapInuse: %v MB\n", m.HeapInuse/1024/1024)
	fmt.Printf("  NextGC: %v MB\n\n", m.NextGC/1024/1024)
}

func main() {
	fmt.Println("Garbage Collection Demo")
	fmt.Println("========================\n")

// Initial stats
	fmt.Println("Before allocation:")
	printGCStats()

// Allocate memory
	fmt.Println("Allocating 1M objects...")
	allocateMemory()

fmt.Println("\nAfter allocation (before GC):")
	printGCStats()

// Force garbage collection
	fmt.Println("Running GC...")
	runtime.GC()

fmt.Println("\nAfter GC:")
	printGCStats()

// Watch GC over time
	fmt.Println("Watching GC for 5 seconds...")
	ticker := time.NewTicker(time.Second)
	defer ticker.Stop()

count := 0
	for range ticker.C {
		allocateMemory()
		count++
		fmt.Printf("Iteration %d - NumGC: ", count)
		var m runtime.MemStats
		runtime.ReadMemStats(&m)
		fmt.Printf("%d, HeapAlloc: %v MB\n", m.NumGC, m.HeapAlloc/1024/1024)

if count >= 5 {
			break
		}
	}

fmt.Println("\nFinal stats:")
	printGCStats()
}

Output

Click Run to execute your code

GC Phases:

Mark - Find all reachable objects
Sweep - Free unreachable memory
Concurrent - Runs alongside your program

Memory Profiling with pprof

Use pprof to identify memory hotspots and optimize allocations:

package main

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

type Data struct {
	values []int
}

func allocateData(n int) []*Data {
	data := make([]*Data, n)
	for i := 0; i < n; i++ {
		data[i] = &Data{
			values: make([]int, 1000),
		}
	}
	return data
}

func profileMemory() {
	// Create memory profile
	f, err := os.Create("mem.prof")
	if err != nil {
		fmt.Println("Could not create memory profile:", err)
		return
	}
	defer f.Close()

runtime.GC() // Get up-to-date statistics
	if err := pprof.WriteHeapProfile(f); err != nil {
		fmt.Println("Could not write memory profile:", err)
	}

fmt.Println("Memory profile written to mem.prof")
	fmt.Println("Analyze with: go tool pprof mem.prof")
}

func main() {
	fmt.Println("Memory Profiling Demo")
	fmt.Println("=====================\n")

// Initial memory stats
	var m runtime.MemStats
	runtime.ReadMemStats(&m)
	fmt.Printf("Initial HeapAlloc: %v MB\n\n", m.HeapAlloc/1024/1024)

// Allocate memory
	fmt.Println("Allocating 10,000 Data objects...")
	data := allocateData(10000)

runtime.ReadMemStats(&m)
	fmt.Printf("After allocation: %v MB\n\n", m.HeapAlloc/1024/1024)

// Keep data alive
	fmt.Printf("Allocated %d objects\n", len(data))

// Profile memory
	fmt.Println("\nCreating memory profile...")
	profileMemory()

fmt.Println("\nTo analyze the profile:")
	fmt.Println("  1. go tool pprof mem.prof")
	fmt.Println("  2. Type 'top' to see top memory consumers")
	fmt.Println("  3. Type 'list main' to see line-by-line allocation")
	fmt.Println("  4. Type 'web' to visualize (requires graphviz)")
}

Output

Click Run to execute your code

pprof Commands:

# Create profile
go test -memprofile=mem.prof

# Analyze profile
go tool pprof mem.prof

# Interactive commands:
top       # Show top memory consumers
list main # Show line-by-line allocation
web       # Visualize (requires graphviz)

Object Reuse with sync.Pool

Reduce allocations by reusing objects with sync.Pool:

package main

import (
	"fmt"
	"sync"
)

type Buffer struct {
	data []byte
}

var bufferPool = sync.Pool{
	New: func() interface{} {
		// Create new buffer when pool is empty
		return &Buffer{
			data: make([]byte, 1024),
		}
	},
}

func processWithoutPool(n int) {
	for i := 0; i < n; i++ {
		// Allocate new buffer each time
		buf := &Buffer{
			data: make([]byte, 1024),
		}
		// Use buffer
		_ = buf
		// Buffer is garbage collected
	}
}

func processWithPool(n int) {
	for i := 0; i < n; i++ {
		// Get buffer from pool
		buf := bufferPool.Get().(*Buffer)

// Use buffer
		_ = buf

// Return buffer to pool
		bufferPool.Put(buf)
	}
}

func benchmark(name string, fn func(int), iterations int) {
	fmt.Printf("\n%s:\n", name)

// Run and time
	start := make(chan struct{})
	done := make(chan struct{})

go func() {
		<-start
		fn(iterations)
		close(done)
	}()

close(start)
	<-done

fmt.Printf("Completed %d iterations\n", iterations)
}

func main() {
	fmt.Println("sync.Pool Optimization Demo")
	fmt.Println("============================\n")

iterations := 1000000

fmt.Println("Processing without pool (allocates every time):")
	benchmark("Without Pool", processWithoutPool, iterations)

fmt.Println("\nProcessing with pool (reuses buffers):")
	benchmark("With Pool", processWithPool, iterations)

fmt.Println("\nBenefits of sync.Pool:")
	fmt.Println("  ✓ Reduces allocations")
	fmt.Println("  ✓ Reduces GC pressure")
	fmt.Println("  ✓ Improves performance")
	fmt.Println("  ✓ Reuses memory")

fmt.Println("\nBest practices:")
	fmt.Println("  • Use for frequently allocated objects")
	fmt.Println("  • Reset object state before Put()")
	fmt.Println("  • Don't rely on objects staying in pool")
	fmt.Println("  • Pool is safe for concurrent use")
}

Output

Click Run to execute your code

sync.Pool Best Practices:

Use for frequently allocated, short-lived objects
Reset object state before Put()
Don't rely on objects staying in pool
Pool is safe for concurrent use
Objects may be garbage collected at any time

Understanding Escape Analysis

The compiler analyzes whether variables can stay on the stack or must escape to the heap:

package main

import "fmt"

// Stays on stack - returned by value
func noEscape() int {
	x := 42
	return x
}

// Escapes to heap - pointer returned
func escapesPointer() *int {
	x := 42
	return &x // x escapes to heap
}

// Escapes to heap - stored in interface
func escapesInterface() interface{} {
	x := 42
	return x // x escapes to heap
}

// Escapes to heap - captured by closure
func escapesClosure() func() int {
	x := 42
	return func() int {
		return x // x escapes to heap
	}
}

// Escapes to heap - too large for stack
func escapesSize() *[1000000]int {
	var arr [1000000]int
	return &arr // Too large, goes to heap
}

// Stays on stack - slice with known size
func noEscapeSlice() {
	s := make([]int, 10) // Small, stays on stack
	s[0] = 1
}

// Escapes to heap - slice size unknown at compile time
func escapesSlice(n int) []int {
	s := make([]int, n) // Size unknown, goes to heap
	return s
}

func main() {
	fmt.Println("Escape Analysis Examples")
	fmt.Println("========================\n")

fmt.Println("1. No escape (stack):")
	val := noEscape()
	fmt.Printf("   Value: %d\n\n", val)

fmt.Println("2. Escapes via pointer:")
	ptr := escapesPointer()
	fmt.Printf("   Pointer: %p, Value: %d\n\n", ptr, *ptr)

fmt.Println("3. Escapes via interface:")
	iface := escapesInterface()
	fmt.Printf("   Interface: %v\n\n", iface)

fmt.Println("4. Escapes via closure:")
	fn := escapesClosure()
	fmt.Printf("   Closure result: %d\n\n", fn())

fmt.Println("5. Escapes due to size:")
	large := escapesSize()
	fmt.Printf("   Large array pointer: %p\n\n", large)

fmt.Println("6. No escape (small slice):")
	noEscapeSlice()
	fmt.Println("   Small slice on stack\n")

fmt.Println("7. Escapes (dynamic slice):")
	dynSlice := escapesSlice(100)
	fmt.Printf("   Dynamic slice: %v...\n\n", dynSlice[:3])

fmt.Println("To see escape analysis:")
	fmt.Println("  go build -gcflags='-m' memory-escape.go")
	fmt.Println("\nLook for messages like:")
	fmt.Println("  'moved to heap: x'")
	fmt.Println("  'x escapes to heap'")
}

Output

Click Run to execute your code

Variables Escape When:

Pointer is returned from function
Stored in interface{}
Captured by closure
Too large for stack
Size unknown at compile time

Memory Optimization Techniques

Practical techniques to reduce memory allocations:

package main

import (
	"fmt"
	"runtime"
)

// ❌ Bad - creates many small allocations
func inefficientConcat(n int) string {
	result := ""
	for i := 0; i < n; i++ {
		result += "x" // Each += allocates new string
	}
	return result
}

// ✅ Good - preallocates slice
func efficientBuild(n int) string {
	buf := make([]byte, 0, n) // Preallocate capacity
	for i := 0; i < n; i++ {
		buf = append(buf, 'x')
	}
	return string(buf)
}

// ❌ Bad - slice grows dynamically
func inefficientSlice() []int {
	var nums []int // No capacity
	for i := 0; i < 10000; i++ {
		nums = append(nums, i) // Reallocates multiple times
	}
	return nums
}

// ✅ Good - preallocates slice
func efficientSlice() []int {
	nums := make([]int, 0, 10000) // Preallocate capacity
	for i := 0; i < 10000; i++ {
		nums = append(nums, i) // No reallocation
	}
	return nums
}

// ❌ Bad - pointer escapes unnecessarily
func inefficientPointer() *int {
	x := 42
	return &x // x escapes to heap
}

// ✅ Good - return by value
func efficientValue() int {
	x := 42
	return x // Stays on stack
}

func measureAllocations(name string, fn func()) {
	var m1, m2 runtime.MemStats

runtime.ReadMemStats(&m1)
	fn()
	runtime.ReadMemStats(&m2)

allocs := m2.Mallocs - m1.Mallocs
	fmt.Printf("%s:\n", name)
	fmt.Printf("  Allocations: %d\n", allocs)
	fmt.Printf("  Allocated: %d bytes\n\n", m2.TotalAlloc-m1.TotalAlloc)
}

func main() {
	fmt.Println("Memory Optimization Techniques")
	fmt.Println("==============================\n")

// String concatenation
	fmt.Println("1. String Building:")
	measureAllocations("Inefficient (+=)", func() {
		_ = inefficientConcat(1000)
	})
	measureAllocations("Efficient (preallocate)", func() {
		_ = efficientBuild(1000)
	})

// Slice allocation
	fmt.Println("2. Slice Allocation:")
	measureAllocations("Inefficient (grow)", func() {
		_ = inefficientSlice()
	})
	measureAllocations("Efficient (preallocate)", func() {
		_ = efficientSlice()
	})

// Pointer vs value
	fmt.Println("3. Return Type:")
	measureAllocations("Inefficient (pointer)", func() {
		for i := 0; i < 10000; i++ {
			_ = inefficientPointer()
		}
	})
	measureAllocations("Efficient (value)", func() {
		for i := 0; i < 10000; i++ {
			_ = efficientValue()
		}
	})

fmt.Println("Optimization Tips:")
	fmt.Println("  ✓ Preallocate slices with make([]T, 0, capacity)")
	fmt.Println("  ✓ Use strings.Builder for string concatenation")
	fmt.Println("  ✓ Return values instead of pointers when possible")
	fmt.Println("  ✓ Reuse objects with sync.Pool")
	fmt.Println("  ✓ Profile with pprof to find hotspots")
}

Output

Click Run to execute your code

Optimization Checklist:

✓ Preallocate slices: make([]T, 0, capacity)
✓ Use strings.Builder for string concatenation
✓ Return values instead of pointers when possible
✓ Reuse objects with sync.Pool
✓ Avoid unnecessary interface{} conversions
✓ Profile with pprof to find hotspots

Preventing Memory Leaks

Common memory leak patterns and how to fix them:

package main

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

// Memory leak example - goroutine leak
func leakyGoroutines() {
	// ❌ Bad - goroutines never stop
	for i := 0; i < 10; i++ {
		go func() {
			for {
				// Infinite loop, never exits
				time.Sleep(time.Second)
			}
		}()
	}
	fmt.Println("Started 10 leaky goroutines")
}

// Fixed version - with cancellation
func fixedGoroutines() {
	done := make(chan struct{})

// ✅ Good - goroutines can be stopped
	for i := 0; i < 10; i++ {
		go func() {
			for {
				select {
				case <-done:
					return // Clean exit
				default:
					time.Sleep(time.Second)
				}
			}
		}()
	}

fmt.Println("Started 10 controlled goroutines")

// Stop after 3 seconds
	time.Sleep(3 * time.Second)
	close(done)
	fmt.Println("Stopped all goroutines")
}

// Memory leak - forgotten references
type Cache struct {
	data map[string][]byte
}

func (c *Cache) leakyAdd(key string, value []byte) {
	// ❌ Bad - never removes old entries
	c.data[key] = value
}

func (c *Cache) fixedAdd(key string, value []byte, maxSize int) {
	// ✅ Good - limits cache size
	if len(c.data) >= maxSize {
		// Remove oldest entry (simplified)
		for k := range c.data {
			delete(c.data, k)
			break
		}
	}
	c.data[key] = value
}

func demonstrateLeaks() {
	fmt.Println("\nMemory Leak Demonstration:")
	fmt.Println("==========================\n")

// Show goroutine count
	fmt.Printf("Initial goroutines: %d\n", runtime.NumGoroutine())

// Create leak
	leakyGoroutines()
	time.Sleep(time.Second)
	fmt.Printf("After leaky start: %d goroutines\n", runtime.NumGoroutine())

// Fixed version
	fixedGoroutines()
	time.Sleep(time.Second)
	fmt.Printf("After cleanup: %d goroutines\n", runtime.NumGoroutine())
}

func demonstrateCacheLeak() {
	fmt.Println("\nCache Leak Demonstration:")
	fmt.Println("=========================\n")

cache := &Cache{data: make(map[string][]byte)}

// Leaky cache
	fmt.Println("Adding 1000 items to leaky cache...")
	for i := 0; i < 1000; i++ {
		key := fmt.Sprintf("key%d", i)
		cache.leakyAdd(key, make([]byte, 1024))
	}
	fmt.Printf("Cache size: %d items\n", len(cache.data))

// Fixed cache
	fixedCache := &Cache{data: make(map[string][]byte)}
	fmt.Println("\nAdding 1000 items to fixed cache (max 100)...")
	for i := 0; i < 1000; i++ {
		key := fmt.Sprintf("key%d", i)
		fixedCache.fixedAdd(key, make([]byte, 1024), 100)
	}
	fmt.Printf("Cache size: %d items (limited)\n", len(fixedCache.data))
}

func main() {
	fmt.Println("Memory Leak Prevention")
	fmt.Println("======================\n")

demonstrateLeaks()
	demonstrateCacheLeak()

fmt.Println("\nCommon Memory Leaks:")
	fmt.Println("  1. Goroutine leaks (no cancellation)")
	fmt.Println("  2. Unbounded caches (no eviction)")
	fmt.Println("  3. Forgotten timers (not stopped)")
	fmt.Println("  4. Circular references (rare in Go)")
	fmt.Println("  5. Global variables (never freed)")

fmt.Println("\nPrevention Tips:")
	fmt.Println("  ✓ Always provide goroutine cancellation")
	fmt.Println("  ✓ Limit cache sizes with eviction policies")
	fmt.Println("  ✓ Stop timers when done")
	fmt.Println("  ✓ Use pprof to detect leaks")
	fmt.Println("  ✓ Monitor goroutine count in production")
}

Output

Click Run to execute your code

Common Memory Leaks:

Goroutine leaks (no cancellation mechanism)
Unbounded caches (no eviction policy)
Forgotten timers (not stopped)
Global variables holding references
Unclosed resources (files, connections)

Common Mistakes

1. Not preallocating slices

// ❌ Wrong - grows dynamically
var items []Item
for i := 0; i < 10000; i++ {
    items = append(items, Item{}) // Multiple reallocations
}

// ✅ Correct - preallocate
items := make([]Item, 0, 10000)
for i := 0; i < 10000; i++ {
    items = append(items, Item{}) // No reallocation
}

2. String concatenation in loops

// ❌ Wrong - creates many strings
result := ""
for i := 0; i < 1000; i++ {
    result += "x" // Each += allocates
}

// ✅ Correct - use strings.Builder
var builder strings.Builder
builder.Grow(1000) // Preallocate
for i := 0; i < 1000; i++ {
    builder.WriteString("x")
}
result := builder.String()

3. Ignoring escape analysis

// ❌ Wrong - unnecessary heap allocation
func getPointer() *int {
    x := 42
    return &x // x escapes to heap
}

// ✅ Correct - return by value
func getValue() int {
    x := 42
    return x // Stays on stack
}

Exercise: Memory-Efficient Cache

Task: Build a memory-efficient LRU cache.

Requirements:

Fixed maximum size (100 items)
Evict least recently used items
Use sync.Pool for temporary objects
Minimize allocations
Thread-safe

Show Solution

package main

import (
    "container/list"
    "fmt"
    "sync"
)

type entry struct {
    key   string
    value interface{}
}

var entryPool = sync.Pool{
    New: func() interface{} {
        return &entry{}
    },
}

type LRUCache struct {
    mu       sync.Mutex
    capacity int
    cache    map[string]*list.Element
    lru      *list.List
}

func NewLRUCache(capacity int) *LRUCache {
    return &LRUCache{
        capacity: capacity,
        cache:    make(map[string]*list.Element),
        lru:      list.New(),
    }
}

func (c *LRUCache) Get(key string) (interface{}, bool) {
    c.mu.Lock()
    defer c.mu.Unlock()
    
    if elem, ok := c.cache[key]; ok {
        c.lru.MoveToFront(elem)
        return elem.Value.(*entry).value, true
    }
    return nil, false
}

func (c *LRUCache) Put(key string, value interface{}) {
    c.mu.Lock()
    defer c.mu.Unlock()
    
    if elem, ok := c.cache[key]; ok {
        c.lru.MoveToFront(elem)
        elem.Value.(*entry).value = value
        return
    }
    
    // Get entry from pool
    e := entryPool.Get().(*entry)
    e.key = key
    e.value = value
    
    elem := c.lru.PushFront(e)
    c.cache[key] = elem
    
    // Evict if over capacity
    if c.lru.Len() > c.capacity {
        oldest := c.lru.Back()
        if oldest != nil {
            c.lru.Remove(oldest)
            oldEntry := oldest.Value.(*entry)
            delete(c.cache, oldEntry.key)
            
            // Return to pool
            entryPool.Put(oldEntry)
        }
    }
}

func main() {
    cache := NewLRUCache(100)
    
    // Add items
    for i := 0; i < 150; i++ {
        cache.Put(fmt.Sprintf("key%d", i), i)
    }
    
    // Check cache
    if val, ok := cache.Get("key0"); ok {
        fmt.Printf("Found: %v\n", val)
    } else {
        fmt.Println("key0 evicted (LRU)")
    }
    
    if val, ok := cache.Get("key100"); ok {
        fmt.Printf("Found: %v\n", val)
    }
    
    fmt.Println("Cache working with LRU eviction!")
}

Summary

Stack is fast, automatic, function-scoped
Heap is flexible, garbage collected, slower
Escape analysis determines stack vs heap
GC uses concurrent mark-and-sweep
pprof identifies memory hotspots
sync.Pool reuses objects to reduce allocations
Preallocate slices when size is known
strings.Builder for efficient concatenation
Return values instead of pointers when possible
Prevent leaks with proper resource management

What's Next?

You've mastered Go's memory management! Next, you'll learn about Escape Analysis in depth, understanding exactly when and why variables escape to the heap, and how to optimize your code accordingly.

Previous Generics & Reflection

Next Escape Analysis

Stack vs Heap Allocation

Garbage Collection

Memory Profiling with pprof

Object Reuse with sync.Pool

Understanding Escape Analysis

Memory Optimization Techniques

Preventing Memory Leaks

Common Mistakes

1. Not preallocating slices

2. String concatenation in loops

3. Ignoring escape analysis

Exercise: Memory-Efficient Cache

Summary

What's Next?

Enjoying these tutorials?