Claude Skill

go-optimizations

Guides the agent to write and review performance-sensitive Go code by applying CPU cache awareness, false sharing prevention, instruction-level parallelism, data alignment, escape analysis, allocation reduction, inlining, profiling, GC tuning, and Docker/Kubernetes GOMAXPROCS con

LLM Mart · 0 points · 0 views 0 listing impressions 0 install-command copies
Download v0lka-skills-development_idiomatic-go_go-optimizations-ce9c4a1.zip · 5 KB

Install

skills CLI npx skills add https://github.com/v0lka/skills/tree/main/development/idiomatic-go/go-optimizations
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install v0lka-skills@llmmart
Git git clone https://github.com/v0lka/skills.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole v0lka/skills collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

Go Optimization Patterns

"Make it correct, make it clear, make it concise, make it fast, in that order." -- Wes Dyer

Apply these rules only to performance-sensitive code paths. Do NOT sacrifice readability for micro-optimizations unless profiling shows a bottleneck.


1. CPU Cache Awareness

Cache Lines

A CPU fetches memory in 64-byte cache lines, not individual variables. One cache line holds 8 int64 values. Optimize data layout to maximize useful data per cache line.

Key rule: Iterating a slice where you skip elements is still fast if accesses fall within the same cache lines. The bottleneck is memory access, not iteration count.

Slice of Structs vs. Struct of Slices

When iterating over a single field across many records, a struct of slices provides better spatial locality than a slice of structs because the target field values are contiguous in memory.

// SLOWER when summing only field `a` -- fields interleaved in memory
type Foo struct {
    a int64
    b int64
}
func sumFoo(foos []Foo) int64 { /* iterates a, skips b, a, skips b... */ }

// FASTER -- all `a` values contiguous
type Bar struct {
    a []int64
    b []int64
}
func sumBar(bar Bar) int64 { /* iterates bar.a directly */ }

Use struct-of-slices layout when hot loops access only a subset of fields (column-oriented access pattern).

Predictability and Stride

  • Unit stride (contiguous elements): best -- predictable, minimal cache lines.
  • Constant stride (e.g., every 2nd element): predictable but less efficient.
  • Non-unit stride (linked list, slice of pointers): NOT predictable -- CPU cannot prefetch.

Prefer slices over linked lists and pointer-chasing structures in hot paths. Even if a linked list is allocated contiguously, the CPU cannot predict the access pattern.

Critical Stride (Cache Placement)

Modern caches are set-associative. When stride size equals the critical stride (number of cache sets x cache line size, typically 4 KB for an 8-way 32 KB L1D), all accessed blocks map to the same cache set, causing conflict misses.

Practical example: a matrix with exactly 512 int64 columns hits a critical stride on typical hardware. Using 513 columns avoids it and can be ~50% faster when reusing the same matrix.

Rule: When working with large matrices or strided access, avoid dimensions that are exact powers of 2 or multiples of the critical stride.


2. False Sharing

When two goroutines write to different variables that share the same cache line, the entire line is invalidated on each write across cores (MESI protocol). This is false sharing.

// BAD -- sumA and sumB likely share a cache line
type Result struct {
    sumA int64
    sumB int64
}

// GOOD -- padding forces separate cache lines
type Result struct {
    sumA int64
    _    [56]byte  // 64 - 8 = 56 bytes padding
    sumB int64
}

When to apply: any struct whose fields are written concurrently by different goroutines on hot paths. Alternative: use channels so goroutines communicate local results instead of sharing memory.


3. Instruction-Level Parallelism (ILP)

Modern CPUs execute independent instructions in parallel (superscalar). Data hazards (one instruction depends on the result of another) prevent parallelism.

Technique: introduce a temporary variable to break dependency chains so the CPU can execute more instructions in parallel.

// SLOWER -- s[0] increment must complete before checking s[0]
for i := 0; i < n; i++ {
    s[0]++
    if s[0]%2 == 0 {
        s[1]++
    }
}

