In the previous installments, we discussed batch updates and batch deletes. In this tutorial, we'll take a closer look at how to implement asynchronous fetching and in what situations your application can benefit from this new API.

1. The Problem

Like batch updates, asynchronous fetching has been on the wish list of many developers for quite some time. Fetch requests can be complex, taking a non-trivial amount of time to complete. During that time the fetch request blocks the thread it's running on and, as a result, blocks access to the managed object context executing the fetch request. The problem is simple to understand, but what does Apple's solution look like.

2. The Solution

Apple's answer to this problem is asynchronous fetching. An asynchronous fetch request runs in the background. This means that it doesn't block other tasks while it's being executed, such as updating the user interface on the main thread.

Asynchronous fetching also sports two other convenient features, progress reporting and cancellation. An asynchronous fetch request can be cancelled at any time, for example, when the user decides the fetch request takes too long to complete. Progress reporting is a useful addition to show the user the current state of the fetch request.

Asynchronous fetching is a flexible API. Not only is it possible to cancel an asynchronous fetch request, it's also possible to make changes to the managed object context while the asynchronous fetch request is being executed. In other words, the user can continue to use your application while the application executes an asynchronous fetch request in the background.

3. How Does It Work?

Like batch updates, asynchronous fetch requests are handed to the managed object context as an NSPersistentStoreRequest object, an instance of the NSAsynchronousFetchRequest class to be precise.

An NSAsynchronousFetchRequest instance is initialized with an NSFetchRequest object and a completion block. The completion block is executed when the asynchronous fetch request has completed its fetch request.

Let's revisit the to-do application we created earlier in this series and replace the current implementation of the NSFetchedResultsController class with an asynchronous fetch request.

Step 1: Project Setup

Download or clone the project from GitHub and open it in Xcode 7. Before we can start working with the NSAsynchronousFetchRequest class, we need to make some changes. We won't be able to use the NSFetchedResultsController class for managing the table view's data since the NSFetchedResultsController class was designed to run on the main thread.

Step 2: Replacing the Fetched Results Controller

Start by updating the ViewController class as shown below. We remove the fetchedResultsController property and create a new property,items, of type [Item] for storing the to-do items. This also means that the ViewController class no longer needs to conform to the NSFetchedResultsControllerDelegate protocol.

import UIKit
import CoreData

class ViewController: UIViewController, UITableViewDataSource, UITableViewDelegate {

    let ReuseIdentifierToDoCell = "ToDoCell"
    
    @IBOutlet weak var tableView: UITableView!
    
    var managedObjectContext: NSManagedObjectContext!
    
    var items: [NSManagedObject] = []

    ...

}

Before we refactor the viewDidLoad() method, I first want to update the implementation of the UITableViewDataSource protocol. Take a look at the changes I've made.

func numberOfSectionsInTableView(tableView: UITableView) -> Int {
    return 1
}

func tableView(tableView: UITableView, numberOfRowsInSection section: Int) -> Int {
    return items.count
}

func configureCell(cell: ToDoCell, atIndexPath indexPath: NSIndexPath) {
    // Fetch Record
    let record = items[indexPath.row]
    
    // Update Cell
    if let name = record.valueForKey("name") as? String {
        cell.nameLabel.text = name
    }
    
    if let done = record.valueForKey("done") as? Bool {
        cell.doneButton.selected = done
    }
    
    cell.didTapButtonHandler = {
        if let done = record.valueForKey("done") as? Bool {
            record.setValue(!done, forKey: "done")
        }
    }
}

func tableView(tableView: UITableView, commitEditingStyle editingStyle: UITableViewCellEditingStyle, forRowAtIndexPath indexPath: NSIndexPath) {
    if (editingStyle == .Delete) {
        // Fetch Record
        let record = items[indexPath.row]
        
        // Delete Record
        managedObjectContext.deleteObject(record)
    }
}

We also need to change one line of code in the prepareForSegue(_:sender:) method as shown below.

// Fetch Record
let record = items[indexPath.row]

Last but not least, delete the implementation of the NSFetchedResultsControllerDelegate protocol since we no longer need it.

