axiom-concurrency-profiling

Concurrency Profiling — Instruments Workflows

Profile and optimize Swift async/await code using Instruments.

When to Use

✅ Use when:

• UI stutters during async operations
• Suspecting actor contention
• Tasks queued but not executing
• Main thread blocked during async work
• Need to visualize task execution flow

❌ Don't use when:

• Issue is pure CPU performance (use Time Profiler)
• Memory issues unrelated to concurrency (use Allocations)
• Haven't confirmed concurrency is the bottleneck

Swift Concurrency Template

What It Shows

Track	Information
Swift Tasks	Task lifetimes, parent-child relationships
Swift Actors	Actor access, contention visualization
Thread States	Blocked vs running vs suspended

Statistics

• Running Tasks: Tasks currently executing
• Alive Tasks: Tasks present at a point in time
• Total Tasks: Cumulative count created

Color Coding

• Blue: Task executing
• Red: Task waiting (contention)
• Gray: Task suspended (awaiting)

Workflow 1: Diagnose Main Thread Blocking

Symptom: UI freezes, main thread timeline full

1. Profile with Swift Concurrency template
2. Look at main thread → "Swift Tasks" lane
3. Find long blue bars (task executing on main)
4. Check if work could be offloaded

Solution patterns:

// ❌ Heavy work on MainActor
@MainActor
class ViewModel: ObservableObject {
    func process() {
        let result = heavyComputation()  // Blocks UI
        self.data = result
    }
}

// ✅ Offload heavy work
@MainActor
class ViewModel: ObservableObject {
    func process() async {
        let result = await Task.detached {
            heavyComputation()
        }.value
        self.data = result
    }
}

Workflow 2: Find Actor Contention

Symptom: Tasks serializing unexpectedly, parallel work running sequentially

1. Enable "Swift Actors" instrument
2. Look for serialized access patterns
3. Red = waiting, Blue = executing
4. High red:blue ratio = contention problem