Realm Swift Async Future

[bdkjones]

It would be useful to know how Realm intends to support Swift Concurrency.

The old "thread-isolation" paradigm doesn't work in async/await because once a Task suspends to await something, it can resume on ANY thread, not just the one on which it was previously running.

People evaluating Realm as an option for their apps should know where the project stands on migrating to modern concurrency. A general plan, timeline, etc. It's a MAJOR inflection point in the Swift language and API design.

[tgoyne]

We are currently trying to determine what is possible and what would actually be useful. Real-world examples of parts of an app where async would be useful but you can't use it because of Realm would be very helpful for this. Most of the words written on the internet so far about how to adopt async in your app are along the lines of "here's how to make your app buggier and slower using async anti-patterns" rather than anything we'd want to support, and there's a lot of things we could possibly do which wouldn't actually be used by anyone.

"What is possible" is complicated by that the concurrency implementation in Swift 5.6 is still quite incomplete and it is unclear which of the things in the evolution documents are actually going to happen and which are using "future directions" as a euphemism for "things we recognize could be useful but we aren't going to do".

Some rambley thoughts on some of the things we might want to do:

More @MainActor async functions

Realm already works totally fine in @MainActor functions, and it might turn out that people write enough @MainActor functions which touch Realm that it's worth adding some more async APIs that can only work there. We currently have just async Realm.init(), and the implementation of that is such that it's only useful for synchronized Realms. We could probably also make that usefully offload some work off the main thread for local Realms.

