1# Sendable
2 
3Use this when:
4 
5- A value or reference type must cross an isolation boundary safely.
6- You are resolving "non-Sendable type" compiler diagnostics.
7- You need to decide between value types, `@unchecked Sendable`, actors, or region-based isolation.
8 
9Skip this file if:
10 
11- The issue is about which actor should own the state. Use `actors.md`.
12- The issue is about how async functions execute. Use `threading.md`.
13 
14Jump to:
15 
16- Isolation Domains
17- Value Types (Structs, Enums)
18- Reference Types (Classes)
19- Functions and Closures (@Sendable)
20- @unchecked Sendable
21- Region-Based Isolation / `sending`
22- Global Variables
23- Decision Tree
24 
25## What is Sendable?
26 
27`Sendable` indicates a type is safe to share across isolation domains (actors, tasks, threads). The compiler verifies thread-safety at compile time.
28 
29```swift
30public protocol Sendable {}
31```
32 
33Empty protocol, but triggers compiler verification of thread-safety.
34 
35> **Course Deep Dive**: This topic is covered in detail in [Lesson 4.1: Explaining the concept of Sendable in Swift](https://www.swiftconcurrencycourse.com?utm_source=github&utm_medium=agent-skill&utm_campaign=lesson-reference)
36 
37## Isolation Domains
38 
39Three types of isolation in Swift Concurrency:
40 
41### 1. Nonisolated (default)
42 
43No concurrency restrictions, but can't modify isolated state:
44 
45```swift
46func computeValue(a: Int, b: Int) -> Int {
47    return a + b
48}
49```
50 
51### 2. Actor-isolated
52 
53Dedicated isolation domain with serialized access:
54 
55```swift
56actor Library {
57    var books: [String] = []
58    
59    func addBook(_ title: String) {
60        books.append(title)
61    }
62}
63 
64// External access requires await
65await library.addBook("Swift Concurrency")
66```
67 
68### 3. Global actor-isolated
69 
70Shared isolation domain across types:
71 
72```swift
73@MainActor
74func updateUI() {
75    // Runs on main thread
76}
77```
78 
79## Data Races vs Race Conditions
80 
81### Data Race
82 
83Multiple threads access shared mutable state, at least one writes, without synchronization:
84 
85```swift
86// ⚠️ Data race
87var counter = 0
88DispatchQueue.global().async { counter += 1 }
89DispatchQueue.global().async { counter += 1 }
90```
91 
92**Detection**: Enable Thread Sanitizer in scheme settings.
93 
94**Prevention**: Use actors or Sendable types:
95 
96```swift
97actor Counter {
98    private var value = 0
99    
100    func increment() {
101        value += 1
102    }
103}
104```
105 
106### Race Condition
107 
108Timing-dependent behavior leading to unpredictable results:
109 
110```swift
111let counter = Counter()
112 
113for _ in 1...10 {
114    Task { await counter.increment() }
115}
116 
117// May print inconsistent values
118print(await counter.getValue())
119```
120 
121**Key difference**: Swift Concurrency prevents data races but not race conditions. You must still ensure proper sequencing.
122 
123> **Course Deep Dive**: This topic is covered in detail in [Lesson 4.2: Understanding Data Races vs. Race Conditions: Key Differences Explained](https://www.swiftconcurrencycourse.com?utm_source=github&utm_medium=agent-skill&utm_campaign=lesson-reference)
124 
125## Value Types (Structs, Enums)
126 
127### Implicit conformance
128 
129Non-public structs/enums with Sendable members:
130 
131```swift
132// Implicitly Sendable
133struct Person {
134    var name: String
135}
136```
137 
138### Explicit conformance required
139 
140Public types need explicit declaration:
141 
142```swift
143public struct Person: Sendable {
144    var name: String
145}
146```
147 
148**Why**: Compiler can't verify internal details of public types across modules.
149 
150### Frozen types
151 
152Public frozen types can be implicitly Sendable:
153 
154```swift
155@frozen
156public struct Point: Sendable {
157    public var x: Double
158    public var y: Double
159}
160```
161 
162### All members must be Sendable
163 
164```swift
165public struct Person: Sendable {
166    var name: String
167    var hometown: Location // Must also be Sendable
168}
169 
170public struct Location: Sendable {
171    var name: String
172}
173```
174 
175> **Course Deep Dive**: This topic is covered in detail in [Lesson 4.3: Conforming your code to the Sendable protocol](https://www.swiftconcurrencycourse.com?utm_source=github&utm_medium=agent-skill&utm_campaign=lesson-reference)
176 
177### Copy-on-write makes mutability safe
178 
179```swift
180public struct Person: Sendable {
181    var name: String // Mutable but safe due to COW
182}
183```
184 
185Each mutation creates a copy, preventing concurrent access to same instance.
186 
187> **Course Deep Dive**: This topic is covered in detail in [Lesson 4.4: Sendable and Value Types](https://www.swiftconcurrencycourse.com?utm_source=github&utm_medium=agent-skill&utm_campaign=lesson-reference)
188 
189## Reference Types (Classes)
190 
191### Requirements for Sendable classes
192 
193Must be:
1941. `final` (no inheritance)
1952. Immutable stored properties only
1963. All properties Sendable
1974. No superclass or `NSObject` only
198 
199```swift
200final class User: Sendable {
201    let name: String
202    let id: Int
203    
204    init(name: String, id: Int) {
205        self.name = name
206        self.id = id
207    }
208}
209```
210 
211### Why non-final classes can't be Sendable
212 
213Child classes could introduce unsafe mutability:
214 
215```swift
216// Can't be Sendable
217class Purchaser {
218    func purchase() { }
219}
220 
221// Could introduce data races
222class GamePurchaser: Purchaser {
223    var credits: Int = 0 // Mutable!
224}
225```
226 
227### Actor isolation makes classes Sendable
228 
229```swift
230@MainActor
231class ViewModel {
232    var data: [Item] = [] // Safe due to actor isolation
233}
234// Implicitly Sendable
235```
236 
237### Composition over inheritance
238 
239```swift
240final class Purchaser: Sendable {
241    func purchase() { }
242}
243 
244final class GamePurchaser {
245    let purchaser: Purchaser = Purchaser()
246    // Handle credits separately
247}
248```
249 
250> **Course Deep Dive**: This topic is covered in detail in [Lesson 4.5: Sendable and Reference Types](https://www.swiftconcurrencycourse.com?utm_source=github&utm_medium=agent-skill&utm_campaign=lesson-reference)
251 
252## Functions and Closures (@Sendable)
253 
254Mark functions/closures that cross isolation domains:
255 
256```swift
257actor ContactsStore {
258    func removeAll(_ shouldRemove: @Sendable (Contact) -> Bool) async {
259        contacts.removeAll { shouldRemove($0) }
260    }
261}
262```
263 
264### Captured values must be Sendable
265 
266```swift
267let query = "search"
268 
269// ✅ Immutable capture
270store.filter { contact in
271    contact.name.contains(query)
272}
273 
274var query = "search"
275 
276// ❌ Mutable capture
277store.filter { contact in
278    contact.name.contains(query) // Error
279}
280```
281 
282### Capture lists for mutable values
283 
284```swift
285var query = "search"
286 
287// ✅ Capture immutable snapshot
288store.filter { [query] contact in
289    contact.name.contains(query)
290}
291```
292 
293> **Course Deep Dive**: This topic is covered in detail in [Lesson 4.6: Using @Sendable with closures](https://www.swiftconcurrencycourse.com?utm_source=github&utm_medium=agent-skill&utm_campaign=lesson-reference)
294 
295## @unchecked Sendable
296 
297**Use as last resort.** Tells compiler to skip verification—you guarantee thread-safety.
298 
299### When to use
300 
301Manual locking mechanisms the compiler can't verify:
302 
303```swift
304final class Cache: @unchecked Sendable {
305    private let lock = NSLock()
306    private var items: [String: Data] = [:]
307    
308    func get(_ key: String) -> Data? {
309        lock.lock()
310        defer { lock.unlock() }
311        return items[key]
312    }
313    
314    func set(_ key: String, value: Data) {
315        lock.lock()
316        defer { lock.unlock() }
317        items[key] = value
318    }
319}
320```
321 
322### Risks
323 
324- No compile-time safety
325- Easy to introduce data races
326- Must manually ensure all access uses lock
327 
328```swift
329final class Cache: @unchecked Sendable {
330    private let lock = NSLock()
331    private var items: [String: Data] = [:]
332    
333    // ⚠️ Forgot lock - data race!
334    var count: Int {
335        items.count
336    }
337}
338```
339 
340**Better**: Use actor instead:
341 
342```swift
343actor Cache {
344    private var items: [String: Data] = [:]
345    
346    var count: Int { items.count }
347    
348    func get(_ key: String) -> Data? {
349        items[key]
350    }
351    
352    func set(_ key: String, value: Data) {
353        items[key] = value
354    }
355}
356```
357 
358> **Course Deep Dive**: This topic is covered in detail in [Lesson 4.7: Using @unchecked Sendable](https://www.swiftconcurrencycourse.com?utm_source=github&utm_medium=agent-skill&utm_campaign=lesson-reference)
359 
360## Region-Based Isolation
361 
362Compiler allows non-Sendable types in same scope:
363 
364```swift
365class Article {
366    var title: String
367    init(title: String) { self.title = title }
368}
369 
370func check() {
371    let article = Article(title: "Swift")
372    
373    Task {
374        print(article.title) // ✅ OK - same region
375    }
376}
377```
378 
379**Why**: No mutation after transfer, so no data race risk.
380 
381### Breaks when accessed after transfer
382 
383```swift
384func check() {
385    let article = Article(title: "Swift")
386    
387    Task {
388        print(article.title)
389    }
390    
391    print(article.title) // ❌ Error - accessed after transfer
392}
393```
394 
395## The sending Keyword
396 
397Enforces ownership transfer for non-Sendable types:
398 
399### Parameter values
400 
401```swift
402actor Logger {
403    func log(article: Article) {
404        print(article.title)
405    }
406}
407 
408func printTitle(article: sending Article) async {
409    let logger = Logger()
410    await logger.log(article: article)
411}
412 
413// Usage
414let article = Article(title: "Swift")
415await printTitle(article: article)
416// article no longer accessible here
417```
418 
419### Return values
420 
421```swift
422@SomeActor
423func createArticle(title: String) -> sending Article {
424    return Article(title: title)
425}
426```
427 
428Transfers ownership to caller's region.
429 
430> **Course Deep Dive**: This topic is covered in detail in [Lesson 4.8: Understanding region-based isolation and the sending keyword](https://www.swiftconcurrencycourse.com?utm_source=github&utm_medium=agent-skill&utm_campaign=lesson-reference)
431 
432## Global Variables
433 
434Must be concurrency-safe since accessible from any context.
435 
436### Problem
437 
438```swift
439class ImageCache {
440    static var shared = ImageCache() // ⚠️ Not concurrency-safe
441}
442```
443 
444### Solution 1: Actor isolation
445 
446```swift
447@MainActor
448class ImageCache {
449    static var shared = ImageCache()
450}
451```
452 
453### Solution 2: Immutable + Sendable
454 
455```swift
456final class ImageCache: Sendable {
457    static let shared = ImageCache()
458}
459```
460 
461### Solution 3: nonisolated(unsafe)
462 
463**Last resort** - you guarantee safety:
464 
465```swift
466struct APIProvider: Sendable {
467    nonisolated(unsafe) static private(set) var shared: APIProvider!
468    
469    static func configure(apiURL: URL) {
470        shared = APIProvider(apiURL: apiURL)
471    }
472}
473```
474 
475Use `private(set)` to limit mutation points.
476 
477> **Course Deep Dive**: This topic is covered in detail in [Lesson 4.9: Concurrency-safe global variables](https://www.swiftconcurrencycourse.com?utm_source=github&utm_medium=agent-skill&utm_campaign=lesson-reference)
478 
479## Custom Locks + Sendable
480 
481### Legacy code with locks
482 
483```swift
484final class BankAccount: @unchecked Sendable {
485    private var balance: Int = 0
486    private let lock = NSLock()
487    
488    func deposit(amount: Int) {
489        lock.lock()
490        balance += amount
491        lock.unlock()
492    }
493    
494    func getBalance() -> Int {
495        lock.lock()
496        defer { lock.unlock() }
497        return balance
498    }
499}
500```
501 
502### Migration strategy
503 
504**New code**: Use actors
505 
506**Existing code**: 
5071. If isolated and small scope → migrate to actor
5082. If widely used → use `@unchecked Sendable`, file migration ticket
509 
510```swift
511// Better: Migrate to actor
512actor BankAccount {
513    private var balance: Int = 0
514    
515    func deposit(amount: Int) {
516        balance += amount
517    }
518    
519    func getBalance() -> Int {
520        balance
521    }
522}
523```
524 
525> **Course Deep Dive**: This topic is covered in detail in [Lesson 4.10: Combining Sendable with custom Locks](https://www.swiftconcurrencycourse.com?utm_source=github&utm_medium=agent-skill&utm_campaign=lesson-reference)
526 
527## Decision Tree
528 
529```
530Need to share type across isolation domains?
531├─ Value type (struct/enum)?
532│  ├─ Public? → Add explicit Sendable
533│  └─ Internal? → Implicit Sendable (if members Sendable)
534│
535├─ Reference type (class)?
536│  ├─ Can be final + immutable? → Sendable
537│  ├─ Needs mutation?
538│  │  ├─ Can use actor? → Use actor (automatic Sendable)
539│  │  ├─ Main thread only? → @MainActor
540│  │  └─ Has custom lock? → @unchecked Sendable (temporary)
541│  └─ Can be struct instead? → Refactor to struct
542│
543└─ Function/closure? → @Sendable attribute
544```
545 
546## Common Patterns
547 
548### Restructure to avoid non-Sendable dependencies
549 
550```swift
551// Instead of storing non-Sendable type
552public struct Person: Sendable {
553    var hometown: String // Just the name
554    
555    init(hometown: Location) {
556        self.hometown = hometown.name
557    }
558}
559```
560 
561### Prefer actors for mutable state
562 
563```swift
564// Instead of @unchecked Sendable with locks
565actor Cache {
566    private var items: [String: Data] = [:]
567    
568    func get(_ key: String) -> Data? {
569        items[key]
570    }
571}
572```
573 
574### Use @MainActor for UI-bound types
575 
576```swift
577@MainActor
578class ViewModel: ObservableObject {
579    @Published var items: [Item] = []
580}
581```
582 
583## Best Practices
584 
5851. **Prefer value types** - structs/enums are easier to make Sendable
5862. **Use actors for mutable state** - automatic thread-safety
5873. **Avoid @unchecked Sendable** - use only for proven thread-safe code
5884. **Mark public types explicitly** - don't rely on implicit conformance
5895. **Ensure all members Sendable** - one non-Sendable breaks the chain
5906. **Use @MainActor for UI types** - simple isolation for view models
5917. **Capture immutably** - use capture lists for mutable variables
5928. **Test with Thread Sanitizer** - catches runtime data races
5939. **File migration tickets** - track @unchecked Sendable usage
594 
595## Further Learning
596 
597For migration strategies, real-world examples, and actor patterns, see [Swift Concurrency Course](https://www.swiftconcurrencycourse.com).
598 
599