< Previous PageNext Page > Hide TOC

Creating and Managing Operation Objects

Introduced in Mac OS X v10.5, operation objects and operation queue objects simplify the job of executing multiple, finite tasks in a concurrent manner. Operation objects provide a way for you to encapsulate tasks into distinct objects. Each subclass of NSOperation that you create represents a unique type of task to be performed by your application. When you want to perform one of these tasks, simply create the appropriate operation object and either run it directly or add it to an operation queue.

The encapsulation provided by operation objects makes them a good way to manage your application’s independent tasks. Encasing the data and behavior for a given task inside a single object provides a clean demarcation between that task and the rest of your application. Having individual tasks inside objects also makes it easier to reuse those tasks in other code.

One of the other great benefits of operation objects, though, is the ability to add them to an operation queue. An operation queue manages the execution of operation objects within separate threads of your application. You do not have to write any thread creation or management code to make this happen either. The operation queue takes care of all the thread management work behind the scenes so that you can focus on what you want to run, and not how you want to run it. Operation queues can also manage interoperation dependencies to make sure your tasks execute in the correct order.

The following sections provide background on operation objects and show you how to define custom operation objects and run them with and without an operation queue. Even if you do not plan to run tasks in separate threads, you should consider using operation objects to manage tasks. The encapsulation they provide makes for better code reuse and management over time.

In this section:

About Operation Objects and Operation Queues
Configuration Options for Operation Objects
Defining Operation Objects
Running Operations

About Operation Objects and Operation Queues

Operation objects provide a flexible mechanism for encapsulating the code and data associated with a task. Operation queue objects provide an advanced infrastructure for executing those operations in background threads. Together these objects simplify the steps needed to create background tasks and run them in your application.

Table 2-1 lists the classes associated with implementing and managing operations.

Configuration Options for Operation Objects

The NSOperation class is flexible and supports several different configuration and usage variants. These variants make it possible to design your operation objects in several different ways, depending on your needs. Fortunately, there are simple options if you just want the basic behavior provided by NSOperation, and even the more advanced configuration options do not require large amounts of work.

Table 2-2 lists the basic options for creating your NSOperation object. The overrides column lists the methods you need to override to support each configuration option. You may need to override additional methods, but this column lists the ones you should always override.

The environment in which your operation objects runs depends partly on how you run the operation object and how you have customized that object. Table 2-3 lists the different options for running your operation objects.

Defining Operation Objects

There are two ways to create an operation object: You can subclass NSOperation or create an NSInvocationOperation object to wrap an existing method. Either technique results in essentially the same operation object; the only difference is how you define the task. The following sections show you how to use operation objects to implement tasks and how you configure those objects for execution.

Using an NSInvocationOperation Object

The NSInvocationOperation class is a concrete subclass of NSOperation that, when run, invokes a selector on the object you specify. You might use this class as a convenient way to define operation objects without having to subclass NSOperation. For example, if your application uses operations to perform a large number of tasks, you might not want to define separate operation objects for each. Instead, you could use NSInvocationOperation to create tasks out of existing methods. You might also use this class when the task you need to perform is determined more dynamically. In such a case, each potential task could be associated with a different selector that you use to create the resulting operation object.

Listing 2-1 shows a custom class that creates a new NSInvocationOperation object and adds it to the application’s shared operation queue. The operation queue in this example is accessed through a custom method of the application delegate, but you could create the operation queue anywhere in your application. Once added to the queue, the operation runs automatically in a background thread until it completes or is explicitly cancelled.

Listing 2-1  Creating a task with NSInvocationOperation

@implementation MyCustomClass

- (void)launchTaskWithData:(id)data

{

    NSInvocationOperation* theOp = [[NSInvocationOperation alloc] initWithTarget:self

                    selector:@selector(myTaskMethod:) object:data];

    // Add the operation to the internal operation queue managed by the application delegate.

    [[MyAppDelegate sharedOperationQueue] addOperation:theOp];

}

