Getting Ready For The Image

The focus of this tutorial is Core Animation and specifically how to use a QTMovieLayer as well as animating an image across the screen using a CALayer. I, therefore, will not spend any time addressing NSOperation and I think we’ve covered this adequately on this site. I would suggest, however, that you familiarize yourself with Marcus’ post on NSOperation as he discusses calling back into the main thread once the NSOperation has completed. I employ Marcus’ technique in this project so that I can be notified when the image I’m wanting to animate is ready.

You can download the demo project for this post from here: Movie Image Flick Demo Project

Download the project and run it. It will prompt you to select a QuickTime movie to play. Once the movie starts playing, tap your spacebar and watch the images pop off of the movie and animate to random places on the screen. Tap the spacebar quickly to see the effect work in rapid succession.

As in my NSOperation post, I want the video playback to be completely flicker free. I achieve this by obtaining a reference to a copy of the QTMovie object from which I obtain the image at the given time. If you take a look at my main: function in my NSOperation derived class, you’ll see how I am notifying the main thread that it may now do something with the image I’ve obtained.

ImageGrabber.m:main

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

- (void)main;
{
    if( movie )
    {
        NSImage* image;
        image = [movie frameImageAtTime:time 
                      withAttributes:imageAttrs error:nil];
        [image retain];
 
        [[AppDelegate shared] performSelectorOnMainThread:@selector(imageReady:)
                                               withObject:image
                                            waitUntilDone:YES];
        [image release];
    }
 
}

In the second last line of the function, notice I am calling back into my main thread and letting the app delegate know that the image is ready. I am also handing the image to the imageReady: function. This is very convenient for what we need to do next. But first, let’s discuss drawing the layers with no backing view or window.

Drawing Layers In Thin Air

This project employs a trick that makes it appear as if the layers are being drawn without a backing view. This is, of course, not really possible, so instead we do a little trick. I achieved this effect by creating a borderless window with a transparent background. As usual, I want to give credit where credit is due. Lucas Newman answered a question I posted on Scott Stevenson’s blog to find out how Lucas did this in his demo project a the Silicon Valley CocoaHeads meeting on Core Animation. You simply create your own NSWindow derived class and override the initWithContentRect: method. Here is the resulting initialization code I came up with from his suggestion.

BorderlessWindow.m:initWithContentRect

1
2
3
4
5
6
7
8
9
10
11
12
13
14

- (id) initWithContentRect: (NSRect) contentRect
                 styleMask: (unsigned int) aStyle
                   backing: (NSBackingStoreType) bufferingType
                     defer: (BOOL) flag
{
    if (![super initWithContentRect: contentRect 
                 styleMask: NSBorderlessWindowMask 
                   backing: bufferingType 
                   defer: flag]) return nil;
    [self setBackgroundColor: [NSColor clearColor]];
    [self setOpaque:NO];
 
    return self;
}

The only issue with using a transparent backing window/view is that you cannot click through it even though it looks like you ought to be able to. There is probably a way to pass the click on to the next front most window, but I haven’t yet researched this. I’ll let you know when I find the answer, or if you know the answer, post it in the comments.

Rapid Fire Image Animation

I created a method to initialize my NSOperation derived objects and hand them off to the NSOperationQueue. I hooked it up to the spacebar and can then tap the spacebar as quickly as possible and watch the images just pop off the playing movie. Here is my flickIt: function.

AppDelegate.m:flickIt

1
2
3
4
5
6
7
8
9
10
11
12

- (IBAction)flickIt:(id)sender;
{
    ImageGrabber *grabber = [[ImageGrabber alloc] init];
 
    [grabber setTime:[movie currentTime]];
    // Hand off the background movie to the NSOperation derived
    // object
    [grabber setMovie:movieBak];
 
    // Add the oepration to the queue. It will be run immediately.
    [queue addOperation:grabber];
}

This function creates the NSOpeartion derived objects and passes a reference to the current time in the playing movie as well as a reference to the background movie that I use to pull the image data from. Remember that this object is copied from the original QTMovie object and is used to keep from needing to pull the image data from the QTMovie object that is actually playing in the QTMovieLayer. Pulling the image from the QTMovie object that is being used for playback would cause the playback to stutter.

