React to Changes - Swift SDK
On this page
- Register a Realm Change Listener
- Register a Collection Change Listener
- Register an Object Change Listener
- Register a Key Path Change Listener
- Realm Collections
- Write Silently
- Stop Watching for Changes
- Key-value Observation
- Key-value Observation Compliance
- Managed vs. Unmanaged KVO Considerations
- Observing Realm Lists
- React to Changes to a Class Projection
- Notification Delivery
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.
Important
Order Matters
In collection notification handlers, always apply changes in the following order: deletions, insertions, then modifications. Handling insertions before deletions may result in unexpected behavior.
Collection notifications provide a change
parameter that reports which
objects are deleted, added, or modified during the write transaction. This
RealmCollectionChange
resolves to an array of index paths that you can pass to a UITableView
's
batch update methods.
Important
High-frequency updates
This example of a collection change listener does not support high-frequency updates. Under an intense workload, this collection change listener may cause the app to throw an exception.
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.
Register a Key Path Change Listener
New in version 10.12.0.
In addition to registering a notification handler on an object
or collection, you can pass an optional string keyPaths
parameter to specify the key path or
key paths to watch.
Example
// Define the dog class. class Dog: Object { var name = "" var favoriteToy = "" var age: Int? } var objectNotificationToken: NotificationToken? func objectNotificationExample() { let dog = Dog() dog.name = "Max" dog.favoriteToy = "Ball" dog.age = 2 // Open the default realm. let realm = try! Realm() try! realm.write { realm.add(dog) } // Observe notifications on some of the object's key paths. Keep a strong // reference to the notification token or the observation will stop. // Invalidate the token when done observing. objectNotificationToken = dog.observe(keyPaths: ["favoriteToy", "age"], { change in switch change { case .change(let object, let properties): for property in properties { print("Property '\(property.name)' of object \(object) changed to '\(property.newValue!)'") } case .error(let error): print("An error occurred: \(error)") case .deleted: print("The object was deleted.") } }) // Now update to trigger the notification try! realm.write { dog.favoriteToy = "Frisbee" } // When you specify one or more key paths, changes to other properties // do not trigger notifications. In this example, changing the "name" // property does not trigger a notification. try! realm.write { dog.name = "Maxamillion" } }
New in version 10.14.0.
You can observe a partially type-erased PartialKeyPath on Objects or RealmCollections.
objectNotificationToken = dog.observe(keyPaths: [\Dog.favoriteToy, \Dog.age], { change in
When you specify keyPaths
, only changes to those
keyPaths
trigger notification blocks. Any other changes do not trigger
notification blocks.
Example
Consider a Dog
object where one of its properties is a list of
siblings
:
class Dog: Object { var name = "" var siblings: List<Dog> var age: Int? }
If you pass siblings
as a keyPath
to observe, any insertion,
deletion, or modification to the siblings
list would trigger a
notification. However, a change to someSibling.name
would not trigger
a notification, unless you explicitly observed ["siblings.name"]
.
Note
Multiple notification tokens on the same object which filter for separate key paths do not filter exclusively. If one key path change is satisfied for one notification token, then all notification token blocks for that object will execute.
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.
Write Silently
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:_:):
Tip
See also:
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
invalidate()
method.
Important
Retain Tokens as Long as You Want to Observe
Notifications stop if the token is in a local variable that goes out of scope.
Key-value Observation
Key-value Observation Compliance
Realm Database objects are key-value observing (KVO) compliant for most properties:
Almost all managed (non-ignored) properties on
Object
subclassesThe
invalidated
property onObject
andList
You cannot observe LinkingObjects
properties via Key-value observation.
Important
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 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 threadYou 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.
Example
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
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.
Tip
See also:
Examples of using Realm with ReactiveCocoa from Objective-C , and ReactKit from Swift.
React to Changes to a Class Projection
Like other realm objects, you can react to changes to a class projection. When you register a class projection change listener, you see notifications for changes made through the class projection object directly. You also see notifications for changes to the underlying object's properties that project through the class projection object.
Properties on the underlying object that are not @Projected
in the
class projection do not generate notifications.
This notification block fires for changes in:
Person.firstName
property of the class projection's underlyingPerson
object, but not changes toPerson.lastName
orPerson.friends
.PersonProjection.firstName
property, but not another class projection that uses the same underlying object's property.
let realm = try! Realm() let projectedPerson = realm.objects(PersonProjection.self).first(where: { $0.firstName == "Jason" })! let token = projectedPerson.observe(keyPaths: ["firstName"], { change in switch change { case .change(let object, let properties): for property in properties { print("Property '\(property.name)' of object \(object) changed to '\(property.newValue!)'") } case .error(let error): print("An error occurred: \(error)") case .deleted: print("The object was deleted.") } }) // Now update to trigger the notification try! realm.write { projectedPerson.firstName = "David" }
Notification Delivery
If you don't need strict guarantees around when notifications are delivered, subscribe to a dispatch queue instead of the main thread. If your notification logic does need strict guarantees, use care in how you write things in your notification handlers. Otherwise, you may trigger this error:
Cannot register notification blocks from within write transactions.
This issue occurs when you try to perform updates as a result of a notification, but the notification occurs while a write transaction is in progress.
The observe function takes a dispatch queue. If that's set, Realm delivers notifications there instead of to the current thread. Realm's notification system promises that notifications for writes on different threads are always delivered synchronously as part of the refresh process. As long as you aren't performing writes on the current thread, you can rely on the guarantee that your app cannot see the value you read from an object change without receiving a notification about the change in between the reads.