Bridging completion handlers to Swift's async/await

Before Swift introduced structured concurrency and async/await, most asynchronous APIs in iOS used completion handlers. While many system frameworks have since adopted native async functions, we still often encounter callback-based APIs.

To integrate those with Swift’s modern concurrency model, we can bridge them using continuations. Let's look at how to do that.

Architecture & Design Patterns for iOS

This book is a practical guide to essential architectural principles and design patterns for iOS development. It covers strategies for building maintainable apps with Swift and SwiftUI, including dependency injection, navigation, common patterns, and modularization.

LEARN MORE

What continuations do

Every time we call await, the current code suspends by creating a continuation that captures the state at the point of suspension. When an awaited function completes, the captured state is recreated from the continuation and the original code resumes. This all happens behind the scenes when we use existing async functions.

To create our own async functions, we can use so called continuation functions. Continuation functions give us control over suspending and resuming a function.

Let's see how to do that.

Using withCheckedContinuation

Let's look at a simple example. Suppose we have an API that loads data using a completion handler:

func load(completion: (Int) -> Void) {
    ...
}

We can bridge it to Swift concurrency like this:

func load() async -> Int {
    return await withCheckedContinuation({ continuation in
        load() { result in
            continuation.resume(returning: result)
        }
    })
}

In the example above, we use Swift's withCheckedContinuation function to suspend and then call resume after we get a result from our completion handler function. Resuming from a continuation must happen exactly once.

Besides withCheckedContinuation(), there are other continuation functions we can use:

• withCheckedThrowingContinuation()
• withUnsafeContinuation()
• withUnsafeThrowingContinuation()

Using withCheckedThrowingContinuation

If our callback reports errors, we can use the throwing version instead. For example, if we have:

func load(completion: (Result<Int, Error>) -> Void) {
}

We can wrap it into an async throws function as follows:

func load() async throws -> Int {
    return try await withCheckedThrowingContinuation({ continuation in
        load() { result in
            switch result {
            case .success(let successResult):
                continuation.resume(returning: successResult)
            case .failure(let error):
                continuation.resume(throwing: error)
            }
        }
    })
}

This lets us use the try await syntax when calling the function.

Using withUnsafeContinuation() and withUnsafeThrowingContinuation()

Both functions, withUnsafeContinuation() and withUnsafeThrowingContinuation() behave the same as withCheckedContinuation() and withCheckedThrowingContinuation(). The only difference is that while checked continuations perform runtime checks for missing or multiple resume operations, unsafe continuations don't.

Checked continuations are generally safer and preferred for most cases.