// This is the method that does the actual work of the task.

- (void)myTaskMethod:(id)data

{

    // Perform the task.

}

@end

Defining a Simple NSOperation Subclass

If you want a more explicit separation between your general application code and your task-specific code, you can subclass NSOperation directly to implement your tasks. When you subclass NSOperation, you put all of your task-based code, along with the data needed to implement that task, into your subclass. If all of the data belongs to the operation object, you can avoid synchronization issues. Even in situations where an operation does use a shared object, you now have the option of taking locks at the operation object level, where doing so might be more efficient.

To define a minimal operation object, create a new subclass of NSOperation, add whatever instance variables you need to your subclass, and implement the following methods:

• a custom initialization method

• the main method

In general, you should use a custom initialization method to configure your operation object as much as possible. If you define accessor methods for instance variables and plan to call those methods from other threads, be sure to employ some sort of synchronization to prevent thread-safety issues. Better yet, avoid accessing member variables from multiple threads entirely. Instead, just set the variables from a single thread at initialization time and read them back only after the operation finishes.

The actual implementation of your task goes inside the main method. This method is defined by NSOperation but the default implementation does nothing. Your implementation of this method should perform the desired task and then notify any interested clients when the results are ready. The notification process can vary depending on your needs. You can use an actual notification object, set a flag, send a message to the main thread using one of the perform selector routines of NSObject, or you can have interested clients register for KVO notifications on your object’s isFinished property.

If your task is long-lived—that is, it takes more than a few milliseconds to execute—your main method should periodically check to see if the operation was cancelled. You do this by calling the isCancelled method of your operation object. If this method ever returns YES, your main method should immediately stop what it is doing and exit, leaving any pending calculations unfinished. The exact amount of time you should wait between calls to isCancelled depends entirely on how responsive you want your task to be. If the task can be programmatically terminated, you might want to call this method more frequently. If it can only be cancelled by the user, once every millisecond is probably sufficient, but more frequently would be even better.

To run your operation, create a new instance and add it to an operation queue as described in “Using a Queue to Run Operations.” For additional options on how to run your operation, see “Running an Operation Object Directly.”

Configuring Dependencies Among Operation Objects

Dependencies define the relationships between operation objects. You use dependencies in your application to enforce a specific execution order for your operations. When you add a dependency to an operation object, you prevent that operation object from starting until the dependent operation has finished. For example, you might use a dependency to prevent one operation from starting until the data it needed was generated by a different operation object.

To establish dependencies between operations, use the addDependency: method. To remove dependencies, use the removeDependency: method. You can add as many dependencies as you want to a given operation, but it is a programmer error to create circular dependencies.

Dependencies rely on each operation object sending out appropriate KVO notifications whenever the status of the object changes. If you customize the behavior of your operation objects, you may need to generate appropriate KVO notifications from your custom code to avoid causing issues with dependencies. For more information on KVO notifications and operation objects, see “Maintaining KVO Compliance.” For additional information on configuring dependencies, see NSOperation Class Reference.

Customizing the Execution Environment of an Operation Object

The default runtime environment for operations is a thread. If you run an operation from an operation queue, the NSOperationQueue object creates a new thread and runs the operation in it. If you run an operation directly, the operation runs in the current thread. Threads are not the only environment you can use in conjunction with operations, however. Through customization, it is possible to configure a custom environment.

The NSOperation class itself is simply an abstraction for a task. It does not matter how that task is executed. What is important is the encapsulation that the class provides. You could create an operation object that performs its task by launching a separate process or by calling an asynchronous function and handling the resulting callback. Both of these options are perfectly acceptable and might not involve threads at all.

The following sections show how to modify an operation object to use a different runtime environment or use a slightly modified version of the existing thread environment.

Configuring a Custom Runtime Environment

Configuring an operation object to use a different environment involves override the following methods at a minimum:

• isConcurrent

• start

The implementation of your isConcurrent method is pretty simple. Override it and return YES to let Cocoa know that the operation object configures its own runtime environment.

