1# Threading
2 
3Use this when:
4 
5- You need to understand the relationship between tasks and threads.
6- You are debugging suspension points, actor reentrancy, or unexpected execution contexts.
7- You need Swift 6.2 behavior guidance (`nonisolated async`, `@concurrent`, `nonisolated(nonsending)`).
8 
9Skip this file if:
10 
11- You mainly need to protect mutable state. Use `actors.md`.
12- You need to make types safe to transfer. Use `sendable.md`.
13 
14Jump to:
15 
16- Core Concepts (Tasks vs Threads)
17- Cooperative Thread Pool
18- Suspension Points and Actor Reentrancy
19- Swift 6.2 Changes (SE-461, SE-466)
20- Default Isolation Domain
21- Debugging Thread Execution
22- Common Misconceptions
23- Migration Strategy
24 
25## Core Concepts
26 
27### What is a Thread?
28 
29System-level resource that runs instructions. High overhead for creation and switching. Swift Concurrency abstracts thread management away.
30 
31### Tasks vs Threads
32 
33**Tasks** are units of async work, not tied to specific threads. Swift dynamically schedules tasks on available threads from a cooperative pool.
34 
35**Key insight**: No direct relationship between one task and one thread.
36 
37> **Course Deep Dive**: This topic is covered in detail in [Lesson 7.1: How Threads relate to Tasks](https://www.swiftconcurrencycourse.com?utm_source=github&utm_medium=agent-skill&utm_campaign=lesson-reference)
38 
39**Important (Swift 6+)**: Avoid using `Thread.current` inside async contexts. In Swift 6 language mode, `Thread.current` is unavailable from asynchronous contexts and will fail to compile. Prefer reasoning in terms of isolation domains; use Instruments and the debugger to observe execution when needed.
40 
41## Cooperative Thread Pool
42 
43Swift creates only as many threads as CPU cores. Tasks share these threads efficiently.
44 
45### How it works
46 
471. **Limited threads**: Number matches CPU cores
482. **Task scheduling**: Tasks scheduled onto available threads
493. **Suspension**: At `await`, task suspends, thread freed for other work
504. **Resumption**: Task resumes on any available thread (not necessarily the same one)
51 
52```swift
53func example() async {
54    print("Started on: \(Thread.current)")
55    
56    try await Task.sleep(for: .seconds(1))
57    
58    print("Resumed on: \(Thread.current)") // Likely different thread
59}
60```
61 
62### Benefits over GCD
63 
64**Prevents thread explosion**:
65- No excessive thread creation
66- No high memory overhead from idle threads
67- No excessive context switching
68- No priority inversion
69 
70**Better performance**:
71- Fewer threads = less context switching
72- Continuations instead of blocking
73- CPU cores stay busy efficiently
74 
75## Threading Mindset → Isolation Mindset
76 
77### Old way (GCD)
78 
79```swift
80// Thinking about threads
81DispatchQueue.main.async {
82    // Update UI on main thread
83}
84 
85DispatchQueue.global(qos: .background).async {
86    // Heavy work on background thread
87}
88```
89 
90### New way (Swift Concurrency)
91 
92```swift
93// Thinking about isolation domains
94@MainActor
95func updateUI() {
96    // Runs on main actor (usually main thread)
97}
98 
99func heavyWork() async {
100    // Runs on any available thread in pool
101}
102```
103 
104### Think in isolation domains
105 
106**Don't ask**: "What thread should this run on?"
107 
108**Ask**: "What isolation domain should own this work?"
109 
110- `@MainActor` for UI updates
111- Custom actors for specific state
112- Nonisolated for general async work
113 
114### Provide hints, not commands
115 
116```swift
117Task(priority: .userInitiated) {
118    await doWork()
119}
120```
121 
122You're describing the nature of work, not assigning threads. Swift optimizes execution.
123 
124> **Course Deep Dive**: This topic is covered in detail in [Lesson 7.2: Getting rid of the "Threading Mindset"](https://www.swiftconcurrencycourse.com?utm_source=github&utm_medium=agent-skill&utm_campaign=lesson-reference)
125 
126## Suspension Points
127 
128### What is a suspension point?
129 
130Moment where task **may** pause to allow other work. Marked by `await`.
131 
132```swift
133let data = await fetchData() // Potential suspension
134```
135 
136**Critical**: `await` marks *possible* suspension, not guaranteed. If operation completes synchronously, no suspension occurs.
137 
138### Why suspension points matter
139 
1401. **Code may pause unexpectedly** - resumes later, possibly different thread
1412. **State can change** - mutable state may be modified during suspension
1423. **Actor reentrancy** - other tasks can access actor during suspension
143 
144The same entry-isolation rule applies to any unstructured task: choose startup isolation by what the synchronous prefix needs. If nothing before the first `await` needs the main actor—whether that first operation is `Task.sleep`, an actor hop, a `print`, or a Sendable computation—prefer `Task { @concurrent in ... }` and hop back with `MainActor.run` only for the UI mutation. If the synchronous prefix already needs main actor for one statement, keep nearby cheap lines on main with it instead of splitting them out.
145 
146### Actor reentrancy example
147 
148```swift
149actor BankAccount {
150    private var balance: Int = 0
151    
152    func deposit(amount: Int) async {
153        balance += amount
154        print("Balance: \(balance)")
155        
156        await logTransaction(amount) // ⚠️ Suspension point
157        
158        balance += 10 // Bonus
159        print("After bonus: \(balance)")
160    }
161    
162    func logTransaction(_ amount: Int) async {
163        try? await Task.sleep(for: .seconds(1))
164    }
165}
166 
167// Two concurrent deposits
168async let _ = account.deposit(amount: 100)
169async let _ = account.deposit(amount: 100)
170 
171// Unexpected: 100 → 200 → 210 → 220
172// Expected:   100 → 110 → 210 → 220
173```
174 
175**Why**: During `logTransaction`, second deposit runs, modifying balance before first completes.
176 
177### Avoiding reentrancy bugs
178 
179**Complete actor work before suspending**:
180 
181```swift
182func deposit(amount: Int) async {
183    balance += amount
184    balance += 10 // Bonus applied first
185    print("Final balance: \(balance)")
186    
187    await logTransaction(amount) // Suspend after state changes
188}
189```
190 
191**Rule**: Don't mutate actor state after suspension points.
192 
193> **Course Deep Dive**: This topic is covered in detail in [Lesson 7.3: Understanding Task suspension points](https://www.swiftconcurrencycourse.com?utm_source=github&utm_medium=agent-skill&utm_campaign=lesson-reference)
194 
195 
196## Choosing Task entry isolation
197 
198For unstructured `Task { ... }`, choose entry isolation based on the synchronous prefix (everything before the first `await`), not on where the task was created.
199 
200Two common reasons a bare `Task { ... }` starts on `@MainActor`:
201- The task is spawned from a `@MainActor` context.
202- The module enables default main-actor isolation (for example, `defaultIsolation(MainActor.self)`).
203 
204Rule:
205- If the synchronous prefix contains any main-actor work, keep inherited main-actor entry.
206- If the synchronous prefix contains no main-actor work, start with `Task { @concurrent in ... }` and hop back to `MainActor` only when needed.
207 
208```swift
209// ❌ Synchronous prefix is empty; first work hops away
210Task {
211    await hopToOtherIsolationDomain()
212}
213 
214// ❌ Synchronous prefix is only `print` (trivial, non-main); first await hops away
215Task {
216    print("Also not main-thread-bound")
217    await hopToOtherIsolationDomain()
218}
219 
220// ✅ Start off the main actor, hop back only for UI work
221Task { @concurrent in
222    await hopToOtherIsolationDomain()
223    await MainActor.run { updateUI() }
224}
225 
226// ✅ Synchronous prefix DOES contain main-actor work — keep inheritance
227Task {
228    print("debug")              // trivial, non-main — rides along
229    self.isLoading = true       // needs @MainActor, before any await
230    await fetchData()
231}
232```
233 
234The delayed-retry `Task.sleep` pattern (see `performance.md` "Match Task entry isolation to its synchronous prefix") is a specialization of this same rule: the wait is usually not UI-owned, while the final mutation is.
235 
236Note that `Task { @concurrent in ... }` changes the closure's isolation, so any capture of non-Sendable state from the enclosing actor must move inside the `MainActor.run { ... }` hop, or be captured weakly (e.g., `[weak self]` plus a `guard let self`) before being used there. The examples above stay safe by keeping `self` use inside `MainActor.run`. If the body needs to touch non-Sendable state directly, see `sendable.md` before reaching for `@concurrent`.
237 
238## Thread Execution Patterns
239 
240### Default: Background threads
241 
242Tasks run on cooperative thread pool (background threads):
243 
244```swift
245Task {
246    print(Thread.current) // Background thread
247}
248```
249 
250### Main thread execution
251 
252Use `@MainActor` for main thread:
253 
254```swift
255@MainActor
256func updateUI() {
257    Task {
258        print(Thread.current) // Main thread
259    }
260}
261```
262 
263### Inheritance example
264 
265```swift
266@MainActor
267func updateUI() {
268    print("Main thread: \(Thread.current)")
269    
270    await backgroundTask() // Switches to background
271    
272    print("Back on main: \(Thread.current)") // Returns to main
273}
274 
275func backgroundTask() async {
276    print("Background: \(Thread.current)")
277}
278```
279 
280## Swift 6.2 Changes
281 
282### Nonisolated async functions (SE-461)
283 
284**Old behavior**: Nonisolated async functions always switch to background.
285 
286**New behavior**: Inherit caller's isolation by default.
287 
288```swift
289class NotSendable {
290    func performAsync() async {
291        print(Thread.current)
292    }
293}
294 
295@MainActor
296func caller() async {
297    let obj = NotSendable()
298    await obj.performAsync()
299    // Old: Background thread
300    // New: Main thread (inherits @MainActor)
301}
302```
303 
304### Enabling new behavior
305 
306In Xcode 16+:
307 
308```swift
309// Build setting or swift-settings
310.enableUpcomingFeature("NonisolatedNonsendingByDefault")
311```
312 
313### Opting out with @concurrent
314 
315Force function to switch away from caller's isolation:
316 
317```swift
318@concurrent
319func performAsync() async {
320    print(Thread.current) // Always background
321}
322```
323 
324### nonisolated(nonsending)
325 
326Prevent sending non-Sendable values across isolation:
327 
328```swift
329nonisolated(nonsending) func storeTouch(...) async {
330    // Runs on caller's isolation, no value sending
331}
332```
333 
334> **Course Deep Dive**: This topic is covered in detail in [Lesson 7.4: Dispatching to different threads using nonisolated(nonsending) and @concurrent (Updated for Swift 6.2)](https://www.swiftconcurrencycourse.com?utm_source=github&utm_medium=agent-skill&utm_campaign=lesson-reference)
335 
336**Use when**: Method doesn't need to switch isolation, avoiding Sendable requirements.
337 
338## Default Isolation Domain (SE-466)
339 
340### Configuring default isolation
341 
342**Build setting** (Xcode 16+):
343- Default Actor Isolation: `MainActor` or `None`
344 
345**Swift Package**:
346 
347```swift
348.target(
349    name: "MyTarget",
350    swiftSettings: [
351        .defaultIsolation(MainActor.self)
352    ]
353)
354```
355 
356### Why change default?
357 
358Most app code runs on main thread. Setting `@MainActor` as default:
359- Reduces false warnings
360- Avoids "concurrency rabbit hole"
361- Makes migration easier
362 
363### Inference with @MainActor default
364 
365```swift
366// With @MainActor as default:
367 
368func f() {} // Inferred: @MainActor
369 
370class C {
371    init() {} // Inferred: @MainActor
372    static var value = 10 // Inferred: @MainActor
373}
374 
375@MyActor
376struct S {
377    func f() {} // Inferred: @MyActor (explicit override)
378}
379 
380> **Course Deep Dive**: This topic is covered in detail in [Lesson 7.5: Controlling the default isolation domain (Updated for Swift 6.2)](https://www.swiftconcurrencycourse.com?utm_source=github&utm_medium=agent-skill&utm_campaign=lesson-reference)
381```
382 
383### Per-module setting
384 
385Must opt in for each module/package. Not global across dependencies.
386 
387### Backward compatibility
388 
389Opt-in only. Default remains `nonisolated` if not specified.
390 
391## Debugging Thread Execution
392 
393### Print current thread
394 
395**⚠️ Important**: `Thread.current` is unavailable in Swift 6 language mode from async contexts. The compiler error states: "Class property 'current' is unavailable from asynchronous contexts; Thread.current cannot be used from async contexts."
396 
397**Workaround** (Swift 6+ mode only):
398 
399```swift
400extension Thread {
401    public static var currentThread: Thread {
402        Thread.current
403    }
404}
405 
406print("Thread: \(Thread.currentThread)")
407```
408 
409### Debug navigator
410 
4111. Set breakpoint in task
4122. Debug → Pause
4133. Check Debug Navigator for thread info
414 
415### Verify main thread
416 
417```swift
418assert(Thread.isMainThread)
419```
420 
421## Common Misconceptions
422 
423### ❌ Each Task runs on new thread
424 
425**Wrong**. Tasks share limited thread pool, reuse threads.
426 
427### ❌ await blocks the thread
428 
429**Wrong**. `await` suspends task without blocking thread. Other tasks can use the thread.
430 
431### ❌ Task execution order is guaranteed
432 
433**Wrong**. Tasks execute based on system scheduling. Use `await` to enforce order.
434 
435### ❌ Same task = same thread
436 
437**Wrong**. Task can resume on different thread after suspension.
438 
439## Why Sendable Matters
440 
441Since tasks move between threads unpredictably:
442 
443```swift
444func example() async {
445    print("Thread 1: \(Thread.current)")
446    
447    await someWork()
448    
449    print("Thread 2: \(Thread.current)") // Different thread
450}
451```
452 
453Values crossing suspension points may cross threads. **Sendable** ensures safety.
454 
455## Best Practices
456 
4571. **Stop thinking about threads** - think isolation domains
4582. **Trust the system** - Swift optimizes thread usage
4593. **Use @MainActor for UI** - clear, explicit main thread execution
4604. **Minimize suspension points in actors** - avoid reentrancy bugs
4615. **Complete state changes before suspending** - prevent inconsistent state
4626. **Use priorities as hints** - not guarantees
4637. **Make types Sendable** - safe across thread boundaries
4648. **Enable Swift 6.2 features** - easier migration, better defaults
4659. **Set default isolation for apps** - reduce false warnings
46610. **Don't force thread switching** - let Swift optimize
467 
468## Migration Strategy
469 
470### For new projects (Xcode 16+)
471 
4721. Set default isolation to `@MainActor`
4732. Enable `NonisolatedNonsendingByDefault`
4743. Use `@concurrent` for explicit background work
475 
476### For existing projects
477 
4781. Gradually enable Swift 6 language mode
4792. Consider default isolation change
4803. Use `@concurrent` to maintain old behavior where needed
4814. Migrate module by module
482 
483## Decision Tree
484 
485```
486Need to control execution?
487├─ UI updates? → @MainActor
488├─ Specific state isolation? → Custom actor
489├─ Background work? → Regular async (trust Swift)
490└─ Need to force background? → @concurrent (Swift 6.2+)
491 
492Seeing Sendable warnings?
493├─ Can make type Sendable? → Add conformance
494├─ Same isolation OK? → nonisolated(nonsending)
495└─ Need different isolation? → Make Sendable or refactor
496```
497 
498## GCD to Isolation Domain Migration
499 
500Instead of asking "what thread should this run on?" ask "what isolation domain should own this work?"
501 
502- `DispatchQueue.main.async { }` → `@MainActor func updateUI()`
503- `DispatchQueue.global().async { }` → `func work() async` (or `@concurrent` if it must leave caller isolation)
504- `DispatchQueue(label:).sync { }` → `actor` or `Mutex` for protecting state
505- Serial queue for ordering → `actor` (guarantees serial access)
506 
507## Decision Rules
508 
509- UI state → usually `@MainActor`
510- Mutable shared state → usually an `actor`
511- Plain async work with no isolated state → `async` API with explicit ownership
512- Work that must hop away from caller isolation under Swift 6.2-era behavior → consider `@concurrent`
513 
514## Common Mistakes Agents Make
515 
516- Recommending GCD queue hopping when actor isolation already expresses the ownership model.
517- Debugging correctness by thread ID instead of by isolation and ordering.
518- Treating `await` as a blocking call — it suspends the task, freeing the thread.
519- Mapping each `Task` to a conceptual thread.
520- Picking task entry isolation by the enclosing context instead of by the task's synchronous prefix. A `Task { ... }` from `@MainActor` whose first `await` immediately hops away (with no main-actor work before it) should usually be `Task { @concurrent in ... }`.
521 
522## Performance Insights
523 
524### Why fewer threads = better performance
525 
526- **Less context switching**: CPU spends more time on actual work
527- **Better cache utilization**: Threads stay on same cores longer
528- **No thread explosion**: Predictable resource usage
529- **Forward progress**: Threads never block, always productive
530 
531### Cooperative pool advantages
532 
533- Matches hardware (one thread per core)
534- Prevents oversubscription
535- Efficient task scheduling
536- Automatic load balancing
537 
538## Further Learning
539 
540For migration strategies, real-world examples, and advanced threading patterns, see [Swift Concurrency Course](https://www.swiftconcurrencycourse.com).
541 
542