Introduction

Threads let you solve two tricky problems:

• parallel computation — In this world of multicore CPUs, many tasks will run faster if you divide the work between threads that are scheduled on different cores.

  This approach can be useful even on a single core system (as is the case for all current iOS devices). Specifically, if your computation thread spends some fraction of its time blocked (for example, waiting for disk I/O), you can use multiple threads to do useful computation on one thread while the other thread is blocked.

• asynchronous computation — If you have some long-running computation to do and, as is the case on iOS, you must keep the main thread responsive, you can move that computation to a secondary thread. This allows your main thread to treat the computation as it would any other asynchronous operation.

However, threads are not always the right solution. Threads have a significant cost, in terms of both memory and, more importantly, code complexity. In many cases it's a good idea to use the asynchronous APIs available in iOS instead. Specifically, a thread is a poor choice if you expect it to spend a significant amount of its time blocked. For example:

• periodic execution — Starting a thread just to execute code periodically is never a good idea. You should use NSTimer instead.

• networking — On a typical iOS device, the CPU is much faster than the network so, if you start a thread to do your networking synchronously, that thread will spend most of its time blocked. A better approach is to use the asynchronous networking APIs provided by iOS.

Once you've decided that it's appropriate to solve your problem with threads, you need to decide on the overall structure of your code. A common approach is to use the NSThread API directly, or perhaps take advantage of Cocoa's -performSelectorInBackground:withObject: method. It is, however, very easy to run into problems with these mechanism. The first section of this technote (Threads And Their Problems) describe some of those problems, just so you can get a feel for why it's so important to be careful with threads. The next section (NSOperation To The Rescue!) describes how you can use NSOperation to address those problems in a simple and reliable way. Finally, the last section (NSOperations Hints and Tips) offers some hints and tips for using NSOperation effectively.

Threads And Their Problems

Imagine you have an application that displays a list of numbers with a total at the top. Actually, you don't have to imagine this, you can just look at Sample Code 'ListAdder', which was specifically created for this technote. Figure 1 shows the basic UI.

Such an application might have a view controller class with a property that is the list of numbers, represented as a mutable array. Listing 1 shows how this might be declared.

Listing 1  The numbers array declaration

@interface ListAdderViewController () [...]  @property (nonatomic, retain, readonly ) NSMutableArray *   numbers;  [...]  @end

Now imagine, just for the sake of this example, that adding up the list of numbers takes a very long time. So, as the user changes the list, you have to update the total, but you can't do that on the main thread because it would block the user interface too long. Thus you have to do the summation asynchronously. One obvious way to do that is to start a thread. Listing 2 shows how you might do this. You'll note that the core calculation loop contains a long delay so that you can actually see the various threading problems as they crop up.

Listing 2  Recalculating on a thread

// ---- Broken Code ---- Do Not Use ---- Broken Code ---- Do Not Use ----

- (void)recalculateTotalUsingThread
{
    self.recalculating = YES;
    [self performSelectorInBackground:@selector(threadRecalculateNumbers) withObject:self.numbers];
}

- (void)threadRecalculateNumbers
{
    NSAutoreleasePool *     pool;
    NSInteger               total;
    NSUInteger              numberCount;
    NSUInteger              numberIndex;
    NSString *              totalStr;

    pool = [[NSAutoreleasePool alloc] init];
    assert(pool != nil);

    total = 0;
    numberCount = [self.numbers count];
    for (numberIndex = 0; numberIndex < numberCount; numberIndex++) {
        NSNumber *  numberObj;

        // Sleep for a while. This makes it easiest to test various problematic cases.

        [NSThread sleepForTimeInterval:1.0];

        // Do the mathematics.

        numberObj = [self.numbers objectAtIndex:numberIndex];
        assert([numberObj isKindOfClass:[NSNumber class]]);

        total += [numberObj integerValue];
    }

    // The user interface is adjusted by a KVO observer on recalculating.

    totalStr = [NSString stringWithFormat:@"%ld", (long) total];
    self.formattedTotal = totalStr;
    self.recalculating = NO;

    [pool drain];
}

// ---- Broken Code ---- Do Not Use ---- Broken Code ---- Do Not Use ----

This code has numerous issues. The first one is pretty obvious: the end of -threadRecalculateNumbers applies the results to the user interface. In doing so, it ends up calling UIKit on a secondary thread. That's because other parts of the program use key-value observing (KVO) to observe the recalculating property and reload the table view accordingly. If you change recalculating on a secondary thread, this code ends up calling UIKit on a secondary thread, which is not allowed.

Fixing that problem is relatively easy. Listing 3 shows a replacement for -threadRecalculateNumbers with the fix.

Listing 3  Recalculating on a thread, second try