As stated earlier, when my image is ready, the NSOperation derived object, ImageGrabber, calls back into the main thread calling the function called imageReady:. Here is its implementation.

AppDelegate.m:imageReady

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

- (void)imageReady:(NSImage*)image;
{    
    [[NSAnimationContext currentContext] setDuration:1.5f];
 
    // Save off the rectangle of the ready layer before
    // it gets animated. We will use this to reset the
    // ready layer.
    CGRect prevRect = [readyLayer frame];
 
    // Convert the NSImage to a CGImageRef
    CGImageRef imageRef = [self nsImageToCGImageRef:image];
    CFRetain(imageRef);
    readyLayer.contents = (id)imageRef;
    readyLayer.backgroundColor = CGColorCreateGenericRGB(0.0f,0.0f,0.0f,1.0f);
    readyLayer.borderColor = CGColorCreateGenericRGB(0.45f,0.45f,0.45f,1.0f);
    readyLayer.borderWidth = 4.0f;
 
    // Grab a random rectangle on the screen where our image
    // layer will animate to.
    CGRect randRect = [self getRandomRect:prevRect];
    [readyLayer setFrame:randRect];
    [readyLayer setOpacity:1.0f];
 
    // Reset the ready layer so that it is ready for the next image
    readyLayer = [[[CALayer alloc] init] retain];
    readyLayer.frame = prevRect;
    readyLayer.opacity = 0.01f;
 
    [[[window contentView] layer] addSublayer:readyLayer];
}

Notice that we are converting the NSImage that gets passed to this function into a CGImageRef which is what our Core Animation layer requires to set it contents. Here is the code to convert an NSImage to a CGImageRef.

AppDelegate.m:nsImageToCGImageRef

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

- (CGImageRef)nsImageToCGImageRef:(NSImage*)image;
{
    NSData * imageData = [image TIFFRepresentation];
    CGImageRef imageRef;
    if(imageData)
    {
        CGImageSourceRef imageSource = 
                     CGImageSourceCreateWithData(
                           (CFDataRef)imageData,  NULL);
 
        imageRef = CGImageSourceCreateImageAtIndex(
                          imageSource, 0, NULL);
    }
    return imageRef;
}

Preloading A Layer to Animate

Instead of creating the layer, setting its contents, and then animating it all at once, I instead set an empty layer with a near zero opacity to overlay the QTMovieLayer when the movie first loads. Then, when the user taps the spacebar, I populate that invisible layer’s contents with the image data and then animate it. This keeps me from having to create a more complicated animation to get the desired effect.

Once the image layer has it’s new frame set, I re-initialize the ready layer. You see the ready layer get reset with this code from the imageReady: function.

1
2
3
4
5
6

// Reset the ready layer so that it is ready for the next image
readyLayer = [[[CALayer alloc] init] retain];
readyLayer.frame = prevRect;
readyLayer.opacity = 0.01f;
 
[[[window contentView] layer] addSublayer:readyLayer];

Note: I set the opacity to near zero as when it is set to zero it won’t animate the opacity change properly. I’m looking into why this is and will update this post with what I find when I find it.

 

Random Points

When I animate the layers, I simply grab a random point and the screen and then scale the image down to 35% of the original. When I call setFrame: the magic ensues and my screen gets really cluttered with lots of images. As I said before, not very useful, but excellent. Here is the random rectangle calculation function, getRandomRect:.

AppDelegate.m:getRandomRect

1
2
3
4
5
6
7
8
9
10

- (CGRect)getRandomRect:(CGRect)startRect;
{    
    CGPoint point = CGPointMake(random() % 
                          (NSUInteger)NSWidth([window frame]), 
                          random() % 
                           (NSUInteger)NSHeight([window frame]));
 
    return CGRectMake(point.x, point.y, 
                 startRect.size.width * 0.35f, startRect.size.height * 0.35f);
}

Conclusion

The nuances of Core Animation are quite interesting and provide a fun challenge when trying to solve problems. In other words, the devil is in the details. There is probably a better way to achieve the animation code, but I felt that the solution I came up with here works pretty well. There are details about Core Animation that I am still learning, but this type of effect demonstrates exactly the kinds of interesting things that are possible.

