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

Symptom This Skill Applies

App freezes briefly during use Yes — likely hang

UI doesn't respond to touches Yes — main thread blocked

"App not responding" system dialog Yes — severe hang

Xcode Organizer shows hang diagnostics Yes — field hang reports

MetricKit MXHangDiagnostic received Yes — aggregated hang data

Animations stutter or skip Maybe — could be hitch, not hang

App feels slow but responsive No — performance issue, not hang

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

Issue Duration User Experience Tool

Hang

1 second App frozen, unresponsive Time Profiler, System Trace

Hitch 1-3 frames (16-50ms) Animation stutters Animation Hitches instrument

Lag 100-500ms Feels slow but responsive Time Profiler

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:

Type Example Fix

Proactive work Pre-computing data user hasn't requested Lazy initialization, compute on demand

Irrelevant work Processing all notifications, not just relevant ones Filter notifications, targeted observers

Suboptimal API Using blocking API when async exists Switch to async API

2. Main Thread Blocked

The main thread is waiting for something else.

Subcategories:

Type Example Fix

Synchronous IPC Calling system service synchronously Use async API variant

File I/O Data(contentsOf:) on main thread Move to background queue

Network Synchronous URL request Use URLSession async

Lock contention Waiting for lock held by background thread Reduce critical section, use actors

Semaphore/dispatch_sync Blocking on background work Restructure to async completion

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

Scenario Primary Tool Why

Reproduces locally Time Profiler See exactly what main thread is doing

Blocked thread suspected System Trace Shows thread state, lock contention

Field reports only Xcode Organizer Aggregated hang diagnostics

Want in-app data MetricKit MXHangDiagnostic with call stacks

Need precise timing System Trace Nanosecond-level thread analysis

Time Profiler Workflow for Hangs

• Launch Instruments → Select Time Profiler template

• Record during hang → Reproduce the freeze

• Stop recording → Find the hang period in timeline

• Select hang region → Drag to select frozen timespan

• 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

• Launch Instruments → Select System Trace template

• Record during hang → Capture thread states

• Find main thread → Filter to main thread

• Look for red/orange → Blocked states

• 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:

• Hang Rate: Hangs per day per device

• Call Stack: Where the hang occurred

• 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:

Transition Time Limit Consequence

App launch ~20 seconds App killed, crash logged

Background transition ~5 seconds App killed

Foreground transition ~10 seconds App killed

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:

• Field devices have different data sizes

• Network conditions vary (slow connection = longer sync)

• Background apps consume memory/CPU

• 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:

• Add metrics to measure current hang rate

• Refactor incrementally with feature flags

• A/B test to show improvement

• Document risk of not fixing

Anti-Patterns to Avoid

Anti-Pattern Why It's Wrong Instead

DispatchQueue.main.sync from background Can deadlock, always blocks Use .async

Semaphore to convert async to sync Blocks calling thread Stay async with completion/await

File I/O on main thread Unpredictable latency Background queue

Unfiltered notification observer Processes irrelevant events Filter by object/name

Creating formatters in loops Expensive initialization Cache and reuse

Synchronous network request Blocks on network latency URLSession async

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