// ---- Broken Code ---- Do Not Use ---- Broken Code ---- Do Not Use ----

- (void)threadRecalculateNumbers
{
    NSAutoreleasePool *     pool;
    NSInteger               total;
    NSUInteger              numberCount;
    NSUInteger              numberIndex;
    NSString *              totalStr;

    pool = [[NSAutoreleasePool alloc] init];
    assert(pool != nil);

    total = 0;
    numberCount = [self.numbers count];
    for (numberIndex = 0; numberIndex < numberCount; numberIndex++) {
        NSNumber *  numberObj;

        // Sleep for a while. This makes it easiest to test various problematic cases.

        [NSThread sleepForTimeInterval:1.0];

        // Do the mathematics.

        numberObj = [self.numbers objectAtIndex:numberIndex];
        assert([numberObj isKindOfClass:[NSNumber class]]);

        total += [numberObj integerValue];
    }

    // Update the user interface on the main thread.

    totalStr = [NSString stringWithFormat:@"%ld", (long) total];
    [self performSelectorOnMainThread:@selector(threadRecalculateDone:) withObject:totalStr waitUntilDone:NO];

    [pool drain];
}

- (void)threadRecalculateDone:(NSString *)result
{
    // The user interface is adjusted by a KVO observer on recalculating.

    self.formattedTotal = result;
    self.recalculating = NO;
}

// ---- Broken Code ---- Do Not Use ---- Broken Code ---- Do Not Use ----

So, we're done, right? Wrong! While this code fixes the problem mentioned above, it still has other problems. One such problem relates to the numbers property. This is a mutable array, and the code is now accessing the array on one thread (the secondary thread) while potentially mutating the array on another (the main thread). So, what happens if the main thread changes the numbers array while a secondary thread is recalculating? Bad things. Imagine this scenario:

1. The user adds an item. This starts a long recalculation on thread A.

2. A short while later, before thread A completes, the user then removes an item. This starts another long recalculation on thread B.

Now think back to the main recalculation loop. For convenience, it's reproduced in Listing 4, with all the extraneous stuff cut away.

Listing 4  A stripped down recalculation loop

NSUInteger              numberCount;
NSUInteger              numberIndex;

numberCount = [self.numbers count];
for (numberIndex = 0; numberIndex < numberCount; numberIndex++) {
    NSNumber *  numberObj;

    numberObj = [self.numbers objectAtIndex:numberIndex];
    total += [numberObj integerValue];
}

As you can see, the code first gets the count of the number of elements in the array, then iterates over that many elements. If the user removes an item from the numbers array after the secondary thread has initialized numberCount, this code will eventually access an element off the end of the array and crash.

Of course, fixing this is relatively easy: when you start the thread you make an immutable copy of the numbers array and have the thread operate on that. That way the thread is isolated from the changes done by the main thread. Listing 5 shows the basic idea.

Listing 5  Recalculating on a thread, third try

// ---- Broken Code ---- Do Not Use ---- Broken Code ---- Do Not Use ----

- (void)recalculateTotalUsingThread
{
    NSArray *       immutableNumbers;

    self.recalculating = YES;

    immutableNumbers = [[self.numbers copy] autorelease];
    assert(immutableNumbers != nil);
    [self performSelectorInBackground:@selector(threadRecalculateNumbers:) withObject:immutableNumbers];
}

- (void)threadRecalculateNumbers:(NSArray *)immutableNumbers
{
    NSAutoreleasePool *     pool;
    NSInteger               total;
    NSUInteger              numberCount;
    NSUInteger              numberIndex;
    NSString *              totalStr;

    pool = [[NSAutoreleasePool alloc] init];
    assert(pool != nil);

    total = 0;
    numberCount = [immutableNumbers count];
    for (numberIndex = 0; numberIndex < numberCount; numberIndex++) {
        NSNumber *  numberObj;

        // Sleep for a while. This makes it easiest to test various problematic cases.

        [NSThread sleepForTimeInterval:1.0];

        // Do the mathematics.

        numberObj = [immutableNumbers objectAtIndex:numberIndex];
        assert([numberObj isKindOfClass:[NSNumber class]]);

        total += [numberObj integerValue];
    }

    totalStr = [NSString stringWithFormat:@"%ld", (long) total];
    [self performSelectorOnMainThread:@selector(threadRecalculateDone:) withObject:totalStr waitUntilDone:NO];

    [pool drain];
}

// ---- Broken Code ---- Do Not Use ---- Broken Code ---- Do Not Use ----

This fixes all of the crashing bugs associated with threaded recalculation. However, there are still a number of other serious bugs in this code. The most obvious is associated with the order in which results arrive. Imagine the following sequence:

