React to Changes - Swift SDK

Realm Collections

When you observe key paths on the various collection types, expect these behaviors:

• LinkingObjects:: Observing a property of the LinkingObject triggers a notification for a change to that property, but does not trigger notifications for changes to its other properties. Insertions or deletions to the list or the object that the list is on trigger a notification.

• Lists: Observing a property of the list's object will triggers a notification for a change to that property, but does not trigger notifications for changes to its other properties. Insertions or deletions to the list or the object that the list is on trigger a notification.

• Map: Observing a property of the map's object triggers a notification for a change to that property, but does not trigger notifications for changes to its other properties. Insertions or deletions to the Map or the object that the map is on trigger a notification. The change parameter reports, in the form of keys within the map, which key-value pairs are added, removed, or modified during each write transaction.

• MutableSet: Observing a property of a MutableSet's object triggers a notification for a change to that property, but does not trigger notifications for changes to its other properties. Insertions or deletions to the MutableSet or the object that the MutableSet is on trigger a notification.

• Results: Observing a property of the Result triggers a notification for a change to that property, but does not trigger notifications for changes to its other properties. Insertions or deletions to the Result trigger a notification.

Key-value Observation Compliance

Realm objects are key-value observing (KVO) compliant for most properties:

• Almost all managed (non-ignored) properties on Object subclasses

• The invalidated property on Object and List

You cannot observe LinkingObjects properties via Key-value observation.

Managed vs. Unmanaged KVO Considerations

Observing the properties of unmanaged instances of Object subclasses works like any other dynamic property.

Observing the properties of managed objects works differently. With realm-managed objects, the value of a property may change when:

• You assign to it

• The realm is refreshed, either manually with realm.refresh() or automatically on a runloop thread

• You begin a write transaction after changes on another thread

Realm applies changes made in the write transaction(s) on other threads at once. Observers see Key-value observation notifications at once. Intermediate steps do not trigger KVO notifications.

Avoid modifying managed Realm objects from within observeValueForKeyPath(_:ofObject:change:context:). Property values can change when not in a write transaction, or as part of beginning a write transaction.

Observing Realm Lists

Observing changes made to Realm List properties is simpler than NSMutableArray properties:

• You don't have to mark List properties as dynamic to observe them.

• You can call modification methods on List directly. Anyone observing the property that stores it gets a notification.

You don't need to use mutableArrayValueForKey(_:), although realm does support this for code compatibility.

Perform Writes Only on a Different Thread than the Observing Thread

Reading an observed collection or object from inside a change notification always accurately tells you what has changed in the collection passed to the callback since the last time the callback was invoked.

Reading collections or objects outside of change notifications always gives you the exact same values you saw in the most recent change notification for that object.

Reading objects other than the observed one inside a change notification may see a different value prior to the notification for that change being delivered. Realm refresh brings the entire realm from 'old version' to 'latest version' in one operation. However, there might have been multiple change notifications fired between 'old version' and 'latest version'. Inside a callback, you may see changes that have pending notifications.

Writes on different threads eventually become visible on the observing thread. Explicitly calling refresh() blocks until the writes made on other threads are visible and the appropriate notifications have been sent. If you call refresh() within a notification callback, it's a no-op.

Perform Writes on the Observing Thread, Outside of Notifications

At the start of the write transaction all behaviors above apply to this context. Additionally, you can expect to always see the latest version of the data.

Inside a write transaction, the only changes you see are those you've made so far within the write transaction.

Between committing a write transaction and the next set of change notifications being sent, you can see the changes you made in the write transaction, but no other changes. Writes made on different threads do not become visible until you receive the next set of notifications. Performing another write on the same thread sends notifications for the previous write first.

Perform Writes Inside of Notifications

When you perform writes within notifications, you see many of the same behaviors above, with a few exceptions.

Callbacks invoked before the one that performed a write behave normally. While Realm invokes change callbacks in a stable order, this is not strictly the order in which you added the observations.

If beginning the write refreshes the realm, which can happen if another thread is making writes, this triggers recursive notifications. These nested notifications report the changes made since the last call to the callback. For callbacks before the one making the write, this means the inner notification reports only the changes made after the ones already reported in the outer notification. If the callback making the write tries to write again in the inner notification, Realm throws an exception. The callbacks after the one making the write get a single notification for both sets of changes.

