realm-persistence

Realm Persistence for iOS

Overview

Realm's thread-confinement model conflicts with Swift Concurrency's thread-hopping. The zero-copy architecture delivers fast reads but causes memory traps in extensions. Wrong patterns cause "accessed from incorrect thread" crashes.

Core principle: Fresh Realm per actor method, batch all writes, never pass objects across threads, avoid Realm in memory-constrained contexts.

Threading Model

Critical Rule: Thread-Confined Objects

Realm objects CAN ONLY be accessed on the thread where Realm was created.

digraph threading {
    "Using async/await?" [shape=diamond];
    "Memory-constrained? (widget, extension)" [shape=diamond];
    "Use actor + fresh Realm()" [shape=box, style=filled, fillcolor=lightgreen];
    "Use @MainActor + stored Realm" [shape=box, style=filled, fillcolor=lightblue];
    "Don't use Realm" [shape=box, style=filled, fillcolor=red];

    "Using async/await?" -> "Memory-constrained? (widget, extension)" [label="yes"];
    "Using async/await?" -> "Use @MainActor + stored Realm" [label="no"];
    "Memory-constrained? (widget, extension)" -> "Don't use Realm" [label="yes"];
    "Memory-constrained? (widget, extension)" -> "Use actor + fresh Realm()" [label="no"];
}

Pattern 1: Actor + Fresh Realm (Async/Await)

CRITICAL: With async/await, tasks can resume on ANY thread. Stored Realm instance = crash.

// ❌ WRONG: Stored Realm with async
class TaskManager {
    let realm: Realm  // Created on Thread A

    async func fetchTasks() -> [Task] {
        // May execute on Thread B after suspension
        return Array(realm.objects(Task.self))  // CRASH: incorrect thread
    }
}

// ✅ CORRECT: Fresh Realm per method
actor TaskManager {
    func fetchTasks() async throws -> [Task] {
        let realm = try Realm()  // New Realm on actor's thread
        return Array(realm.objects(Task.self))
    }

    func updateTask(_ id: String, completed: Bool) async throws {
        let realm = try Realm()  // Fresh instance, same actor thread
        guard let task = realm.object(ofType: Task.self, forPrimaryKey: id) else {
            return
        }
        try realm.write {
            task.isCompleted = completed
        }
    }
}