Step 3: Creating the Asynchronous Fetch Request

As you can see below, we create the asynchronous fetch request in the view controller's viewDidLoad() method. Let's take a moment to see what's going on.

override func viewDidLoad() {
    super.viewDidLoad()
    
    // Initialize Fetch Request
    let fetchRequest = NSFetchRequest(entityName: "Item")
    
    // Add Sort Descriptors
    fetchRequest.sortDescriptors = [NSSortDescriptor(key: "createdAt", ascending: true)]
    
    // Initialize Asynchronous Fetch Request
    let asynchronousFetchRequest = NSAsynchronousFetchRequest(fetchRequest: fetchRequest) { (asynchronousFetchResult) -> Void in
        dispatch_async(dispatch_get_main_queue(), { () -> Void in
            self.processAsynchronousFetchResult(asynchronousFetchResult)
        })
    }
    
    do {
        // Execute Asynchronous Fetch Request
        let asynchronousFetchResult = try managedObjectContext.executeRequest(asynchronousFetchRequest)
        
        print(asynchronousFetchResult)
        
    } catch {
        let fetchError = error as NSError
        print("\(fetchError), \(fetchError.userInfo)")
    }
}

We start by creating and configuring an NSFetchRequest instance to initialize the asynchronous fetch request. It's this fetch request that the asynchronous fetch request will execute in the background.

// Initialize Fetch Request
let fetchRequest = NSFetchRequest(entityName: "Item")

// Add Sort Descriptors
fetchRequest.sortDescriptors = [NSSortDescriptor(key: "createdAt", ascending: true)]

To initialize an NSAsynchronousFetchRequest instance, we invoke init(request:completionBlock:), passing in fetchRequest and a completion block.

// Initialize Asynchronous Fetch Request
let asynchronousFetchRequest = NSAsynchronousFetchRequest(fetchRequest: fetchRequest) { (asynchronousFetchResult) -> Void in
    dispatch_async(dispatch_get_main_queue(), { () -> Void in
        self.processAsynchronousFetchResult(asynchronousFetchResult)
    })
}

The completion block is invoked when the asynchronous fetch request has completed executing its fetch request. The completion block takes one argument of type NSAsynchronousFetchResult, which contains the result of the query as well as a reference to the original asynchronous fetch request.

In the completion block, we invoke processAsynchronousFetchResult(_:), passing in the NSAsynchronousFetchResult object. We'll take a look at this helper method in a few moments.

Executing the asynchronous fetch request is almost identical to how we execute an NSBatchUpdateRequest. We call executeRequest(_:) on the managed object context, passing in the asynchronous fetch request.

do {
    // Execute Asynchronous Fetch Request
    let asynchronousFetchResult = try managedObjectContext.executeRequest(asynchronousFetchRequest)
    
    print(asynchronousFetchResult)
    
} catch {
    let fetchError = error as NSError
    print("\(fetchError), \(fetchError.userInfo)")
}

Even though the asynchronous fetch request is executed in the background, note that the executeRequest(_:) method returns immediately, handing us an NSAsynchronousFetchResult object. Once the asynchronous fetch request completes, that same NSAsynchronousFetchResult object is populated with the result of the fetch request.

Remember from the previous tutorial that executeRequest(_:) is a throwing method. We catch any errors in the catch clause of the do-catch statement and print them to the console for debugging.

Step 4: Processing the Asynchronous Fetch Result

The processAsynchronousFetchResult(_:) method is nothing more than a helper method in which we process the result of the asynchronous fetch request. We set the view controller's items property with the contents of the result's finalResult property and reload the table view.

func processAsynchronousFetchResult(asynchronousFetchResult: NSAsynchronousFetchResult) {
    if let result = asynchronousFetchResult.finalResult {
        // Update Items
        items = result as! [NSManagedObject]
        
        // Reload Table View
        tableView.reloadData()
    }
}

Step 5: Build & Run

Build the project and run the application in the iOS Simulator. If your application crashes when it attempts to execute the asynchronous fetch request, then you may be using an API that is deprecated as of iOS 9 (and OS X El Capitan).

