React to Changes - iOS SDK¶
Register a Realm Change Listener¶
You can register a notification handler on an entire realm. Realm Database calls the notification handler whenever any write transaction involving that Realm is committed. The handler receives no information about the change.
Register a Collection Change Listener¶
You can register a notification handler on a collection within a realm.
Realm Database notifies your handler:
- After first retrieving the collection.
- Whenever a write transaction adds, changes, or removes objects in the collection.
Notifications describe the changes since the prior notification with three lists of indices: the indices of the objects that were deleted, inserted, and modified.
In collection notification handlers, always apply changes in the following order: deletions, insertions, then modifications. Handling insertions before deletions may result in unexpected behavior.
Register an Object Change Listener¶
You can register a notification handler on a specific object within a Realm. Realm Database notifies your handler:
- When the object is deleted.
- When any of the object's properties change.
The handler receives information about what fields changed and whether the object was deleted.
You can write to a realm without sending a notification to a specific observer by passing the observer's notification token in an array to realm.write(withoutNotifying:_:):
Stop Watching for Changes¶
Observation stops when the token returned by an
observe call becomes
invalid. You can explicitly invalidate a token by calling its
Notifications stop if the token is in a local variable that goes out of scope.
Key-value Observation Compliance¶
Realm Database objects are key-value observing (KVO) compliant for most properties:
- Almost all managed (non-ignored) properties on
You cannot observe
LinkingObjects properties via Key-value observation.
You cannot add an object to a realm (with
realm.add(obj) or similar
methods) while it has any registered observers.
Managed vs. Unmanaged KVO Considerations¶
Observing the properties of unmanaged instances of
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.
Say your app performs a write transaction that increments a property from 1 to 10. On the main thread, you get a single notification of a change directly from 1 to 10. You won't get notifications for every incremental change between 1 and 10.
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
Observing Realm Lists¶
Observing changes made to Realm
List properties is simpler than
- You don't have to mark
Listproperties as dynamic to observe them.
- You can call modification methods on
Listdirectly. 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.