.agents/skills/swift-concurrency/references/sendable.md
Use this when:
@unchecked Sendable, actors, or region-based isolation.Skip this file if:
actors.md.threading.md.Jump to:
sendingSendable indicates a type is safe to share across isolation domains (actors, tasks, threads). The compiler verifies thread-safety at compile time.
public protocol Sendable {}
Empty protocol, but triggers compiler verification of thread-safety.
Course Deep Dive: This topic is covered in detail in Lesson 4.1: Explaining the concept of Sendable in Swift
Three types of isolation in Swift Concurrency:
No concurrency restrictions, but can't modify isolated state:
func computeValue(a: Int, b: Int) -> Int {
return a + b
}
Dedicated isolation domain with serialized access:
actor Library {
var books: [String] = []
func addBook(_ title: String) {
books.append(title)
}
}
// External access requires await
await library.addBook("Swift Concurrency")
Shared isolation domain across types:
@MainActor
func updateUI() {
// Runs on main thread
}
Multiple threads access shared mutable state, at least one writes, without synchronization:
// ⚠️ Data race
var counter = 0
DispatchQueue.global().async { counter += 1 }
DispatchQueue.global().async { counter += 1 }
Detection: Enable Thread Sanitizer in scheme settings.
Prevention: Use actors or Sendable types:
actor Counter {
private var value = 0
func increment() {
value += 1
}
}
Timing-dependent behavior leading to unpredictable results:
let counter = Counter()
for _ in 1...10 {
Task { await counter.increment() }
}
// May print inconsistent values
print(await counter.getValue())
Key difference: Swift Concurrency prevents data races but not race conditions. You must still ensure proper sequencing.
Course Deep Dive: This topic is covered in detail in Lesson 4.2: Understanding Data Races vs. Race Conditions: Key Differences Explained
Non-public structs/enums with Sendable members:
// Implicitly Sendable
struct Person {
var name: String
}
Public types need explicit declaration:
public struct Person: Sendable {
var name: String
}
Why: Compiler can't verify internal details of public types across modules.
Public frozen types can be implicitly Sendable:
@frozen
public struct Point: Sendable {
public var x: Double
public var y: Double
}
public struct Person: Sendable {
var name: String
var hometown: Location // Must also be Sendable
}
public struct Location: Sendable {
var name: String
}
Course Deep Dive: This topic is covered in detail in Lesson 4.3: Conforming your code to the Sendable protocol
public struct Person: Sendable {
var name: String // Mutable but safe due to COW
}
Each mutation creates a copy, preventing concurrent access to same instance.
Course Deep Dive: This topic is covered in detail in Lesson 4.4: Sendable and Value Types
Must be:
final (no inheritance)NSObject onlyfinal class User: Sendable {
let name: String
let id: Int
init(name: String, id: Int) {
self.name = name
self.id = id
}
}
Child classes could introduce unsafe mutability:
// Can't be Sendable
class Purchaser {
func purchase() { }
}
// Could introduce data races
class GamePurchaser: Purchaser {
var credits: Int = 0 // Mutable!
}
@MainActor
class ViewModel {
var data: [Item] = [] // Safe due to actor isolation
}
// Implicitly Sendable
final class Purchaser: Sendable {
func purchase() { }
}
final class GamePurchaser {
let purchaser: Purchaser = Purchaser()
// Handle credits separately
}
Course Deep Dive: This topic is covered in detail in Lesson 4.5: Sendable and Reference Types
Mark functions/closures that cross isolation domains:
actor ContactsStore {
func removeAll(_ shouldRemove: @Sendable (Contact) -> Bool) async {
contacts.removeAll { shouldRemove($0) }
}
}
let query = "search"
// ✅ Immutable capture
store.filter { contact in
contact.name.contains(query)
}
var query = "search"
// ❌ Mutable capture
store.filter { contact in
contact.name.contains(query) // Error
}
var query = "search"
// ✅ Capture immutable snapshot
store.filter { [query] contact in
contact.name.contains(query)
}
Course Deep Dive: This topic is covered in detail in Lesson 4.6: Using @Sendable with closures
Use as last resort. Tells compiler to skip verification—you guarantee thread-safety.
Manual locking mechanisms the compiler can't verify:
final class Cache: @unchecked Sendable {
private let lock = NSLock()
private var items: [String: Data] = [:]
func get(_ key: String) -> Data? {
lock.lock()
defer { lock.unlock() }
return items[key]
}
func set(_ key: String, value: Data) {
lock.lock()
defer { lock.unlock() }
items[key] = value
}
}
final class Cache: @unchecked Sendable {
private let lock = NSLock()
private var items: [String: Data] = [:]
// ⚠️ Forgot lock - data race!
var count: Int {
items.count
}
}
Better: Use actor instead:
actor Cache {
private var items: [String: Data] = [:]
var count: Int { items.count }
func get(_ key: String) -> Data? {
items[key]
}
func set(_ key: String, value: Data) {
items[key] = value
}
}
Course Deep Dive: This topic is covered in detail in Lesson 4.7: Using @unchecked Sendable
Compiler allows non-Sendable types in same scope:
class Article {
var title: String
init(title: String) { self.title = title }
}
func check() {
let article = Article(title: "Swift")
Task {
print(article.title) // ✅ OK - same region
}
}
Why: No mutation after transfer, so no data race risk.
func check() {
let article = Article(title: "Swift")
Task {
print(article.title)
}
print(article.title) // ❌ Error - accessed after transfer
}
Enforces ownership transfer for non-Sendable types:
actor Logger {
func log(article: Article) {
print(article.title)
}
}
func printTitle(article: sending Article) async {
let logger = Logger()
await logger.log(article: article)
}
// Usage
let article = Article(title: "Swift")
await printTitle(article: article)
// article no longer accessible here
@SomeActor
func createArticle(title: String) -> sending Article {
return Article(title: title)
}
Transfers ownership to caller's region.
Course Deep Dive: This topic is covered in detail in Lesson 4.8: Understanding region-based isolation and the sending keyword
Must be concurrency-safe since accessible from any context.
class ImageCache {
static var shared = ImageCache() // ⚠️ Not concurrency-safe
}
@MainActor
class ImageCache {
static var shared = ImageCache()
}
final class ImageCache: Sendable {
static let shared = ImageCache()
}
Last resort - you guarantee safety:
struct APIProvider: Sendable {
nonisolated(unsafe) static private(set) var shared: APIProvider!
static func configure(apiURL: URL) {
shared = APIProvider(apiURL: apiURL)
}
}
Use private(set) to limit mutation points.
Course Deep Dive: This topic is covered in detail in Lesson 4.9: Concurrency-safe global variables
final class BankAccount: @unchecked Sendable {
private var balance: Int = 0
private let lock = NSLock()
func deposit(amount: Int) {
lock.lock()
balance += amount
lock.unlock()
}
func getBalance() -> Int {
lock.lock()
defer { lock.unlock() }
return balance
}
}
New code: Use actors
Existing code:
@unchecked Sendable, file migration ticket// Better: Migrate to actor
actor BankAccount {
private var balance: Int = 0
func deposit(amount: Int) {
balance += amount
}
func getBalance() -> Int {
balance
}
}
Course Deep Dive: This topic is covered in detail in Lesson 4.10: Combining Sendable with custom Locks
Need to share type across isolation domains?
├─ Value type (struct/enum)?
│ ├─ Public? → Add explicit Sendable
│ └─ Internal? → Implicit Sendable (if members Sendable)
│
├─ Reference type (class)?
│ ├─ Can be final + immutable? → Sendable
│ ├─ Needs mutation?
│ │ ├─ Can use actor? → Use actor (automatic Sendable)
│ │ ├─ Main thread only? → @MainActor
│ │ └─ Has custom lock? → @unchecked Sendable (temporary)
│ └─ Can be struct instead? → Refactor to struct
│
└─ Function/closure? → @Sendable attribute
// Instead of storing non-Sendable type
public struct Person: Sendable {
var hometown: String // Just the name
init(hometown: Location) {
self.hometown = hometown.name
}
}
// Instead of @unchecked Sendable with locks
actor Cache {
private var items: [String: Data] = [:]
func get(_ key: String) -> Data? {
items[key]
}
}
@MainActor
class ViewModel: ObservableObject {
@Published var items: [Item] = []
}
For migration strategies, real-world examples, and actor patterns, see Swift Concurrency Course.