1# Tasks
2 
3Use this when:
4 
5- You need to start async work from synchronous code.
6- You are choosing between `Task`, `async let`, and task groups.
7- You need cancellation, priorities, or structured vs unstructured guidance.
8 
9Skip this file if:
10 
11- The problem is mainly actor isolation or sendability. Use `actors.md` or `sendable.md`.
12- The work is stream-shaped. Use `async-sequences.md` or `async-algorithms.md`.
13 
14Jump to:
15 
16- What is a Task?
17- Cancellation
18- Task Groups
19- Discarding Task Groups
20- Advanced: Task Timeout Pattern
21- SwiftUI Integration
22- Structured vs Unstructured Tasks
23- Task Priorities
24 
25## What is a Task?
26 
27Tasks bridge synchronous and asynchronous contexts. They start executing immediately upon creation—no `resume()` needed.
28 
29```swift
30func synchronousMethod() {
31    Task {
32        await someAsyncMethod()
33    }
34}
35```
36 
37 
38### Task entry isolation
39 
40`Task { ... }` inherits the enclosing isolation domain. This is especially easy to miss in modules that use `defaultIsolation(MainActor.self)` because bare tasks then start on `@MainActor` by default.
41 
42Choose task entry isolation using the synchronous prefix rule (everything before the first `await`):
43- If the prefix needs main-actor work, keep inherited `@MainActor` entry.
44- If the prefix does not need main actor, prefer `Task { @concurrent in ... }` and hop back only for UI mutation.
45 
46```swift
47// ❌ Prefix has no main-actor work; first await hops away
48Task {
49    await someActor.refresh()
50}
51 
52// ✅ Prefix needs @MainActor; keep inherited main start
53Task {
54    print("debug")        // trivial non-main line rides along
55    self.isLoading = true  // main-actor state before first await
56    await fetchData()
57}
58```
59 
60For deeper guidance and expanded examples, see `threading.md#choosing-task-entry-isolation`.
61 
62## Task References
63 
64Storing a reference is optional but enables cancellation and result waiting:
65 
66```swift
67final class ImageLoader {
68    var loadTask: Task<UIImage, Error>?
69    
70    func load() {
71        loadTask = Task {
72            try await fetchImage()
73        }
74    }
75    
76    deinit {
77        loadTask?.cancel()
78    }
79}
80```
81 
82Tasks run regardless of whether you keep a reference.
83 
84> **Course Deep Dive**: This topic is covered in detail in [Lesson 3.1: Introduction to tasks in Swift Concurrency](https://www.swiftconcurrencycourse.com?utm_source=github&utm_medium=agent-skill&utm_campaign=lesson-reference)
85 
86## Cancellation
87 
88### Checking for cancellation
89 
90Tasks must manually check for cancellation:
91 
92```swift
93// Throws CancellationError if canceled
94try Task.checkCancellation()
95 
96// Boolean check for custom handling
97guard !Task.isCancelled else {
98    return fallbackValue
99}
100```
101 
102### Where to check
103 
104Add checks at natural breakpoints:
105 
106```swift
107let task = Task {
108    // Before expensive work
109    try Task.checkCancellation()
110    
111    let data = try await URLSession.shared.data(from: url)
112    
113    // After network, before processing
114    try Task.checkCancellation()
115    
116    return processData(data)
117}
118```
119 
120### Child task cancellation
121 
122Canceling a parent automatically notifies all children:
123 
124```swift
125let parent = Task {
126    async let child1 = work(1)
127    async let child2 = work(2)
128    let results = try await [child1, child2]
129}
130 
131parent.cancel() // Both children notified
132```
133 
134Children must still check `Task.isCancelled` to stop work.
135 
136> **Course Deep Dive**: This topic is covered in detail in [Lesson 3.2: Task cancellation](https://www.swiftconcurrencycourse.com?utm_source=github&utm_medium=agent-skill&utm_campaign=lesson-reference)
137 
138## Error Handling
139 
140Task error types are inferred from the operation:
141 
142```swift
143// Can throw
144let throwingTask: Task<String, Error> = Task {
145    throw URLError(.badURL)
146}
147 
148// Cannot throw
149let nonThrowingTask: Task<String, Never> = Task {
150    "Success"
151}
152```
153 
154### Awaiting results
155 
156```swift
157do {
158    let result = try await task.value
159} catch {
160    // Handle error
161}
162```
163 
164### Handling errors internally
165 
166```swift
167let safeTask: Task<String, Never> = Task {
168    do {
169        return try await riskyOperation()
170    } catch {
171        return "Fallback value"
172    }
173}
174```
175 
176> **Course Deep Dive**: This topic is covered in detail in [Lesson 3.3: Error handling in Tasks](https://www.swiftconcurrencycourse.com?utm_source=github&utm_medium=agent-skill&utm_campaign=lesson-reference)
177 
178## SwiftUI Integration
179 
180### The .task modifier
181 
182Automatically manages task lifetime with view lifecycle:
183 
184```swift
185struct ContentView: View {
186    @State private var data: Data?
187    
188    var body: some View {
189        Text(data?.description ?? "Loading...")
190            .task {
191                data = try? await fetchData()
192            }
193    }
194}
195```
196 
197Task cancels automatically when view disappears.
198 
199### Reacting to value changes
200 
201```swift
202.task(id: searchQuery) {
203    await performSearch(searchQuery)
204}
205```
206 
207When `searchQuery` changes:
2081. Previous task cancels
2092. New task starts with updated value
210 
211> **Course Deep Dive**: This topic is covered in detail in [Lesson 3.12: Running tasks in SwiftUI](https://www.swiftconcurrencycourse.com?utm_source=github&utm_medium=agent-skill&utm_campaign=lesson-reference)
212 
213### Priority configuration
214 
215```swift
216// High priority (default for SwiftUI)
217.task(priority: .userInitiated) {
218    await fetchUserData()
219}
220 
221// Lower priority for background work
222.task(priority: .low) {
223    await trackAnalytics()
224}
225```
226 
227## Task Groups
228 
229Dynamic parallel task execution with compile-time unknown task count.
230 
231### Basic usage
232 
233```swift
234await withTaskGroup(of: UIImage.self) { group in
235    for url in photoURLs {
236        group.addTask {
237            await downloadPhoto(url: url)
238        }
239    }
240}
241```
242 
243### Collecting results
244 
245```swift
246let images = await withTaskGroup(of: UIImage.self) { group in
247    for url in photoURLs {
248        group.addTask { await downloadPhoto(url: url) }
249    }
250    
251    return await group.reduce(into: []) { $0.append($1) }
252}
253```
254 
255### Error handling
256 
257```swift
258let images = try await withThrowingTaskGroup(of: UIImage.self) { group in
259    for url in photoURLs {
260        group.addTask { try await downloadPhoto(url: url) }
261    }
262    
263    // Iterate to propagate errors
264    var results: [UIImage] = []
265    for try await image in group {
266        results.append(image)
267    }
268    return results
269}
270```
271 
272**Critical**: Errors in child tasks don't automatically fail the group. Use iteration (`for try await`, `next()`, `reduce()`) to propagate errors.
273 
274> **Course Deep Dive**: This topic is covered in detail in [Lesson 3.5: Task Groups](https://www.swiftconcurrencycourse.com?utm_source=github&utm_medium=agent-skill&utm_campaign=lesson-reference)
275 
276### Early termination on error
277 
278```swift
279try await withThrowingTaskGroup(of: Data.self) { group in
280    for id in ids {
281        group.addTask { try await fetch(id) }
282    }
283    
284    // First error cancels remaining tasks
285    while let data = try await group.next() {
286        process(data)
287    }
288}
289```
290 
291### Cancellation
292 
293```swift
294await withTaskGroup(of: Result.self) { group in
295    for item in items {
296        group.addTask { await process(item) }
297    }
298    
299    // Cancel all remaining tasks
300    group.cancelAll()
301}
302```
303 
304Or prevent adding to canceled group:
305 
306```swift
307let didAdd = group.addTaskUnlessCancelled {
308    await work()
309}
310```
311 
312## Discarding Task Groups
313 
314For fire-and-forget operations where results don't matter:
315 
316```swift
317await withDiscardingTaskGroup { group in
318    group.addTask { await logEvent("user_login") }
319    group.addTask { await preloadCache() }
320    group.addTask { await syncAnalytics() }
321}
322```
323 
324### Benefits
325 
326- More memory efficient (doesn't store results)
327- No `next()` calls needed
328- Automatically waits for completion
329- Ideal for side effects
330 
331### Error handling
332 
333```swift
334try await withThrowingDiscardingTaskGroup { group in
335    group.addTask { try await uploadLog() }
336    group.addTask { try await syncSettings() }
337}
338// First error cancels group and throws
339```
340 
341### Real-world pattern: Multiple notifications
342 
343```swift
344extension NotificationCenter {
345    func notifications(named names: [Notification.Name]) -> AsyncStream<()> {
346        AsyncStream { continuation in
347            let task = Task {
348                await withDiscardingTaskGroup { group in
349                    for name in names {
350                        group.addTask {
351                            for await _ in self.notifications(named: name) {
352                                continuation.yield(())
353                            }
354                        }
355                    }
356                }
357                continuation.finish()
358            }
359            
360            continuation.onTermination = { _ in task.cancel() }
361        }
362    }
363}
364 
365// Usage
366for await _ in NotificationCenter.default.notifications(
367    named: [.userDidLogin, UIApplication.didBecomeActiveNotification]
368) {
369    refreshData()
370}
371```
372 
373> **Course Deep Dive**: This topic is covered in detail in [Lesson 3.6: Discarding Task Groups](https://www.swiftconcurrencycourse.com?utm_source=github&utm_medium=agent-skill&utm_campaign=lesson-reference)
374 
375## Structured vs Unstructured Tasks
376 
377### Structured (preferred)
378 
379Bound to parent, inherit context, automatic cancellation:
380 
381```swift
382// async let
383async let data1 = fetch(1)
384async let data2 = fetch(2)
385let results = await [data1, data2]
386 
387// Task groups
388await withTaskGroup(of: Data.self) { group in
389    group.addTask { await fetch(1) }
390    group.addTask { await fetch(2) }
391}
392```
393 
394> **Course Deep Dive**: This topic is covered in detail in [Lesson 3.7: The difference between structured and unstructured tasks](https://www.swiftconcurrencycourse.com?utm_source=github&utm_medium=agent-skill&utm_campaign=lesson-reference)
395 
396### Unstructured (use sparingly)
397 
398Independent lifecycle, manual cancellation:
399 
400```swift
401// Regular task (unstructured but inherits priority)
402let task = Task {
403    await doWork()
404}
405 
406// Detached task (completely independent)
407Task.detached(priority: .background) {
408    await cleanup()
409}
410```
411 
412## Detached Tasks
413 
414**Use as last resort.** They don't inherit:
415- Priority
416- Task-local values
417- Cancellation state
418 
419```swift
420Task.detached(priority: .background) {
421    await DirectoryCleaner.cleanup()
422}
423```
424 
425### When to use
426 
427- Independent background work
428- No connection to parent needed
429- Acceptable to complete after parent cancels
430- No `self` references needed
431 
432**Prefer**: Task groups or `async let` for most parallel work.
433 
434> **Course Deep Dive**: This topic is covered in detail in [Lesson 3.4: Detached Tasks](https://www.swiftconcurrencycourse.com?utm_source=github&utm_medium=agent-skill&utm_campaign=lesson-reference)
435 
436## Task Priorities
437 
438### Available priorities
439 
440```swift
441.high           // Immediate user feedback
442.userInitiated  // User-triggered work (same as .high)
443.medium         // Default for detached tasks
444.utility        // Longer-running, non-urgent
445.low            // Similar to .background
446.background     // Lowest priority
447```
448 
449### Setting priority
450 
451```swift
452Task(priority: .background) {
453    await prefetchData()
454}
455```
456 
457### Priority inheritance
458 
459Structured tasks inherit parent priority:
460 
461```swift
462Task(priority: .high) {
463    async let result = work() // Also .high
464    await result
465}
466```
467 
468Detached tasks don't inherit:
469 
470```swift
471Task(priority: .high) {
472    Task.detached {
473        // Runs at .medium (default)
474    }
475}
476```
477 
478### Priority escalation
479 
480System automatically elevates priority to prevent priority inversion:
481- Actor waiting on lower-priority task
482- High-priority task awaiting `.value` of lower-priority task
483 
484> **Course Deep Dive**: This topic is covered in detail in [Lesson 3.8: Managing Task priorities](https://www.swiftconcurrencycourse.com?utm_source=github&utm_medium=agent-skill&utm_campaign=lesson-reference)
485 
486## Task.sleep() vs Task.yield()
487 
488### Task.sleep()
489 
490Suspends for fixed duration, non-blocking:
491 
492```swift
493try await Task.sleep(for: .seconds(5))
494```
495 
496**Use for:**
497- Debouncing user input
498- Polling intervals
499- Rate limiting
500- Artificial delays
501 
502**Respects cancellation** (throws `CancellationError`)
503 
504### Task.yield()
505 
506Temporarily suspends to allow other tasks to run:
507 
508```swift
509await Task.yield()
510```
511 
512**Use for:**
513- Testing async code
514- Allowing cooperative scheduling
515 
516**Note**: If current task is highest priority, may resume immediately.
517 
518### Practical: Debounced search
519 
520```swift
521func search(_ query: String) async {
522    guard !query.isEmpty else {
523        searchResults = allResults
524        return
525    }
526    
527    do {
528        try await Task.sleep(for: .milliseconds(500))
529        searchResults = allResults.filter { $0.contains(query) }
530    } catch {
531        // Canceled (user kept typing)
532    }
533}
534 
535// In SwiftUI
536.task(id: searchQuery) {
537    await searcher.search(searchQuery)
538}
539```
540 
541> **Course Deep Dive**: This topic is covered in detail in [Lesson 3.10: Task.yield() vs. Task.sleep()](https://www.swiftconcurrencycourse.com?utm_source=github&utm_medium=agent-skill&utm_campaign=lesson-reference)
542 
543## async let vs TaskGroup
544 
545| Feature | async let | TaskGroup |
546|---------|-----------|-----------|
547| Task count | Fixed at compile-time | Dynamic at runtime |
548| Syntax | Lightweight | More verbose |
549| Cancellation | Automatic on scope exit | Manual via `cancelAll()` |
550| Use when | 2-5 known parallel tasks | Loop-based parallel work |
551 
552```swift
553// async let: Known task count
554async let user = fetchUser()
555async let settings = fetchSettings()
556let profile = Profile(user: await user, settings: await settings)
557 
558// TaskGroup: Dynamic task count
559await withTaskGroup(of: Image.self) { group in
560    for url in urls {
561        group.addTask { await download(url) }
562    }
563}
564```
565 
566## Advanced: Task Timeout Pattern
567 
568Create timeout wrapper using task groups:
569 
570```swift
571func withTimeout<T>(
572    _ duration: Duration,
573    operation: @Sendable @escaping () async throws -> T
574) async throws -> T {
575    try await withThrowingTaskGroup(of: T.self) { group in
576        group.addTask { try await operation() }
577        
578        group.addTask {
579            try await Task.sleep(for: duration)
580            throw TimeoutError()
581        }
582        
583        guard let result = try await group.next() else {
584            throw TimeoutError()
585        }
586        
587        group.cancelAll()
588        return result
589    }
590}
591 
592// Usage
593let data = try await withTimeout(.seconds(5)) {
594    try await slowNetworkRequest()
595}
596```
597 
598**`cancelAll()` is critical** — without it, the losing task keeps running until scope exit.
599 
600`Task.sleep` throws `CancellationError` when the task is cancelled, making it a useful cancellation checkpoint in polling loops. `Task.yield()` only gives other tasks a chance to run and does not check cancellation — if the current task has the highest priority, it may resume immediately.
601 
602> **Course Deep Dive**: This topic is covered in detail in [Lesson 3.14: Creating a Task timeout handler using a Task Group (advanced)](https://www.swiftconcurrencycourse.com?utm_source=github&utm_medium=agent-skill&utm_campaign=lesson-reference)
603 
604## Common Patterns
605 
606### Sequential with early exit
607 
608```swift
609let user = try await fetchUser()
610guard user.isActive else { return }
611 
612let posts = try await fetchPosts(userId: user.id)
613```
614 
615### Parallel independent work
616 
617```swift
618async let user = fetchUser()
619async let settings = fetchSettings()
620async let notifications = fetchNotifications()
621 
622let data = try await (user, settings, notifications)
623```
624 
625### Mixed: Sequential then parallel
626 
627```swift
628let user = try await fetchUser()
629 
630async let posts = fetchPosts(userId: user.id)
631async let followers = fetchFollowers(userId: user.id)
632 
633let profile = Profile(
634    user: user,
635    posts: try await posts,
636    followers: try await followers
637)
638```
639 
640## Common Mistakes Agents Make
641 
642- Replacing structured child work with many unrelated top-level tasks.
643- Using `Task.detached` just to "make it background."
644- Ignoring cancellation in long-running operations.
645- Keeping a stored task forever without a clear owner or cleanup path.
646- Picking entry isolation from the enclosing context rather than the task's synchronous prefix — `Task { await someActor.x() }` from a `@MainActor` context should be `Task { @concurrent in ... }`; a `Task` whose prefix mutates `@MainActor` state should stay on inherited `@MainActor` even if it also has a `print`.
647- Priorities are hints, not guarantees. The system automatically elevates priority to prevent inversion (e.g., a high-priority task awaiting `.value` of a lower-priority task). Do not rely on priority for correctness.
648 
649## Best Practices
650 
6511. **Check cancellation regularly** in long-running tasks
6522. **Use structured concurrency** (avoid detached tasks)
6533. **Leverage SwiftUI's `.task` modifier** for view-bound work
6544. **Choose the right tool**: `async let` for fixed, TaskGroup for dynamic
6555. **Handle errors explicitly** in throwing task groups
6566. **Set priority only when needed** (inherit by default)
6577. **Don't mutate task groups** from outside their creation context
658 
659## Further Learning
660 
661For hands-on examples, advanced patterns, and migration strategies, see [Swift Concurrency Course](https://www.swiftconcurrencycourse.com).
662 
663