Getting Started with async/await in SwiftUI

SwiftUI Concurrency Essentials

June 24, 2021 - 5 min read

Without a doubt, one of the biggest announcements at WWDC21 was Swift Concurrency, most notably the support for async/await.

As developers, we’re constantly faced with the asynchronous nature of the apps we write. Reading a file from disk, fetching data from a remote API on the web, and even getting input from the user - all of these are asynchronous operations. Throughout the years, many different ways to deal with asynchronous code have been implemented - most iOS developers will be familiar with Grand Central Dispatch, completion handlers, or delegates.

The new Swift Concurrency model builds on threads, but abstracts away from them.

At WWDC 2021, Apple did a fantastic job at at explaining all the concepts behind async/await and Structured Concurrency. There are no less than 9 videos, plus an entire chapter about Concurrency in the Swift Language Guide, as well as a ton of sample code (in case you haven’t tried it, check out the copy code feature in the Developer app).

But because there is so much information out there, it is sometimes hard to see the forest before the trees.

This article aims at giving you everything you need to write SwiftUI apps that make use of the new concurrency features in Swift.

So - let’s cut to the chase!

Note: this article is based on Swift 5.5 as included with Xcode 13 (at the time of writing, Xcode 13b1). You will not be able to use this in your production builds until iOS 15 is released to the public and Apple starts accepting builds created with Xcode 13 GA. Nevertheless, it is instructive to learn how to use the new language features and understand the impact they might have on your code - particularly if you are a library or framework vendor.

The sample app

When looking for an easy-to-use API to for our sample app, I came across WordsAPI.com. It’s a fun API that provides a ton of interesting information about words (in the English language). You send it a word, such as “Swift”, and it will return a bunch of information, such as the different meanings of the word (for example, “moving very fast”, “a small bird that resembles a swallow”, or “an English satirist born in Ireland”).

The sample app displays a bunch of words in a List view. When the user taps on one of those words, the app will fetch the meanings of this word from WordAPI.com and display them in a details screen.

Later on in the article, we will add another feature that fetches a random word from WordAPI.com and adds it to the main list when the user pulls to refresh.

Screenshot of the sample with pull-to-refresh in action
Screenshot of the sample with pull-to-refresh in action

Using URLSession and async/await

URLSession is among the many APIs that have been upgraded to support async/await, so fetching data is now a simple one-liner:

let (data, response) = try await URLSession.shared.data(for: urlRequest)

With some minimal level of error handling and JSON parsing (powered by Codable), the code for fetching the details about a word looks like this:

private func search(for searchTerm: String) async -> Word { 
  // build the request
  let request = buildURLRequest(for: searchTerm)
    
  do {
    let (data, response) = try await URLSession.shared.data(for: request) 
    guard let httpResponse = response as? HTTPURLResponse, httpResponse.statusCode == 200 else {
      throw WordsAPI.invalidServerResponse
    }
    let word = try JSONDecoder().decode(Word.self, from: data)
    return word
  }
  catch {
    return Word.empty
  }
}

Note that we marked our search(for searchTerm: String) method as asynchronous by appending async in the method signature. This means we’ll have to use await whenever we call this method. Doing so indicates a so-called suspension point, and gives the runtime the opportunity to suspend the currently executing function. A suspended function is “put on hold” until the function it called returns. While the function is suspended, the thread it was executing on can be used to execute other code in your application.

Updating @Published properties

The sample app uses a view model to act as a central point for fetching data from the WordsAPI endpoint. It is implemented as an ObservableObject, so it can leverage SwiftUI’s state management system:

struct Word {
  let word: String
  let definitions: [Definition]
}


@MainActor
class WordDetailsViewModel: ObservableObject {
  // output
  @Published var result = Word.empty
  @Published var isSearching = false
  
  func executeQuery(for searchTerm: String) async {
    isSearching = true
    result = await search(for: searchTerm)
    isSearching = false
  }
  
  private func buildURLRequest(for searchTerm: String) -> URLRequest { ... }
  
  private func search(for searchTerm: String) async -> Word { ... }
}

Let’s discuss what’s going on here:

  • result is a published property that contains the result of the API call (once this call returns)
  • isSearching indicates whether we’re currently performing a search. This property will be bound to a progress indicator to give the user some visual feedback that we’re waiting for results.
  • executeQuery manages the state of isSearching, and then calls the actual code for performing the API call. Note that this function also needs to be marked as async, as it calls search(for:), which is a function that might suspend (as mentioned in Meet async/await in Swift, functions that may suspend, suspend their callers too).
  • and finally, the entire view model is marked as @MainActor, to indicate any of the code within must be run on the main actor.