In his post, Marcus introduced how to use NSOperation to greatly simplify multi-threading tasks in your application. I am now going to provide a step-by-step walk-through sample application that uses NSOperation, NSOperationQueue, and QTKit.

While looking around the Internet, I noticed that the only examples of using NSOperation available were related to scientific applications. I wanted something that I could relate to a little better and since I’ve been working with QTKit a lot lately, I figured it would be a good framework to build from. This application simply grabs images of a movie while it is playing back and saves them out to a file. It’s pretty simple, but it shows how to do something fairly practical.

Grabbing Movie Image Frames

The application displays a movie and provides a button for the user to click whenever the user wants to save the current frame of the movie to disk while it is playing. Here are some basic requirements I’ve given the app.

• Images are only saved when the movie is playing back
• Clicking the button and the subsequent saving of the current image must not cause the movie to flicker
• Clicking in rapid succession should not cause the application to crash. For each click, a new task (operation) should be generated

Here is a screenshot of the final application.

Follow along in XCode to create the application called QT Image Grab or download the sample project here.

Note If you are already comfortable with setting up an AppDelegate class and making connections in Interface Builder, you can jump down to the section titled Derive A Class From NSOperation

Create The Application

Create a Cocoa Application Using the following steps:

1. Select File > New Project… and choose Cocoa Application in the ensuing dialog. Click Next
2. Enter ‘QTImageGrab’ as the project name. Click Finish

You should see a project workspace like the following:

Create A Controller/Delegate Class

The next thing you need to do is create an application controller, or delegate. To do so, use the following steps:

1. Option-Click on the Classes folder in your workspace and select ‘Add File…’
2. Choose Object-C Class in the ensuing dialog and click Next
3. Name the file ‘AppDelegate.m’ and click Finish
4. A new code window will display with your ‘AppDelegate’ interface code (.h file). Edit the code so that it looks like this:

   1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18

   #import <Cocoa/Cocoa.h> #import <QTKit/QTKit.h> #import <QuartzCore/CoreAnimation.h>   @interface AppDelegate : NSObject { IBOutlet QTMovieView *movieView; IBOutlet NSTextField *outputPath; IBOutlet NSWindow *window;   NSOperationQueue *operationQueue; QTMovie *imagesMovie; }   - (IBAction)grab:(id)sender; - (IBAction)openMovie:(id)sender; - (IBAction)selectOutputDir:(id)sender;   @end