// FASTER (~20%) -- v captures s[0], breaking the dependency chain
for i := 0; i < n; i++ {
    v := s[0]
    s[0] = v + 1
    if v%2 != 0 {  // note: check odd because v is pre-increment
        s[1]++
    }
}

Caveat: Go compiler output changes between versions. Verify with benchmarks and go build -gcflags "-S".


4. Data Alignment

The Go compiler adds padding to ensure each field's memory address is a multiple of its size. Poorly ordered struct fields waste memory.

Rule: sort struct fields by size in descending order.

// BAD -- 24 bytes (7 bytes padding after b1, 7 after b2)
type Foo struct {
    b1 byte   // 1 byte + 7 padding
    i  int64  // 8 bytes
    b2 byte   // 1 byte + 7 padding
}

// GOOD -- 16 bytes (only 6 bytes padding after b1+b2)
type Foo struct {
    i  int64  // 8 bytes
    b1 byte   // 1 byte
    b2 byte   // 1 byte + 6 padding
}

Compact structs reduce memory, improve cache utilization, and lower GC pressure when heap-allocated.


5. Stack vs. Heap and Escape Analysis

Stack allocation is nearly free and self-cleaning (no GC). Heap allocation requires GC work and is ~10x slower.

Escape Rules

Pattern Escapes?
Returning a pointer to a local variable ("sharing up") Yes
Passing a pointer to a callee ("sharing down") No
Variable referenced after function returns Yes
Global variables Yes
Pointer sent to a channel Yes
Variable referenced by a value sent to a channel Yes
Local variable too large for the stack Yes
Slice with runtime-determined length (make([]int, n)) Yes
Backing array reallocated via append May escape
Slice with compile-time constant length (make([]int, 10)) No (usually)

Verify assumptions: go build -gcflags "-m=2" shows escape decisions.

Do NOT return pointers "to avoid a copy" as a premature optimization. Copying within cache lines is extremely fast. Focus on readability and semantics first.


6. Reducing Allocations

API Design (Sharing Down)

Design APIs so callers provide buffers instead of functions returning new allocations:

// BAD -- returned slice escapes to heap
type Reader interface {
    Read(n int) ([]byte, error)
}

// GOOD -- caller provides the buffer (sharing down)
type Reader interface {
    Read(p []byte) (int, error)
}

Compiler Optimizations

The Go compiler avoids []byte to string conversion when used directly in a map lookup:

// SLOWER -- intermediate string variable forces allocation
key := string(bytes)
v, ok = m[key]

// FASTER -- compiler optimizes away the conversion
v, ok = m[string(bytes)]

sync.Pool

Use sync.Pool to reuse frequently allocated objects of the same type. It is NOT a cache (no size/capacity control); objects are drained each GC cycle.

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

func write(w io.Writer) {
    buf := pool.Get().([]byte)
    buf = buf[:0]           // reset before use
    defer pool.Put(buf)
    getResponse(buf)
    _, _ = w.Write(buf)
}

Other Allocation Reducers

  • Use strings.Builder instead of + for string concatenation.
  • Avoid unnecessary []byte to string conversions.
  • Preallocate slices and maps when length is known.
  • Use compact struct layout (see Data Alignment above).

7. Inlining

The Go compiler inlines functions below a complexity budget (~80 cost units). Inlining eliminates call overhead AND enables further optimizations (e.g., keeping variables on the stack).

Fast-Path Inlining

Extract the slow path into a separate function so the main function stays within the inlining budget:

// The Lock method stays small enough to inline
func (m *Mutex) Lock() {
    if atomic.CompareAndSwapInt32(&m.state, 0, mutexLocked) {
        return  // fast path -- inlined
    }
    m.lockSlow()  // slow path -- separate function
}

func (m *Mutex) lockSlow() {
    // complex logic that exceeds inlining budget
}

Check inlining decisions: go build -gcflags "-m=2" reports which functions are inlined and which exceed the budget.


8. Go Diagnostics Tooling

Profiling with pprof

Enable via import _ "net/http/pprof" (safe for production; CPU profile only runs when activated).

