🇺🇸English

Hang Diagnostics

Systematic diagnosis and resolution of app hangs. A hang occurs when the main thread is blocked for more than 1 second, making the app unresponsive to user input.

Red Flags — Check This Skill When

What Is a Hang

A hang is when the main runloop cannot process events for more than 1 second. The user taps, but nothing happens.

User taps → Main thread busy/blocked → Event queued → 1+ second delay → HANG

Key distinction : The main thread handles ALL user input. If it's busy or blocked, the entire UI freezes.

Hang vs Hitch vs Lag

This skill covers hangs. For hitches, see axiom-swiftui-performance. For general lag, see axiom-performance-profiling.

The Two Causes of Hangs

Every hang has one of two root causes:

1. Main Thread Busy

The main thread is doing work instead of processing events.

Subcategories :

2. Main Thread Blocked

The main thread is waiting for something else.

Subcategories :

Decision Tree — Diagnosing Hangs

START: App hangs reported
  │
  ├─→ Do you have hang diagnostics from Organizer or MetricKit?
  │     │
  │     ├─→ YES: Examine stack trace
  │     │     │
  │     │     ├─→ Stack shows your code running
  │     │     │     → BUSY: Main thread doing work
  │     │     │     → Profile with Time Profiler
  │     │     │
  │     │     └─→ Stack shows waiting (semaphore, lock, dispatch_sync)
  │     │           → BLOCKED: Main thread waiting
  │     │           → Profile with System Trace
  │     │
  │     └─→ NO: Can you reproduce?
  │           │
  │           ├─→ YES: Profile with Time Profiler first
  │           │     │
  │           │     ├─→ High CPU on main thread
  │           │     │     → BUSY: Optimize the work
  │           │     │
  │           │     └─→ Low CPU, thread blocked
  │           │           → Use System Trace to find what's blocking
  │           │
  │           └─→ NO: Enable MetricKit in app
  │                 → Wait for field reports
  │                 → Check Organizer > Hangs

Tool Selection

Time Profiler Workflow for Hangs

1. Launch Instruments → Select Time Profiler template
2. Record during hang → Reproduce the freeze
3. Stop recording → Find the hang period in timeline
4. Select hang region → Drag to select frozen timespan
5. Examine call tree → Look for main thread work

What to look for :

• Functions with high "Self Time" on main thread
• Unexpectedly deep call stacks
• System calls that shouldn't be on main thread

System Trace Workflow for Blocked Hangs

1. Launch Instruments → Select System Trace template
2. Record during hang → Capture thread states
3. Find main thread → Filter to main thread
4. Look for red/orange → Blocked states
5. Examine blocking reason → Lock, semaphore, IPC

Thread states :

• Running (blue) : Executing code
• Preempted (orange) : Runnable but not scheduled
• Blocked (red) : Waiting for resource

Common Hang Patterns and Fixes

Pattern 1: Synchronous File I/O

Before (hangs) :

// Main thread blocks on file read
func loadUserData() {
    let data = try! Data(contentsOf: largeFileURL)  // BLOCKS
    processData(data)
}

After (async) :

func loadUserData() {
    Task.detached {
        let data = try Data(contentsOf: largeFileURL)
        await MainActor.run {
            self.processData(data)
        }
    }
}

Pattern 2: Unfiltered Notification Observer

Before (processes all) :

NotificationCenter.default.addObserver(
    self,
    selector: #selector(handleChange),
    name: .NSManagedObjectContextObjectsDidChange,
    object: nil  // Receives ALL contexts
)

After (filtered) :

NotificationCenter.default.addObserver(
    self,
    selector: #selector(handleChange),
    name: .NSManagedObjectContextObjectsDidChange,
    object: relevantContext  // Only this context
)

Pattern 3: Expensive Formatter Creation

Before (creates each time) :

func formatDate(_ date: Date) -> String {
    let formatter = DateFormatter()  // EXPENSIVE
    formatter.dateStyle = .medium
    return formatter.string(from: date)
}

After (cached) :

private static let dateFormatter: DateFormatter = {
    let formatter = DateFormatter()
    formatter.dateStyle = .medium
    return formatter
}()

func formatDate(_ date: Date) -> String {
    Self.dateFormatter.string(from: date)
}

Pattern 4: dispatch_sync to Main Thread

Before (deadlock risk) :

// From background thread
DispatchQueue.main.sync {  // BLOCKS if main is blocked
    updateUI()
}

After (async) :

DispatchQueue.main.async {
    self.updateUI()
}

Pattern 5: Semaphore for Async Result

Before (blocks main thread) :

func fetchDataSync() -> Data {
    let semaphore = DispatchSemaphore(value: 0)
    var result: Data?

    URLSession.shared.dataTask(with: url) { data, _, _ in
        result = data
        semaphore.signal()
    }.resume()

    semaphore.wait()  // BLOCKS MAIN THREAD
    return result!
}

After (async/await) :

func fetchData() async throws -> Data {
    let (data, _) = try await URLSession.shared.data(from: url)
    return data
}

Pattern 6: Lock Contention

Before (shared lock) :

class DataManager {
    private let lock = NSLock()
    private var cache: [String: Data] = [:]

    func getData(for key: String) -> Data? {
        lock.lock()  // Main thread waits for background
        defer { lock.unlock() }
        return cache[key]
    }
}

After (actor) :

actor DataManager {
    private var cache: [String: Data] = [:]

    func getData(for key: String) -> Data? {
        cache[key]  // Actor serializes access safely
    }
}