This last point is crucial: since published properties update the UI, any changes that are made to them need to be run on the main thread. By marking a class with the @MainActor attribute, the Swift compiler will guarantee that all methods and properties on it are only ever called from the main actor. So by annotating WordDetailsViewModel with the @MainActor annotation, we make sure all updates happen on the main thread.

Note: I strongly recommend using view models, as they help to keep your code clean. However, it is definitely possible to forgo view models and make the search(for searchTerm: String) function a member of your SwiftUI view. To see how you would do that, check out WordDetailsViewNoViewModel in the GitHub repository for this article.

Calling asynchronous code from SwiftUI …

The final piece of the puzzle is how to call our asychronous code from SwiftUI. There are many different places you might call from:

  • When the view appears
  • When the user taps on a button
  • When the user pulls to refresh
  • In response to a search request
  • Based on a notification
  • Based on a timer

Let’s look at a few of these to understand the different mechanisms we can use.

… when the view appears

This is probably the most common time to fetch data, and you might have been using the onAppear view modifier in your existing SwiftUI apps to trigger fetching data. We can still use onAppear, but the compiler will complain that we cannot call an asynchronous function here.

onAppear is not asynchronous
onAppear is not asynchronous

One solution to this problem is to create a new Task by calling the async static function (Note: this will be replaced with Task.init in Xcode 13b2), like this:

struct WordDetailsView: View {
  ...  
  var body: some View {
    List {
      ...
    }
    .navigationTitle(word)
    .onAppear {
      async {
        await viewModel.executeQuery(for: word)
      }
    }
  }
}

This works well, but there is an even better solution: because fetching data when a view appears is so common, SwiftUI has a new view modifier that will automatically create a new Task and cancel the task when the view disappears:

struct WordDetailsView: View {
  ...
  var body: some View {
    List {
      ...
    }
    .navigationTitle(word)
    .task {
      await viewModel.executeQuery(for: word)
    }
  }
}

… when the user taps a button

Sometimes, we want to execute asynchronous code in response to a button tap. In Xcode 13b1, most of the button action handlers do not support calling asynchronous code, so we need to create a new asynchronous context by calling async ourselves:

.toolbar {
  ToolbarItem(placement: .primaryAction) {
    Button("Refresh") {
      async {
        await viewModel.refresh()
      }
    }
  }
}

Some of Button‘s action handlers do support calling asynchronous code, however:

Async button action handlers.jpeg
Async button action handlers.jpeg

It’s not quite clear to me why this should only be possible for Buttons that have a role, so maybe we’ll see an update for this in the next beta.

… when the user pulls to refresh

Pull-to-refresh is another welcome addition to this year’s release of SwiftUI. By simply adding the refreshable view modifier, a view receives pull-to-refresh capabilities. Inside the closure, we can update the data that’s displayed in the view:

struct LibraryView: View {
  ...  
  var body: some View {
    List {
      ...
    }
    .searchable(text: $viewModel.searchText)
    .refreshable {
      await viewModel.refresh()
    }
  }
}

… in response to a search request

This year’s release of SwiftUI also brought us the searchable() view modifier - by applying this view modifier to a list view, you get a platform-specific search UI. The first parameter of the view modifer is a binding to a String, which you can then use to drive the search. If you don’t want to use Combine to listen to changes on the search string, you can use the onSubmit(of:) view modifier to react to certain key presses. For example, to trigger the search when the user taps the Search button on their on-screen keyboard (or hits the enter key), you can use this code snippet:

struct WordSearchView: View {
  @StateObject var viewModel = WordsAPIViewModel()
  var body: some View {
    List {
      ...
    }
    .searchable(text: $viewModel.searchTerm)
    .onSubmit(of: .search) {
      async {
        await viewModel.executeQuery()
      }
    }
    .navigationTitle("Search")
  }
}

As you might have noticed, onSubmit‘s closure isn’t marked as asynchronous, which is why we need to create a new Task using the now familiar async { } syntax.

Closure

To summarise:

  1. Use asynchronous versions of Apple’s APIs (if that’s not possible, there is a workaround, which we will learn about in one of the following posts)
  2. Mark functions that call asynchronous code as async
  3. Mark your ObservableObjects as @MainActor
  4. To fetch data when a view appears, use the task view modifier
  5. Use the refreshable view modifier to use pull-to-refresh to fetch data asynchronously
  6. Use async to start a new asynchronous Task from a synchronous context, such as a Button

I hope you found this useful. If you’ve got any questions or suggestions, reach out to me on Twitter, or file a pull request on the repository for this article.

Thanks for reading! 🔥


Read next