In Core Data and Swift: Concurrency, I explained the different concurrency types a managed object context can have. As of iOS 9 (and OS X El Capitan), the ConfinementConcurrencyType is deprecated. The same is true for the init() method of the NSManagedObjectContext class, because it creates an instance with a concurrency type of ConfinementConcurrencyType.

If your application crashes, you are most likely using a managed object context with a ConfinementConcurrencyType concurrency type, which doesn't support asynchronous fetching. Fortunately, the solution is simple. Create a managed object context using the designated initializer, init(concurrencyType:), passing in MainQueueConcurrencyType or PrivateQueueConcurrencyType as the concurrency type.

4. Showing Progress

The NSAsynchronousFetchRequest class adds support for monitoring the progress of the fetch request and it's even possible to cancel an asynchronous fetch request, for example, if the user decides that it's taking too long to complete.

The NSAsynchronousFetchRequest class leverages the NSProgress class for progress reporting as well as canceling an asynchronous fetch request. The NSProgress class, available since iOS 7 and OS X Mavericks, is a clever way to monitor the progress of a task without the need to tightly couple the task to the user interface.

The NSProgress class also support cancelation, which is how an asynchronous fetch request can be canceled. Let's find out what we need to do to implement progress reporting for the asynchronous fetch request.

Step 1: Adding SVProgressHUD

We'll show the user the progress of the asynchronous fetch request using Sam Vermette's SVProgressHUD library. The easiest way to accomplish this is through CocoaPods. This is what the project's Podfile looks like.

source 'https://github.com/CocoaPods/Specs.git'
platform :ios, '9.0'
use_frameworks!

pod 'SVProgressHUD', '~> 1.1'

Run pod install form the command line and don't forget to open the workspace CocoaPods has created for you instead of the Xcode project.

Step 2: Setting Up NSProgress 

In this article, we won't explore the NSProgress class in much detail, but feel free to read more about it in Apple's documentation. We create an NSProgress instance in the view controller's viewDidLoad() method, before we execute the asynchronous fetch request.

// Create Progress
let progress = NSProgress(totalUnitCount: 1)

// Become Current
progress.becomeCurrentWithPendingUnitCount(1)

You may be surprised that we set the total unit count to 1. The reason is simple. When Core Data executes the asynchronous fetch request, it doesn't know how many records it will find in the persistent store. This also means that we won't be able to show the relative progress to the user—a percentage. Instead, we will show the user the absolute progress—the number of records it has found.

You could remedy this issue by performing a fetch request to fetch the number of records before you execute the asynchronous fetch request. I prefer not to do this though, because this also means that fetching the records from the persistent store takes longer to complete because of the extra fetch request at the start.

Step 3: Adding an Observer

When we execute the asynchronous fetch request, we are immediately handed an NSAsynchronousFetchResult object. This object has a progress property, which is of type NSProgress. It's this progress property that we need to observe if we want to receive progress updates.

// Create Progress
let progress = NSProgress(totalUnitCount: 1)

// Become Current
progress.becomeCurrentWithPendingUnitCount(1)

// Execute Asynchronous Fetch Request
let asynchronousFetchResult = try managedObjectContext.executeRequest(asynchronousFetchRequest) as! NSAsynchronousFetchResult

if let asynchronousFetchProgress = asynchronousFetchResult.progress {
    asynchronousFetchProgress.addObserver(self, forKeyPath: "completedUnitCount", options: NSKeyValueObservingOptions.New, context: nil)
}

// Resign Current
progress.resignCurrent()

Note that we call resignCurrent on the progress object to balance the earlier becomeCurrentWithPendingUnitCount: call. Keep in mind that both of these methods need to be invoked on the same thread.

Step 4: Removing the Observer

In the completion block of the asynchronous fetch request, we remove the observer and dismiss the progress HUD.