1. The user adds a bunch of items to the list. This kicks off a recalculation that takes a long time (because calculation time is proportional to the length of the array). This calculation runs on thread A.

2. The user removes all but one item from the list. This kicks off another recalculation, running on thread B, that completes quickly.

3. Thread B completes and applies its results to the user interface. The user interface is now showing the correct number.

4. Thread A completes and applies its results to the user interface. This leaves the user interface showing stale results.

The solution to this problem is to apply some sort of tag to the recalculation operation, and only commit its results if that tag is still valid. This in itself isn't hard to do, but at this point you should start to realize that a more structured approach is needed. One good structure to use here is NSOperation, discussed in detail in the next section. However, before we go there, you should consider two more outstanding problems with the threaded code:

• cancellation — In the above scenario you end up with thread A and B running simultaneously, with thread A's results destined to be discarded. It would be nice if we could stop thread A so that it doesn't waste CPU cycles, battery life, and memory.

• thread-safe deallocation — If you run any threaded code within UIKit objects (such as a view controller), there's a chance that the object's -dealloc method will be called on a secondary thread. This is bad (in the Ghost Busters sense of that word), especially in something like a view controller, where the -dealloc method typically releases UIView objects, and hence might cause their -dealloc method to run on the secondary thread. You can learn more about this problem and its solutions in The Deallocation Problem.

NSOperation provides the infrastructure for solving all of the problems discussed above. In the next section we'll look at how that works.

NSOperation To The Rescue!

NSOperation is a class that allows you to model asynchronous operations in a structured fashion. It provides a way for the high-level parts of your application to start asynchronous operations without worrying about the details of how they are executed. An NSOperation could be run on a thread, or asynchronously via run loop callbacks, or via other, more exotic means. The important thing is that your application's high-level code does not care. It just starts the operation and gets notified when it's finished.

NSOperation encourages a programming model called thread confinement. In this model the resources used by the thread are owned by that thread, not shared between threads. This is a great way to write threaded code without tripping over the sorts of problems discussed in the previous section. A good way to use NSOperation is:

1. Initialize the operation with an immutable copy of the data it needs to do its work.

2. Execute the operation; while it's executing, it only operates on the data it was initialized with and on data that it creates for itself and does not share with other threads.

3. When the operation completes, it makes its results available to the rest of the application, at which point the operation itself no longer touches those results.

Using a separate NSOperation object solves a number of problems with general threaded code:

• you can store ancillary data associated with the operation as properties of the NSOperation object

• you can use these properties, or even the NSOperation object itself, as a tag to decide whether the results of the operation are stale

• the NSOperation object is a handle by which you can cancel the operation

• you can guarantee that all threaded code runs within the operation, and hence avoid deallocation problems

NSOperation also has a number of other useful features:

• Each operation is executed by an operation queue (NSOperationQueue). Each queue has a maximum number of operations that it will execute in parallel (maxConcurrentOperationCount), commonly known as the queue width. This width defaults to a value that's appropriate for the device on which you're running, but you can set it to a value that's appropriate for the task at hand. For example, you can guarantee that operations are serialized (executed one at a time) by setting the queue width to 1. Or, if your operations hit the network, you can use the queue width to limit the number of concurrent network operations.

• You can create operation queues to model your problem space. For example, a file copying program could use one operation queue per disk to avoid thrashing the disk head.

• You can make operations dependent on other operations, and thereby establish chains of operation execution and operation fan in.

It's important to realize that NSOperation and NSOperationQueue don't do anything that you couldn't do yourself. If you really wanted to, you could replicate all of this structure with your own code. However, if you don't have an existing structure for managing asynchronous code, and you don't feel like reimplementing the wheel, NSOperation is for you.

The rest of this section describes how Sample Code 'ListAdder' uses NSOperation to implement asynchronous recalculation.

@interface AdderOperation : NSOperation  - (id)initWithNumbers:(NSArray *)numbers;  // only meaningful after the operation is finished  @property (copy,   readonly ) NSString * formattedTotal;  @end

- (id)initWithNumbers:(NSArray *)numbers
{
    assert(numbers != nil);
    self = [super init];
    if (self != nil) {
        self->_numbers = [numbers copy];
        assert(self->_numbers != nil);
    }
    return self;
}