The start method is where you configure your environment and run your task. In the case of launching a separate process, you might fork and exec the process here, set up a communications channel for receiving the results, and exit. Similarly, in the case of calling an asynchronous function, you would call the function and exit. The key part to both of these techniques is that after setting up the environment, you start the task and then exit from the start method. You do not want your start method to block the current thread, because as strange as it might sound, Cocoa executes concurrent tasks on the current thread. The “concurrency” in this case is provided by you when you set your task in motion and exit.

Of course, the end of your start method does not imply that your task is finished or that your work is done. Another job of your customized NSOperation object (and your start method in particular) is to generate KVO notifications about the current execution status of the operation. In your start method, this means generating change notifications for the isExecuting property. Your start method must do this. Once your task completes (or is cancelled), your operation object must generate another notification for the isExecuting property and another notification for the isFinished (or isCancelled) property.

Listing 2-2 shows the implementation of a simple operation class that forks a process and waits for it to exit. The start method of the operation object creates the NSTask object, registers for the NSTaskDidTerminateNotification notification, launches the task, and exits. Receipt of the notification results in the finalization of the task, which generates the final KVO change notifications. Because the class maintains its own instance variables for the isExecuting and isFinished properties, the implementation of the class also provides overrides of the corresponding accessor methods.

Listing 2-2  Using an operation object to launch a process

@interface TaskOperation : NSOperation {

    NSTask*     task;

    BOOL        executing;

    BOOL        finished;

}

- (void)handleTaskExitedNotification:(NSNotification*)aNotification;

@end

@implementation TaskOperation

- (id)init {

    self = [super init];

    if (self){

        executing = NO;

        finished = NO;

        task = nil;

    }

    return self;

}

- (BOOL)isConcurrent {

    return YES;

}

- (void)start {

    // Create the NSTask object.

    task = [[NSTask alloc] init];

    [task setLaunchPath:@"/usr/bin/myCustomTool"];

    [[[NSApplication sharedApplication] delegate] registerNotifications];

    [[NSNotificationCenter defaultCenter] addObserver:self

            selector:@selector(handleTaskExitedNotification:)

            name:NSTaskDidTerminateNotification

            object:task];

    // If the operation hasn't already been cancelled, launch it.

    if (![self isCancelled]) {

        [self willChangeValueForKey:@"isExecuting"];

        executing = YES;

        [task launch];

        [self didChangeValueForKey:@"isExecuting"];

    }

}

- (void)handleTaskExitedNotification:(NSNotification*)aNotification {

    [self willChangeValueForKey:@"isFinished"];

    [self willChangeValueForKey:@"isExecuting"];

    finished = YES;

    executing = NO;

    // Clean up.

    [[NSNotificationCenter defaultCenter] removeObserver:self

            name:NSTaskDidTerminateNotification

            object:task];

    [task release];

    NSLog(@"Task exit notification received successfully.\n");

    [self didChangeValueForKey:@"isExecuting"];

    [self didChangeValueForKey:@"isFinished"];

}

- (BOOL)isExecuting {

    return executing;

}

- (BOOL)isFinished {

    return finished;

}

@end

As with other operation objects, your code should call the isCancelled method whenever possible to determine whether the operation has been cancelled. If the method ever returns YES, you should abort the current task and set both the isExecuting and isFinished properties to NO.

Maintaining KVO Compliance

The NSOperation class is KVO compliant for the following properties:

• isCancelled

• isConcurrent

• isExecuting

• isFinished

• isReady

• dependencies

• queuePriority

If you override the start method or do any other significant customization of an NSOperation object, other than override main, you must ensure that your custom object remains KVO compliant for these properties. For custom operation objects, the properties you should be most concerned with are the isExecuting and isFinished properties. These are the properties most commonly affected by implementing a custom start method.