// Initialize Asynchronous Fetch Request
let asynchronousFetchRequest = NSAsynchronousFetchRequest(fetchRequest: fetchRequest) { (asynchronousFetchResult) -> Void in
    dispatch_async(dispatch_get_main_queue(), { () -> Void in
        // Dismiss Progress HUD
        SVProgressHUD.dismiss()
        
        // Process Asynchronous Fetch Result
        self.processAsynchronousFetchResult(asynchronousFetchResult)
        
        if let asynchronousFetchProgress = asynchronousFetchResult.progress {
            // Remove Observer
            asynchronousFetchProgress.removeObserver(self, forKeyPath: "completedUnitCount")
        }
    })
}

Before we implement observeValueForKeyPath(_:ofObject:change:context:), we need to show the progress HUD before creating the asynchronous fetch request.

// Show Progress HUD
SVProgressHUD.showWithStatus("Fetching Data", maskType: .Gradient)

Step 5: Progress Reporting

All that's left for us to do, is implement the observeValueForKeyPath(_:ofObject:change:context:) method. We check if context is equal to ProgressContext, create a status object by extracting the number of completed records from the change dictionary, and update the progress HUD. Note that we update the user interface on the main thread.

override func observeValueForKeyPath(keyPath: String?, ofObject object: AnyObject?, change: [String : AnyObject]?, context: UnsafeMutablePointer<Void>) {
    if keyPath == "completedUnitCount" {
        dispatch_async(dispatch_get_main_queue(), { () -> Void in
            if let changes = change, number = changes["new"] {
                // Create Status
                let status = "Fetched \(number) Records"
                
                // Show Progress HUD
                SVProgressHUD.setStatus(status)
            }
        })
    }
}

5. Dummy Data

If we want to properly test our application, we need more data. While I don't recommend using the following approach in a production application, it's a quick and easy way to populate the database with data.

Open AppDelegate.swift and update the application(_:didFinishLaunchingWithOptions:) method as shown below. The populateDatabase() method is a simple helper method in which we add dummy data to the database.

func application(application: UIApplication, didFinishLaunchingWithOptions launchOptions: [NSObject: AnyObject]?) -> Bool {
    // Populate Database
    populateDatabase()

    ...
    
    return true
}

The implementation is straightforward. Because we only want to insert dummy data once, we check the user defaults database for the key "didPopulateDatabase". If the key isn't set, we insert dummy data.

private func populateDatabase() {
    // Helpers
    let userDefaults = NSUserDefaults.standardUserDefaults()
    guard userDefaults.objectForKey("didPopulateDatabase") == nil else { return }
    
    // Create Entity
    let entityDescription = NSEntityDescription.entityForName("Item", inManagedObjectContext: self.managedObjectContext)
    
    for index in 0...1000000 {
        // Initialize Record
        let record = NSManagedObject(entity: entityDescription!, insertIntoManagedObjectContext: self.managedObjectContext)
        
        // Populate Record
        record.setValue(NSDate(), forKey: "createdAt")
        record.setValue("Item \(index)", forKey: "name")
    }
    
    // Save Changes
    saveManagedObjectContext()
    
    // Update User Defaults
    userDefaults.setBool(true, forKey: "didPopulateDatabase")
}

The number of records is important. If you plan to run the application on the iOS Simulator, then it's fine to insert 100,000 or 1,000,000 records. This won't work as good on a physical device and will take too long to complete.

In the for loop, we create a managed object and populate it with data. Note that we don't save the changes of the managed object context during each iteration of the for loop.

Finally, we update the user defaults database to make sure the database isn't populated the next time the application is launched.

Great. Run the application in the iOS Simulator to see the result. You'll notice that it takes a few moments for the asynchronous fetch request to start fetching records and update the progress HUD.

6. Breaking Changes

By replacing the fetched results controller class with an asynchronous fetch request, we have broken a few pieces of the application. For example, tapping the checkmark of a to-do item doesn't seem to work any longer. While the database is being updated, the user interface doesn't reflect the change. The solution is fairly easy to fix and I'll leave it up to you to implement a solution. You should now have enough knowledge to understand the problem and find a suitable solution.

Conclusion

I'm sure you agree that asynchronous fetching is surprisingly easy to use. The heavy lifting is done by Core Data, which means that there's no need to manually merge the results of the asynchronous fetch request with the managed object context. Your only job is to update the user interface when the asynchronous fetch request hands you the results.