1# Actors
2 
3Use this when:
4 
5- You need to protect class-based mutable state from concurrent access.
6- You are choosing between `actor`, `@MainActor`, `nonisolated`, or `Mutex`.
7- You are resolving protocol conformance issues on actor-isolated types.
8 
9Skip this file if:
10 
11- You mainly need to make a value safe to transfer across boundaries. Use `sendable.md`.
12- You are debugging execution threads or suspension behavior. Use `threading.md`.
13 
14Jump to:
15 
16- Actor Isolation
17- Global Actors / @MainActor
18- Isolated vs Nonisolated
19- Actor Reentrancy
20- Isolated Deinit / Isolated Conformances (Swift 6.2+)
21- `#isolation` Macro
22- Mutex: Alternative to Actors
23- Decision Tree
24 
25## What is an Actor?
26 
27Actors protect mutable state by ensuring only one task accesses it at a time. They're reference types with automatic synchronization.
28 
29```swift
30actor Counter {
31    var value = 0
32    
33    func increment() {
34        value += 1
35    }
36}
37```
38 
39**Key guarantee**: Only one task can access mutable state at a time (serialized access).
40 
41> **Course Deep Dive**: This topic is covered in detail in [Lesson 5.1: Understanding actors in Swift Concurrency](https://www.swiftconcurrencycourse.com?utm_source=github&utm_medium=agent-skill&utm_campaign=lesson-reference)
42 
43## Actor Isolation
44 
45### Enforced by compiler
46 
47```swift
48actor BankAccount {
49    var balance: Int = 0
50    
51    func deposit(_ amount: Int) {
52        balance += amount
53    }
54}
55 
56let account = BankAccount()
57account.balance += 1 // ❌ Error: can't mutate from outside
58await account.deposit(1) // ✅ Must use actor's methods
59```
60 
61### Reading properties
62 
63```swift
64let account = BankAccount()
65await account.deposit(100)
66print(await account.balance) // Must await reads too
67```
68 
69Always use `await` when accessing actor properties/methods—you don't know if another task is inside.
70 
71## Actors vs Classes
72 
73### Similarities
74 
75- Reference types (copies share same instance)
76- Can have properties, methods, initializers
77- Can conform to protocols
78 
79### Differences
80 
81- **No inheritance** (except `NSObject` for Objective-C interop)
82- **Automatic isolation** (no manual locks needed)
83- **Implicit Sendable** conformance
84 
85```swift
86// ❌ Can't inherit from actors
87actor Base {}
88actor Child: Base {} // Error
89 
90// ✅ NSObject exception
91actor Example: NSObject {} // OK for Objective-C
92```
93 
94## Global Actors
95 
96Shared isolation domain across types, functions, and properties.
97 
98### @MainActor
99 
100Ensures execution on main thread:
101 
102```swift
103@MainActor
104final class ViewModel {
105    var items: [Item] = []
106}
107 
108@MainActor
109func updateUI() {
110    // Always runs on main thread
111}
112 
113@MainActor
114var title: String = ""
115```
116 
117### Custom global actors
118 
119```swift
120@globalActor
121actor ImageProcessing {
122    static let shared = ImageProcessing()
123    private init() {} // Prevent duplicate instances
124}
125 
126@ImageProcessing
127final class ImageCache {
128    var images: [URL: Data] = [:]
129}
130 
131@ImageProcessing
132func applyFilter(_ image: UIImage) -> UIImage {
133    // All image processing serialized
134}
135```
136 
137**Use private init** to prevent creating multiple executors.
138 
139> **Course Deep Dive**: This topic is covered in detail in [Lesson 5.2: An introduction to Global Actors](https://www.swiftconcurrencycourse.com?utm_source=github&utm_medium=agent-skill&utm_campaign=lesson-reference)
140 
141## @MainActor Best Practices
142 
143### When to use
144 
145UI-related code that must run on main thread:
146 
147```swift
148@MainActor
149final class ContentViewModel: ObservableObject {
150    @Published var items: [Item] = []
151}
152```
153 
154### Replacing DispatchQueue.main
155 
156```swift
157// Old way
158DispatchQueue.main.async {
159    // Update UI
160}
161 
162// Modern way
163await MainActor.run {
164    // Update UI
165}
166 
167// Better: Use attribute
168@MainActor
169func updateUI() {
170    // Automatically on main thread
171}
172```
173 
174### MainActor.assumeIsolated
175 
176**Use sparingly** - assumes you're on main thread, crashes if not:
177 
178```swift
179func methodB() {
180    assert(Thread.isMainThread) // Validate assumption
181    
182    MainActor.assumeIsolated {
183        someMainActorMethod()
184    }
185}
186```
187 
188**Prefer**: Explicit `@MainActor` or `await MainActor.run` over `assumeIsolated`.
189 
190> **Course Deep Dive**: This topic is covered in detail in [Lesson 5.3: When and how to use @MainActor](https://www.swiftconcurrencycourse.com?utm_source=github&utm_medium=agent-skill&utm_campaign=lesson-reference)
191 
192## Isolated vs Nonisolated
193 
194### Default: Isolated
195 
196Actor methods are isolated by default:
197 
198```swift
199actor BankAccount {
200    var balance: Double
201    
202    // Implicitly isolated
203    func deposit(_ amount: Double) {
204        balance += amount
205    }
206}
207```
208 
209### Isolated parameters
210 
211Reduce suspension points by inheriting caller's isolation:
212 
213```swift
214struct Charger {
215    static func charge(
216        amount: Double,
217        from account: isolated BankAccount
218    ) async throws -> Double {
219        // No await needed - we're isolated to account
220        try account.withdraw(amount: amount)
221        return account.balance
222    }
223}
224```
225 
226### Isolated closures
227 
228```swift
229actor Database {
230    func transaction<T>(
231        _ operation: @Sendable (_ db: isolated Database) throws -> T
232    ) throws -> T {
233        beginTransaction()
234        let result = try operation(self)
235        commitTransaction()
236        return result
237    }
238}
239 
240// Usage: Multiple operations, one await
241try await database.transaction { db in
242    db.insert(item1)
243    db.insert(item2)
244    db.insert(item3)
245}
246```
247 
248### Generic isolated extension
249 
250```swift
251extension Actor {
252    func performInIsolation<T: Sendable>(
253        _ block: @Sendable (_ actor: isolated Self) throws -> T
254    ) async rethrows -> T {
255        try block(self)
256    }
257}
258 
259// Usage
260try await bankAccount.performInIsolation { account in
261    try account.withdraw(amount: 20)
262    print("Balance: \(account.balance)")
263}
264```
265 
266### Nonisolated
267 
268Opt out of isolation for immutable data:
269 
270```swift
271actor BankAccount {
272    let accountHolder: String
273    
274    nonisolated var details: String {
275        "Account: \(accountHolder)"
276    }
277}
278 
279// No await needed
280print(account.details)
281```
282 
283### Protocol conformance
284 
285```swift
286extension BankAccount: CustomStringConvertible {
287    nonisolated var description: String {
288        "Account: \(accountHolder)"
289    }
290}
291```
292 
293> **Course Deep Dive**: This topic is covered in detail in [Lesson 5.4: Isolated vs. non-isolated access in actors](https://www.swiftconcurrencycourse.com?utm_source=github&utm_medium=agent-skill&utm_campaign=lesson-reference)
294 
295## Isolated Deinit (Swift 6.2+)
296 
297Clean up actor state on deallocation:
298 
299```swift
300actor FileDownloader {
301    var downloadTask: Task<Void, Error>?
302    
303    isolated deinit {
304        downloadTask?.cancel() // Can call isolated methods
305    }
306}
307```
308 
309**Requires**: iOS 18.4+, macOS 15.4+
310 
311> **Course Deep Dive**: This topic is covered in detail in [Lesson 5.5: Using Isolated synchronous deinit](https://www.swiftconcurrencycourse.com?utm_source=github&utm_medium=agent-skill&utm_campaign=lesson-reference)
312 
313## Global Actor Isolated Conformance (Swift 6.2+)
314 
315Protocol conformance respecting actor isolation:
316 
317```swift
318@MainActor
319final class PersonViewModel {
320    let id: UUID
321    var name: String
322}
323 
324extension PersonViewModel: @MainActor Equatable {
325    static func == (lhs: PersonViewModel, rhs: PersonViewModel) -> Bool {
326        lhs.id == rhs.id && lhs.name == rhs.name
327    }
328}
329```
330 
331**Enable**: `InferIsolatedConformances` upcoming feature.
332 
333> **Course Deep Dive**: This topic is covered in detail in [Lesson 5.6: Adding isolated conformance to protocols](https://www.swiftconcurrencycourse.com?utm_source=github&utm_medium=agent-skill&utm_campaign=lesson-reference)
334 
335## Actor Reentrancy
336 
337**Critical**: State can change between suspension points.
338 
339```swift
340actor BankAccount {
341    var balance: Double
342    
343    func deposit(amount: Double) async {
344        balance += amount
345        
346        // ⚠️ Actor unlocked during await
347        await logActivity("Deposited \(amount)")
348        
349        // ⚠️ Balance may have changed!
350        print("Balance: \(balance)")
351    }
352}
353```
354 
355### Problem
356 
357```swift
358async let _ = account.deposit(50)
359async let _ = account.deposit(50)
360async let _ = account.deposit(50)
361 
362// May print same balance three times:
363// Balance: 150
364// Balance: 150
365// Balance: 150
366```
367 
368### Solution
369 
370Complete actor work before suspending:
371 
372```swift
373func deposit(amount: Double) async {
374    balance += amount
375    print("Balance: \(balance)") // Before suspension
376    
377    await logActivity("Deposited \(amount)")
378}
379```
380 
381**Rule**: Don't assume state is unchanged after `await`.
382 
383> **Course Deep Dive**: This topic is covered in detail in [Lesson 5.7: Understanding actor reentrancy](https://www.swiftconcurrencycourse.com?utm_source=github&utm_medium=agent-skill&utm_campaign=lesson-reference)
384 
385## #isolation Macro
386 
387Inherit caller's isolation for generic code:
388 
389```swift
390extension Collection where Element: Sendable {
391    func sequentialMap<Result: Sendable>(
392        isolation: isolated (any Actor)? = #isolation,
393        transform: (Element) async -> Result
394    ) async -> [Result] {
395        var results: [Result] = []
396        for element in self {
397            results.append(await transform(element))
398        }
399        return results
400    }
401}
402 
403// Usage from @MainActor context
404Task { @MainActor in
405    let names = ["Alice", "Bob"]
406    let results = await names.sequentialMap { name in
407        await process(name) // Inherits @MainActor
408    }
409}
410```
411 
412**Benefits**: Avoids unnecessary suspensions, allows non-Sendable data.
413 
414### Task Closures and Isolation Inheritance
415 
416When spawning unstructured `Task` closures that need to work with `non-Sendable` types, you must capture the isolation parameter to inherit the caller's isolation context.
417 
418**Problem**: `Task` closures are `@Sendable`, which prevents capturing `non-Sendable` types:
419 
420```swift
421func process(delegate: NonSendableDelegate) {
422  Task {
423    delegate.doWork() // ❌ Error: capturing non-Sendable type
424  }
425}
426```
427 
428**Solution**: Use `#isolation` parameter and capture it inside the `Task`:
429 
430```swift
431func process(
432  delegate: NonSendableDelegate,
433  isolation: isolated (any Actor)? = #isolation
434) {
435  Task {
436    _ = isolation  // Forces capture, Task inherits caller's isolation
437    delegate.doWork()  // ✅ Safe - running on caller's actor
438  }
439}
440```
441 
442**Why `_ = isolation` is required**: Per [SE-0420](https://github.com/swiftlang/swift-evolution/blob/main/proposals/0420-inheritance-of-actor-isolation.md), `Task` closures only inherit isolation when "a non-optional binding of an isolated parameter is captured by the closure." The `_ = isolation` statement forces this capture. The capture list syntax `[isolation]` should work but currently does not.
443 
444**When to use this pattern**:
445- Spawning `Task`s that work with `non-Sendable` delegate objects
446- Fire-and-forget async work that needs access to caller's state
447- Bridging callback-based APIs to async streams while keeping delegates alive
448 
449**Note**: This pattern keeps the `non-Sendable` value alive and accessible within the `Task`. The `Task` runs on the caller's isolation domain, so no cross-isolation "sending" occurs.
450 
451> **Course Deep Dive**: This topic is covered in detail in [Lesson 5.8: Inheritance of actor isolation using the #isolation macro](https://www.swiftconcurrencycourse.com?utm_source=github&utm_medium=agent-skill&utm_campaign=lesson-reference)
452 
453## Custom Actor Executors
454 
455**Advanced**: Control how actor schedules work.
456 
457### Serial executor
458 
459```swift
460final class DispatchQueueExecutor: SerialExecutor {
461    private let queue: DispatchQueue
462    
463    init(queue: DispatchQueue) {
464        self.queue = queue
465    }
466    
467    func enqueue(_ job: consuming ExecutorJob) {
468        let unownedJob = UnownedJob(job)
469        let executor = asUnownedSerialExecutor()
470        
471        queue.async {
472            unownedJob.runSynchronously(on: executor)
473        }
474    }
475}
476 
477actor LoggingActor {
478    private let executor: DispatchQueueExecutor
479    
480    nonisolated var unownedExecutor: UnownedSerialExecutor {
481        executor.asUnownedSerialExecutor()
482    }
483    
484    init(queue: DispatchQueue) {
485        executor = DispatchQueueExecutor(queue: queue)
486    }
487}
488```
489 
490### When to use
491 
492- Integration with legacy DispatchQueue-based code
493- Specific thread requirements (e.g., C++ interop)
494- Custom scheduling logic
495 
496**Default executor is usually sufficient.**
497 
498> **Course Deep Dive**: This topic is covered in detail in [Lesson 5.9: Using a custom actor executor](https://www.swiftconcurrencycourse.com?utm_source=github&utm_medium=agent-skill&utm_campaign=lesson-reference)
499 
500## Mutex: Alternative to Actors
501 
502Synchronous locking without async/await overhead (iOS 18+, macOS 15+).
503 
504### Basic usage
505 
506```swift
507import Synchronization
508 
509final class Counter {
510    private let count = Mutex<Int>(0)
511    
512    var currentCount: Int {
513        count.withLock { $0 }
514    }
515    
516    func increment() {
517        count.withLock { $0 += 1 }
518    }
519}
520```
521 
522### Sendable access to non-Sendable types
523 
524```swift
525final class TouchesCapturer: Sendable {
526    let path = Mutex<NSBezierPath>(NSBezierPath())
527    
528    func storeTouch(_ point: NSPoint) {
529        path.withLock { path in
530            path.move(to: point)
531        }
532    }
533}
534```
535 
536### Error handling
537 
538```swift
539func decrement() throws {
540    try count.withLock { count in
541        guard count > 0 else {
542            throw Error.reachedZero
543        }
544        count -= 1
545    }
546}
547```
548 
549### Mutex vs Actor
550 
551| Feature | Mutex | Actor |
552|---------|-------|-------|
553| Synchronous | ✅ | ❌ (requires await) |
554| Async support | ❌ | ✅ |
555| Thread blocking | ✅ | ❌ (cooperative) |
556| Fine-grained locking | ✅ | ❌ (whole actor) |
557| Legacy code integration | ✅ | ❌ |
558 
559**Use Mutex when**:
560- Need synchronous access
561- Working with legacy non-async APIs
562- Fine-grained locking required
563- Low contention, short critical sections
564 
565**Use Actor when**:
566- Can adopt async/await
567- Need logical isolation
568- Working in async context
569 
570> **Course Deep Dive**: This topic is covered in detail in [Lesson 5.10: Using a Mutex as an alternative to actors](https://www.swiftconcurrencycourse.com?utm_source=github&utm_medium=agent-skill&utm_campaign=lesson-reference)
571 
572## Common Patterns
573 
574### View model with @MainActor
575 
576```swift
577@MainActor
578final class ContentViewModel: ObservableObject {
579    @Published var items: [Item] = []
580    
581    func loadItems() async {
582        items = try await api.fetchItems()
583    }
584}
585```
586 
587### Background processing with custom actor
588 
589```swift
590@ImageProcessing
591final class ImageProcessor {
592    func process(_ images: [UIImage]) async -> [UIImage] {
593        images.map { applyFilters($0) }
594    }
595}
596```
597 
598### Mixed isolation
599 
600```swift
601actor DataStore {
602    private var items: [Item] = []
603    
604    func add(_ item: Item) {
605        items.append(item)
606    }
607    
608    nonisolated func itemCount() -> Int {
609        // ❌ Can't access items
610        return 0
611    }
612}
613```
614 
615### Transaction pattern
616 
617```swift
618actor Database {
619    func transaction<T>(
620        _ operation: @Sendable (_ db: isolated Database) throws -> T
621    ) throws -> T {
622        beginTransaction()
623        defer { commitTransaction() }
624        return try operation(self)
625    }
626}
627```
628 
629## Best Practices
630 
6311. **Prefer actors over manual locks** for async code
6322. **Use @MainActor for UI** - all view models, UI updates
6333. **Minimize work in actors** - keep critical sections short
6344. **Watch for reentrancy** - don't assume state unchanged after await
6355. **Use nonisolated sparingly** - only for truly immutable data
6366. **Avoid assumeIsolated** - prefer explicit isolation
6377. **Custom executors are rare** - default is usually best
6388. **Consider Mutex for sync code** - when async overhead not needed
6399. **Complete actor work before suspending** - prevent reentrancy bugs
64010. **Use isolated parameters** - reduce suspension points
641 
642## Decision Tree
643 
644```
645Need thread-safe mutable state?
646├─ Async context?
647│  ├─ Single instance? → Actor
648│  ├─ Global/shared? → Global Actor (@MainActor, custom)
649│  └─ UI-related? → @MainActor
650│
651└─ Synchronous context?
652   ├─ Can refactor to async? → Actor
653   ├─ Legacy code integration? → Mutex
654   └─ Fine-grained locking? → Mutex
655```
656 
657## Further Learning
658 
659For migration strategies, advanced patterns, and real-world examples, see [Swift Concurrency Course](https://www.swiftconcurrencycourse.com).
660 
661