If your custom operation object also manages its own set of custom dependencies, you should also add KVO notifications for the isReady property. You should also override the isReady method and force it to return NO until your custom dependencies were satisfied. (Be sure to call super if you also support the default dependency management of NSOperation .) Unless you override the addDependency: or removeDependency: methods, you should not need to worry about the dependencies property.

Although you could generate KVO notifications for other properties of NSOperation, it is unlikely you would ever need to do so. If you need to cancel an operation, you can simply use the existing cancel method to do so. Similarly, there should be little need for you to modify the queue priority information in an operation object. Finally, unless your operation is capable of changing its concurrency status dynamically, you do not need to provide KVO notifications for the isConcurrent property.

For an example that shows how to generate KVO notifications for the isExecutable and isFinished properties, see Listing 2-2.

Responding to Errors

If your operation object is unable to perform its task for some reason, it is your responsibility to make that determination and generate the appropriate errors. Similarly, if your operation object is dependent on other operations that may fail, it is also your responsibility to respond to potential errors and abort the current operation as needed.

Operation objects that are not concurrent (that is, their isConcurrent method returns NO) automatically catch and suppress any exceptions thrown by the operation object’s main method. Thus, an operation that generates an exception may appear to finish normally even if it did not. If an operation may fail, it is up to you to provide a way for dependent operations to determine that an error occurred and do something about it. For example, you might want to provide a custom method for reporting whether the operation completed successfully. The isReady method of dependent operation objects could then call this method and use it to determine whether it is safe to execute.

Running Operations

Once you have an operation object, you need to know how to run it. There are two ways to run an operation object: directly or from an operation queue. The following sections show you how to use both of these options.

Using a Queue to Run Operations

By far, the easiest way to run an operation is to add it to an operation queue. The NSOperationQueue class defines the basic interface for managing operation objects within an application. An operation queue is typically a long-lived object—that is, you create it and keep it around for the lifetime of your application. An application can create any number of operation queues, although one is usually sufficient.

To run an operation, all you have to do is add that operation to a queue using the addOperation: method, as shown in Listing 2-3. This method gets the application’s shared queue object and adds the specified operation to it.

Listing 2-3  Adding an operation to a queue

- (void)myQueueUpOperation:(NSOperation*)theOp

{

    // Get the custom queue object from the app delegate.

    NSOperationQueue* myQueue = [[[NSApplication sharedApplication] delegate] myOperationQueue];

    [myQueue addOperation:theOp];

}

In most cases, operations are run shortly after they are added to an operation queue. The operation queue may delay execution of an operation for any of several reasons, however. Specifically, an operation may be delayed if it is dependent on other operations that have not yet completed. It may also be delayed if the operation queue determines that there are not enough system resources to run it.

Operation queues try to balance the available system resources with the amount of work that needs to be done. Rather than spawn a number of operations and let them vie for processor time, operation queues work with the kernel to run as many operations as possible while still using the available processor cores efficiently. The maximum number of simultaneous operations typically matches the number of available cores. If the system load is particularly heavy or several cores are dedicated to other tasks, however, the operation queue may run fewer operations.

If you want to remove an operation from a queue before it completes its task, you must cancel it. You can cancel individual operation objects by calling their cancel method or you can cancel all of the operation objects in a queue by calling the cancelAllOperations method of the queue object. You should cancel only operations that you no longer need to perform. Issuing a cancel command puts the operation object into the “cancelled” state, which prevents it from being run again.

For information about using operation queues, see NSOperationQueue Class Reference.

Running an Operation Object Directly

It is possible to run operation objects directly and not use an operation queue. You might do so in cases where you want to run it either from the current thread or from a different thread. Or you might simply want to manage the execution of operations yourself without an operation queue.

To run an operation object directly, all you have to do is create the object, make sure it is ready, and then call its start method. It is important that an operation object is ready before you attempt to run it. The isReady method of NSOperation reports on the readiness of the operation, checking to make sure that any dependent operations have already finished. Once that method returns YES, you can call the start method to run the operation in the current thread.

< Previous PageNext Page > Hide TOC