Pattern 7: App Launch Hang (Watchdog)

Before (too much work) :

func application(_ application: UIApplication,
                 didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    loadAllUserData()      // Expensive
    setupAnalytics()       // Network calls
    precomputeLayouts()    // CPU intensive
    return true
}

After (deferred) :

func application(_ application: UIApplication,
                 didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    // Only essential setup
    setupMinimalUI()
    return true
}

func applicationDidBecomeActive(_ application: UIApplication) {
    // Defer non-essential work
    Task {
        await loadUserDataInBackground()
    }
}

Pattern 8: Image Processing on Main Thread

Before (blocks UI) :

func processImage(_ image: UIImage) {
    let filtered = applyExpensiveFilter(image)  // BLOCKS
    imageView.image = filtered
}

After (background processing) :

func processImage(_ image: UIImage) {
    imageView.image = placeholder

    Task.detached(priority: .userInitiated) {
        let filtered = applyExpensiveFilter(image)
        await MainActor.run {
            self.imageView.image = filtered
        }
    }
}

Xcode Organizer Hang Diagnostics

Window > Organizer > Select App > Hangs

The Organizer shows aggregated hang data from users who opted into sharing diagnostics.

Reading the report :

1. Hang Rate : Hangs per day per device
2. Call Stack : Where the hang occurred
3. Device/OS breakdown : Which configurations affected

Interpreting call stacks :

• Your code at top : Main thread busy with your work
• System API at top : You called blocking API on main thread
• pthread_mutex/semaphore : Lock contention or explicit waiting

MetricKit Hang Diagnostics

Adopt MetricKit to receive hang diagnostics in your app:

import MetricKit

class MetricsSubscriber: NSObject, MXMetricManagerSubscriber {
    func didReceive(_ payloads: [MXDiagnosticPayload]) {
        for payload in payloads {
            if let hangDiagnostics = payload.hangDiagnostics {
                for diagnostic in hangDiagnostics {
                    analyzeHang(diagnostic)
                }
            }
        }
    }

    private func analyzeHang(_ diagnostic: MXHangDiagnostic) {
        // Duration of the hang
        let duration = diagnostic.hangDuration

        // Call stack tree (needs symbolication)
        let callStack = diagnostic.callStackTree

        // Send to your analytics
        uploadHangDiagnostic(duration: duration, callStack: callStack)
    }
}

Key MXHangDiagnostic properties :

• hangDuration: How long the hang lasted
• callStackTree: MXCallStackTree with frames
• signatureIdentifier: For grouping similar hangs

Watchdog Terminations

The watchdog kills apps that hang during key transitions:

Watchdog disabled in :

• Simulator
• Debugger attached
• Development builds (sometimes)

Watchdog kills are logged as crashes with exception type EXC_CRASH (SIGKILL) and termination reason Namespace RUNNINGBOARD, Code 3735883980 (hex 0xDEAD10CC — indicates app held a file lock or SQLite database lock while being suspended).

Pressure Scenarios

Scenario 1: Manager Says "Just Add a Loading Spinner"

Situation : App hangs during data load. Manager suggests adding spinner to "fix" it.

Why this fails : Adding a spinner doesn't prevent the hang—the UI still freezes, the spinner won't animate, and the app remains unresponsive.

Correct response : "A spinner won't animate during a hang because the main thread is blocked. We need to move this work off the main thread so the spinner can actually spin and the app stays responsive."

Scenario 2: "It Works Fine in Testing"

Situation : QA can't reproduce the hang. Logs show it happens in production.

Analysis :

1. Field devices have different data sizes
2. Network conditions vary (slow connection = longer sync)
3. Background apps consume memory/CPU
4. Watchdog is disabled in debug builds

Action :

• Add MetricKit to capture field diagnostics
• Test with production-sized datasets
• Test without debugger attached
• Check Organizer for hang reports

Scenario 3: "We've Always Done It This Way"

Situation : Legacy code calls synchronous API on main thread. Refactoring is "too risky."

Why it matters : Even if it worked before:

• Data may have grown larger
• OS updates may have changed timing
• New devices have different characteristics
• Users notice more as apps get faster

Approach :

1. Add metrics to measure current hang rate
2. Refactor incrementally with feature flags
3. A/B test to show improvement
4. Document risk of not fixing

Anti-Patterns to Avoid

Hang Prevention Checklist

Before shipping, verify:

• No Data(contentsOf:) or file reads on main thread
• No DispatchQueue.main.sync from background threads
• No semaphore.wait() on main thread
• Formatters (DateFormatter, NumberFormatter) are cached
• Notification observers filter appropriately
• Launch work is minimized (defer non-essential)
• Image processing happens off main thread
• Database queries don't run on main thread
• MetricKit adopted for field diagnostics

Resources

WWDC : 2021-10258, 2022-10082

Docs : /xcode/analyzing-responsiveness-issues-in-your-shipping-app, /metrickit/mxhangdiagnostic

Skills : axiom-metrickit-ref, axiom-performance-profiling, axiom-swift-concurrency, axiom-lldb (interactive thread inspection at freeze point)

Weekly Installs

94

Repository

charleswiltgen/axiom

GitHub Stars

610

First Seen

Jan 21, 2026

Security Audits

Gen Agent Trust HubPassSocketPassSnykPass

Installed on

opencode78

claude-code74

codex72

gemini-cli71

cursor71

github-copilot67