Profile Endpoint What It Shows
CPU /debug/pprof/profile?seconds=30 Where the app spends CPU time
Heap /debug/pprof/heap?gc=1 Current heap allocations
Allocs /debug/pprof/allocs All past heap allocations
Goroutine /debug/pprof/goroutine/?debug=0 Stack traces of all goroutines
Block /debug/pprof/block Where goroutines block on sync primitives
Mutex /debug/pprof/mutex Mutex contention

Key signals from CPU profile:

  • Excessive runtime.mallogc => too many small heap allocations.
  • Time in channel/mutex ops => excessive contention.
  • Time in syscall.Read/syscall.Write => improve I/O buffering.

Memory leak detection:

  1. GET /debug/pprof/heap?gc=1 (forces GC first)
  2. Wait
  3. GET /debug/pprof/heap?gc=1 again
  4. go tool pprof -http=:8080 -diff_base <file2> <file1>

Important: enable only ONE profiler at a time to avoid erroneous observations.

Block and mutex profiles must be explicitly enabled:

  • runtime.SetBlockProfileRate(rate)
  • runtime.SetMutexProfileFraction(rate)

Execution Tracer

go test -bench=. -trace=trace.out
go tool trace trace.out

Shows: goroutine scheduling, GC phases, parallelism quality. Use runtime/trace for user-defined tasks:

ctx, task := trace.NewTask(context.Background(), "myTask")
trace.WithRegion(ctx, "main", func() {
    // work
})
task.End()

CPU profiling vs tracing: profiling is sample-based per-function (10ms granularity); tracing is event-based per-goroutine (no rate bound).


9. Garbage Collector Tuning

Go GC is concurrent mark-and-sweep. Controlled by GOGC (default: 100), which sets heap growth percentage before next GC. A GC also runs if none has triggered in 2 minutes.

Scenario Recommendation
Steady load increase GOGC=100 is fine
Sudden traffic spike Increase GOGC to reduce GC frequency during ramp
Extreme spike (seconds) Pre-allocate a large byte slice to raise the heap floor

Pre-allocation trick for extreme spikes:

// In main.go -- lazy allocation via mmap, no physical memory until used
var _ = make([]byte, 1_000_000_000) // 1 GB virtual reservation

This raises the GC trigger threshold (next GC at 2 GB if GOGC=100) without consuming physical memory.

Debug GC: GODEBUG=gctrace=1 go test -bench=. -v


10. Go in Docker and Kubernetes

GOMAXPROCS defaults to the host's logical CPU count, NOT the container's CPU limit. With a 4-core limit on an 8-core host, Go spawns 8 OS threads. CFS (Completely Fair Scheduler) throttles after the quota is consumed, causing up to 300% latency penalty.

Example: 8 threads x 50ms = 400ms quota consumed in 50ms, application paused for remaining 50ms.

Fix: use go.uber.org/automaxprocs:

import _ "go.uber.org/automaxprocs"

This automatically sets GOMAXPROCS to match the container CPU quota, preventing CFS throttling.

Track: Go issue #33803 for native CFS awareness.