Async write transactions are already in progress, and will let you do things like await realm.write { ... } to acquire the write mutex without blocking the main thread if another thread holds it, invoke the block on the main thread, and then perform most of the actual disk i/o on a background thread. (There's also non-Concurrency versions of this API and the ability to only do the begin or commit async).

An async version of Realm.objects() and things like sorting could be useful. await realm.objects(MyClass.self).where { prop > 10 }.sort(by: \.otherProp) could run the query and sort it on a background thread and then resume the caller once that's ready.

Change notifications and sync progress notifications could be provided as async sequences. It's unclear if this would be useful.

Frozen object improvements

Frozen objects aren't thread-confined, so they can already be used in async functions. We're currently working on low-level improvements to how they work to fix some of the problems with them (such as that acquiring a frozen object on startup and retaining it forever results in your Realm file growing endlessly). We're looking into ways to make it so that they can be marked as Sendable so that you don't need to use @unchecked Sendable.

There's probably API improvements we could make to improve the experience of mutating frozen objects. This is something that the Realm Kotlin team is currently trying to solve (Kotlin has similar concepts of structured concurrency that benefit from a Frozen-first design) and we'll be looking to them for inspiration.

We could do an async version of realm.objects().freeze(), which would do all the querying/sorting/etc. on a different thread, and as the end result is frozen it wouldn't need to be actor-confined.

Currently you can't observe frozen objects. This is mostly an artificial limitation that we could loosen.

@ThreadSafe improvements

We recently shipped the @ThreadSafe property wrapper, which also makes things async-safe. We haven't yet gotten any meaningful feedback on this, so we don't know if people are just happily using it, unaware that it exists, or if there's some problem with it that makes it not useful which we need to fix. At the minimum there's probably a lot of room for performance improvements to it.

Actor-confined Realms

It's probably possible to implement actor-confined Realms (although possibly not the runtime checks to catch misuse?). This would look something like:

actor MyActor {
    private let realm = try! Realm(actor: self)

    func store(_ obj: Object) {
        try! realm.write {
            realm.add(obj)
        }
    }

    func get(_ pk: Int) -> Object? {
        return realm.object(ofType: Object.self, forPrimaryKey: pk)?.freeze()
    }
}

Within the actor you could use the Realm normally, including in an async function with async calls between interactions with Realm. Anything which escapes from the actor would have to be frozen. It may or may not be possible to catch places where you forget to do this.

Most users seem to hate anything which forces them to have multiple Realm instances, and a Realm instance per actor is really doubling down on that. Maybe you could have a singletone actor and make everything take it as an isolated parameter? That seems really awful and I'd expect people to actually end up with a 10k LOC actor that they hate.

---

We are definitely not in a position to give an ETA on any of this or a promise that any of it will happen (other than the things I said are already in progress).

[tgoyne]

How to better support bulk writes on a background thread while still letting the main thread perform writes is something we've talked about a bit. It's pretty important for sync, as right now if the device receives a giant changeset from the server the sync worker thread can hold the write lock for an unreasonable amount of time. We have an improvement in progress for that, but it's specifically a change to the sync client and not a generalized solution.

Async writes will help somewhat here. Being able to asynchronously begin the write on the main thread will mean that at least the UI isn't blocked while you're waiting, but of course that doesn't help you if you need the UI to be blocked until you can write.

Asynchronous commits can optionally batch a sequence of commits together, which lowers the performance penality from regularly releasing and reacquiring the write lock on the background thread to give other threads a chance to write. Ideally we'd get to the point where you could reasonably write for obj in objectsToCreate { await realm.write { realm.create(ObjectType.self, value: obj) } } and not need a long-lived write transaction at all (and then probably rethink the need for mandatory explicit write blocks), but even with the async write improvements we're pretty far from that.

[PhilippeWeidmann]

We are using Realm as a caching layer for our app and we are doing a lot of background writes and only reading on the main thread.
We saw that you recently added the @ThreadSafe wrapper. I asked about its performance on the mongodb forums but I didn't get an answer.
All the features described in this post seem very cool 🚀. @tgoyne You are saying in the post that there is a lot of room for performance improvements, how safe is it to use this new property wrapper?

[flowbe]

Actor-confined Realms look so cool, I'd love this feature please! 🙏🏻 🎉

[23prash]

For the initial problem
i,e "The old "thread-isolation" paradigm doesn't work in async/await because once a Task suspends to await something it can resume on ANY thread" ..

I wonder if actor isolation of realm will solve the problem because actor isolation means thread safe access to mutable state but that still means the mutable state could be access by 2 or more different threads (in a safe way) and wouldn't that break the "thread isolation" paradigm?

My understanding of this problem is - once a realm object is accessed using a thread it needs to be modified on the same one.
pls let me know if my assumption is wrong or if ThreadSafe and actor isolation would not solve the problem.

[bdkjones]

The Base Problem Is Correct

I'm happy to see that you guys have nailed the fundamental concurrency problem for Realm: "Let an app do a huge background write/commit without beachballing the main thread." That's spot-on. Nobody wants to have 15 different threads all trying to write simultaneously; it's always going to be 1 UI thread and 1 background thread doing a big import/update.

Unfortunately, the current advice in the docs is impossible: "If you're doing background writes or using device sync, don't do any writes on the main thread." I can avoid big writes on the main thread, but when a user toggles a checkbox or selects an item from a pop-up button, those tiny writes HAVE to be done on the main thread.

Concurrency Toe-Dip

Assuming that we do not hit any await points inside a Task, is it currently safe to dispatch a background realm like this:

func bigBackgroundWork()
{
    let task = Task {
        let realm = try! Realm()

        try! realm.write {
             // Do a bunch of work with this realm. Add new objects, modify existing objects, etc.
        }
    }

    // If we store `task` as an iVar instead of a local variable, we could even:
   task.cancel()
}

I know that 10.26.0 introduced writeAsync, but I'm interested in having cancellation support because my background tasks frequently have to rip through 100,000+ items and find/update Realm model objects.

Yielding Writes?

When I have, say, 100,000 updates to do on a background Realm, I currently batch those into smaller write blocks. But it would be awesome if there were a "yielding" write available. Meaning I could tell Realm: "Listen, I want to run this background write block where I update 100,000 objects, but if the main thread suddenly needs to write something, pause this write transaction, yield to the main thread, and then pick back up when the main thread is done."

That only makes sense when the background write is a unit of discrete updates where a clean "pause" can occur, such as looping through 10,000 objects one at a time. Or possibly as a manual check that the developer could include, similar to how we can check if cancellation has been requested for a Task. Something like someRealm.isTheMainThreadWaitingOnMe

[aehlke]

Is there a way to "yield" to other pending writes in the same actor and realm which are waiting for a write to finish today? Because even if I commit the write, it doesn't suddenly start writes on other threads that were already waiting, and will continue to block those others if I start another write again.

In other words I have iteration over many hundreds of thousands of objects and I'm writing just a few at a time, but unless I sleep for long periods between those writes, other threads never stop waiting for their turn to write

[tgoyne]

This is now finally the primary thing that I'm working on and we'll hopefully be able to ship some better async support soon.

The first big piece to arrive is support for strict concurrency/sendable checking, which is actually pretty useful even if you aren't using async/await. It currently will unfortunately warn for safe uses of frozen objects, but otherwise does a pretty good job of catching invalid threading.

The next bit will be actor-confined Realms with much nicer support for async writes. This lets you do things like the following:

@BackgroundActor
func writeStuff() throws {
    let realm = try await Realm.open(actor: BackgroundActor.self)
    try await realm.asyncWrite {
        _ = realm.create(Foo.self, value: [])
    }
}

There's an incomplete and very lightly tested implementation of this on the "tg/actor" branch if you want to play with it, but many perfectly reasonable things will currently not work.

[tgoyne]

10.40.0 will ship two significant improvements to async/await support.

async/await can now be used with realm.write(). try await realm.asyncWrite { ... } will suspend the current task while waiting for the write lock, call the write block inside the original actor context, and then to the actual writing to disk on a background thread. For writes where you're not doing a lot of work inside the write block, this gives pretty similar performance to doing your write on a background queue, but without all the hassle of passing your objects between threads. You'll still want to do things like bulk insertions explicitly in the background, but our hope is that just using asyncWrite() in a @MainActor function will be fine for most of your writes.

Actor-isolated Realms let you use Realm inside async functions without the function being @MainActor, with the caveat that the function does still need to be isolated to some actor. This can be either a local actor instance or a custom global actor. For example, if you want a function to run off the main thread but don't need to run multiple instances of it in parallel, you can do:

@globalActor actor BackgroundActor: GlobalActor {
    static var shared = BackgroundActor()
}

@BackgroundActor backgroundThreadFunction() async throws {
    let realm = try await Realm(actor: BackgroundActor.shared)
    try await realm.asyncWrite {
        _ = realm.create(MyObject.self)
    }
    // Thread-confined Realms would sometimes throw an exception here, as we
    // may end up on a different thread after an `await`
    print("\(realm.objects(MyObject.self).count)")
}

Alternatively, you may wish to use Realm inside an actor, which is now supported:

actor MyActor {
    // An implicitly-unwrapped optional is used here to let us pass `self` to
    // `Realm(actor:)` within `init`
    var realm: Realm!
    init() async throws {
        realm = try await Realm(actor: self)
    }

    var count: Int {
        realm.objects(MyObject.self).count
    }

    func create() async throws {
        try await realm.asyncWrite {
            realm.create(MyObject.self)
        }
    }
}

---

There's a few more things on our roadmap that didn't make it into the initial set of work.

Currently frozen objects are awkward with Sendable checking. Because the static type for frozen and live objects are the same, the compiler has no idea that some objects are safe to pass between threads and others aren't, and using frozen objects produces a lot of spurious sendability warnings. To fix this, we plan to introduce some sort of Frozen<T> wrapper for objects which will expose a read-only interface to the underlying object and let us mark it as Sendable.

@ThreadSafe currently doesn't work usefully with async functions, so passing objects between isolation contexts involves a lot of boilerplate. Some compiler bugs related to property wrappers and sendability checking means that the obvious fixes for this don't really work, but we'll be looking for something that does.

Running an async query is currently possible but awkward. You can do weird things like the following to run a query on background thread and then get the result back in the original context, but obviously this needs a better API:

var iterator = realm.objects(SwiftObject.self).sorted(by: [\.name]).collectionPublisher.values.makeAsyncIterator()
let results = try await iterator.next()

// or
for await results in realm.objects(SwiftObject.self).sorted(by: [\.name]).collectionPublisher.values {
    // ...
    break
}

[neckaros]

What is the recommended way while @threadsafe does not work? passing Id and fetching?

Also using
Realm(actor: BackgroundActor.shared)
gives a warning:

Reference to static property 'shared' is not concurrency-safe because it involves shared mutable state

[tgoyne]

The @ThreadSafe property wrapper doesn't work with actor-isolated Realms, but ThreadSafeReference does.

[aehlke]

Is there a roundup of latest best practices (for when we're able to use latest swift versions)? It's a bit much to absorb the details of the changes such as is found in these threads and the changelog to piece it together. thanks

[bootuz]

When I use this approach I get a warning in Xcode:
Non-sendable type 'Realm' returned by implicitly asynchronous call to nonisolated function cannot cross actor boundary

actor MyActor {
    // An implicitly-unwrapped optional is used here to let us pass `self` to
    // `Realm(actor:)` within `init`
    var realm: Realm!
    init() async throws {
        realm = try await Realm(actor: self)
    }

    var count: Int {
        realm.objects(MyObject.self).count
    }

    func create() async throws {
        try await realm.asyncWrite {
            realm.create(MyObject.self)
        }
    }
}

[tgoyne]

Swift 6 includes a feature which lets us eliminate this warning, but currently using it just makes the compiler crash. I've reported the bug to Apple and I'm hoping they fix it by the final release. If they don't fix it there's an alternative of switching to await Realm.open(config) but we don't want to ship the API change if we don't have to.

[bootuz]

It looks like Realm object doesn't have open method.

[tgoyne]

Correct, that is a thing we would add to work around the compiler bug if it is not fixed.