5. Now we need to add the QTKit framework to your project. Option-Click the Frameworks folder in your project and select Add > Existing Frameworks… In the ensuing dialog, navigate to /System/Library/Frameworks and select QTKit.framework. Click Add
6. Now switch over to your implementation file for ‘AppDelegate’ (.m file). Add the implementation code so that the file looks like this:
   

   1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31

   @implementation AppDelegate   - (void)awakeFromNib; { // We're going to add some initialization code here }   - (IBAction)grab:(id)sender; { // This is where will will start the process for grabbing the current image.   }   - (IBAction)openMovie:(id)sender; { // Here we load our movie using an open panel dialog.   }   - (IBAction)selectOutputDir:(id)sender; { // Here we will select an output directory where the current frame // image will be saved to. }   - (void)dealloc; { // We're going to have some cleanup to do. }   @end

   
   We will actually add some code to do something in each of these methods shortly, but first we need to hook it up to the user interface in Interface Builder.

Make The Interface Builder Connections

Now that we’ve specified all of our actions and outlets in the AppDelegate code, let’s make the connections in our NIB file. To do so, use the following steps.

1. In the tree view of your project in XCode, expand the smart folder labeled NIB Files and double click the file called MainMenu.nib Interface Builder will load the NIB file.
2. In Interface Builder click and drag an NSObject from the Library palette into your NIB file and rename the object to AppDelegate as shown:
3. With the AppDelegate selected, select Tools > Inspector from the menu bar. In the inspector, select the Object Identity tab (tab 6) and in the Class field, enter AppDelegate.
4. Now we need to tell our application to use the AppDelegate object as its delegate. Control-Click on the File’s Owner object in the MainMenu.nib window and drag a connection to the AppDelegate object and select delegate in the ensuing pop-up menu.
5. All we have left now is to drag the controls onto the window and connect the actions and outlets. Edit the main window dragging controls to it so as to make it look like this. Note: The black area of the window is a QTMovieView which you’ll be able to find in the object library. It’s dimensions are set to a standard DV video format of 720 x 480 pixels.
6. Drag a connection (Control-Click) from the Grab button to the AppDelegate and select grab: from the dropdown.
7. Drag a connection from the File | Open… menu item to the AppDelegate and select openMovie: from the dropdown.
8. Drag a connection from the Select Output Folder Path button to the AppDelegate and select selectOutputDir: from the dropdown.
9. Drag a connection from the AppDelegate object to the Output Folder Path text field and select the outputPath NSTextField from the dropdown.
10. Drag a connection from the AppDelegate object to the QTMovieView and select movieView from the dropdown.

Now we are finished in Interface Builder. Let’s return to XCode and start populating our event handlers with code. Don’t forget to save your NIB file in Interface Builder.

Adding Event Handling Code

For most of our event handlers, you can simply copy and paste the code from this section as their use is simply to set up the application and not directly related to the use of NSOperation or NSOperationQueue.

- (void)awakeFromNib

1
2
3
4
5

- (void)awakeFromNib;
{
    // Initialize the queue
    operationQueue = [[NSOperationQueue alloc] init];
}

- (IBAction)selectOutputDir:(id)sender;

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

- (IBAction)selectOutputDir:(id)sender;
{
    NSOpenPanel *openPanel;
 
    openPanel = [NSOpenPanel openPanel];
    [openPanel setCanChooseDirectories:YES];
    [openPanel setAllowsMultipleSelection:NO];
    [openPanel setResolvesAliases:YES];
    [openPanel setCanChooseFiles:NO];
 
    if ([openPanel runModalForTypes:nil] == NSOKButton)
    {
        NSString *directory = [openPanel directory];
        [outputPath setStringValue:directory];
    }
 
}

- (void)dealloc

1
2
3
4
5
6

- (void)dealloc;
{
    [super dealloc];
    if( imagesMovie )
        [imagesMovie release];
}

There are two other event handlers that we need to fill in, but they will require a little bit of explanation, so first let’s go and create our NSOpeation derived class that will do all of the work we need.

Derive A Class From NSOperation

In our application, we want to get the current image of the movie while it is playing back and save it out to disk. This is the operation that we want our NSOoperation to complete in a separate thread. In order to do this, we need to create a new Objective-C class that derives from NSOperation. To do so, complete the following steps.

1. In the XCode treeview, Option-Click the Classes folder and select Add | New File…. In the ensuing dialog, select Objective-C Class and click next. Enter the name ‘GragQTImageOperation.m’ making sure that Also create “GrabQTImageOperation.h” is checked and click Finish
2. In the header file for the new Objective-C class you just created, change the interface so that our object inherits from NSOperation.

   1 2 3

   @interface GrabQTImageOperation : NSOperation {   }

Give Our NSOperation Something To Do

Our new class now needs some objects to work with and a method to do the work. To do work, an NSOperation derived class, must override the method called main:. Edit the file GrabQTImageOperation.m and provide the following function declaration.

1
2
3
4

- (void)main
{
 
}

In order to do the work, we need the following objects:

• QTMovie*: a pointer to a QTMovie view from which we will obtain our image to save.
• NSDictionary*: a dictionary to hold our attributes we will use when exporting to an image format
• NSLock*: a lock object to synchronize access to our QTMovie object.
• NSString*: a pointer to the output folder path we will use to save the files to.
• QTTime: a QTTime object representing the point in time as the movie was playing at which the grab button was clicked.

Change the GrabQTImageOperation header file to look like this.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

#import <Cocoa/Cocoa.h>
#import <QTKit/QTKit.h>
 
@interface GrabQTImageOperation : NSOperation {
    QTMovie* movie;
    NSDictionary *imageAttrs;
    NSLock *lock;
    NSString *outputPath;
    QTTime time;
 
}
 
@property (assign) QTMovie *movie;
@property (assign) NSString *outputPath;
@property (assign) QTTime time;
 
- (void)main;
- (void)saveImage:(NSImage*)image;
@end

The method saveImage: actually saves the image to disk. Go ahead and add its declaration in the header as shown above. We’ll get back to that in a minute.

Implement main:

Now we need to switch to our implementation file (GrabQTImageOperation.m) and enter the following code into the main: function.

1
2
3
4
5
6
7
8
9
10
11

- (void)main
{
    if( movie )
    {
        NSImage* image;
        [lock lock];
        image = [movie frameImageAtTime:time withAttributes:imageAttrs error:nil];
        [lock unlock];
        [self saveImage:image];
    }
}

All we are doing at this point is getting the image at the specified time from our QTMovie reference and passing it on to our saveImage: method. Now fill we can populate the rest of the methods with the code we need to finish our NSOperation derived class.

- (id)init

1
2
3
4
5
6
7
8
9
10
11

- (id)init
{
    lock = [[NSLock alloc] init];
    // Specify that we want to save out a high-quality image.
    imageAttrs = [NSDictionary dictionaryWithObjectsAndKeys:
                       QTMovieFrameImageTypeNSImage, QTMovieFrameImageType,
                       [NSNumber numberWithBool:YES], QTMovieFrameImageHighQuality, nil];
    [imageAttrs retain];
    [super init];
    return self;
}

- (void)saveImage:(NSImage*)image

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

- (void)saveImage:(NSImage*)image;
{
    NSArray *representations;
    NSData *bitmapData;
 
    representations = [image representations];
 
    // Specify that we want to save the file as a JPG
    bitmapData = [NSBitmapImageRep representationOfImageRepsInArray:representations 
                                usingType:NSJPEGFileType 
                                properties:[NSDictionary dictionaryWithObject:[NSDecimalNumber numberWithFloat:1.0] 
                                forKey:NSImageCompressionFactor]];
 
    // Creates a long filename, but at least it's unique.
    NSString *filename = [[NSProcessInfo processInfo] globallyUniqueString];
    filename = [filename stringByAppendingString:@".jpg"];
    NSString *imgOut = [outputPath stringByAppendingString:@"/"];
    imgOut = [imgOut stringByAppendingString:filename];
    [bitmapData writeToFile:imgOut  atomically:YES];
}

And finally, don’t forget to add our synthesize calls at the top of the implementation.

1
2
3
4
5
6
7

@implementation GrabQTImageOperation
 
@synthesize movie;
@synthesize time;
@synthesize images;
@synthesize outputPath;
...

Finish Implementing AppDelegate

Now that we’ve finished creating our NSOperation derived class, we can finish the implementation of our AppDelegate. First add the following code to the openMovie: event handler.

- (IBAction)openMovie:(id)sender

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

- (IBAction)openMovie:(id)sender;
{
    NSOpenPanel *openPanel;
 
    openPanel = [NSOpenPanel openPanel];
    [openPanel setCanChooseDirectories:NO];
    [openPanel setAllowsMultipleSelection:NO];
    [openPanel setResolvesAliases:YES];
    [openPanel setCanChooseFiles:YES];
 
    if ([openPanel runModalForTypes:nil] == NSOKButton)
    {
        NSArray *filesToOpen = [openPanel filenames];
        NSString *theFilePath = [filesToOpen objectAtIndex:0];
        QTMovie *movie = [QTMovie movieWithFile:theFilePath error:nil];
        imagesMovie = [QTMovie movieWithFile:theFilePath error:nil];
        [imagesMovie retain];
        [movieView setMovie:movie];		
    }
 
}

Take note of these two lines:

1
2

QTMovie *movie = [QTMovie movieWithFile:theFilePath error:nil];
imagesMovie = [QTMovie movieWithFile:theFilePath error:nil];

Notice that we are loading the same movie into memory twice. The first is for the object called movie which will be used in our QTMovieView for actual movie playback. The other movie is an instance variable called imagesMovie which will act as a background movie. It will be passed to our NSOperation derived class and it is the object from which the images will be obtained for saving to disk.

We use two movie objects representing the same file on disk in order to satisfy one of our requirements which was to ensure that the movie doesn’t flicker or stutter when the operation is happening. One movie reference is for display, the other for processing.

And finally, we now need to populate our grab: method which initializes our NSOperation derived objects and passes them off to the NSOperationQueue which runs them immediately. First, we need to import our header file at the top of AppDelegate.h like this:

1

#import "GrabQTImageOperation.h"

And now, here is the implementation of grab: in AppDelegate.m.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

- (IBAction)grab:(id)sender;
{
    NSString *path = [outputPath stringValue];
    if( !path || [path length] <= 0 )
    {
        NSAlert *alert = [NSAlert alertWithMessageText:@"Set Output Directory" defaultButton:@"OK" alternateButton:nil otherButton:nil informativeTextWithFormat:@"You must first select an output directory before grabbing images."];
 
        [alert beginSheetModalForWindow:window
            modalDelegate:self
            didEndSelector:nil
            contextInfo:NULL];
 
        return;
    }
 
    // Check to see if the movie is playing	
    if( [[movieView movie] rate] > 0.0f )
    {
        // If so, create our NSOperation derived object and hand it off to the queue
        GrabQTImageOperation *op = [[GrabQTImageOperation alloc] init];
        [op setMovie:imagesMovie];
        [op setTime:[[movieView movie] currentTime]];
        [op setOutputPath:path];
 
        // As soon as this method finishes, the operation is set to work
        [operationQueue addOperation:op];
    }
}

The first thing we do is make sure our output path is set. If it is not, we alert the user and return. Otherwise, we check to see if our movie is playing by checking the movie’s current rate. If it is playing, then we are going to spin off one of our new GrabQTImageOperation objects to grab the image at the currentTime. Once we hand the image operation off to the NSOperationQueue we can watch the specified folder in the Finder and images will start to display.

To see the application run, click Build and Go

Conclusion

Developing with NSOperation and NSOperationQueue is a very pleasant experience to me so far. This was a fun application to build and the results are quite pleasing. I was able to achieve all of my project requirements with very little effort. It’s a great addition to the toolset now available in OS X 10.5 Leopard.

Fortunately, Apple has made a lot of progress in OS X 10.5 Leopard. NSThread itself has received a number of very useful new methods that make threading easier. In addition, they have introduced two new objects: NSOperation and NSOperationQueue. In this Tutorial I will walk through a basic example that shows how to use these new Objects and how they make multi-threading your application nearly trivial.

You can get the example project here: Async Downloader Example Project

In this tutorial, I will demonstrate one way in which to use NSOperation and NSOperationQueue to handle tasks that are best performed on background threads. The intent of this tutorial is to demonstrate a basic use of these classes and is not intentioned to be the only way to use them.

If you are familiar with Java, or one of its variants, the NSOperation object is very similar to the java.lang.Runnable interface. Like, in Java’s Runnable interface, the NSOperation object is designed to be extended. Also like Java’s Runnable, there is a minimum of one method to override. For NSOperation that method is -(void)main. One of the easiest ways to use an NSOperation is to load it into an NSOperationQueue. As soon as the operation is loaded into the queue, the queue will kick it off and begin processing. As soon as the operation is complete the queue will release it.

NSOperation Example

In this example, I have written an NSOperation that fetches a webpage as a string, parses it into an NSXMLDocument and then passes that NSXMLDocument back to the main thread in the application before completing.

PageLoadOperation.h

1
2
3
4
5
6
7
8
9
10
11
12

#import <Cocoa/Cocoa.h>
 
 
@interface PageLoadOperation : NSOperation {
    NSURL *targetURL;
}
 
@property(retain) NSURL *targetURL;
 
- (id)initWithURL:(NSURL*)url;
 
@end

PageLoadOperation.m

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38

#import "PageLoadOperation.h"
#import "AppDelegate.h"
 
@implementation PageLoadOperation
 
@synthesize targetURL;
 
- (id)initWithURL:(NSURL*)url;
{
    if (![super init]) return nil;
    [self setTargetURL:url];
    return self;
}
 
- (void)dealloc {
    [targetURL release], targetURL = nil;
    [super dealloc];
}
 
- (void)main {
    NSString *webpageString = [[[NSString alloc] initWithContentsOfURL:[self targetURL]] autorelease];
 
    NSError *error = nil;
    NSXMLDocument *document = [[NSXMLDocument alloc] initWithXMLString:webpageString 
                                                              options:NSXMLDocumentTidyHTML 
                                                                error:&error];
    if (!document) {
        NSLog(@"%s Error loading document (%@): %@", _cmd, [[self targetURL] absoluteString], error);
        return;
    }	
 
    [[AppDelegate shared] performSelectorOnMainThread:@selector(pageLoaded:)
                                           withObject:document
                                        waitUntilDone:YES];
    [document release];
}
 
@end

As you can see, this class is very simple. It accepts a URL in the init and stores it. When the main method is called it constructs a string from the URL and then passes that string into the init of an NSXMLDocument. If there is no error with the loading of the xml document, it is then passed back to the AppDelegate, on the main thread, and the task is complete. When the main method of the NSOperation ends the queue will automatically release the object.

AppDelegate.h

1
2
3
4
5
6
7
8
9
10

#import <Cocoa/Cocoa.h>
 
@interface AppDelegate : NSObject {
	NSOperationQueue *queue;
}
 
+ (id)shared;
- (void)pageLoaded:(NSXMLDocument*)document;
 
@end

AppDelegate.m

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58

#import "AppDelegate.h"
#import "PageLoadOperation.h"
 
@implementation AppDelegate
static AppDelegate *shared;
static NSArray *urlArray;
 
- (id)init
{
    if (shared) {
        [self autorelease];
        return shared;
    }
    if (![super init]) return nil;
 
    NSMutableArray *array = [[NSMutableArray alloc] init];
    [array addObject:@"http://www.google.com"];
    [array addObject:@"http://www.apple.com"];
    [array addObject:@"http://www.yahoo.com"];
    [array addObject:@"http://www.zarrastudios.com"];
    [array addObject:@"http://www.macosxhints.com"];
    urlArray = array;
 
    queue = [[NSOperationQueue alloc] init];
    shared = self;
    return self;
}
 
- (void)applicationDidFinishLaunching:(NSNotification *)aNotification
{
    for (NSString *urlString in urlArray) {
        NSURL *url = [NSURL URLWithString:urlString];
        PageLoadOperation *plo = [[PageLoadOperation alloc] initWithURL:url];
        [queue addOperation:plo];
        [plo release];
    }
}
 
- (void)dealloc
{
    [queue release], queue = nil;
    [super dealloc];
}
 
+ (id)shared;
{
    if (!shared) {
        [[AppDelegate alloc] init];
    }
    return shared;
}
 
- (void)pageLoaded:(NSXMLDocument*)document;
{
    NSLog(@"%s Do something with the XMLDocument: %@", _cmd, document);
}
 
@end

In this example AppDelegate, two things are occurring. First, in the init method, the NSOperationQueue is being initialized and an array of urls is being loaded. Then when the application has completed its load, the applicationDidFinishLaunching: method is called by the NSApplication instance and the AppDelegate loops over the urls, creating a task for each one and loading those tasks into the NSOperationQueue. As soon as each item is loaded into the queue the queue will kick it off by assigning it to a NSThread and the thread will then run the main method of the operation. Once the operation is complete the thread will report back to the queue and the queue will release the operation.

NSOperationQueue Concurrency

In this very simple example, it is quite difficult to load up the queue with enough objects to actually see it running them in parallel. However, if you run tasks that take more time than these, you will see that the queue will run all of the tasks at the same time. Fortunately, if you want to limit how many tasks are running in parallel you can alter the init method in the App Delegate as follows:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

- (id)init
{
    if (shared) {
        [self autorelease];
        return shared;
    }
    if (![super init]) return nil;
 
    NSMutableArray *array = [[NSMutableArray alloc] init];
    [array addObject:@"http://www.google.com"];
    [array addObject:@"http://www.apple.com"];
    [array addObject:@"http://www.yahoo.com"];
    [array addObject:@"http://www.zarrastudios.com"];
    [array addObject:@"http://www.macosxhints.com"];
    urlArray = array;
    queue = [[NSOperationQueue alloc] init];
    [queue setMaxConcurrentOperationCount:2];
    shared = self;
    return self;
}

In this updated init method, the queue is throttled down to 2 operations running at the same time. The rest of the operations will wait until one of the first two is completed and then they will get an opportunity to run until the queue is empty.

Conclusion

That is the NSOperation and NSOperationQueue in its most basic form. You will note that most of the code in this example has nothing to do with the building up or using of the NSOperation or the NSOperationQueue. The actual code required to use the NSOperation is amazingly small. Yet with this small amount of code you can easily start using multiple threads in your application and provide a better experience for the user and be able to fine tune those complicated tasks.