After the callback completes the write and returns, Realm does not invoke any of the subsequent callbacks as they no longer have any changes to report. Realm provides a notification later for the write as if the write had happened outside of a notification.

If beginning the write doesn't refresh the realm, the write happens as usual. However, Realm invokes the subsequent callbacks in an inconsistent state. They continue to report the original change information, but the observed object/collection now includes the changes from the write made in the previous callback.

If you try to perform manual checks and write handling to get more fine-grained notifications from within a write transaction, you can get notifications nested more than two levels deep. An example of a manual write handling is checking realm.isInWriteTransaction, and if so making changes, calling realm.commitWrite() and then realm.beginWrite(). The nested notifications and potential for error make this manual manipulation error-prone and difficult to debug.

You can use the writeAsync API to sidestep complexity if you don't need fine-grained change information from inside your write block. Observing an async write similar to this provides notifications even if the notification happens to be delivered inside a write transaction:

let token = dog.observe(keyPaths: [\Dog.age]) { change in
   guard case let .change(dog, _) = change else { return }
   dog.realm!.writeAsync {
      dog.isPuppy = dog.age < 2
   }
}

However, because the write is async the realm may have changed between the notification and when the write happens. In this case, the change information passed to the notification may no longer be applicable.

Updating a UITableView Based on Notifications

If you only update a UITableView via notifications, in the time between a write transaction and the next notification arriving, the TableView's state is out of sync with the data. The TableView could have a pending update scheduled, which can appear to cause delayed or inconsistent updates.

You can address these behaviors in a few ways.

The following examples use this very basic UITableViewController.

class TableViewController: UITableViewController {
    let realm = try! Realm()
    let results = try! Realm().objects(DemoObject.self).sorted(byKeyPath: "date")
    var notificationToken: NotificationToken!
    override func viewDidLoad() {
        super.viewDidLoad()
        tableView.register(UITableViewCell.self, forCellReuseIdentifier: "cell")
        notificationToken = results.observe { (changes: RealmCollectionChange) in
            switch changes {
            case .initial:
                self.tableView.reloadData()
            case .update(_, let deletions, let insertions, let modifications):
                // Always apply updates in the following order: deletions, insertions, then modifications.
                // Handling insertions before deletions may result in unexpected behavior.
                self.tableView.beginUpdates()
                self.tableView.deleteRows(at: deletions.map { IndexPath(row: $0, section: 0) }, with: .automatic)
                self.tableView.insertRows(at: insertions.map { IndexPath(row: $0, section: 0) }, with: .automatic)
                self.tableView.reloadRows(at: modifications.map { IndexPath(row: $0, section: 0) }, with: .automatic)
                self.tableView.endUpdates()
            case .error(let err):
                fatalError("\(err)")
            }
        }
    }
    override func tableView(_ tableView: UITableView, numberOfRowsInSection section: Int) -> Int {
        return results.count
    }
    override func tableView(_ tableView: UITableView, cellForRowAt indexPath: IndexPath) -> UITableViewCell {
        let object = results[indexPath.row]
        let cell = tableView.dequeueReusableCell(withIdentifier: "cell", for: indexPath)
        cell.textLabel?.text = object.title
        return cell
    }
    func delete(at index: Int) throws {
        try realm.write {
            realm.delete(results[index])
        }
    }
}

func delete(at index: Int) throws {
    try realm.write(withoutNotifying: [notificationToken]) {
        realm.delete(results[index])
    }
    tableView.deleteRows(at: [IndexPath(row: index, section: 0)], with: .automatic)
}

func delete(at index: Int) throws {
    try realm.write {
        realm.delete(results[index])
    }
    realm.refresh()
}

func delete(at index: Int) throws {
    func delete(at index: Int) throws {
        @ThreadSafe var object = results[index]
        DispatchQueue.global().async {
            guard let object = object else { return }
            let realm = object.realm!
            try! realm.write {
                if !object.isInvalidated {
                    realm.delete(object)
                }
            }
        }
    }
}