- (void)main
{
    NSUInteger      numberCount;
    NSUInteger      numberIndex;
    NSInteger       total;

    // This method is called by a thread that's set up for us by the NSOperationQueue.

    assert( ! [NSThread isMainThread] );

    // Do the heavy lifting (-:

    total = 0;
    numberCount = [self.numbers count];
    for (numberIndex = 0; numberIndex < numberCount; numberIndex++) {
        NSNumber *  numberObj;

        // Check for cancellation.

        if ([self isCancelled]) {
            break;
        }

        // Sleep for a second. This makes it easiest to test cancellation 
        // and so on.

        [NSThread sleepForTimeInterval:1.0];

        // Do the mathematics.

        numberObj = [self.numbers objectAtIndex:numberIndex];
        assert([numberObj isKindOfClass:[NSNumber class]]);

        total += [numberObj integerValue];
    }

    // Set our output properties base on the value we calculated. Our client 
    // shouldn't look at these until -isFinished goes to YES (which happens when 
    // we return from this method).

    self.formattedTotal = [self.formatter stringFromNumber:[NSNumber numberWithInteger:total]];
}

@interface ListAdderViewController () [...]

@property (nonatomic, retain, readonly ) NSOperationQueue * queue;
@property (nonatomic, retain, readwrite) AdderOperation *   inProgressAdder;

[...]

@end

@implementation ListAdderViewController

[...]

- (id)init
{
    self = [super initWithStyle:UITableViewStyleGrouped];
    if (self != nil) {
        [...] 

        self->_queue = [[NSOperationQueue alloc] init];
        assert(self->_queue != nil);

        [...] 
    }
    return self;
}

[...]

@end

- (void)recalculateTotalUsingOperation
{
    // If we're already calculating, cancel that operation.

    if (self.inProgressAdder != nil) {
        [self.inProgressAdder cancel];
    }

    // Start up a replacement operation.

    self.inProgressAdder = [[[AdderOperation alloc] initWithNumbers:self.numbers] autorelease];
    assert(self.inProgressAdder != nil);

    [self.inProgressAdder addObserver:self 
        forKeyPath:@"isFinished" 
        options:0 
        context:&self->_formattedTotal
    ];

    [self.queue addOperation:self.inProgressAdder];

    // The user interface is adjusted by a KVO observer on recalculating.

    self.recalculating = YES;
}

- (void)observeValueForKeyPath:(NSString *)keyPath 
    ofObject:(id)object 
    change:(NSDictionary *)change 
    context:(void *)context
{
    if (context == &self->_formattedTotal) {
        AdderOperation *    op;

        // If the operation has finished, call -adderOperationDone: on the main thread to deal 
        // with the results.

        // can be running on any thread
        assert([keyPath isEqual:@"isFinished"]);
        op = (AdderOperation *) object;
        assert([op isKindOfClass:[AdderOperation class]]);
        assert([op isFinished]);

        [self performSelectorOnMainThread:@selector(adderOperationDone:)
            withObject:op 
            waitUntilDone:NO
        ];
    } [...]
}

- (void)adderOperationDone:(AdderOperation *)op
{
    assert([NSThread isMainThread]);

    assert(self.recalculating);

    // Always remove our observer, regardless of whether we care about 
    // the results of this operation.

    [op removeObserver:self forKeyPath:@"isFinished"];

    // Check to see whether these are the results we're looking for. 
    // If not, we just discard the results; later on we'll be notified 
    // of the latest add operation completing.

    if (op == self.inProgressAdder) {
        assert( ! [op isCancelled] );

        // Commit the value to our model.

        self.formattedTotal = op.formattedTotal;

        // Clear out our record of the operation. The user interface is adjusted 
        // by a KVO observer on recalculating.

        self.inProgressAdder = nil;
        self.recalculating = NO;
    }
}

if (op == self.inProgressAdder) {     [... do something with inProgressAdder ...]     self.inProgressAdder = nil; }

@interface AdderOperation : NSOperation
{
    [... instance variables elided ...]
}

- (id)initWithNumbers:(NSArray *)numbers;

// set up by the init method that can't be changed

@property (copy,   readonly ) NSArray *         numbers;
@property (assign, readonly ) NSUInteger        sequenceNumber;

// must be configured before the operation is started

@property (assign, readwrite) NSTimeInterval    interNumberDelay;

// only meaningful after the operation is finished

@property (assign, readonly ) NSInteger         total;
@property (copy,   readonly ) NSString *        formattedTotal;

@end

@interface AdderOperation ()

// only accessed by the operation thread

@property (retain, readwrite) NSNumberFormatter *   formatter;

// read/write versions of public properties

@property (assign, readwrite) NSInteger             total;
@property (copy,   readwrite) NSString *            formattedTotal;

@end

NSOperations Hints and Tips

This section contains a bunch of general hints and tips for using NSOperation.

- (IBAction)buttonAction:(id)sender
{
    #pragma unused(sender)
    [self performSelectorInBackground:@selector(recalculate) withObject:nil];
}

- (void)recalculate
{
    while ( ! self.cancelled ) {
        [... calculate ...]
    }
}

- (void)viewWillDisappear:(BOOL)animated
{
    [super viewWillDisappear:animated];
    self.cancelled = YES;
    // race starts here
}