Files (skills)
  • SKILL.md 11.3 KB
    ---
    name: go-optimizations
    description: Guides the agent to write and review performance-sensitive Go code by applying CPU cache awareness, false sharing prevention, instruction-level parallelism, data alignment, escape analysis, allocation reduction, inlining, profiling, GC tuning, and Docker/Kubernetes GOMAXPROCS configuration. Use when writing hot-path Go code, reviewing performance-critical sections, reducing allocations, profiling applications, tuning GC behavior, or deploying Go services in containers.
    ---
    
    # Go Optimization Patterns
    
    > "Make it correct, make it clear, make it concise, make it fast, in that order." -- Wes Dyer
    
    Apply these rules only to performance-sensitive code paths. Do NOT sacrifice readability for micro-optimizations unless profiling shows a bottleneck.
    
    ---
    
    ## 1. CPU Cache Awareness
    
    ### Cache Lines
    
    A CPU fetches memory in **64-byte cache lines**, not individual variables. One cache line holds 8 `int64` values. Optimize data layout to maximize useful data per cache line.
    
    **Key rule**: Iterating a slice where you skip elements is still fast if accesses fall within the same cache lines. The bottleneck is memory access, not iteration count.
    
    ### Slice of Structs vs. Struct of Slices
    
    When iterating over a single field across many records, a **struct of slices** provides better spatial locality than a **slice of structs** because the target field values are contiguous in memory.
    
    ```go
    // SLOWER when summing only field `a` -- fields interleaved in memory
    type Foo struct {
        a int64
        b int64
    }
    func sumFoo(foos []Foo) int64 { /* iterates a, skips b, a, skips b... */ }
    
    // FASTER -- all `a` values contiguous
    type Bar struct {
        a []int64
        b []int64
    }
    func sumBar(bar Bar) int64 { /* iterates bar.a directly */ }
    ```
    
    Use struct-of-slices layout when hot loops access only a subset of fields (column-oriented access pattern).
    
    ### Predictability and Stride
    
    - **Unit stride** (contiguous elements): best -- predictable, minimal cache lines.
    - **Constant stride** (e.g., every 2nd element): predictable but less efficient.
    - **Non-unit stride** (linked list, slice of pointers): NOT predictable -- CPU cannot prefetch.
    
    Prefer slices over linked lists and pointer-chasing structures in hot paths. Even if a linked list is allocated contiguously, the CPU cannot predict the access pattern.
    
    ### Critical Stride (Cache Placement)
    
    Modern caches are **set-associative**. When stride size equals the critical stride (number of cache sets x cache line size, typically 4 KB for an 8-way 32 KB L1D), all accessed blocks map to the same cache set, causing **conflict misses**.
    
    Practical example: a matrix with exactly 512 `int64` columns hits a critical stride on typical hardware. Using 513 columns avoids it and can be ~50% faster when reusing the same matrix.
    
    **Rule**: When working with large matrices or strided access, avoid dimensions that are exact powers of 2 or multiples of the critical stride.
    
    ---
    
    ## 2. False Sharing
    
    When two goroutines write to different variables that share the same cache line, the entire line is invalidated on each write across cores (MESI protocol). This is **false sharing**.
    
    ```go
    // BAD -- sumA and sumB likely share a cache line
    type Result struct {
        sumA int64
        sumB int64
    }
    
    // GOOD -- padding forces separate cache lines
    type Result struct {
        sumA int64
        _    [56]byte  // 64 - 8 = 56 bytes padding
        sumB int64
    }
    ```
    
    **When to apply**: any struct whose fields are written concurrently by different goroutines on hot paths. Alternative: use channels so goroutines communicate local results instead of sharing memory.
    
    ---
    
    ## 3. Instruction-Level Parallelism (ILP)
    
    Modern CPUs execute independent instructions in parallel (superscalar). **Data hazards** (one instruction depends on the result of another) prevent parallelism.
    
    **Technique**: introduce a temporary variable to break dependency chains so the CPU can execute more instructions in parallel.
    
    ```go
    // SLOWER -- s[0] increment must complete before checking s[0]
    for i := 0; i < n; i++ {
        s[0]++
        if s[0]%2 == 0 {
            s[1]++
        }
    }
    
    // FASTER (~20%) -- v captures s[0], breaking the dependency chain
    for i := 0; i < n; i++ {
        v := s[0]
        s[0] = v + 1
        if v%2 != 0 {  // note: check odd because v is pre-increment
            s[1]++
        }
    }
    ```
    
    **Caveat**: Go compiler output changes between versions. Verify with benchmarks and `go build -gcflags "-S"`.
    
    ---
    
    ## 4. Data Alignment
    
    The Go compiler adds padding to ensure each field's memory address is a multiple of its size. Poorly ordered struct fields waste memory.
    
    **Rule**: sort struct fields by size in **descending order**.
    
    ```go
    // BAD -- 24 bytes (7 bytes padding after b1, 7 after b2)
    type Foo struct {
        b1 byte   // 1 byte + 7 padding
        i  int64  // 8 bytes
        b2 byte   // 1 byte + 7 padding
    }
    
    // GOOD -- 16 bytes (only 6 bytes padding after b1+b2)
    type Foo struct {
        i  int64  // 8 bytes
        b1 byte   // 1 byte
        b2 byte   // 1 byte + 6 padding
    }
    ```
    
    Compact structs reduce memory, improve cache utilization, and lower GC pressure when heap-allocated.
    
    ---
    
    ## 5. Stack vs. Heap and Escape Analysis
    
    Stack allocation is nearly free and self-cleaning (no GC). Heap allocation requires GC work and is ~10x slower.
    
    ### Escape Rules
    
    | Pattern | Escapes? |
    |---|---|
    | Returning a pointer to a local variable ("sharing up") | Yes |
    | Passing a pointer to a callee ("sharing down") | No |
    | Variable referenced after function returns | Yes |
    | Global variables | Yes |
    | Pointer sent to a channel | Yes |
    | Variable referenced by a value sent to a channel | Yes |
    | Local variable too large for the stack | Yes |
    | Slice with runtime-determined length (`make([]int, n)`) | Yes |
    | Backing array reallocated via `append` | May escape |
    | Slice with compile-time constant length (`make([]int, 10)`) | No (usually) |
    
    **Verify assumptions**: `go build -gcflags "-m=2"` shows escape decisions.
    
    **Do NOT** return pointers "to avoid a copy" as a premature optimization. Copying within cache lines is extremely fast. Focus on readability and semantics first.
    
    ---
    
    ## 6. Reducing Allocations
    
    ### API Design (Sharing Down)
    
    Design APIs so callers provide buffers instead of functions returning new allocations:
    
    ```go
    // BAD -- returned slice escapes to heap
    type Reader interface {
        Read(n int) ([]byte, error)
    }
    
    // GOOD -- caller provides the buffer (sharing down)
    type Reader interface {
        Read(p []byte) (int, error)
    }
    ```
    
    ### Compiler Optimizations
    
    The Go compiler avoids `[]byte` to `string` conversion when used directly in a map lookup:
    
    ```go
    // SLOWER -- intermediate string variable forces allocation
    key := string(bytes)
    v, ok = m[key]
    
    // FASTER -- compiler optimizes away the conversion
    v, ok = m[string(bytes)]
    ```
    
    ### sync.Pool
    
    Use `sync.Pool` to reuse frequently allocated objects of the same type. It is NOT a cache (no size/capacity control); objects are drained each GC cycle.
    
    ```go
    var pool = sync.Pool{
        New: func() any {
            return make([]byte, 1024)
        },
    }
    
    func write(w io.Writer) {
        buf := pool.Get().([]byte)
        buf = buf[:0]           // reset before use
        defer pool.Put(buf)
        getResponse(buf)
        _, _ = w.Write(buf)
    }
    ```
    
    ### Other Allocation Reducers
    
    - Use `strings.Builder` instead of `+` for string concatenation.
    - Avoid unnecessary `[]byte` to `string` conversions.
    - Preallocate slices and maps when length is known.
    - Use compact struct layout (see Data Alignment above).
    
    ---
    
    ## 7. Inlining
    
    The Go compiler inlines functions below a complexity budget (~80 cost units). Inlining eliminates call overhead AND enables further optimizations (e.g., keeping variables on the stack).
    
    ### Fast-Path Inlining
    
    Extract the slow path into a separate function so the main function stays within the inlining budget:
    
    ```go
    // The Lock method stays small enough to inline
    func (m *Mutex) Lock() {
        if atomic.CompareAndSwapInt32(&m.state, 0, mutexLocked) {
            return  // fast path -- inlined
        }
        m.lockSlow()  // slow path -- separate function
    }
    
    func (m *Mutex) lockSlow() {
        // complex logic that exceeds inlining budget
    }
    ```
    
    **Check inlining decisions**: `go build -gcflags "-m=2"` reports which functions are inlined and which exceed the budget.
    
    ---
    
    ## 8. Go Diagnostics Tooling
    
    ### Profiling with pprof
    
    Enable via `import _ "net/http/pprof"` (safe for production; CPU profile only runs when activated).
    
    | Profile | Endpoint | What It Shows |
    |---|---|---|
    | CPU | `/debug/pprof/profile?seconds=30` | Where the app spends CPU time |
    | Heap | `/debug/pprof/heap?gc=1` | Current heap allocations |
    | Allocs | `/debug/pprof/allocs` | All past heap allocations |
    | Goroutine | `/debug/pprof/goroutine/?debug=0` | Stack traces of all goroutines |
    | Block | `/debug/pprof/block` | Where goroutines block on sync primitives |
    | Mutex | `/debug/pprof/mutex` | Mutex contention |
    
    **Key signals from CPU profile**:
    - Excessive `runtime.mallogc` => too many small heap allocations.
    - Time in channel/mutex ops => excessive contention.
    - Time in `syscall.Read`/`syscall.Write` => improve I/O buffering.
    
    **Memory leak detection**:
    1. `GET /debug/pprof/heap?gc=1` (forces GC first)
    2. Wait
    3. `GET /debug/pprof/heap?gc=1` again
    4. `go tool pprof -http=:8080 -diff_base <file2> <file1>`
    
    **Important**: enable only ONE profiler at a time to avoid erroneous observations.
    
    Block and mutex profiles must be explicitly enabled:
    - `runtime.SetBlockProfileRate(rate)`
    - `runtime.SetMutexProfileFraction(rate)`
    
    ### Execution Tracer
    
    ```bash
    go test -bench=. -trace=trace.out
    go tool trace trace.out
    ```
    
    Shows: goroutine scheduling, GC phases, parallelism quality. Use `runtime/trace` for user-defined tasks:
    
    ```go
    ctx, task := trace.NewTask(context.Background(), "myTask")
    trace.WithRegion(ctx, "main", func() {
        // work
    })
    task.End()
    ```
    
    **CPU profiling vs tracing**: profiling is sample-based per-function (10ms granularity); tracing is event-based per-goroutine (no rate bound).
    
    ---
    
    ## 9. Garbage Collector Tuning
    
    Go GC is concurrent mark-and-sweep. Controlled by `GOGC` (default: 100), which sets heap growth percentage before next GC. A GC also runs if none has triggered in 2 minutes.
    
    | Scenario | Recommendation |
    |---|---|
    | Steady load increase | `GOGC=100` is fine |
    | Sudden traffic spike | Increase `GOGC` to reduce GC frequency during ramp |
    | Extreme spike (seconds) | Pre-allocate a large byte slice to raise the heap floor |
    
    **Pre-allocation trick** for extreme spikes:
    
    ```go
    // In main.go -- lazy allocation via mmap, no physical memory until used
    var _ = make([]byte, 1_000_000_000) // 1 GB virtual reservation
    ```
    
    This raises the GC trigger threshold (next GC at 2 GB if `GOGC=100`) without consuming physical memory.
    
    **Debug GC**: `GODEBUG=gctrace=1 go test -bench=. -v`
    
    ---
    
    ## 10. Go in Docker and Kubernetes
    
    `GOMAXPROCS` defaults to the **host's** logical CPU count, NOT the container's CPU limit. With a 4-core limit on an 8-core host, Go spawns 8 OS threads. CFS (Completely Fair Scheduler) throttles after the quota is consumed, causing up to **300% latency penalty**.
    
    **Example**: 8 threads x 50ms = 400ms quota consumed in 50ms, application paused for remaining 50ms.
    
    **Fix**: use `go.uber.org/automaxprocs`:
    
    ```go
    import _ "go.uber.org/automaxprocs"
    ```
    
    This automatically sets `GOMAXPROCS` to match the container CPU quota, preventing CFS throttling.
    
    **Track**: [Go issue #33803](https://github.com/golang/go/issues/33803) for native CFS awareness.
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.