Swift Concurrency - Swift SDK

SDK Concurrency Caveats

As you implement concurrency features in your app, consider this caveat about the SDK's threading model and Swift concurrency threading behaviors.

Async/Await APIs

Many Swift SDK APIs that involve working with an Atlas App Services app or a synchronized database are compatible with Swift's async/await syntax. For examples, check out:

• Authenticate Users

• Manage Email/Password Users

• Link User Identities

• Open a Synced Database or a non-synced database

• Await notifications from another actor

• Manage Sync Subscriptions

• Async/Await Call a Serverless Function

• Async/Await Query MongoDB

• Async/Await CRUD operations

If you have specific feature requests related to Swift async/await APIs, check out the MongoDB Feedback Engine for Realm. The Swift SDK team plans to continue to develop concurrency-related features based on community feedback and Swift concurrency evolution.

Tasks and TaskGroups

Swift concurrency provides APIs to manage Tasks and TaskGroups. The Swift concurrency documentation defines a task as a unit of work that can be run asynchronously as part of your program. Task allows you to specifically define a unit of asynchronous work. TaskGroup lets you define a collection of Tasks to execute as a unit under the parent TaskGroup.

Tasks and TaskGroups provide the ability to yield the thread to other important work or to cancel a long-running task that could be blocking other operations. To get these benefits, you might be tempted to use Tasks and TaskGroups to manage database writes in the background.

However, the thread-confined constraints described in Suspending Execution with Await above apply in the Task context. If your Task contains await points, subsequent code might run or resume on a different thread and violate the SDK's thread confinement.

You must annotate functions that you run in a Task context with @MainActor to ensure code that accesses the database only runs on the main thread. This negates some of the benefits of using Tasks, and may mean this is not a good design choice for apps that use the SDK unless you are using Tasks solely for networking activities like managing users.

Actor Isolation

Actor isolation provides the perception of confining database access to a dedicated actor, and therefore seems like a safe way to manage database access in an asynchronous context.

However, using the database in a non-@MainActor async function is currently not supported.

In Swift 5.6, this would often work by coincidence. Execution after an await would continue on whatever thread the awaited thing ran on. Using await Realm() in an async function would result in the code following that running on the main thread until your next call to an actor-isolated function.

Swift 5.7 instead hops threads whenever changing actor isolation contexts. An unisolated async function always runs on a background thread instead.

If you have code which uses await Realm() and works in 5.6, marking the function as @MainActor will make it work with Swift 5.7. It will function how it did - unintentionally - in 5.6.

Errors Related to Concurrency Code

Most often, the error you see related to accessing the database through concurrency code is Realm accessed from incorrect thread. This is due to the thread-isolation issues described on this page.

To avoid threading-related issues in code that uses Swift concurrency features:

• Upgrade to a version of the Swift SDK that supports actor-isolated databases, and use this as an alternative to manually managing threading. For more information, refer to Use Atlas Device SDK for Swift with Actors.

• Do not change execution contexts when accessing a database. If you open a database on the main thread to provide data for your UI, annotate subsequent functions where you access the database asynchronously with @MainActor to ensure it always runs on the main thread. Remember that await marks a suspension point that could change to a different thread.

• Apps that do not use actor-isolated databases can use the writeAsync API to perform a background write. This manages database access in a thread-safe way without requiring you to write specialized code to do it yourself. This is a special API that outsources aspects of the write process - where it is safe to do so - to run in an async context. Unless you are writing to an actor-isolated database, you do not use this method with Swift's async/await syntax. Use this method synchronously in your code. Alternately, you can use the asyncWrite API with Swift's async/await syntax when awaiting writes to asynchronous databases.

• If you want to explicitly write concurrency code that is not actor-isolated where accessing a database is done in a thread-safe way, you can explicitly pass instances across threads where applicable to avoid threading-related crashes. This does require a good understanding of the SDK's threading model, as well as being mindful of Swift concurrency threading behaviors.

Sendable, Non-Sendable, and Thread-Confined Types

The Swift SDK public API contains types that fall into three broad categories:

• Sendable

• Not Sendable and not thread confined

• Thread-confined

You can share types that are not Sendable and not thread confined between threads, but you must synchronize them.

Thread-confined types, unless frozen, are confined to an isolation context. You cannot pass them between these contexts even with synchronization.