Cocoa with Love

A big weakness in Objective-C's weak typing

2011-06-30T02:34:00.001-07:00

We generally assume that we can send any message we want to a variable in our code typed as "id" and Objective-C's dynamic message handling will make the invocation work correctly at runtime. In some rare cases, this assumption is wrong. I'll look at situations where you need to be careful about sending messages to "id" typed variables and a situation where a limitation in the Objective-C language requires a hideous workaround to avoid serious bugs.

Introduction

We generally assume we can send any message we like to an "id" variable (or a Class variable). In fact, that's the real purpose of the "id" type: it is the "any" type in Objective-C to which any Objective-C message may be sent.

We use this in lots of different situations but one of the most common is sending messages to objects store in an NSArray:

NSString *description = [[someArray objectAtIndex:0] substringFromIndex:5];

In this code sample, we don't need to cast the result of the objectAtIndex: invocation to an NSString before sending it the substringFromIndex: message — we know that as long as the object at index 0 actually is an object that responds to the substringFromIndex: selector, it will work.

This post is about invoking methods on either of Objective-C's two "weak" types: id or Class. This post does not apply if the variable you invoke a method on is typed to anything else (even id<SomeProtocol> will count as "anything else" and avoid the issues in this post).

False assumptions

The false assumption often applied here is that the compiler doesn't need to know any type information. In reality, even though the method lookup happens at runtime, that's only enough to ensure the correct method is invoked, it is not enough to ensure the parameters will work.

The compiler definitely does need to infer some information about the method signature involved. Even though the compiler does not necessarily need to know the type of the id, it does need to know the byte lengths of all parameters and the explicit type of any return values. This is because marshalling of the parameters (pushing and popping them from the stack) is configured at compile time.

Normally, we don't need to take any steps for this to happen though. The parameter information is obtained by looking at the name of the method you're trying to invoke, searching through the included headers for methods matching the invoked method name and then getting the parameter lengths from the first matching method it finds.

99.99% of the time, there's no problem with this: even if there's ambiguity about the exact method you're really targeting, the parameters are likely to be the same between matching method because method names in Objective-C generally imply the types of the data, so this type of conflict is likely to cause no difference in signature.

And then there's that other 0.01% of the time...

Catastrophic failure

Imagine you have class MyClass with an instance method named currentPoint that returns an int. You want to get the currentPoint from an object stored in an array, so you use the code:

int result = [[someArray objectAtIndex:0] currentPoint];

When you run the code, you know the exact value returned from invoking currentPoint on the first object in the array should be zero (because you set it to zero and you can see in the debugger that it is still zero) but the value that ends up in the result is 2,147,483,647 (or some other partial garbage value).

What has gone wrong?

The correct method is invoked at runtime. The problem is that the compiler marshalled the parameters for this invocation incorrectly leading to data corruption of the return type.

The compiler needs to push parameters onto the stack correctly before the message send and perform the message send using the correct variant of objc_msgSend to get the return value back afterwards. This is what has failed.

The compiler prepares parameters using the method signature (which it gets by looking at the type of the receiver and all method names that are valid for the receiver) and trying to work out which method you're likely to be invoking. Since the type of the receiver (i.e. the result from objectAtIndex:) is just id then we have no explicit type information so the compiler will look through the list of all known methods.

Unfortunately, instead of our MyClass method, the compiler decided to match against the NSBezierPath method named currentPoint and has prepared the parameters to match that method's signature. The NSBezierPath method returns an NSPoint which is a struct and handles the return parameter very differently compared to the int parameter our real method actually uses. This has lead to our return type getting corrupted.

I use the example of a struct value return type here because it is the most likely to generate a bug, since a struct return type causes the compiler to generate an objc_msgSend_stret for the message invocation instead of a regular objc_msgSend. However, it is also possible to create problems with non-return parameters of different lengths, particularly if the conflict is between floating point and non-floating point parameters or struct and non-struct parameters.

Fixing the problem (most of the time)

The best way to fix the problem is to add additional type information about the receiver, so that there will only be 1 possible match for the method name.

We do this by casting the receiver:

int result = [(MyClass *)[someArray objectAtIndex:0] currentPoint];

A MyClass receiver has only one match for currentPoint so there is no possible conflict with the NSBezierPath method and the problem here is solved.

Why is this allowed to happen? Why isn't there a compiler error?

Technically, there is a compiler warning that will alert you to this category of problem. The compiler warning "Strict Selector Matching" (a.k.a. -Wstrict-selector-match) will tell you when there is a conflict between two different method names when you're invoking a method on either of Objective-C's two weak types (id or Class).

It would be great if Strict Selector Matching always worked and we could turn it on at all times. That Apple don't turn it on by default is either because they consider the problem rare enough to ignore or it is an admission of the significant limitations of the warning as it currently behaves:

It will over-warn you. Basically, there's no reason to care if there is a conflict between two methods different but totally compatible method signatures but this compiler warning will still occur.
Plenty of Apple's own methods will cause spurious warnings due to point (1). I'm looking at you, different implementations of objectForKey:, count and most methods in NSNotificationCenter versus NSDistributedNotificationCenter. These spurious warnings may force you to carefully typecast large numbers of method calls that won't actually cause any problem.
It will not warn you about conflicts between a class and instance methods. This one is a bit absurd since a Class object is regularly handled as a generic id.
It won't help if you haven't imported the correct definition at all. If you failed to import the declaration of the correct method but you did import the declaration of a different method with a matching name but different signature, then I'm not sure the compiler could warn you about this problem.

A scenario where casting won't fix the problem

Imagine in the example above, the problem was between two class methods, instead of two instance methods.

i.e. instead of a conflict between -[NSBezierPath currentPoint] and -[MyClass currentPoint], the conflict was between +[NSBezierPath currentPoint] and +[MyClass currentPoint].

For the instance methods, we fixed the problem by casting to the specific object type required but when your objects are both Class, it is not possible to cast to the specific Class involved. Seriously: you cannot cast classes in Objective-C.

I consider this a serious failing of Objective-C. It makes avoiding this scenario with conflicting class method names hideous. If you're not able to change the name of the method, then the only work around looks like this:

int result = objc_msgSend([someArray objectAtIndex:0], @selector(currentPoint));

That's right: we would need to bypass the compiler entirely and insert the objc_msgSend call ourselves.

It gets worse though, since objc_msgSend uses a variable argument list by default, if the parameters you need to pass/receive from objc_msgSend are not signature compatible with a variable argument list, then you'll need to fully cast the objc_msgSend yourself to make certain that the parameters are passed correctly:

SomeReturnType result =
    ((SomeReturnType(*)(id, SEL, float, short, WeirdStruct))objc_msgSend)
    (
        [someArray objectAtIndex:0],
        @selector(methodWithMultipleVariables:thatAreNot:varArgCompatible:),
        someFloat,
        someShort,
        someWeirdStruct
    );

And if SomeReturnType is a struct, you'll need to use objc_msgSend_stret instead and for floating point types, you'll need to use objc_msgSend_fpret.

Conclusion

I would like to give a blanket suggestion that you switch on "Strict Selector Matching" in your Workspace/Project/Target settings for every project but unfortunately, the limitations of this warning make that suggestion difficult.

Spurious warnings from Apple's code, every time you try to use objectForKey: (or a large group of other methods) on an id typed variable can be infuriating and pointlessly increase your workload.

The warning doesn't catch all problems because it doesn't check conflicts between methods in the Class and id spaces. Along with the spurious warnings nuisance, the argument that you could skip the warning itself (and simply keep this potential problem in mind as a potential issue) is probably valid.

The warning itself should be fixed in GCC and Clang to make it useable enough to leave on in all situations. It shouldn't give a warning when the parameters in conflicting signatures are compatible. It should also gain cross checking between Class and id when the type in the code is id.

And Objective-C really needs a way to declare a type that is a specific Class. Even syntax as ugly as @classtype(SomeClass) would do it but I'm sure something more graceful could be found.

I've seen people argue that if you ever require a specific Class then you're designing things badly. I think the bugs caused by method name conflicts are a situation where you may not (if you can't rename either method) be able to cleanly design your way around this serious problem without the ability to cast a Class to something more specific.

In addition to allowing a conflict between two Class methods to be resolved more gracefully it would also help in the unrelated situation where a method wants a Class object passed as a parameter but that Class must be a subclass of a specific class.

An RSS-feed and location-based iOS application

2011-06-19T08:18:00.001-07:00

The purpose of this post is so that I will have a link to give people when they ask: how do I write an iOS application that pulls data from an RSS feed, displays it pretty and can put things on a map. I'll show you all of that and more as I rewrite my oldest iOS application from scratch: FuelView.

The app presented in this post, FuelView, is freely available on the Australian App Store.

Introduction

I am commonly asked to write a post where I show a basic "pull data from the network and display" application.

But I think "basic" is boring and I try to avoid it in my blog posts. Instead, I decided to rewrite an application that looks simple but actually has a deceptively large amount of work to perform. It's a far better example of a real-world iOS application since there should always be enough work done transparently by your application that it leaves the user with a "Wow!"

The actual application is only 3 screens. While a truly simple three screen application might take about 2-3 hours per screen to implement (even if you're just stumbling your way through), this program actually took me about twice that time to implement (around 15 hours or two full days of programming) and I definitely knew what I was doing, since I've written the entire program before.

If you're curious though, in its first incarnation, this program took me 2 weeks to fully implement — way back in July 2008. It was the first program I ever tried to write for iPhone OS 2.0 and I did a lot of things the wrong way. Having a vague idea what you're trying to do really does make a 5 to 10 times difference to implementation time and unfortunately, the only way to learn is to stumble headlong into things and run the risk of getting everything wrong the first time.

There's a reason why this version is a rewrite from scratch.

Useful code in this post

While the application in this post is only directly useful to people living in Western Australia, I think this is a really interesting project as it contains a lot of very useful snippets of code (some of which I've written posts on before) including:

An iOS version of my Gloss Gradient drawing code (you can see the Mac version in Drawing gloss gradients in CoreGraphics)
Two persistent stores with one NSPersistentStoreCoordinator. It seems like a strange scenario that would only be needed in strange situations but the use case turns out to be really common.
A full set of "single line Core Data fetch" methods (something I've previously written about in Core Data: one line fetch)
Getting the GPS location (which you can also see in my earlier posts: WhereIsMyMac, a Snow Leopard CoreLocation project and A sample iPhone application with complete unit tests)
Pulling data from an RSS feed (using my XMLFetcher class from Classes for fetching and parsing XML or JSON via HTTP)
Caching data in the Application Support directory (using a DirectoryLocations category from Finding or creating the application support directory)
Function to create a two point CGGradientRef from two UIColors (another in a long list of convenience functions that I'm surprised aren't part of Cocoa)
An example of using a category as an Adapter interface (something I discussed in Adapter interfaces in Objective-C, using categories without giving any concrete examples)
Scrolling a text field that isn't in a table (a similar idea but different implementation to my earlier post Sliding UITextFields around to avoid the keyboard)
A Core Data Postcode database (originally created from a CSV file as shown in Writing a parser using NSScanner)
A flexible, reusable controller/table/cell structure (as I discussed in UITableView construction, drawing and management)
A CheckmarkCell that self-manages radio button style selection (without the UITableViewController needing to do anything when the cell is selected, the cells in the section will automatically ensure only one is selected at a time)
Forward geocoding using Google's Maps API (MKReverseGeocoder goes the other way but a non-Cocoa approach is needed to go from an address to longitude/latitude)

Plus a whole lot more. It really is a densely packed little program.

So where is all the "useful code"? If you skip forward to the second last section, I reveal where in the program you can find all of these code samples.

About FuelView

FuelView is an application for getting fuel (petrol/gasoline, diesel, etc) prices in Western Australia. It pulls its information from an RSS feed provided by the Western Australian government's "Fuel Watch" scheme that provides fuel prices for all stations in that state.

(No, I don't live in Western Australia — I'm on the opposite coast of Australia — but it seemed like a good idea for an iPhone app at the time.)

The application looks like this:

Download the complete project associated with this post: FuelView.zip (330kb).

Note: the code is all freely available under a zlib-style license but this license does not extend to the other assets. You may not use the icons or application name in your own programs.

The previous version of FuelView (1.1.10 is available for free from the iTunes App Store in Australia. I'll be resubmitting this version (probably 1.2) in a week or two.

Deceptive complexity

It all looks very simple; you get the location from the GPS, you pull the correct RSS feed for the location, stick pins in a map for the result.

If that were the actual number of steps involved, it would be great. However, it's not so simple. Let's take a quick look at the issues that will cause the most trouble for this program.

User location issues

The GPS gives latitude/longitude but the getting the RSS requires a Western Australian suburb name. In order to make this work, you need to be able to look up all the Western Australian suburbs and find the nearest one for your longitude/latitude. This requires a database of suburb names and their longitude/latitude and some code to search this.

Additionally, I want to be able to let the user specify a postcode for their location instead of using the GPS. Again, I need to be able to look up the suburb name for the postcode. Additionally, any code that requires the user's location must be able to tolerate the location being a postcode, not a raw longitude latitude.

A further complication arises because the FuelWatch RSS feed only exists for "larger" suburbs. Names of smaller suburbs can't be used, so the list of suburbs must be filtered to match the list that the FuelWatch website recognizes.

Station location issues

The RSS feed gives the fuel station locations as street addresses but I need longitude and latitudes for them so I can stick pins in the map or calculate the distance between the user and the station.

While this is a similar problem to resolving the user's location, it is actually trickier since new stations appear all the time, so this database must be dynamic (unlike the static postcode database).

I need to actually perform geocoding of fuel stations but there's a problem: Google's APIs are highly restrictive about how often you can make requests. The only way to avoid problems is to pre-populate the database and then have users only perform forward geocoding requests when an unknown fuel station appears and immediately add the new station to the database.

Custom drawing

Then I have the more straightforward complexity of custom drawing. I want to have most of the interface follow a custom aesthetic (because plain is boring) and that takes time and effort. I also need to ensure that drawing and layout function properly on an iPad and an iPhone.

The real design of the program

In the diagram here, the green objects are the 3 main view controllers, the orange objects are the main "model" of the program (being the data that is actually displayed and passed between the ResultsViewController and the MapViewController) and the blue objects are the data controllers or functional pipelines of the program.

You can see some of the "deceptive complexity" here: the ResultsViewController is managing three different kinds of model data, and is also managing input from the CLLocationManager and UITextField. All this is apart from the normal responsibility of showing and displaying the UITableView and its rows.

Initial design of the program

While I'd love to say: I had this entire design ready when I started, it's simply not true. What I actually had was a quick UI design and a quick sketch of the data pipeline.

My inital sketch for the UI looked like this:

I didn't really need to do this sketch for this program (since the UI is pretty simple) but it's a good way to start all user programs.

As you can see, in the three years since I wrote FuelView, I had entirely forgotten about the need to resolve postcodes to suburb names and resolve station locations — instead I've simply shown the network pipeline.

This forgetfulness is pretty disappointing. Not only does it make me think the program is taking longer than it should but it ultimately leads to some of the design problems I discuss later.

But we're not there yet.

First implementation iteration

I'm going to refer to the design stages as "iterations". These steps are often called milestones (or mini-milestones when they're this small) but milestone implies you're only going forward, instead of the reality where you normally need to update the existing interfaces on your classes as part of integrating new features — so I prefer to think about it as iterating the program.

The first iteration involved implementing the program as described in the "FuelView Initial Dataflow design" shown above.

Created a new project from my PageViewController template
Pulled in an XMLFetcher
Hardwired the code to pull the RSS feed for a specific suburb
Displayed the list of addresses from the results as a basic text list

Second design iteration

Now I need to be able to resolve locations from the CLLocationManager to suburb names. I also need to be able to resolve user-entered postcodes to actual suburb names. Finally, there needs to be logic so that a manually entered suburb name supercedes the GPS.

Again, I wouldn't ordinarily draw little design diagrams for this but — its a blog post and big walls of text are boring.

Second implementation iteration

To make the second design iteration work, I go through the following steps:

Modified the CSVImporter from my Writing a parser using NSScanner post to generate a list of Western Australian postcodes with longitude and latitude. At the same time, I need to filter out suburbs that won't be recognized by the FuelWatch website
Brought in a standard class for managing a Core Data NSManagedObjectContext and used the class to perform lookups on the list of Postcodes
Added code to the ResultsViewController for CLLocationManager GPS locations
Added code to the ResultsViewController to switch between the CLLocationManager and user-entered Postcode data sources

Design Mistake #1

In a general sense, the program is "well-designed" but it still contains two design mistakes. I could fix these mistakes but (a) I'm lazy and (b) I wanted to talk about both of them since I think they're under-discussed design problems.

By this point in the implementation, the first mistake has emerged: the ambiguous overuse of the word "location".

Yes, ambiguous naming is a design mistake. It's not exactly an aspect of design that is thoroughly discussed — probably because it's considered self-evident — but as your program evolves and new functions, roles and elements are added to existing classes, it is sometimes necessary to change the names of the classes.

In this program, the word location has a few different meanings:

GPS location from the CLLocationManager (gpsLocation in the program)
User-specified postcode (usingManualLocation/postcodeValue in the program)
Resolved suburb name used for searching (location property on ResultsViewController — a Postcode object
The location of fuel stations (instances of the Location class)

Yuck, what a nightmare.

The single biggest mistake here is that the location property on the ResultsViewController is a Postcode object, despite the name implying the Location class. This is an ambiguity you should work really hard to avoid — and fix when it occurs.

A far better approach would actually be: rename the PostcodesController to SuburbsController, rename Postcode to Suburb, rename the suburb property on Suburb to name and rename the location property to suburb. In addition, it would be better to rename Location to Station.

Third implementation iteration

Now that the main data path is working, it's time to start on the custom views.

The GradientBackgroundTable will be the main UITableView class in the program. Its name is a bit of a misnomer: not so much of a misnomer that it's a design mistake but the table can draw as a gradient but can also draw as a flat color — it would be better named "Custom colored background table" or something like that.

Each result row will be represented using the following classes:

ResultCell — controller that constructs the rest of the row
ResultCellBackground — set as the backgroundView of the cell. Draws the gray gradient background and not much else
ResultView — draws all of the text (does not use UILabels) and uses the Gloss Gradient code to construct the backing for the actual price display

This now brings us a main screen that looks like this:

Note that each row simply shows an orange "cents per litre" line under the price. Ultimately, this should show the distance from the user's current GPS location to the station but since I don't yet have the locations for the stations, I can only show "cents per litre". Note that this "cents per litre" will continue to display in the final program if the user is using a manually-entered postcode (and I don't necessarily know their GPS location).

Fourth implementation iteration

Now I need to resolve station locations. I have the street addresses from the FuelWatch RSS feed results but I need to turn this into longitude and latitude to calculate the distance or stick a pin in a map.

I'll use the Google APIs for this. As I've said though, the Google Maps API won't let you perform a large number of requests per second so I need to aggressively pre-cache station locations and only perform a geocoding request when a new fuel station appears for the first time.

The LocationsController and the Location lookup generally work like the Postcode lookup on the PostcodesController when the station is cached, otherwise, I need a callback when the actual response comes back from Google.

The LocationsController normally uses two Core Data data stores: one is read-only and is the "pre-cached" set of fuel station results (shipped with the application). The second is the read-write data store, saved in the Application Support directory (which is writeable, unlike the application's bundle). This second location will get all new locations for which we need to query Google.

To prepare the pre-cached file of stations that we can ship with the application, the best approach is simply to run in the iPhone Simulator with the LocationController's primary data store set to Read/Write (and the read-only store removed) and when the primary data store fills with results, let it save to file, copy the cached results file from the iPhone Simulator's directory back into the Project.

Once the location is resolved to a longitude and latitude, I can calculate the approximate distance to the user's GPS location, using the approximate kilometres per longitude and latitude at 30 degrees latitude (this is not highly accurate but is sufficient given that most of Western Australia is relatively close to 30 degrees latitude.

With the locations available, I can display the distance in the ResultsView and color code the distance bar based on how far away the station is.

Maps Key Note: I have removed my Google Maps API key from the code. If you want to use this code, you'll need to apply for your own Google Maps API key and set it the MapsKey at the top of the LocationsController.m file.

Fifth implementation iteration

Implementing the SettingsViewController to switch fuel types and the MapsViewController to show the current array of results on a map turns out to be very simple. There's not a significant amount of complexity in either of these views.

Design Mistake #2

One point to notice in the implementation of the MapViewController is that I needed to implement an "Adapter category" on NSDictionary to allow the NSDictionary to respond to the MKAnnotion protocol so I could use the dictionaries to display the pins in the map.

How is this a design mistake?

Needing to put categories on generic classes like this is an indication that you probably should have used a dedicated class to contain your data. The results in the program should not be generic NSDictionary objects.

Until this point, the "generic"-ness of the main data type in the program has been ignored. The reality though is that the construction of NSDictionary results from XPathResultNodes and the resolving of station location for each result has been handled by the ResultsViewController — this is all work that a Result class should be performing for itself instead of using a generic NSDictionary class and making the ResultViewController handle all the work.

But ad hoc trickery like adding categories to generic container classes is a big flag that you've forgotten to use a custom class for objects that genuinely need their own behaviors. If you find yourself needing something like this: replace the generic container with a proper custom class.

I'm not saying that adapter categories are a bad idea. Sometimes you can't or shouldn't change the underlying class — in this case and adapter is a good thing. But here in FuelView I can change the underlying class and should, in order to reduce the code burden on our controllers.

So where is all the "useful code"?

An iOS version of my Gloss Gradient drawing code

The GlossGradients.m code is in the project. It's very similar to the original code except that there aren't HSV conversion methods on UIColor like there is on NSColor, so I've had to write these methods myself. It is used in the ResultsView drawing code.

Two persistent stores with one NSPersistentStoreCoordinator

The LocationsController uses two different persistent stores: a read-only store inside the application bundle that is shipped with the application contains the pre-supplied results for station lookups. But the application bundle can't be changed, so I create a read-write store in the Application Support directory. The NSPersistentStoreCoordinator is smart enough to save the store to the correct location automatically.

A full set of "single line Core Data fetch" methods

The NSManagedObjectContext+FetchAdditions.m file contains a range of different fetch request creation methods and single line fetching implementations (for set, array and single object results). It is used in the LocationsController and the PostcodesController to perform the actual queries on the Core Data context.

Getting the GPS location

The ResultsViewController operates as a CLLocationManagerDelegate. The location receiving code is pretty simple but I think the error handling code in locationFailedWithCode: is more interesting.

Pulling data from an RSS feed

Of course, an RSS feed is just XML. We're after the <item> nodes in the result so I use an XMLFetcher to with an XPath query of "//item". You can see this in the setLocation: method and the response is handled in the responseReceived: method (the XPathQueryNodes are turned into an NSDictionary).

Caching data in the Application Support directory

The application support directory is accessed/created in the persistentStoreCoordinator method of the LocationsController. As I said above, this is for writing extra Locations to the Locations Core Data context.

Function to create a two point CGGradientRef from two UIColors

The function TwoPointGradient is pretty simple; it just creates a CGGradientRef taking two UIColors to use as the endpoints of the gradient. However, it's 23 lines of code that don't need to be retyped in the ResultCellBackground, ResultView and the PageCellBackground.

An example of using a category as an Adapter interface

Putting an adapter on a generic container class is a bad idea if you can easily change the class to something of your own implementation. But this is still an example of adapting a class' interface to suit your own needs — something that is very useful when you don't have control over the underlying class.

Scrolling a text field that isn't in a table

The manually entered postcode is in a text field on a UIToolbar and when the keyboard appears, the entire UIToolbar scrolls up with the keyboard. This behavior is handled by the PageViewController (everything below the "Handle the sliding/scrolling of the view when the keyboard appears" pragma except the dealloc method). The PageViewController needs to be set as the delegate of the UITextField for this to work.

A Core Data Postcode database

The PostcodesController shows how to implement a static data store using Core Data. I think I could probably write a base-class for this type of singleton that would dramatically reduce the common code between the PostcodesController and the LocationsController.

A flexible, reusable controller/table/cell structure

The PageViewController, PageCell, all the view controllers and all the table cells are directly based on the code I presented in UITableView construction, drawing and management.

A CheckmarkCell that self-manages radio button style selection

It's strongly reliant on the PageViewController and PageCell classes but the CheckmarkCell shows an easy way (easy for the rest of the program) to manage a section in a table where only one row can be selected.

Forward geocoding using Google's Maps API

The locationForAddress:receiver: method in LocationsController performs an XML request on Googles Maps API to forward geocode addresses into longitude and latitude (the response is handled in mapsResponseReceived:). Again: you'll need your own Maps API Key to make this work.

Conclusion

Download the complete project associated with this post: FuelView.zip (330kb).

Note: the code is all freely available under a zlib-style license but this license does not extend to the other assets. You may not use the icons or application name in your own programs.

The app presented in this post, FuelView, is freely available on the Australian App Store.

I did this rewrite of FuelView for three reasons:

I hadn't written any code at work for a week or two — I needed to scratch my codemonkey itch with a few hours of actual programming instead of meetings and documentation.
Preparing code like this for my blog motivates me to review my reusable classes and make them more presentable.
I'm often asked to show an iOS program that pulls data from an RSS feed.

The first two points are entirely for my own purposes and went fine, thanks.

On the third point — this is definitely code that pulls from an RSS feed. I hope the scale of the program doesn't make it hard to see how the basics work. In addition to RSS feed handling though, there's lot of other code here so I hope there's something here for programmers at a range of different skill levels.

Classes for fetching and parsing XML or JSON via HTTP

2011-05-30T00:50:00.001-07:00

In this post I show two reusable classes for fetching data via HTTP: one that parses the result as XML and another that parses as JSON. These are relatively simple tasks but due to the number of required steps, they can become tiresome if you don't have robust, reusable code for the task. These classes will work on iOS or on the Mac but the optional error alerts and password dialogs are only implemented for iOS.

Introduction

In my experience, "fetching data via HTTP" is probably the second most common task that iOS applications perform after "displaying a list of things in a table". Since I wrote a recent post showing how I handle display in tables, showing my reusable classes for fetching via HTTP seemed like a reasonable follow up.

As with the post on UITableView management, this post is all about trying to make the HTTP fetching, handling and processing as simple and reusable as possible.

What I hope to demonstrate is that even though the Cocoa API makes it look like you need to bolt NSURLConnection delegate methods onto your own classes every time you need a network connection, it doesn't mean that you actually need to do all this work every time you need a network connection. For the most common tasks like this, you should develop your own, reusable approaches that you like, that serve your needs and that make new code easier.

There are lots of alternative approaches around that demonstrate similar ideas. My implementation is a simple implementation compared to full frameworks (for a more thorough implementation along similar lines, you may want to look at RestKit). I hope you'll still be able to see the contrast compared to ad hoc solutions though, especially if you've ever jammed HTTP communication into your projects without thinking about keeping the interface clean and simple.

You can download the four classes discussed in this project: HTTPXMLJSONFetchers.zip (16kB)

HTTP connections in Cocoa

BSD sockets and CFHTTPStream are generally too low level to use regularly. Unless your program requires meticulous control of the network layer, you probably want to use NSURLConnection for handling HTTP fetching.

Technically, NSURLConnection can perform network connections in a single instruction: +[NSURLConnection sendSynchronousRequest:returningResponse:error:]. Synchronous connection should be avoided in all but a few rare worker-thread situations because it stops your program's user-interface and it doesn't allow careful error handling.

This means that when fetching via HTTP, you should be using NSURLConnection's delegate methods. The delegate methods are:

- (void)connection:(NSURLConnection *)connection didReceiveResponse:(NSURLResponse *)response
- (void)connection:(NSURLConnection *)connection didReceiveData:(NSData *)data
- (void)connection:(NSURLConnection *)connection didFailWithError:(NSError *)error
- (void)connection:(NSURLConnection *)aConnection didReceiveAuthenticationChallenge:(NSURLAuthenticationChallenge *)aChallenge
- (void)connectionDidFinishLoading:(NSURLConnection *)connection

and a thorough implementation means implementing all 5 of these methods.

A commonly seen case for this is to add the NSURLConnection delegate methods to your UITableViewController and make that view controller manage the connection.

While this might seem like a good idea (the view controller can track the status of the connection and provide visual updates and also present its own errors) the reality is that fully handling the connection takes a lot of code. How much code? The code I use is 530 lines long (including comments and spacing).

But there's also a more serious problem: bolting NSURLConnection to your UITableViewController limits code reuse. If your network code is tied closely to the view controller, there's more work involved in adding network behaviors to other view controllers or parts of your program.

Why do NSURLConnection delegates take so much code to implement? In the simplest case, they don't (you could probably manage a connection in 20 lines or so) but you'd be overlooking a lot of subtler behaviors. Errors, password authentication, cancelling the connection cleanly and offering simple construction versus meticulous construction are the type of behaviors that get left out if you're rewriting the code every time or operating under serious time constraints.

HTTPFetcher

The idea behind my HTTPFetcher class is really simple: it's reusable NSURLConnection delegate. It handles all the NSURLConnection delegate work and calls back when it has the results. It provides default error handling, password authentication and while it has a very simple default constructor, it still provides enough hooks that you can customize its behavior.

The interface to the class is really just construction methods, a start, a cancel and some properties. The assign properties are for configuring the connection before you start it. The readonly properties are for gathering information once the connection is complete.

@interface HTTPFetcher : NSObject <UITextFieldDelegate>

@property (nonatomic, readonly) NSData *data;
@property (nonatomic, readonly) NSURLRequest *urlRequest;
@property (nonatomic, readonly) NSDictionary *responseHeaderFields;
@property (nonatomic, readonly) NSInteger failureCode;
@property (nonatomic, assign) BOOL showAlerts;
@property (nonatomic, assign) BOOL showAuthentication;
@property (nonatomic, assign) void *context;

- (id)initWithURLRequest:(NSURLRequest *)aURLRequest
    receiver:(id)aReceiver
    action:(SEL)receiverAction;
- (id)initWithURLString:(NSString *)aURLString
    receiver:(id)aReceiver
    action:(SEL)receiverAction;
- (id)initWithURLString:(NSString *)aURLString
    timeout:(NSTimeInterval)aTimeoutInterval
    cachePolicy:(NSURLCacheStoragePolicy)aCachePolicy
    receiver:(id)aReceiver
    action:(SEL)receiverAction;
- (void)start;
- (void)cancel;

@end

You initialize the class in whatever way you choose (the middle init method shown here is the simplest), optionally configure the class (the most common configuration is to set the context pointer so that when the connection completes, you can remember where to set the data), start the connection and then it will invoke the receiverAction on your receiver object (the receiver action takes one parameter: the HTTPFetcher itself).

// Example fetcher creation
fetcher = [[HTTPFetcher alloc]
    initWithURLString:@"http://some-domain.com/some/path"
    receiver:self
    action:@selector(receiveResponse:)];
[fetcher start];

// Example fetcher response handling
- (void)receiveResponse:(HTTPFetcher *)aFetcher
{
    NSAssert(aFetcher == fetcher,
        @"In this example, aFetcher is always the same as the fetcher ivar we set above");
    if ([fetcher.data length] > 0)
    {
        [self doSomethingWithTheData:fetcher.data];
    }
    [fetcher release];
    fetcher = nil;
}

Ordinarily, your program will want to customize the code that presents the errors and make the presentation consistent to your application. You can do this with the HTTPFetcher class by either subclassing or editing the class itself or you can disable the alerts and authentication functionality and perform the work outside the class. However, if you don't have time to do this customization, there is default behavior in the class that will suffice.

HTTPFetcher memory management: the HTTPFetcher does not retain itself while running and does not retain the receiver. This is because the expected behavior is that the receiver retains the HTTPFetcher and we don't want a retain cycle. If you create the HTTPFetcher and don't have a retain count on it, it will immediately auto-cancel itself and dealloc.

XMLFetcher

The HTTPFetcher is fine if you simply want the data from an HTTP connection. For my own purposes though, I've never used the HTTPFetcher on its own — I've always used it as the base-class for classes which post-process the HTTP data before invoking the receiver's callback method.

The XMLFetcher class is for turning an XML response into something more useful. Instead of needing to look at the data property of the HTTPFetcher, you can use the results property which is the array of nodes matching a given XPath query on the XML result.

@interface XMLFetcher : HTTPFetcher

@property (nonatomic, copy, readonly) NSString *xPathQuery;
@property (nonatomic, retain, readonly) NSArray *results;

- (id)initWithURLString:(NSString *)aURLString
    xPathQuery:(NSString *)query
    receiver:(id)aReceiver
    action:(SEL)receiverAction;

@end

I've previously spoken about how I'm not a fan of the event-driven model (sometimes called a SAX parser) promoted by Apple in the iOS API. It is certainly memory efficient and faster for large files but it requires you perform your own structured handling which is tiresome, prone to mistakes and not really reusable. I personally prefer a document-based model like the NSXML API that exists in Mac OS X but not in iOS.

The XMLFetcher class blends the libXML-based XPath based parsing and querying with the HTTPFetcher.

However, I've addressed a number of the shortcomings of my previous libXML-based parsing. The biggest problem with that earlier code was that it simply packaged the XML into NSDictionarys (which is inelegant at best) — so instead, the results are now a dedicated XPathResultNode class which can cleanly represent attributes, childNodes and contentStrings. There's also better handling of content strings either side of subnodes and concatenating of text data spread over subnodes.

@interface XPathResultNode : NSObject

@property (nonatomic, retain, readonly) NSString *name;
@property (nonatomic, retain, readonly) NSMutableDictionary *attributes;
@property (nonatomic, retain, readonly) NSMutableArray *content;

+ (NSArray *)nodesForXPathQuery:(NSString *)query onHTML:(NSData *)htmlData;
+ (NSArray *)nodesForXPathQuery:(NSString *)query onXML:(NSData *)xmlData;

- (NSArray *)childNodes;
- (NSString *)contentString;
- (NSString *)contentStringByUnifyingSubnodes;

@end

XPath query note: XPath queries can be a little difficult to get used to — if you're not accustomed to XPath, it can be hard to extract the exact nodes you want. Like regular expressions though, they're a highly specialized language for extracting data and once you understand the different functions available, they are the quickest way of getting specific nodes out of XML.

Compiler note: the XPathResultNode.m file contains a comment at the time which explains the Xcode compiler settings required to make it work. Basically, you need to include libxml in the include path and link your project with libxml2.dylib.

JSONFetcher

The JSONFetcher is really just the same idea as the XMLFetcher — parse the result from HTTPFetcher once complete, this time as JSON data.

The class I've written relies on SBJSON, Stig Brautaset's BSD-licensed JSON parsing library. You will need to download these files separately and include them in your project (it's 3 .m files and 4 .h files).

SBJSON isn't your only option for JSON handling in iOS or Mac OS X. There are a few other JSON libraries for iOS and Mac discussed here on Stackoverflow if you'd prefer options. Obviously though, you'd need to make minor adjustments to integrate a different parser.

With a JSON response, there's not the same expectation of needing to find a subnode within a larger result (as is the common case for XML), so the JSON parser simply parses the whole JSON structure and returns it all.

@interface JSONFetcher : HTTPFetcher

@property (nonatomic, readonly) id result;

@end

Conclusion

You can download the four classes discussed in this project: HTTPXMLJSONFetchers.zip (16kB)

I've presented my classes for handling these tasks. I don't expect that everyone has the same data and network requirements as I do, so there's every chance that you would need very different classes to suit your own exact needs.

The point is really to consider reuse in your own code — how can you evolve your classes so that when you start a new project you need to rewrite as little as possible — you can simply bring in your own class for handling network data, pass different parameters into its constructor and your network connection is done.

Until I had composed these classes for my own purposes, new projects involved hundreds of lines of code that went through a copy, paste, refactor process from existing projects I'd written. While copy, paste, refactor will work, it is slower, more prone to errors and harder to keep up-to-date than properly reusable classes. In most cases, you should view copy and paste as a failure of your own processes. That's a hard rule to adhere to, since copy, paste, refactor is faster than designing a reusable class — or at least it is initially (compared to an up-front design effort). You need to have the discipline to recognize the common behaviors between classes or projects and refactor into shared classes if required.

A final thought: I realize I I haven't really shown these classes at work in an example program. If you can't work out how to use them in a real program, please wait a week or two: I plan to share a real-world project that uses them to handle all its network communication.

Presenting a Mac dialog sheet with visual cue effects

2011-05-05T04:37:00.001-07:00

In this post, I'll show you how to use visual effects over a window to make a dialog sheet stand out when it is presented over the top. It's a pretty simple use of Core Image but is a useful technique to capture attention when needed.

Introduction

Getting the user's attention when required and drawing their focus to important areas is an important point when trying to iterate and improve your user interface.

Of particular importance: how to you force the user's attention from one part of the screen to another when an important event occurs.

That's a task that the code in this post aims to address. By visually disrupting the normal window area, we inform the user that their attention is briefly needed elsewhere.

Of course, this is not a good thing to do frequently. Forcing the user to shift their attention from one side of the screen to another is generally considered poor form. However, some screen features (especially sheets and alerts) have a fixed location so keeping the activity local is not always possible.

The sample application

Download the Xcode project for this post: PresentSheetWithEffect.zip (190kB)

The sample application shows the following window:

When either of the two buttons are pressed, a sheet (either a window loaded from a NIB file or an NSAlert, depending on the button) is presented over the window.

As the sheet is presented, a trio of Core Image effects are applied over the window:

Reducing saturation
Reducing exposure
Applying gloom (darkened glow from dark areas)

The result is shown in this second screenshot:

The aim is to make the alert — which is pretty bland — visually pop out and draw the user's attention to it (since it is modal and they're not allowed to do anything else until they dismiss it).

Visual overlays

Visual disruption of the background is common in iOS. Users of Safari in iOS would be familiar with the dark, semi-transparent overlays over the main webpage area when the keyboard focus is in the Safari address bar. Even Safari on the Mac darkens the main page except for search terms when searching for text within a page.

However, this overlay normally needs to be very dark since the color of the main page behind the overlay is not known and the overlay needs to provide contrast in as many cases as possible.

With Core Image on the Mac, we have a range of different options that don't require turning the screen completely dark. For this post, I've chosen to reduce saturation, take a little out of the brightness and apply a gloom. Of course you might prefer a different selection of filters.

An important consideration with the filters to apply: they shouldn't look too flashy and they shouldn't hurt the eyes of the user who will likely be focussed on a region within the filtered area. For example: I had initially tried a gaussian blur filter but this actually hurts your eyes a little if it is applied while you're trying to focus — you subconsciously try to focus as the blur gradually makes this impossible.

A great big block of code

The following method applies the filters and presents the sheet. The filters will only work if the window's contentView has a Core Animation layer (in this program, the Core Animation is enabled in the XIB file).

- (void)presentSheetWithWindow:(id)aSheetWindow
    delegate:(id)modalWindowDelegate
    didEndSelector:(SEL)didEndSelector
{
    // 'sheetWindow' is an instance variable tracking the currently presented
    // window. If a window is already being presented, dismiss it first before
    // presenting this new one
    if (sheetWindow)
    {
        [self dismissSheetForWindow:sheetWindow];
    }
    sheetWindow = [aSheetWindow retain];
    
    // We're going to fade the effect in
    CATransition *animation = [CATransition animation];
    [animation setType:kCATransitionFade];
    [[[[self window] contentView] layer] addAnimation:animation forKey:@"layerAnimation"];
    
    // The effect will be applied to this new view that we'll lay over the top
    // of everything else
    blankingView =
        [[[NSView alloc] initWithFrame:[[[self window] contentView] bounds]] autorelease];
    [[[self window] contentView] addSubview:blankingView];

    // Construct the three effects
    CIFilter *exposureFilter = [CIFilter filterWithName:@"CIExposureAdjust"];
    [exposureFilter setDefaults];
    [exposureFilter setValue:[NSNumber numberWithDouble:-1.25] forKey:@"inputEV"];
    CIFilter *saturationFilter = [CIFilter filterWithName:@"CIColorControls"];
    [saturationFilter setDefaults];
    [saturationFilter setValue:[NSNumber numberWithDouble:0.35] forKey:@"inputSaturation"];
    CIFilter *gloomFilter = [CIFilter filterWithName:@"CIGloom"];
    [gloomFilter setDefaults];
    [gloomFilter setValue:[NSNumber numberWithDouble:0.75] forKey:@"inputIntensity"];
    
    // Apply the effects to the blankingView layer
    [[blankingView layer] setBackgroundFilters:
        [NSArray arrayWithObjects:exposureFilter, saturationFilter, gloomFilter, nil]];

    // Present the sheet -- different code depending on whether we're presenting
    // a dialog or regular window
    if ([sheetWindow isKindOfClass:[NSAlert class]])
    {
        if (modalWindowDelegate == nil)
        {
            modalWindowDelegate = self;
            didEndSelector = @selector(didEndPresentedAlert:returnCode:contextInfo:);
        }
        [(NSAlert *)sheetWindow
            beginSheetModalForWindow:[self window]
            modalDelegate:modalWindowDelegate
            didEndSelector:didEndSelector
            contextInfo:NULL];
    }
    else
    {
        [[NSApplication sharedApplication]
            beginSheet:sheetWindow
            modalForWindow:[self window]
            modalDelegate:modalWindowDelegate
            didEndSelector:didEndSelector
            contextInfo:NULL];
    }
}

The rest of the sample application

Download the Xcode project for this post: PresentSheetWithEffect.zip (190kB)

The sample application also shows the expected usage: a separate subview controller controls the subview but invokes the window controller to actually present the sheet.

The presentation code is written to account for the fact that different subview controllers may attempt to present errors at different times without any real coordination but the current incarnation does not allow for sheet "stacking" (i.e. if a new sheet is presented, any existing sheet is immediately dismissed). If you need stacked sheets, you'd need to make changes to permit that.

Conclusion

Core Image allows a lot of flexibility with this type of visual effect. Even if you're not trying to be as "cute" as the trio of effects used in this sample post, the ability to do something as basic as turning down the saturation is quite powerful.

Remember: the purpose with visual effects should be to speed up the user experience by drawing focus to where it is needed. If you're slowing the user down, you're doing it wrong.

Background audio through an iOS movie player

2011-04-20T03:03:00.001-07:00

Background audio in iOS is supposed to be as simple as entering a setting in your Info.plist and making sure your kAudioSessionProperty_AudioCategory is appropriate. This is true unless your audio is part of a movie file or is played in a movie player that has just played video — suddenly it becomes fiddly, hard to test, unreliable and changeable from version to version of iOS.

Introduction

I was not sure I wanted to write this post. It runs the risk of pointing out that I'm not perfect. But all programs have bugs and my programs are no different.

And anyway, as both Han Solo and Lando Calrissian validly said of the Millenium Falcon's failure to reach light speed, "it's not my fault". Of course, as it was in Star Wars, so it is in real life: your users don't care whose fault it is, they just want it fixed.

Obviously, I develop and sell a product named StreamToMe, available through the iOS App Store, that plays video and music and lists "Background audio" as one of its features. In this post, I'm going to talk about why background audio has worked and then not worked, been fixed and then not worked again only to be mostly fixed with some issues outstanding.

How can a feature that is simple, according to Apple's documentation, cause such a quality headache in a program?

In this post I'll be looking at playing background audio through the iOS movie playing APIs (either MPMoviePlayerController or AVPlayer/AVQueuePlayer). I've recently written a post on the history of iOS media APIs but as you'll see in this post, background audio is functionality that relates to the implications of the APIs, not the APIs themselves. You need to discover the "de facto" behavior yourself and hope you're correct.

Specific points will include:

why an application that also plays video has so much more difficulty with background audio than other kinds of applications
why background audio has broken multiple times in StreamToMe since iOS 4 was released, despite using no undocumented functionality and despite the documented API remaining nominally unchanged
why background audio is affected by seemingly unrelated choices like Apple's HTTP live streaming and 3G network

I'll also briefly look at quality management on a complicated program and how the largely undocumented behaviors of Apple's video APIs make perfect testing impossible.

Apple's documentation for background audio in iOS

Apple's documentation for background audio makes it sound very simple. It is 4 paragraphs long under the heading "Playing Background Audio" on the Executing Code in the Background page.

Additionally, Technical Q&A QA1668 discusses "How to play audio in the background with MPMoviePlayerController" by ensuring the Audio Session Category is correct.

Background audio is mentioned in a few other pages but it mostly repeats the information found in these two locations.

It all sounds pretty simple: it seems like background audio should "just work".

What happens to a file that contains video?

The movie players in iOS are explicitly capable of working in the background

But in the above linked Technical Q&A QA1668, the question explicitly mentions "audio-only movies and other audio files". There is no mention of what happens to files that have a video track.

In fact, there is no mention anywhere in the iOS documentation that I could find about what happens to a video file when you switch into the background.

All we can do is examine the behaviors experimentally. The following are the behaviors I've noticed in iOS 4.3 when switching video into the background.

Any file that contains a video track of any sort will be paused if the application switches into the background.

This pause is sent from the CALayer displaying the video frames. This is a private class for an MPMoviePlayerController and is your own AVPlayerLayer for an AVPlayer.

You can't really control this — even in the situation where it's your own AVPlayerLayer — the pause is sent from private methods (so you can't legally override them), during a private "UIApplicationDidSuspendNotification" (so you can't legally block or intercept this). This notification occurs between the UIApplicationWillResignActiveNotification and the UIApplicationDidEnterBackgroundNotification.

Nor can you simply disconnect the AVPlayerLayer of an AVPlayer to avoid the pause being sent — this actually leads to a crash if the file is still playing for reasons that are not explained and could be either a bug in iOS or expected behavior (it's not at all clear).

If you attempt to start a file playing video in the background it will fail with an error

While a video file started in the foreground will simply pause, a video file started in the background will actually give an error abort playback entirely.

This can even occur for a file that was pausing on entering the background but which you attempt to resume.

If you attempt to play a file without video but the previous file contained video, the new file will also fail in many cases

The video system in iOS has a degree of latency between commands you request and actual changes in playback.

My guess (again, none of this is explained in the documentation) is that this latency occurs because your video commands need to be sent to the separate mediaserverd process in iOS that handles all media playback. This process then makes the required changes and sends back response notifications.

This seems to create a situation where if you cancel the playback of a file and immediately start a new file, some of the properties of the old file will remain for a time.

In the case of playing an audio-only file immediately after a video file, this latency appears to be long enough for the audio-only file to be rejected with an error as though it was a file with video.

Even a file with the video tracks disabled will still fail

If you're using an AVPlayer or AVQueuePlayer, you can disable all the video tracks any time after the AVPlayerItemStatusReadyToPlay notification is sent using the following code:

for (AVPlayerItemTrack *track in player.currentItem.tracks)
{
    if ([track.assetTrack.mediaType isEqual:AVMediaTypeVideo])
    {
        track.enabled = NO;
    }
}

This will stop the tracks playing but despite the tracks being disabled, the effect on background play remains the same: presence of video in the file still causes the player to pause.

How StreamToMe has handled video in the background

As you can tell by the summary of experimentally determined functionality above, iOS really strongly doesn't want you to play video in the background.

Frankly, iOS's restrictions in this area are contrary to what people want.

Where iOS makes a huge distinction between audio-only media and media with both video and audio, many users do not. We are accustomed to Quicktime and iTunes and VLC and MPlayer and most other media applications being able to perform all the same tasks with either video or audio.

Even for users who only use StreamToMe to play music, it's hard to avoid video in StreamToMe because StreamToMe puts a still image for the album artwork into a video track to display artwork for music files — in the eyes of iOS, basically every files StreamToMe plays counts as video.

It was necessary to find a way around these restrictions. And so begins the story of half a dozen application updates over 3 major iOS updates.

iOS 4.0

In iOS 4.0, StreamToMe used MPMoviePlayerController and was able, through a bizarre sequence of layer manipulation operations in the MPMovieMediaTypesAvailableNotification method (basically removing the video render layer and reinserting at the right time), to convince the MPMoviePlayerController to proceed, even when it was playing video in the background.

Technically, you didn't need to remove the layer to get it to play in the background (all you needed was to resume after the "UIApplicationDidSuspendNotification" pause) but if you didn't remove the video layer, video frames would still be rendered and queued for display, leading to out of memory problems or weird speedy video quirks when the video came back to the foreground.

I'm not going to share the code that did this: it was messy, not advisable and doesn't work anymore. I was fully aware that this was a bizarre thing to do and that I would need to keep a really close eye on iOS updates to ensure that it kept working.

iOS 4.2

From the betas of iOS 4.2, it became apparent that the layer manipulation would no longer work to allow background video to work smoothly and no combination of actions I could find would make it work again. Playing the audio from a file also containing video looking like it would be impossible.

Fortunately, with StreamToMe, I control both ends of the client-server communication and there was another solution: upon entering the background, StreamToMe could reload the stream from the server with the video track stripped off by the server.

This server reconnection results in a second pause or so (more over 3G) while the new stream was started and sometimes a jump back to the start of the previous HTTP live stream segment but otherwise the experience is tolerable.

However, there was a catch: MPMoviePlayerController didn't like being torn down and recreated in a short space of time. In iOS 4.2, doing this would actually result in an error.

But the new AVQueuePlayer API introduced in iOS 4.1 did support queuing a new stream and then switching to it. In fact, it did it pretty well (after all, that's what the whole "queue" is about). Unfortunately, switching to AVQueuePlayer from MPMoviePlayerController is not a small task: AVQueuePlayer offers no user interface (you have to implement one entirely for yourself) and the entire property observation model is completely different.

The following code sample shows how a switch to a background track was managed in the UIApplicationDidEnterBackgroundNotification. A new "background" variant of the URL for the current item is generated by the STMQueuePlayerController (the StreamToMe class that relates the StreamToMe representation of files to the AVQueuePlayer represenation) is generated, seeked to the same point as the current file, inserted into the queue and played.

if (resyncTask)
{
    [[UIApplication sharedApplication] endBackgroundTask:resyncTask];
}
resyncTask = [[UIApplication sharedApplication]
    beginBackgroundTaskWithExpirationHandler:^{resyncTask = 0;}];

AVPlayerItem *backgroundItem =
    [[AVPlayerItem alloc]
        initWithURL:[[STMQueuePlayerController sharedPlayerController]
            urlForFile:[[STMQueuePlayerController sharedPlayerController] currentFile]
            inBackground:YES
            offset:CMTimeGetSeconds(player.currentTime)]];
[backgroundItem                              // seek the item, not the player
    seekToTime:player.currentTime
    toleranceBefore:kCMTimeZero
    toleranceAfter:kCMTimeZero];
[player insertItem:backgroundItem afterItem:currentItem];

[self stopObservingPlayerItem:currentItem];  // stop observing the old AVPlayerItem
[currentItem release];
currentItem = [backgroundItem retain];
[self startObservingPlayerItem:currentItem]; // begin observing the new AVPlayerItem

[player advanceToNextItem];
[player play];

The resyncTask is ended when this new file sends an AVPlayerItemStatusReadyToPlay and is used to ensure that we don't get suspended while restarting the playback.

Needing to rewrite the code for AVQueuePlayer left a brief gap at the start of iOS 4.2 until StreamToMe 3.3 was released, where background audio was broken in StreamToMe.

iOS 4.3

But iOS 4.3 turned out to be a bit of a one-two punch. On paper, the big change was AirPlay video — the new feature in iOS 4.3 that didn't work with AVQueuePlayer (seriously) — but it turns out that iOS 4.3 also changed how movie players were paused when going into the background. This change to pausing behavior was not clear to me until after iOS 4.3 was released, so StreamToMe's background behavior broke again.

What happened is that StreamToMe used to read whether the stream was currently playing (i.e. not paused) and only transition to the background version of the stream if it was actively playing. Unfortunately, the -[AVPlayer rate] which previously returned 1.0 for a previously playing video stream during the UIApplicationDidEnterBackgroundNotification would now return 0.0 (i.e. reporting that the stream was paused).

The fix is pretty simple: when we receive UIApplicationWillResignActiveNotification we needed to record whether the current file was playing or paused and use that information later in the UIApplicationDidEnterBackgroundNotification (the private "UIApplicationDidSuspendNotification" that pauses the file occurs between these two notifications).

Unfortunately, I didn't realize until the last moment on an update that the AVPlayerLayer had also started pausing audio-only files, not just files with video. To me, this seems like a significant change in behavior; why should an audio-only file suddenly start getting paused when the application enters the background? It's not my fault but I need to fix it anyway — unfortuntely due to the slowness in realizing this problem, this separate fix for audio-only files in StreamToMe (files with neither video nor album artwork in a video track) had to be held over until the 3.5.4 update.

More than StreamToMe was affected: iOS 4.3 actually broke background video for Apple's apps too. While Apple's apps (iPod, Movies, Safari, YouTube) have always paused the current video when switching into the background, you used to be able to resume the video from the multitasking bar, lock screen or headphones. From iOS 4.3, this behavior has been blocked; the video may play for a fraction of a second but then will immediately stop again.

3G and slow WiFi affecting background audio?

Even after fixing these problems it turns out iOS 4.3 had one more suprise. It now appears that the code I showed above that handles the track change:

[player insertItem:backgroundItem afterItem:currentItem];
[player advanceToNextItem];
[player play];

will work on a local WiFi network but on a high latency WiFi or 3G connection can cause the proper, background-safe version of the file (which is the "next item" loaded here) to be rejected.

Why on earth would the speed of the network affect this?

I'm not entirely certain but it appears that when the network is fast enough, the command:

[player insertItem:backgroundItem afterItem:currentItem];

actually fetches the first segment of the stream and updates all the track information, so it correctly realizes that there is no video track.

But on a slower network, this first segment of the stream is not loaded so the call to [player play]; immediately results in an error and the file being rejected from the stream.

The fix for this is that you need to defer the call to [player play]; until after a AVPlayerItemStatusReadyToPlay notification is sent for the new file.

Yuck.

Why was this not caught in testing?

As I write this, the current version of StreamToMe is 3.5.4 and it still contains this 3G/slow WiFi problem.

Yes, I know what the cause of the bug is. Yes, I already have a fix for it. Unfortunately, the agony of release cycles and the nuisance of the App Store approval process means that I'm going to sit on this fix until I've finished the other features I wanted to include in the next update — the background audio over 3G/slow WiFi is simply too narrow a niche to justify an update right now.

However, there's one thing I've noticed about media application users: people seem to use their media within specific niches and if their specific niche isn't working, they're prepared to eviscerate you.

How StreamToMe and ServeToMe are tested

As an independent developer, it is very difficult to handle quality assurance. I don't have a dedicated tester; I have a few people who help me test but they're all volunteers and tend to use the application however they feel. They're not really robust testers. While I use the application all day, I don't really exercise the whole application: on any given day, I focus on pretty specific issues.

Despite these resource limitations, I do have a pretty extensive set of tests. Unfortunately, the scope of the application means that the tests are arguably too extensive for my ability to run them all.

For file compatibility, I have 280 different test files in a regression suite that I run (literally media files in a folder that I run through the program and process the log file to ensure no unexpected errors). This takes 8 hours.

For server functionality, I have a test harness that tests every server command (fortunately, this takes just 30 seconds).

For client functionality, I have a 166 step, user-operated test script. This takes about an hour to perform, sitting in front of the application, pressing buttons in order.

Just 10 hours for these steps but it only tests 1 version of the program.

If you include all the different platforms for which there is platform-specific code, there are 4 versions of the server that need testing (Windows XP, Windows 7, Mac OS X 10.5, Mac OS X 10.6) and 6 versions of the client (iOS 3 on any iOS device, iOS 3.2 iPad, iOS 4 on iPhone 3G, iOS 4 on iPhone 3Gs, iOS 4 on iPhone 4, iOS 4 on iPad).

You should realize that just running this suite in these testing environments would take me about a week. And that's if I worked non-stop on StreamToMe, which I don't.

But the bug slips through: how do you fix it?

It is unreasonable for me to fully test minor releases and sometimes minor issues slip through. Needing to limit testing so that it is manageable has resulted in some minor bugs but it does not describe why this latest 3G/slow-WiFi problem escaped testing.

Even if I had run my full test suite on version 3.5.4 of StreamToMe, it would not have detected the problem between 3G and background audio. This is because the test script tested background audio on local WiFi — you don't generally insert repeats of tests into your script unless you suspect something about the repeat in a new context will actually affect the test. In this case, I had no reason to suspect that the two ideas would be connected.

An interesting thought to consider here: the code coverage through my program is identical on local WiFi and 3G. The difference is either somewhere in Apple's code or purely a timing problem.

All you can do in these situations is add the scenario to your test cases, fix the bug and makes sure it keeps getting tested in new releases.

Conclusion

I hope you can see that even when APIs are documented, the usage and implications of the API can be unknown and subject to misunderstandings and change over time. The fact that video cannot play in the background is barely mentioned by the documentation but the details of video being paused, stopped or rejected with an error is completely absent from documentation (you will only discover this by experimentation).

Lack of information is always hard to deal with in testing. You can only exercise documented or otherwise suspected behavior, and even so, you need to be practical. You can't simply say: test everything about background audio. You need to formulate your tests based on what you think is likely to have different effects.

The decision by Apple to forbid video in the background is frustrating and puzzling from my perspective. Why can't iOS simply ignore video packets in the background — particularly for disabled tracks? I can only presume that there's a technical reason for this behavior but since we haven't been informed of the boundaries, it remains frustrating.

Additionally, the entire iOS environment makes this type of problem exceptionally difficult to characterize and test. UI automation is insanely difficult in iOS and even if it improved (I'm keeping my eye on Cucumber+Frank) it probably wouldn't be able to exercise background switches and realtime and network issues easily.

User interface strings in Cocoa

2011-04-05T21:57:00.001-07:00

In this post, I'll look at best practice for using and managing text strings in your user interface. This is a fairly simple topic but Cocoa has established "best practices" for handling user interface strings that new Cocoa developers should be aware of. Since it is inevitably related, I'll also look at the steps involved in localizing the strings in your applications but remember: you should follow good practice for string handling, even if you have no intention of ever translating your application.

Introduction (the wrong way)

Putting a text string in your user interface is not a difficult thing to do on a technical level. In code, filling in text can be as simple as setting the text property of a UILabel to a literal string:

someUserInterfaceLabel.text = @"Text to display";

(This code is for an iOS UILabel. On Mac OS X, you would set the stringValue property of an NSTextField but otherwise the step is the same.)

While this will work, you should never set a user interface string this way.

Setting labels with literal strings (the right way)

The most thorough way to put a literal string into your Cocoa application's user interface is:

someUserInterfaceLabel.text =
    NSLocalizedStringFromTable(
        @"Text to display",       // the native language string
        @"SomePageLabels",        // the category
        @"Label display string"); // a comment describing context

This is pretty verbose though. It is often okay to just use:

someUserInterfaceLabel.text = NSLocalizedString(@"Text to display", nil);

If you take no other steps, this will produce exact the same output as the "wrong way" example.

You should always use the NSLocalizedString[...] macros for every user interface string in your code.

But wait... this NSLocalizedString[...] stuff requires more typing and unless you take yet more additional steps, it won't have any functional difference? If I'm not planning to translate my program right now, aren't they a complete waste of time?

Why NSLocalizedString is important, even if you don't intend to translate

Obviously, the NSLocalizedString[...] functions (and the less common CFCopyLocalizedString[...] variants) are functions that exist to enable localization (i.e. letting you translate your application into different languages).

Technically, they're not even functions — they're just macros that invoke the -[NSBundle localizedStringForKey:value:table:] method — but you should always use the macro and not the underlying method for reasons I'll discuss in the "Mechanics of Translation" section below.

However, even if you're not intending to ever localize your application, you should always use NSLocalizedString.

There are a few reasons for this:

Futureproofing: The future is hard to predict: you never know if you'll want to translate in the future. Needing to go through your code and find rogue literal strings is time consuming and prone to mistakes. Instead, everything should always have NSLocalizedString from the beginning.
MVC practices: It keeps the exact details of your model/presentation layer at least one level of indirection removed from your controller code. In some cases, you can simply change the .strings files for your program to update the user interface and not need to change code due to this separation.
Separation of concerns: It clearly identifies text strings intended for user presentation as opposed to text strings used as keys for programming use only.
Discourages other bad practices: with your user interface strings detached from your controller, you'll be less likely to try to read static strings back from the user interface (a very bad idea) or place programmer-targetted strings in the user-interface.

Get into the habit of using NSLocalizedString. It's really simple to do — even when you're hacking code together quickly, you should be able to use it.

The first two points in the previous list are self-explanatory but the second two merit further explanation.

Separation of concerns

It is always helpful in programming to be able to glance at code and understand the intent. Consider the following piece of code in isolation:

[someDictionary setObject:@"value" forKey:SomeKeyNameString];
[someDictionary setObject:NSLocalizedString(@"value", nil) forKey:SomeOtherKeyNameString];

Without knowing what someDictionary is for or what the purpose of the SomeKeyNameString and SomeOtherKeyNameString values are, we know that the second string is intended for display in the user interface at some point whereas the first string is purely for tracking a value internally.

This clear labelling of intent is helpful as strings for user display have a very different role in a program compared to strings for internal use.

Discourages other bad practices

If you treat NSLocalizedString in your mind as though its output is a black box, this can help you avoid poor controller design when managing user interface elements. It can act as a conceptual tool to encourage you to design things the right way, instead of a lazy way.

Your controller code should treat user interface strings as something that can be written but not read. Reading static strings back from the user interface is always bad (it ends up being a form of "common or data coupling" — a bad design practice).

In the "Separation of concerns" example above, you might consider that since the keys SomeKeyNameString and SomeOtherKeyNameString are defined in global variables in this example, that perhaps you'd want to define your localized strings in global variables. In most cases a global variable for a user string is actually a bad idea.

We define dictionary keys in global variables because more than one location in the program may need to use exact the same value or the exchange of information between the two points will fail. But with user interface strings, you should never have a second piece of code that requires the exact same value: you should never read back from the user interface or require user interface collusion. Generally, the only situation where the same string should appear multiple times is if the same user interface code is displaying it (i.e. you're drawing the same object) but in this case, the code is common and the string should only need to appear once in the code.

If you need to uniquely identify a label or the state of a text displaying item, testing the text it contains is the wrong way to do that. A far better way is to use the tag value of any UIView/NSActionCell and then map the tag value onto the object's role or function (tag is a pointer sized value so you can store a non-retained object reference here if needed, not just an integer). The tag property is not reserved for any other purpose; it is intended for the controller to track user interface items and their state.

Mechanics of translation (when you're ready)

Eventually, you may actually have to translate your program. Let's look at the steps involved.

Create your ".strings" files

The files you need to translate are the ".strings" files in your application. By default though, your project probably won't have any ".strings" files (except possibly an InfoPlist.strings file which is for translating your Info.plist file's strings).

The first step is to make sure you have a localized directory somewhere (probably in the Resources subdirectory of your project's folder). The localized directory should be named "en.lproj" if you're starting with English strings, otherwise you'll want to replace "en" with the appropriate ISO 639-1 or ISO 639-2 designators. If needed you can use the script and region identifiers too as described in Apple's Language and Locale Designations.

A note on folder names: it is common to see "English.lproj" used as the name for English localization instead of "en.lproj" — in fact, Xcode 3 still generates folders with this name if you Get Info on a file and select "Make file localizable". Apple have stated that these old, "full" names are deprecated from Mac OS X 10.4 onwards in favor of ISO 639-1 or ISO 639-2 designators. Don't use the old "English.proj" style names anymore and replace with "en.lproj" if it is autocreated (yes, you might need to update your Xcode paths if you change the folder name).

Now we can create ".strings" files automatically from all the NSLocalizedString references in your program. To do this, open a Terminal in your Project's root directory and run the following command:

find -E . -iregex '.*\.(m|h|mm)$' -print0 | xargs -0 genstrings -a -o Resources/en.lproj

This will process all .m, .h and .mm files in your directory hierarchy and create ".strings" files for them in the en.lproj directory (note, the en.lproj directory must already exist). This assumes that the localized resources directory you created is located at "Resources/en.proj", relative to your Project's root directory; obviously, you'll need to change this if your localized resources are elsewhere.

The ".strings" file will be filled with entries that look like this:

/* This comment provided comes from the last parameter of the NSLocalizedString macro. */
"Some UI string %@ to translate %@" = "Some UI string %1$@ to translate %2$@";

Your translator just needs to translate the right-hand side of the equality statement. Notice that placeholders in your strings are given ordinal positions (1 and 2 in this case) so that the translation can change the order of placeholders if necessary (obviously, if you use placeholders, you should include a comment that explains what they're going to be).

Localization versus Internationalization: generally, the whole process of creating new language variants is referred to as localization. In reality though, it comprises two steps:

Internationalization: where you decouple the program from the original locale

Localization: where you add translations and behaviors for each new locale
By that terminology, the inclusion of NSLocalizedString wrappers and the creation of ".strings" files is the "Internationalizing" phase.

genstrings will only handle static NSLocalizedString and CFCopyLocalizedString strings

The only strings that will be automatically extracted are those wrapped in NSLocalizedString[...] and CFCopyLocalizedString[...] macros. Obviously, all your user interface text needs to be wrapped in these but also remember that the underlying -[NSBundle localizedStringForKey:value:table:] method will not be automatically extracted.

Why would you ever use -[NSBundle localizedStringForKey:value:table:] directly then? The answer is for dynamically generated strings.

The genstrings command will raise an error if it detects anything other than a static string in the localization macros. This is appropriate because you don't want your translators translating variable names and function calls (they only need to translate the results of those calls).

The answer to why you would use -[NSBundle localizedStringForKey:value:table:] is then: the actual strings to be translated are located elsewhere in the code (or are in a ".strings" file that was not generated from code) and you are simply looking them up dynamically.

Encoding problems

From Mac OS X 10.5 onwards, you can put any UTF-8 characters in your NSLocalizedString constants. Prior to this, they were required to be pure 7-bit ASCII with all Unicode escaped with \\Uxxxx style escaping or you could use MacRoman with the -macRoman command-line option to use MacRoman high-ASCII characters.

A quick swipe at almost everybody: UTF-8 has been around since 1993 and Unicode 2.0 since 1996; if you have created any 8-bit character content since 1996 in anything other than UTF-8, then I hate you.

I weep to think of the years of programmer time that are still wasted attempting to support non-Unicode formats without characters getting garbled because people are still creating content using ancient encodings without useful identifiers to indicate what nonsense encoding they're using (or worse, people creating content that explicitly uses the wrong encoding for an encoding-specific text field).

MacRoman? Atrocious. Big-5? I hope you want to see garbage output. Windows Latin? You suck. If you're creating new content using anything other than UTF-8, UTF-16 or UTF-32 then you should be forced to serve prison time with whatever idiot monkey decided that UTF-16 should be allowed little-endian and big-endian variants instead of a single authoritative encoding.

The actual text files generated by genstrings are UTF-16 in whatever byte order your system happens to use. i.e. UTF-16BE on PowerPC and UTF-16LE on Intel Macs.

Grumble.

Translating XIB files

Not all your strings will come from your code. The other common text location is in XIB files. XIB files can be a little bit trickier than strings in code due to two factors:

While you can extract the strings from a XIB file easily, you also have to merge them back in once the translation is complete — basically another step that can go wrong
The ".strings" file format extracted from XIB files is uglier and doesn't have easy room for comments to send to the translator

For these two reasons, I generally avoid putting text in XIB files if reasonably possible — it is normally easier to have text inserted at NIB load time by the code. Of course, menus, button labels and automator labels can't reasonably be moved into code so you're still likely to need a number of XIB files translated.

You extract the .strings from XIB files in a similar way to extracting the strings from code. However, first we must make all of our XIB files localizable (if they aren't already).

To localize your XIB files, select them all in the Xcode project Group Tree, Get Info on them and then from the first tab, select "Make file localizable".

Then, go to the localized directory where your files all ended up (if there's multiple, you'll need to do this for each one) and run the following in Terminal:

for file in *.xib; do
    ibtool --export-strings-file "$file".strings "$file"
done

This will generate all the ".strings" files for your XIB files.

Once the ".strings" files are localized, create a new ".lproj" directory with the appropriate language name for the new translations and put all the ".strings" files in it. Then open a Terminal in this new folder and run:

for file in *.xib.strings; do
    basename=`basename "$file" .strings`
    ibtool --strings-file "$file" --write "$basename" "../en.lproj/$basename"
done

This will merge all the ".xib.strings" files in the current directory with the XIB files from the en.lproj directory, creating the translated XIB files.

Translating other resources

The same "Make file localizable" step that we used for the XIB files in the previous section can be applied to any resource file in your Xcode group tree so you can localize other resources in whatever way is apppropriate.

Here's a tip though: avoid localizing anything other than strings and XIB files by whatever means possible. Having non-strings files for translation will cause you nothing but pain and suffering.

In particular: avoid localizing images. Work as hard as you can to keep all text out of images (except in logos that don't require translation). You can perform quite sophisticated drawing and text handling in Cocoa code if needed and this will almost always be easier than localizing images.

I haven't really touched on non-string code localization topics in this post. There's date, time, numbers, error descriptions and other stuff — most of the time, the classes and APIs for these make it clear what you need to do. Just read Apple's Internationalization documentation.

Conclusion

Most programmers should already know the information in this post. Numerous other Mac programming blogs have discussed the topic:

See how anciently old those second two links are? I'm not telling you new information. The advice remains the same: always, ALWAYS use NSLocalizedString for your user interface strings.

Actual translation can happen later or not at all — my point is that your need for translation (or lack of need) should not determine whether you use NSLocalizedString as it is best practice in any case. Of course you can rest assured that translation will all work out if your code is already NSLocalizedString-compliant.

Mac QuartzGL (2D drawing on the graphics card) performance

2011-03-25T04:45:00.001-07:00

QuartzGL was introduced as an official feature in Mac OS X 10.5 Leopard (although it was a developer-only feature in Mac OS X 10.4 as Quartz 2D Extreme). However, it is off by default and is largely ignored by most developers. In this post, I look at how to enable QuartzGL, the performance impact it has on different kinds of drawing and whether you should use it in your Mac programs.

Introduction

A graphics card can render 3D graphics hundreds of times faster than a CPU and graphics cards are used to accelerate compositing of windows on the desktop for a many-fold performance increase.

Despite the advantages of graphics cards in these areas, 2D geometry on the Mac is normally generated by the CPU in main memory. You can opt to have your program drawn on the graphics card instead but this option is off by default. This 2D on the graphics card drawing is named QuartzGL.

QuartzGL works by generating an an OpenGL ARB_fragment_program (pixel buffer drawing commands) and performing on the graphics card what would ordinarily be performed on the CPU.

It shouldn't take you very long to guess the reason that it is disabled by default: QuartzGL does not improve all kinds of drawing. An ARB_fragment_program does not use the same geometry processing that 3D graphics relies upon, so it's unlikely to be the most optimized part of the GPU. For some kinds of drawing, it will perform considerably worse than regular CPU-based drawing. The question I hope to answer is: what kinds of operation go faster, what kinds are unaffected and what kinds might go slower?

How to enable QuartzGL

You can enable QuartzGL for your program by editing your Info.plist file. Just insert a boolean value QuartzGLEnable and set it to true.

<key>QuartzGLEnable</key>
<true/>

Of course, you could also do this for any program if you wish. Edit the Info.plist and see what happens the next time you run it.

The test code

I'll run three tests:

drawing semi-transparent rectangles
drawing text
drawing randomly placed lines

If you're curious about why I'm testing these: I experimented with a number of different drawing primitives and decided that these were the most common drawing primitives that produced the most widely varying results.

This is the drawing code:

#if TEST == 1

    [[[NSColor redColor] colorWithAlphaComponent:0.01] set];
    for (NSInteger k = 0; k < 1000; k++)
    {
        [[NSBezierPath bezierPathWithRect:rect] fill];
    }

#elif TEST == 2

    for (NSInteger j = 0; j < 2000; j++)
    {
        NSString *displayString =
            @"A string to excercise basic Cocoa text drawing.";
        [displayString
            drawAtPoint:NSMakePoint(0, 0.5 * self.bounds.size.height)
            withAttributes:nil];
    }

#elif TEST == 3

    [[NSColor grayColor] set];
    for (NSInteger l = 0; l < 2000; l++)
    {
        CGFloat xCoord1 = self.bounds.size.width * random() / (CGFloat)INT_MAX;
        CGFloat xCoord2 = self.bounds.size.width * random() / (CGFloat)INT_MAX;
        CGFloat yCoord1 = self.bounds.size.height * random() / (CGFloat)INT_MAX;
        CGFloat yCoord2 = self.bounds.size.height * random() / (CGFloat)INT_MAX;
        
        NSBezierPath *line = [NSBezierPath bezierPath];
        [line moveToPoint:NSMakePoint(xCoord1, yCoord1)];
        [line lineToPoint:NSMakePoint(xCoord2, yCoord2)];
        [line stroke];
    }

#endif

Test results

You can download the complete project for the QuartzGLTest (32kb).

I ran the test on a 2.66Ghz Quad Core Mac Pro with an ATI Radeon HD 4870 graphics card. I used the Quartz Debug program to disable "Beam Sync" during the tests. The window in the test application is resizeable but I ran it at the default 480 by 400 pixel content size.

The raw FPS rates here are not really important (I chose the number of iterations fairly arbitrarily). The important point is the relative difference between the QuartzGL and CPU tests.

As you can see, QuartzGL's impact ranges from nearly a 10 times performance improvement in the best case, through to an 83% speed reduction.

Conclusion

The performance improvement for semi-transparent rectangles is considerable but it is hard to recommend QuartzGL in general. Time consuming drawing operations are likely to have an even mix of both lines and flat color areas, resulting in a negligible difference either way.

I spent some time once talking with an engineer who had worked on what was then Quartz 2D Extreme. He gave the impression that Apple had been initially very hopeful about its potential — as were many onlookers like myself. It just seemed like drawing on the graphics card should be 10 times faster for everything. But as this engineer related, they simply could get around bottlenecks that kept the whole system at disappointing speeds.

Ultimately, you are more likely to improve drawing performance more through reducing redraw than through increasing draw speed. For example, you could cache areas of your drawing in CoreAnimation layers, eliminating the need to redraw and relying on what your graphics card does well: compositing. As an aside, CoreAnimation appears to disable QuartzGL so you can't do both.

It's unclear if graphics card drawing will improve in future. I doubt the current ARB_fragment_program implementation will ever see dramatic improvement but with OpenCL and other forms of GPU-based programming, it certainly feels like a reimplementation using a newer technology could yield better results. Of course, this "feeling" didn't help the original ARB_fragment_program implementation succeed. Additionally, OpenCL remains constrained by features that only work on specific graphics cards (like image buffers). And OpenCL doesn't change the bottleneck of transferring data backwards and forwards between the CPU and graphics card (something which does not necessarily improve even when the CPU and GPU themselves increase in speed).

Finally, none of this should be taken as an indication that Quartz drawing on the CPU is particularly slow; it's not. But if you're wondering if you could squeeze a little extra performance out of your program by switching to QuartzGL — probably not unless the key limitation in your program is raw pixel fill rate and you have relatively few lines.

A history of iOS media APIs (iPhone OS 2.0 to iOS 4.3)

2011-03-20T05:26:00.001-07:00

After initially starting with a small set of fairly basic media APIs in iPhone OS 2.0, the APIs and the features they provide have dramatically increased in the past 2 years and provided a rapidly moving target for developers trying to remain current. In this post, I'll try to summarize all of the different APIs in iOS 4.3 for playing media, when they arrived, what their purposes are, what their limitations are and what it's been like to remain up-to-date and support new features.

Introduction

This post has two purposes:

To detail the different media APIs in iOS and to explain the scenarios to which they are best suited.
To show how many updates have been made to the media APIs and what that has meant to any iOS developer attempting to keep their media applications compiling successfully against the latest SDKs and up-to-date with the latest media features in iOS.

Note: I'll be limiting discussion to time-based media in this post, i.e. audio and video APIs. I realize that still photos are "media" but since photos are generally handled as basic graphics, they are handled in a very different manner to audio and video which use specialized hardware processing and handling in iOS.

I was inspired to write this post while working on StreamToMe version 3.5.2 — an update to one of my applications to improve the experience of users running iOS 4.3. Nominally, iOS 4.3 only added logging features to some media classes and added an "allowsAirPlay" property to the MPMoviePlayerController. Despite these seemingly limited changes to the APIs, StreamToMe still required some significant changes to work smoothly and deliver the features that users expect in iOS 4.3.

But I'm getting ahead of myself.

iPhone OS 2.0

Playback APIs

The first version of iPhone OS available to developers arrived with 5 media playing APIs:

AudioUnits/AUGraphs
AudioQueues
MPMoviePlayerController
AudioServicesPlaySystemSound
UIWebView

AudioUnits/AUGraphs are the "low-level" API in both Mac OS and iOS. If you want to process audio in any way, mix more than one source of audio, want to generate your own samples or otherwise access the raw Linear-PCM values, these have always been the best option — in many cases, close to the only option.

I've previously written a post showing what is probably the simplest possible AudioUnit program: an iOS Tone Generator. Of course, most people require considerably more complexity than this. A good next step if you're trying to learn about lower level audio APIs is the MixerHost sample project you'll find in the iOS documentation. Apple tend to favor C++ wrappers around these C APIs so you may also want to be familiar with the classes in AUPublic folder — you can start to see how these are used by looking at the very similar iPhoneMultichannelMixerTest.

AudioQueues are for playing or recording buffers of data. AudioQueueNewInput remains a common means of capturing microphone input and AudioQueueNewOutput is a common way to play to the speaker. The AudioQueue API is, like AudioUnits, a pure C API still requires a fairly meticulous set up. Where AudioUnits require that you push PCM samples into buffers yourself, AudioQueues let you push the buffers and not worry about the sample format. In fact, AudioQueues generally deal with buffers of still-compressed MP3 or AAC data.

I've written a series of posts on using AudioQueues (in conjunction with AudioFileStream) to play from an HTTP stream starting with Streaming and playing an MP3 stream and ending with Streaming MP3/AAC audio again

AudioServicesPlaySystemSound will play up to 30 second segments. Its purpose is really for brief UI or notification sounds played asynchronously. You create the sound using AudioServicesCreateSystemSoundID and then play with AudioServicesPlaySystemSound. Not much more to say than that.

Living out on its own in iPhone OS 2.0, was MPMoviePlayerController — the only Objective-C class for media playback in iPhone OS 2.0. It offered no programmatic control other than play, no options to configure the UI or movie and no feedback about state. You gave it a URL (either file or HTTP) and it presented the interface, handled the entire experience and posted a notification when it was done. The canonical code example used to be the MoviePlayer sample project but this has not been updated since iOS 3.0 and since iOS 4.0 broke backwards compatibility with this class, you'll need to ensure that the MPMoviePlayerController's view is inserted into the view hierarchy before this project will work.

UIWebView offered an experience similar to MPMoviePlayerController but had an added advantage: it was the only way to output over the TV out dock cables until iOS 3.2 (MPMoviePlayerController, despite being implemented by the same internal private classes, has this functionality disabled). While playing a movie through UIWebView didn't break in iOS 4 like MPMoviePlayerController did, the ability to play to the TV went away without explanation.

Media support APIs

AudioFile
AudioFileStream
AudioSession
OpenAL
MPVolumeSettingsAlertShow
MPVolumeView

AudioFile offers a fairly rich set of metadata and parsing functions for files that are fully saved to disk. AudioFileStream offers a limited subset of the AudioFile functionality but has the advantage that the file doesn't need to be fully saved or downloaded — it can be a continuous source or progressive source.

AudioSession is mostly for handling audio routing (is the audio going to the headphones or the speaker) and for determining how your application's audio is blended with audio that other applications may be playing. If you need to handle interruptions (like when an iPhone rings) this API will help you.

OpenAL is an audio standard for controlling the positioning of the audio in 3D — mostly used for games. You can look at the oalTouch sample project for an example of how to set this up in iOS.

The MPVolumeSettingsAlertShow and related functions show a dialog so the user can change the volume. The MPVolumeView is a slider so that the user can change the volume.

Code maintenance considerations

Code written using AudioUnits, AudioQueues, AudioSessions and AudioServicesPlaySystemSound for iPhone OS 2.0 will generally continue to work in the latest version of iOS (iOS 4.3). Despite additions to these APIs, backwards compatibility remains high. However, many new classes like AVAudioPlayer, AVPlayer, AVAudioRecorder, AVAudioSession and AVCaptureSession provide alternative ways of doing similar things so you may need to consider these alternatives compared to these earlier APIs.

As I mentioned, MPMoviePlayerController code written for iPhone OS 2.0 but linked against iOS 4.3 SDKs will likely not work since this code requires a view be inserted into the hierarchy starting with iOS 3.2.

UIWebView stopped outputting over TV out in iOS 3.2 so there's no longer a real reason to use a web view instead of a real movie view.

I rarely use the AudioFile APIs anymore. It's not due to compatibility issues but instead I feel it's been superceded: AudioFileStream (rather than AudioFile) is required for streaming or progressive downloads, AVAudioPlayer (iOS 2.2) is easier for playing files stored on the device (apparently it uses AudioFile/AudioQueue internally) and ExtAudioFile (iOS 2.1) can convert between media formats using the hardware and hence can plug into an AUGraph better.

In my experience, the MPVolumeView slider is more commonly used than the MPVolumeSettingsAlertShow dialog — with MPVolumeView supporting AirPlay audio in iOS 4.2 and later, the MPVolumeView become even more compelling. It used to infuriate me that in the simulator, the MPVolumeView simply didn't appear — it worked fine on the device but didn't draw itself in simulator (many hours were lost around wondering if its absence was a bug). The MPVolumeView still doesn't appear in the simulator (for no reason I can understand) but at least it now draws a label saying "No volume available".

iPhone OS 2.1

Arriving just 2 months after iPhone OS 2, iPhone OS 2.1 brought audio conversion as the main addition to the SDK. The AudioConverter functions introduced various forms of PCM conversions and conversions to and from compressed audio formats (MP3 and AAC).

The ability to convert MP3/AAC was important since it could take advantage of the audio hardware (previously decompression required software handling which consumes much more battery power).

Since the primary purpose for audio conversion is to allow a file — like an MP3 — to be opened and fed into a processing pipeline like an AUGraph, the ExtAudioFile functions were also added to streamline this process.

Code maintenance considerations

If you had code that decompressed audio in software or performed PCM conversion in anything less than an optimal manner, it was now a waste of CPU cycles relative to newer code that used these APIs.

iPhone OS 2.2

Arriving just 2 months after iPhone OS 2.1 (now just 4 months after iPhone OS 2) the iPhone OS 2.2 update introduced the AVAudioPlayer — the first Objective-C API for dedicated audio playback in iPhone OS. The AVAudioPlayer requires that the file be fully saved on your iOS device (so it isn't suitable for continuous streams, network streams or progressive downloads).

Code maintenance considerations

If you had code that used AudioFile and AudioQueue, chances are that it would have been much easier to write your program using AVAudioPlayer instead — however, AudioFile and AudioQueue continue to work, so there was no need to update to AVAudioPlayer. Later on, AVPlayer superceded almost all of AVAudioPlayer's functionality (with the exception of audio metering and playing from a non-URL buffer) so you need to consider if this is still the class you want to use.

iPhone OS 3.0

Arriving approximately 1 year after iPhone OS 2.0, iPhone OS 3.0 brought the following media APIs:

AVAudioRecorder
AVAudioSession
MPMediaQuery, MPMediaPickerController and MPMusicPlayerController classes

AVAudioRecorder provided the first Objective-C approach for recording sound. It offers a simple way to record sound to a file but doesn't allow processing of the sound on-the-fly (for that, AudioQueueNewInput is still required).

AVAudioSession provided an Objective-C approach for managing the application's audio session but bizarrely, it still lacks any facility for handling routing changes (i.e. a switch from the headphones to the speaker or to the dock connector). For this reason, I still generally avoid this class — the AudioSession C functions are clean an simple enough that sacrificing functionality for the improved simplicity of AVAudioSession doesn't seem like a great tradeoff.

The MPMediaQuery, MPMediaPickerController classes and MPMusicPlayerController added the ability to browse, control or play music from the user's iTunes library on the device. This allows you to offer basic library browsing and playing capability. In iPhone OS 3, there was no way to apply different processing to the files — you had to use MPMusicPlayerController.

Arguably though, the 2 biggest media additions in iPhone OS 3 didn't require a new API: HTTP live streaming and video capture on the iPhone 3Gs. Video capture was added into the existing UIImagePickerController and the MPMoviePlayerController added handling of HTTP live streaming.

While MPMoviePlayerController has always supported opening an MP4 file over HTTP, this has three major disadvantages:

It is not really optimized for streaming (so the many HTTP byte range requests required can end up being slow).
An MP4 file can't be generated on-the-fly (so it's not suitable for continuous sources, live remuxed sources or live transcoded sources).
You can't dynamically change bitrate on an MP4 file (you can't handle 3G and WiFi bitrates in a single URL).

All of which were addressed by Apple's HTTP live streaming.

Code maintenance considerations

HTTP live streaming did bring with it the following additional problems:

As a new protocol, the segmented MPEG-TS and M3U8 files required completely new software to generate them.
It was initially only supported by MPMoviePlayerController (no other interface could be used except UIWebView which was just a different way of presenting the same interface).
You don't have any access to the transport layer — all communication is handled by Apple's internal libraries making careful control of network access difficult or impossible.

The MPMusicPlayerController's remote controlling of the iPod application is still relevant but since iOS 4.0 introduced the ability to get the URL and play the music in AVAudioPlayer or AVPlayer instead, MPMusicPlayerController's playback capabilities seem limited.

Despite adding video to UIImagePickerController, you still were not able to get a live image from the camera or programmatically take a picture. Still image capture didn't arrive until iPhone OS 3.1. Actual movie capture didn't arrive until iOS 4.

In iPhone OS 3, you couldn't get a URL for MPMediaQuery results, meaning that you could play files from the user's iTunes library but couldn't do anything interesting. It wasn't until iOS 4 that you could finally get a URL (a weird "ipod-library" URL) that could be used to open the file in lower-level audio APIs to actually perform processing, mixing or other more interesting effects to music.

With HTTP live streaming in place, Apple introduced bitrate restrictions for media into the App Store submission guidelines. This meant that you needed to update your code to throttle streaming audio connections over 3G yourself (a tricky thing to do since NSURLConnection won't generally do this and you need to resort to CFHTTPReadStream), and all HTTP live streams over 3G needed to have a 64kbps fallback variant. If you've ever tried to squeeze video into 64kbps, you'll know how tight a restriction that is.

AVAudioSession's inability to handle routing changes prevented it from properly superceding the older AudioSession functions.

iPhone OS 3.1

UIVideoEditorController was the only significant media addition in iPhone OS 3.1. It allowed you to present the trimming/re-encoding interface for videos stored in the user's Photo Library.

iOS 3.2

The first iPad release and the first release to be named "iOS" made two changes that were significant to for media playback: the addition of multiple screen support and a radical overhaul of the MPMoviePlayerController.

Prior to iOS 3.2, the only App Store legal way to output via the dock connector to a TV was to load a movie in a UIWebView and let the movie player in the web view connect to the TV screen and output via the dock connector. With the iPad, you could finally use UIScreen to find additional screens and place your views on that screen instead of the main screen.

MPMoviePlayerController was finally overhauled to provide a lot of the feature it sorely needed:

Inline (non-fullscreen) playback if desired, with smooth switching between fullscreen and non-fullscreen
Ability to programmatically seek and get the current playback point
Ability to set the control style (including disabling the standard user-interface entirely)
Provided a location to actually insert a background image if desired

The "set and forget" movie player was reborn as MPMoviePlayerViewController, a UIViewController that handles all display and handling automatically and which handles all communication with its internal MPMoviePlayerController automatically.

Code maintenance considerations

While older MPMoviePlayerController code linked against previous SDKs would continue to work, if you ever linked the code against a iOS 3.2 SDK or newer, it would now fail since the new MPMoviePlayerController requires its view be inserted into the view hierarchy or that fullscreen be set to YES.

Remember: Apple rarely allow you to link against anything except the newest SDK, so any attempt to recompile old projects with MPMoviePlayerController code will result in no video being shown unless you update the code. For this reason, Apple's MoviePlayer sample project continues to not work (they haven't updated since iPhone OS 3.0).

Given the size of the iPad screen, users now expect a non-fullscreen view to be possible.

The "Done" button of the MPMoviePlayerController (visible in fullscreen) no longer ends the movie. It just pauses it and shrinks it to the inline (non-fullscreen) view. This creates another new trait of the MPMoviePlayerController that you must adapt to handle.

iOS 4.0

The biggest update since iPhone OS 2.0, iOS 4 brought a huge number of changes to media APIs.

ALAsset (and related classes)
AVCaptureSession (and related classes)
AVComposition (and related classes)
AVPlayer, AVPlayerItem, AVAsset (and related classes)
The ability to get the URL for an MPMediaItem
startVideoCapture and stopVideoCapture in UIImagePickerController
UIScreen and MPMoviePlayerController changes from iOS 3.2 brought to non-iPad devices
Background audio
beginReceivingRemoteControlEvents and endReceivingRemoteControlEvents

The huge additions to the AVFoundation.framework — particularly the AVPlayer and AVComposition class hierarchies — reflect Apple providing APIs that replace what Quicktime's API used to provide on the Mac: sophisticated media handling that could be used to implement a complete music or movie editing program if required. Ultimately, since Quicktime 7 is deprecated in favor of Quicktime X on the Mac, I expect that these APIs will probably appear in a future version of Mac OS X and represent multi-track mixing, editing and composition in Cocoa for the future.

AVPlayer in iOS 4.0 ultimately didn't offer any advantages over MPMoviePlayerController for playing regular media. AVPlayer is required for playing AVCompositions but for regular files, it was largely the same as MPMoviePlayerController with the user interface disabled (made possible since iOS 3.2).

The ALAsset classes finally provided a way to search through the photo and video media without using the UIImagePickerController. It also provided a better way to handle reading and writing photo and video media to the user's photo library.

AVCaptureSesssion and the other AVCapture classes finally provided the ability to capture video data without the UIImagePickerController interface and perform realtime processing of video data. The classes also included the ability to handle audio capture too, providing an alternative to the AudioQueueNewInput function for processing audio while it is recording (remember AVAudioRecorder will still let you record audio direct to a file without processing).

Background audio was largely painless — just a setting in your Info.plist — although trying to get videos to continue playing their audio in the background is a near impossibility (you need to disable the video track or if you're using HTTP live streaming, you need to restart the stream without video or iOS will forcibly pause playback when you hit the background).

Code maintenance considerations

iOS 4.0 required updating of all MPMoviePlayerController code for non-iPad devices in the same way that iOS 3.2 required updating for the iPad.

AVPlayer has no built-in interface. You must entirely create it yourself. This remains a problem for anyone who needs to use AVPlayer instead of the standard MPMoviePlayerController because implementing video playback controls can take a long time and requires a lot of subtle features.

UIWebView stopped playing to the TV in iOS 4. No idea why but this functionality has not returned.

The inline (non-fullscreen) iPhone/iPod version of the MPMoviePlayerController user interface offers no button to return to fullscreen when playing audio. This creates an annoying difference between the iPhone/iPod and iPad versions of the MPMoviePlayerController which you need to handle.

iOS 4.1

The biggest update in this version was the AVQueuePlayer. The iOS 4.0 headers actually hinted at being able to queue multiple items for an AVPlayer but obviously this functionality was held over.

AVQueuePlayer is an important class as it is the only player in iOS that will attempt to cache subsequent items for play to allow nearly gapless playback between items in a list. Like AVPlayer though, it has no user-interface so if you want to use this player, you need to write your own interface completely.

Code maintenance considerations

AVQueuePlayer would be the unambiguously best player in iOS if it:

could provide an inbuilt UI if requested
could use AirPlay video

Until these features are brought to AVQueuePlayer, there are still reasons why you would need to use MPMoviePlayerController instead.

iOS 4.2

The first version of iOS to merge iPad and iPhone/iPod lines. For media APIs, it added the CoreMIDI framework and AirPlay audio support.

AirPlay audio ended up being very simple: any existing MPVolumeView would allow you to select an AirPlay destination for your application's audio. Many applications required zero code changes if they already featured an MPVolumeView.

I have no experience with this framework but from the look of it, CoreMIDI appears to be for controlling MIDI devices over the network, not for actually playing/synthesizing on the iPhone/iPod/iPad so it is perhaps only tangentially related to media on an iOS device.

Code maintenance considerations

If any MPVolumeViews in your program are too small, they won't be able to show the AirPlay controls, so a new minimum width requirement is effectively established.

iOS 4.3

The biggest addition in iOS 4.3 was AirPlay video. In essence this only required you set the flag allowsAirPlay to YES on the MPMoviePlayerController.

Additionally a large set of logging, error tracking and statistics gathering APIs were added to the AV media classes (AVPlayerItemAccessLog, AVPlayerItemErrorLog) and MPMoviePlayerController (MPMovieAccessLog, MPMovieErrorLog).

Code maintenance considerations

The allowsAirPlay flag on the MPMoviePlayerController carries with it an implicit requirement: that you're actually using MPMoviePlayerController. If you've been playing media with a different API, then you'll need to switch to MPMoviePlayerController to take advantage of AirPlay video. This was the biggest change that StreamToMe required for iOS 4.3 — since StreamToMe uses the AVQueuePlayer by default (for its superior track transitions and more detailed track and asset control) it needed to allow switching to the MPMoviePlayerController in the case where AirPlay video is desired. For a program as focussed on media play as StreamToMe, allowing a runtime switch between two interfaces at the core of the program was a big effort. Fortunately, StreamToMe has always had MPMoviePlayerController code for supported iOS prior to 4.1 but this was the first time a dynamic switch between interfaces had been needed.

The second change, much less expected since it wasn't really documented, it that iOS 4.3 no longer lets you observe the playerItem.asset.tracks key path of an AVQueuePlayer, instead you must now observe playerItem.tracks.assetTrack key path to get the same value. Technically while linked against iOS 4.2, you can still observe the old key path even when running on iOS 4.3 but it suddenly incurs a dramatic performance hit. Finding the exact cause of this issue was time consuming — as I said, it wasn't documented in any change notes I could find.

The final point that made compatibility difficult: if you have an MPMoviePlayerController with allowsAirPlay set to YES and useApplicationAudioSession set to NO, and the MPMoviePlayerController wants to launch straight to the Apple TV without displaying on the local device first, then the entire movie player interface disappears, never to return. This is undoubtedly a temporary bug but it provided another unexpected reason to make maintenance updates to StreamToMe.

Conclusion

This has been a lot of classes and functions to summarize. I hope I haven't missed anything important.

Obviously, I'm closer to the media APIs than to some other traits of iOS (so I might have a skewed perspective on their prominence) but I think that the media APIs are close to the most, if not the most updated area of iOS. Attempting to keep media applications up-to-date with the latest media features available remains a busy task.

Of course despite the huge amount of work (on the part of both Apple and the 3rd party application developers) these additions have certainly improved the media experience in iOS. The original iPhone OS felt hugely limiting at the time and users were certainly crying out for the additions that have appeared. The idea that the only movie player interface used to be fullscreen, the only audio playback API was AudioQueue or raw AudioUnits, there was no programmatic camera access and no access to the iPod library in the original iPhone OS highlights how many more options are now available.

Of course, the constant changes to the API also leave me feeling embarrassed when they trip me up or otherwise get ahead of my release schedules. The StreamToMe 3.5.2 update is coming soon, I promise!

Advanced drawing using AppKit

2011-01-31T19:40:00.001-08:00

In this post, I'll look at drawing a detailed image in code by combining multiple visual elements. Unlike previous posts I've done on drawing in Cocoa, this will focus on the AppKit classes. The code will use NSGraphicsContext, NSBezierPath, NSAffineTransform, NSGradient, NSGlyph and show you some simple ways to export the contents of an NSView to a file.

Introduction

I was reading an article on the Mac App Store and instead of paying attention to the article or working (which is what I was supposed to be doing at the time) I found myself staring at the accompanying image (a large version of the Mac App Store icon). Being the Cocoa programmer that I am, I found myself mentally deconstructing the icon and wondering how you'd draw something similar in Cocoa.

Only after I'd written the code and decided to write a post on it did I pay attention to the fact that I've already written a series of posts on creating icons. I'm not trying to be repetitive (this post is about Cocoa drawing techniques; it is not a suggested way to create application icons as the previous post was) but now that it's too late to change, I wish I had chosen a more novel visual subject for this post.

Update 2011-05-28: this post is a Mac application. If you'd like to see the same design drawn using iOS CoreGraphics code, check out this blog post by Marcus Crafter.

The sample app

You can download the complete sample project used in this post here IconApp.zip (96kB)

The application has a single window into which it draws an icon. You can resize the window and the icon always scales to fit. You can export the icon to a PDF or PNG file.

Obviously, while inspired by the Mac App Store icon, this design is not trying to accurately replicate it. The real purpose is to show how to achieve the multiple, layered gradients, curve drawing, path-based clipping, shadowing and scaling you're likely to need if you want to create a non-trivial design in code.

Scale-to-fit (respecting aspect ratio) and center

Even before we start drawing, we need to ensure that the image will always be scaled to fit the window. The first step is to find a scale that will fit the square icon into the view regardless of view size or aspect ratio:

NSSize nativeSize = [self nativeRect].size;
NSSize boundsSize = self.bounds.size;
CGFloat nativeAspect = nativeSize.width / nativeSize.height;
CGFloat boundsAspect = boundsSize.width / boundsSize.height;
CGFloat scale = nativeAspect > boundsAspect ?
    boundsSize.width / nativeSize.width :
    boundsSize.height / nativeSize.height;

In this case, the nativeRect of the view is defined as NSMakeRect(0, 0, 512, 512);

Once we have the desired scale factor, we resize the current drawing context and center it:

NSAffineTransform *transform = [[NSAffineTransform alloc] init];
[transform
    translateXBy:0.5 * (boundsSize.width - scale * nativeSize.width)
    yBy:0.5 * (boundsSize.height - scale * nativeSize.height)];
[transform scaleBy:scale];
[transform set];

Once we've applied this affine transform, we can draw as though our canvas is the nativeRect size but it will perform an aspect fit for any view size.

I haven't shown it here but if you change the current transform (or the current clipping path as I also do later) you should remember to place a call to [[NSGraphicsContext currentContext] saveGraphicsState] before your changes and follow your drawing by a call to [[NSGraphicsContext currentContext] restoreGraphicsState] to put everything back again.

Draw the background and shadow

We draw the background circle initially using a flat color, with an NSShadow enabled.

We use a flat color while drawing the shadow (instead of the gradient that we want in the final output) because the gradient drawing method we're going to use actually clips to the gradient's boundary, so the shadow wouldn't be drawn (because the shadow would be outside the clipping boundary).

Also, gradients don't anti-alias their edges. Drawing the shape with a flat color that is approximately the average color of the gradient will give us a nice, anti-aliased edge.

[NSShadow setShadowWithOffset:NSMakeSize(0, -8 * scale) blurRadius:12 * scale
    color:[NSColor colorWithCalibratedWhite:0 alpha:0.75]];
[[NSColor colorWithCalibratedWhite:0.9 alpha:1.0] set];
[[NSBezierPath bezierPathWithOvalInRect:ellipseRect] fill];
[NSShadow clearShadow];

Coding practice aside: If you're a good coder, you should avoid "magic numbers". Magic numbers are unnamed numbers used without explanation in the code. They are considered bad practice (instead, you should assign values to a constant that names the value and explains any derivation, then you may use it).

However, I normally make an exception for drawing code (as I have in this case). If a number is chosen purely for aesthetic purposes and has no real relationship to any other value, I leave it magic on the assumption that its aesthetic purpose (with derivation or geometric relationship) is obvious.

You do need to keep a tight reign on permissive number usage though. You'll notice lower down in this post (in the "Gloss Gradient" code), where there's a blend of calculated, derived and relationship-related values as well as purely aesthetic values, I've bothered to use named constants instead, to clarify what is derived, what is proportionate and which arc is which.

The shadow methods in the previous code block are convenience methods from a category implemented as follows:

@implementation NSShadow (SingleLineShadows)

+ (void)setShadowWithOffset:(NSSize)offset blurRadius:(CGFloat)radius
    color:(NSColor *)shadowColor
{
    NSShadow *aShadow = [[[self alloc] init] autorelease];
    [aShadow setShadowOffset:offset];
    [aShadow setShadowBlurRadius:radius];
    [aShadow setShadowColor:shadowColor];
    [aShadow set];
}

+ (void)clearShadow
{
    NSShadow *aShadow = [[[self alloc] init] autorelease];
    [aShadow set];
}

@end

We then draw the gradient over the top:

NSBezierPath *ellipse = [NSBezierPath bezierPathWithOvalInRect:ellipseRect];
NSGradient *borderGradient =
    [[[NSGradient alloc]
        initWithStartingColor:[NSColor colorWithCalibratedWhite:1.0 alpha:1.0]
        endingColor:[NSColor colorWithCalibratedWhite:0.82 alpha:1.0]]
    autorelease];
[borderGradient drawInBezierPath:ellipse angle:-90];

Layered gradients to form the background

Single, simple gradients tend to look bland and artificial. Our eyes expect much more complex lighting than a single gradient normally provides.

For this gradient, I wanted a pear shape as though a circular gradient had been smudged upwards. NSGradient does have methods that allow the gradient to be drawn as a circle along a path but the aesthetic is harsher than the soft, blurry look I wanted.

The easiest way to get a natural, soft-lighting style gradient effect is simply to lay a few gradients on top of each other. By getting the alpha transparency of each gradient right, the gradients will all appear to be part of the same effect. Of course, this is also slow, particularly at high resolutions, so it is an approach to use sparingly.

The final result in the bottom right corner of this image is achieved by drawing a black background, then drawing the top-left, top-right and bottom-left gradients over the top of the black background.

Here's the code to paint the center of the circle black. We then set the clipping path of the context so that all further drawing will be clipped to inside the border of the circle.

NSRect ellipseCenterRect = NSInsetRect(ellipseRect, 16, 16);
[[NSColor blackColor] set];
NSBezierPath *ellipseCenter = [NSBezierPath bezierPathWithOvalInRect:ellipseCenterRect];
[ellipseCenter fill];

[ellipseCenter setClip];

Now that the code is complete, I realize that I didn't need to clip here. I could have used the -[NSBezierPath drawInBezierPath:relativeCenterPosition:] method for the gradients to automatically draw them clipped to the ellipseCenter path and they would have clipped themselves (nothing else would have needed clipping). Performance-wise, it doesn't really matter though (either I apply the clip or the method does)..

Once the background is drawn, we begin layering the gradients. This is the code that draws the top-left of the gradients shown above:

NSGradient *bottomGlowGradient =
    [[[NSGradient alloc]
        initWithColorsAndLocations:
            [NSColor colorWithCalibratedRed:0 green:0.94 blue:0.82 alpha:1.0], 0.0,
            [NSColor colorWithCalibratedRed:0 green:0.62 blue:0.56 alpha:1.0], 0.35,
            [NSColor colorWithCalibratedRed:0 green:0.05 blue:0.35 alpha:1.0], 0.6,
            [NSColor colorWithCalibratedRed:0 green:0.0 blue:0.0 alpha:1.0], 0.7,
        nil]
    autorelease];
[bottomGlowGradient
    drawInRect:ellipseCenterRect relativeCenterPosition:NSMakePoint(0, -0.2)];

The floral heart adornment

The floral heart is a character from the Arial Unicode MS font. Getting the bezier path of a font character is a little cumbersome, since you need to use NSLayoutManager to get the glyph for you before you can ask NSBezierPath to create a path from the glyph.

NSString *floralHeart = @"\u2766";
NSRange stringRange = NSMakeRange(0, [floralHeart length]);
NSFont *arialUnicode =
    [[NSFontManager sharedFontManager]
        fontWithFamily:@"Arial Unicode MS"
        traits:0
        weight:5
        size:345];
NSLayoutManager *layoutManager = [[[NSLayoutManager alloc] init] autorelease];
NSTextStorage *textStorage =
    [[[NSTextStorage alloc] initWithString:floralHeart] autorelease];
[textStorage addAttribute:NSFontAttributeName value:arialUnicode range:stringRange];
[textStorage fixAttributesInRange:stringRange];
[textStorage addLayoutManager:layoutManager];
NSInteger numGlyphs = [layoutManager numberOfGlyphs];
NSGlyph *glyphs = (NSGlyph *)malloc(sizeof(NSGlyph) * (numGlyphs + 1)); // includes space for NULL terminator
[layoutManager getGlyphs:glyphs range:NSMakeRange(0, numGlyphs)];
[textStorage removeLayoutManager:layoutManager];

NSBezierPath *floralHeartPath = [[[NSBezierPath alloc] init] autorelease];
[floralHeartPath moveToPoint:NSMakePoint(130, 140)];
[floralHeartPath appendBezierPathWithGlyphs:glyphs count:numGlyphs inFont:arialUnicode];
free(glyphs);

If there's an easier way to do this, I'd love to know. It certainly seems like you should just be able to ask for the path for a Unicode character directly.

The floral heart is then drawn using a gradient and shadow in almost the same way as the frame (we even use the same gradient).

Update: As Christopher Lloyd points out in the comments, you can get the NSGlyph more easily using the CTFont function CTFontGetGlyphsForCharacters. It saves 9 lines of code but it breaks my effort to do everything in this post using AppKit instead of the Core APIs:

// Replaces lines 1, 2, 9-18 of previous code block
NSInteger numGlyphs = 1; // hard-coded glyph count for floral heart character
NSGlyph *glyphs = (NSGlyph *)malloc(sizeof(NSGlyph) * (numGlyphs + 1)); // includes space for NULL terminator
CTFontGetGlyphsForCharacters(
    (CTFontRef)arialUnicode, (const UniChar *)L"\u2766", (CGGlyph *)glyphs, numGlyphs);

Gloss gradient

The icon is finished off with a gloss gradient. The gloss gradient is drawn between two arcs and it is these arcs that are the tricky part.

The gloss itself is inset from the frame to ensure that between the nearly white color of the frame and the gloss gradient, we still get a dark rim for contrast.

The left and right edges of the gloss start just above the middle of the circle (I chose 0.02π radians), following the arc of the circle at the top and through the middle of the image it bulges down to approximately the middle of the circle.

I got the trignometry for the top arc correct but I didn't really bother with the bottom bulging arc (since its exact placement doesn't really matter. Due to the nature of the 3 point arc drawing method I used for this bottom arc, if you get the radius wrong for the three point locations, the arc either straightens out near the left and right endpoints or the arc overshoots these points. I'm sure I could have done this better (a bézier curve might have been a smarter choice since a proper circle was not required for this curve).

const CGFloat glossInset = 8;
CGFloat glossRadius = (ellipseCenterRect.size.width * 0.5) - glossInset;
NSPoint center = NSMakePoint(NSMidX(ellipseRect), NSMidY(ellipseRect));

double arcFraction = 0.02;
NSPoint arcStartPoint = NSMakePoint(
    center.x - glossRadius * cos(arcFraction * M_PI),
    center.y + glossRadius * sin(arcFraction * M_PI));
NSPoint arcEndPoint = NSMakePoint(
    center.x + glossRadius * cos(arcFraction * M_PI),
    center.y + glossRadius * sin(arcFraction * M_PI));

NSBezierPath *glossPath = [[[NSBezierPath alloc] init] autorelease];
[glossPath moveToPoint:arcStartPoint];
[glossPath
    appendBezierPathWithArcWithCenter:center
    radius:glossRadius
    startAngle:arcFraction * 180
    endAngle:(1.0 - arcFraction) * 180];

const CGFloat bottomArcBulgeDistance = 70;
const CGFloat bottomArcRadius = 2.6;
[glossPath moveToPoint:arcEndPoint];
[glossPath
    appendBezierPathWithArcFromPoint:
        NSMakePoint(center.x, center.y - bottomArcBulgeDistance)
    toPoint:arcStartPoint
    radius:glossRadius * bottomArcRadius];
[glossPath lineToPoint:arcStartPoint];

Exporting

Exporting a view to a PDF file is extremely simple in Cocoa:

[[iconView dataWithPDFInsideRect:[iconView nativeRect]]
    writeToURL:[savePanel URL]
    atomically:YES];

However, you'll quickly see that gradients with transparency don't output correctly in Mac OS X (everything else, including the shadows, work fine). The internets claim it's a limitation of PDF 1.4 (the PDF standard used in Mac OS X).

Instead we need to export to PNG if we want to keep the transparency. There's a few different ways to do this but the quickest and easiest is:

NSRect iconViewFrame = iconView.frame;
[iconView setFrame:[iconView nativeRect]];

NSBitmapImageRep *bitmapImageRep =
    [iconView bitmapImageRepForCachingDisplayInRect:[iconView frame]];
[iconView
    cacheDisplayInRect:[iconView bounds]
    toBitmapImageRep:bitmapImageRep];
[[bitmapImageRep representationUsingType:NSPNGFileType properties:nil]
    writeToURL:[savePanel URL]
    atomically:YES];

[iconView setFrame:iconViewFrame];

This approach contains a few potential problems:

we need to resize the view to render at the desired "native" resolution
it caches the screen render so it may contain screen-related oddities (like your screen's color profile)

Ultimately, creating your own NSBitmapImageRep, setting the NSGraphicsContext using graphicsContextWithBitmapImageRep:, locking focus yourself and invoking drawRect: directly will avoid these issues and is more flexible. But it would have been more work so I didn't bother for this sample project (I mostly put this export code into the app so I could create the app's icon).

Conclusion

You can download the complete sample project used in this post here IconApp.zip (96kB)

Ultimately, it's uncommon to construct this many visual elements in code; these things are invariably easier in a drawing program and a prerendered bitmap would be faster (this is quite slow at large sizes).

However there are many situations where drawing in code can offer advantages — particularly if your designs need to reshape or adapt to fit content. Buttons and other controls containing text are a an example, particularly if your design cannot simply be stretched.

Even if the most complicated thing you need to do is anti-alias a path filled by a gradient, there are a few tricks contained in this post that I hope will help.

Submitting functionality for a future version of iOS

2011-01-26T00:48:00.001-08:00

A number of websites are reporting that my application, StreamToMe 3.5 was approved with mention of a piece of future iOS functionality. While this was actually the case, it does not mean that Apple have started accepting apps for this new version of iOS.

What happened? What is this article about?

A few different websites (Mac Rumors, Engadget and dozens of others according to Google) have picked up on an unfortunate point: the "What's new in version 3.5" text for StreamToMe discussed a feature that will be enabled once a future version of iOS is released.

From these articles, it appears people are assuming that Apple have started accepting submissions for applications built with iOS 4.3. At the time of this post, the current SDK is iOS 4.2 so approval of an iOS 4.3 linked application would be newsworthy.

While I love the attention, it pains me to point out the fact that it might not be as newsworthy as people hope.

While the feature line was not a lie, this version of StreamToMe has not been linked against iOS 4.3 — it is an iOS 4.2 application — and Apple are not ready for people to mention future functionality in their programs.

Can I submit my app linked against iOS 4.3?

Apple won't let you submit an application to the iOS app store if it is linked against a future or beta version of the iOS SDK. At the moment, the current version of the iOS SDK is iOS 4.2. Do not submit an application linked against a beta SDK — it will be rejected.

If you are an Apple developer, Apple will probably email you when iOS 4.3 submissions are being accepted. They have traditionally done this about 2 weeks before the release of the iOS version to consumers and there's no reason to expect this to change in future.

Apple have not notified developers that they can submit using iOS 4.3. Therefore you should only use iOS 4.2 for current submissions.

So what's up with StreamToMe claiming iOS 4.3 behavior then?

First: it was a bit of clumsy copy writing on my part. I shouldn't have mentioned it when I submitted and have removed the mention from the application description.

Sometimes there are elements of a future version of iOS that you can defensively code to support. In this case, I wanted to invoke a single method to support functionality, should it become available in a future version.

How does StreamToMe use this magic method without linking against it?

The answer is: dynamically. StreamToMe looks at runtime to see if the magic method is there. The code looks like this:

if ([someCurrentObject respondsToSelector:@selector(magicMethodToEnableFutureFunctionality:)])
{
    IMP imp = [someCurrentObject methodForSelector:@selector(magicMethodToEnableFutureFunctionality:)];
    if (imp)
    {
        ((void(*)(id, SEL, BOOL))imp)(someCurrentObject, @selector(magicMethodToEnableFutureFunctionality:), YES);
    }
}

I've used the name magicMethodToEnableFutureFunctionality: here instead of the real method name, to protect the guilty party involved.

Getting the IMP followed by the ugly looking typecast function invocation is just to make sure the parameter is passed to magicMethodToEnableFutureFunctionality: correctly (since the compiler has no method declaration to use, we typecast to ensure correctness). You can achieve the same result by declaring the method in a category of the someCurrentObject's class but I preferred this approach here purely to keep my only-temporary-until-the-future-version-is-official code in one place. In either case the respondsToSelector: call is required as it is the step that ensures the method exists.

By doing everything both dynamically and defensively, the limitations associated with linkage and current iOS funtionality are avoided.

That's great, I can make all my future changes like this!

Be careful!

This type of action is a calculated risk. The risk is that the final release of the iOS version you're hoping to support in future might change the name of the method to something else, in which case, this code have any effect. The future version of iOS could change the type of the parameter — which could cause your program to crash until you change your code. There's also the risk that the future functionality could be removed from iOS entirely before release for whatever reason.

While you're coding defensively to support changes, you're still creating risk.

The reasons I decided to take this risk with StreamToMe 3.5 were:

The functionality was very simple (one simple method was all that was required)
StreamToMe 3.5's feature set was complete and it was due for a release now, while the future iOS release is an indeterminate time into the future
I didn't think anyone would really notice until after iOS 4.3 (oops: I spot a flaw in my plan)

Even if you do include changes like this: don't mention them in your text. Clearly, such mentions may slip through accidentally but it is against your developer agreement to mention future functionality.

Conclusion

StreamToMe 3.5 is mega-hyper-super wünderfantastic. You should buy 12 copies just for yourself and dozens more for your friends.

But sorry, it's not an iOS 4.3 application. It was built using the current, plain vanilla Xcode 3.2.5 and plain chocolate (without sprinkles) iOS 4.2 SDK. What it may or may not support in the future remains something to be seen when it happens. The world continues to turn at the normal, sub-ludicrous speed.

Please, don't link your own applications against future iOS versions and submit then until Apple give the green light to do so. You'll just get told to resubmit using the current SDK.

If you're prepared to be a cavalier cowboy coder like I have been, and take crazy risks that promise future functionality without any real guarantee, well you can clearly do that but at least know you're taking a risk so that when you get burned you'll understand why.

UITableView construction, drawing and management (revisited)

2010-12-19T23:33:00.001-08:00

In this post, I'll show you the current classes I use to construct and manage UITableViews in a number of different projects. This code is an amalgamation and evolution of some ideas that I've presented in a few earlier posts including my posts on heterogenous cells in a table view and easy custom table view drawing. But this implementation also chooses to do some things differently in an effort to continuously simplify the task of creating customized tables and views in iOS.

Introduction

In this post, I present a the following sample application.

Download the Xcode project for the sample application: TableDesignRevisited.zip (65kB)

The application contains a top-level table view with 3 sections. Each section in this table view contains a different kind of row, with different construction, drawing and behaviors. The "Simple text" rows display text and are selectable but then simply deselect with no further action. The "Rows loaded from NIBs", when tapped, push in a "Detail View Controller". The "Editable Text Fields" section contains rows you can tap to edit.

The purpose of this sample class is to demonstrate the approach and implementation that I use for structuring views and controllers in a basic iOS application containing these types of elements.

This post is a reply to the handful of different readers who have read some of my earlier posts on techniques and practices involving UITableView and UITableViewController and asked if my approaches have changed at all in the last couple years.

Key features of the sample application

The application's use of table views and cells demonstrates numerous, highly advantageous features:

heterogeneous (i.e. different kinds of) views in a single table without needing conditional code to separate their behaviors
fully custom drawn headers, rows and backgrounds — I realize the rows in this sample application may look very similar to Apple's normal UITableViewCells in a grouped UITableView but if you look close, you'll notice the background of the cells is a subtle left-to-right gradient and the tables background is a subtle gradient instead of the standard table texture (and the selection color is totally different). All custom drawing can be easily modified or tweaked to make the application look novel and distinctive or it can be disabled to revert to the default drawing code.
all default row and header drawing can handle either "grouped" or "plain" UITableView styles (so you're not locked into one aesthetic)
fully animated insertion and removal of all table view cells
the app demonstrates view and cells constructed both in code and loaded from NIB files and makes the code path for loading tables and cells from NIBs fast and easy
the table is managed by a custom UIViewController, not a UITableViewController. This means that it avoids the UITableViewController limitation of only managing the UITableView — you can load additional views as part of the hierarchy
view scrolling to avoid text under the keyboard (which is the biggest advantage of UITableViewController) is handled by the custom UIViewController so this UITableViewController functionality is retained

Evolution over time

Some of these features were part of previous posts that I've written, including:

The code in this post is probably closest to being a descendant of the original "Heterogeneous cells" post. Many of the ideas for simplifying the UITableViewController implementation remain from that post.

Specifically, the "Heterogeneous cells" aim of handling the UITableView data source and delegate methods automatically in a base class carries through into this code. The approach from "Easy custom UITableView drawing" of customizing cell drawing by setting the subviews — not by putting drawing code into UITableViewCell — is also followed here.

However, there are some changes in style and approach.

Reduced construction of views in code

Except for the simplest views, I rarely construct views in code anymore, in favor of loading most views from NIB files.

I originally kept to NIB files because I felt that Interface Builder for iOS 2 lacked features and that precise configuration required setup in code anyway. There were also performance concerns early on which turned out not to be accurate. If you remember: there is rarely any speed advantage to construction in code and it's generally ugly to read and hard to maintain.

So the arguments against NIB files turned out to be inaccurate or out-of-date and all that was required was code that allowed seamless use of NIB files for loading.

While loading NIBs for UIViewControllers is part of the standard API, it is a little less clear-cut with UITableViewCells. I use an approach where only the content view of the UITableViewCell is typically loaded from a NIB — and it's as simple as overriding the -nibName method.

No easy path for loading table section headers from NIB files exists in these classes but customized table headers are rare enough that I don't think that's important.

Elimination of the dedicated Cell Controller class

The Cell Controller class originally existed for the purpose of binding a controller directly to the data for a row and keeping control separate from the UITableViewCell which is a view by inheritance.

The Cell Controller was a key feature of the a Heterogeneous cells in a UITableViewController post but frankly, it didn't integrate well with the classes around it. Additionally, connecting target/actions from subviews of a UITableViewCell to the Cell Controller could also cause minor problems in some cases.

Instead, I've chosen to embrace the idea that UITableViewCell is really a controller (despite inheriting from UIView) and putting most of the cell control code there. Associated with this, I don't use the UITableViewCell for any drawing (that is done by the content view, background view and selected background view). The UITableViewCell is just the controller that loads these other views and connects them to the data.

Eliminating the Cell Controller class had an additional advantage: greater decoupling of the row's data and the controller (which is now the UITableViewCell subclass). Row data is stored along with a pointer to the desired subclass of UITableViewCell but the connection between the two is only made when the cell is prepared for display. Until that point, the row data is not directly connected to any view controller; a much better approach that works within the UITableView/UITableViewCell architecture.

Fully animated, rarely using reloadData

An additional problem with the original Heterogeneous cells implementation was that it required all the data and cell controllers for the table to be fully constructed, then -[UITableView reloadData] was called to recreate the whole table in the new state.

The new implementation is focussed on animating rows and sections into and out of the table and the methods for manipulating the rows and sections all focus on this.

Of course, it is possible to pass UITableViewRowAnimationNone for the animations and this then requires that you do subsequently call reloadData, so the old approach is still possible.

Forgiving approach to row and section indices

The methods for manipulating row and sections in this implementation will attempt to fix row indices or create missing sections if you mess up. The intention is not to encourage laziness but rather to be forgiving if a bug slips through. It's better to have a row appear in the wrong section of the table than to have the whole program crash due to an index out-of-bounds issue.

The implementation and how to use it

Code in the view controller

The RootViewController is the controller for the main screen (as shown in the screenshot above).

The rows in this view are all constructed in a similar way (with different cell classes for each section and different data for each row). Here's how the rows in the "Rows loaded from NIBs" section are constructed:

[self addSectionAtIndex:1 withAnimation:UITableViewRowAnimationFade];
for (NSInteger i = 0; i < 4; i++)
{
    [self
        appendRowToSection:1
        cellClass:[NibLoadedCell class]
        cellData:[NSString stringWithFormat:
            NSLocalizedString(@"This is row %ld", @""), i + 1]
        withAnimation:(i % 2) == 0 ?
            UITableViewRowAnimationLeft :
            UITableViewRowAnimationRight];
}

The view for the row is configured in this single statement. You specify:

the data
the Class that will be used to control and display the data when it comes into view
the location of the row within the section/row hierarchy
the animation used to bring the cell into view

Obviously, the "data" used here is fairly simple: just NSString and NSDictionary instances. In a real program, you would pass your Model objects for each row as the cellData parameter.

As with the original "Heterogeneous cells" post, there is no additional work required in the view controller once this declarative work is done; the UITableViewDataSource and UITableViewDelegate implementations are all handled automatically.

Animation is not required; you can specify UITableViewRowAnimationNone and then follow the insertion with a call to -[UITableView reloadData] or -[UITableView reloadSections:withRowAnimation:] when you're ready for the table to refresh.

Code in the table view cell subclasses

The implementation for each row is intended to be as hassle-free as possible too. The implementation of the NibLoadedCell, which is totally custom drawn, custom layout, custom row height and custom action is three, tiny methods long:

+ (NSString *)nibName
{
    return @"NibCell";
}

- (void)handleSelectionInTableView:(UITableView *)aTableView
{
    [super handleSelectionInTableView:aTableView];
    
    NSInteger rowIndex = [self indexPath].row;
    [((PageViewController *)aTableView.delegate).navigationController
        pushViewController:
            [[[DetailViewController alloc] initWithRowIndex:rowIndex] autorelease]
        animated:YES];
}

- (void)configureForData:(id)dataObject
    tableView:(UITableView *)aTableView
    indexPath:(NSIndexPath *)anIndexPath
{
    [super configureForData:dataObject tableView:aTableView indexPath:anIndexPath];
    
    label.text = dataObject;
}

Following in the tradition of making the common case the easiest, all you need to do is set the -nibName and the default implementation knows how to load the nib and set a range of properties including the default row height based on the size of the view in the NIB file.

Common behaviors like deselecting the row after selection are automatically handled by the super implementation of handleSelectionInTableView: and the default implementation of configureForData:tableView:indexPath: handles the setting of the custom row background and selection background.

Flexibility

The architecture allows you to do things different depending on how you want to work.

As an example: the LabelCell and TextFieldCell are constructed in code in their finishConstruction implementations but the NibLoadedCell is loaded from a NIB by overriding the -nibName method and returning the name of its NIB file. Similarly, the RootViewController's table is constructed in code by overriding the -loadView method but the DetailViewController comes from a NIB file simply by overriding the -nibName method and returning the name of its NIB file.

The rows use the PageCellBackground for drawing by invoking the super implementation in configureForData:tableView:indexPath:. You can easily avoid invoking the super implementation here to revert to standard UITableViewCell drawing.

Want the default UITableView headers instead of custom drawn ones? Remove the self.useCustomHeaders = YES; line from the -viewDidLoad method in RootViewController.

The custom drawn views will all draw themselves in the UITableViewStyleGrouped or UITableViewStylePlain styles. You can see the difference by changing the style of the created table in the loadView method of RootViewController.

How it works

None of the code is hugely groundbreaking in any way. Most of the code simply works because of the default behaviors in the base classes:

PageViewController — handles (almost) all data source and delegate methods. If you make this view controller the delegate for any UITextField in the table, it will also handle scrolling of the table and resizing of the view to keep the text field out from underneath the onscreen keyboard.
PageCell — loads the contentView for the UITableViewCell from a NIB file (if specified). In addition or as an alternative, you can configure or construct the contentView in the finishConstruction method. This method also provides the PageViewController with information about row including the row height (which can be extracted from the NIB). Other methods include an overrideable set of methods for handling the configuration of the view (used to connect the view and data or otherwise prepare the view for display) and handling touches in the view.
PageCellBackground — draws a custom cell background in either UITableViewStylePlain or UITableViewStyleGroup styles. The PageCellBackground is applied in the PageCell's configureForData:tableView:indexPath: default implementation (so you can disable it by subclassing this method and not invoking the super implementation). Alternately, if you just want to change the aesthetic of the cell background, you can change the subclass of PageCellBackground used by overriding the +[PageCell pageCellBackgroundClass] method.

Missing features or situations this won't handle

Different structures for the row data

As I mentioned in the original "Heterogeneous cells" post, the approach used in this implementation offers simplification over the default UITableViewController templates because it makes some assumptions about the structure of your data. Specifically, it assumes that the data for every row in the table is loaded and a PageCellDescription constructed for each row's data.

The downside is that the current implementation would not integrate in its current form with any design that requires the data be store or structure in a different way. An example of a different storage arrangement is data fetched using a NSFetchedResultsController — you'd need a base class that works differently to integrate with NSFetchedResultsController's different approach to loading and caching data.

Declarative handling of sections

As I've mentioned a couple times, the current PageViewController only handles almost all of the data source and delegate methods for the UITableView. The biggest omission is any handling of the section headers — setting the text for the section headers still requires implementing the tableView:titleForHeaderInSection:.

Looking at the code, you could possibly make some minor improvements by handling the sections as a description data structure (in the same way that each rows is described by a PageViewCellDescription instance). This would allow you to bind the section's title, header and footer view and other section attributes together when you add the section to the table.

The actual simplification this would bring is likely minor though, so I haven't bothered yet.

Customized for your own program

While the default behaviors in the PageViewController, PageCell and PageCellBackground view will work as they are, their purpose is to allow simple customization in your own program.

Distinctive classes in your program should have their distinctive traits applied in subclasses but for defaults you want to establish across your entire program, it's often easiest to insert custom behaviors like custom drawing directly into PageCellBackground or -[PageViewController tableView:viewForHeaderInSection:]. There's no need to keep these defaults if your program never uses them.

Conclusion

Download the Xcode project for the sample application: TableDesignRevisited.zip (65kB)

The code in this post is not particularly advanced — most regular iOS programmers could easily figure it out for themselves.

Instead, this post is just a basic reveal of how I structure my views in some of my own programs so that new developers can get ideas about how they should structure their own tables, views and controllers for basic user-interface management in iOS.

This code represents 2 years of iteration since some of the earlier posts I've written on UITableViews and their management. Maybe there's an opportunity to learn from this evolution or maybe there's an opportunity to learn from my earlier naïvity and newer eccentricities. I'm certainly happy with how my approach has evolved and I think the current state of these classes represents a base from which you can very quickly implement new table-based views using much less code than starting from Apple's Xcode templates.

Version control for solo Mac developers

2010-12-12T22:42:00.001-08:00

In this post, I'll take a quick look at how to keep your projects in git and how to manage that easily on the Mac. More importantly though, I'll take a look at why you'd want to do this, even if you're the only developer, you don't need to share your code, you don't have formalized releases that need to be tagged and you already have a backup system protecting your code.

Introduction

After my posts a few weeks back on deployment scripts, where I implored everyone to use version control systems for all projects, I received a few different emails asking about how I actually handle this.

The main points to learn in this post are:

Every project you ever work on should be in version control
Nothing needs to be centralized (you don't need a server) but you can use any computer as a server if you wish
You can avoid the (often cryptic) command-line for most tasks
I'll show you all the required steps
I'll show you how it will help you as a solo developer, even if you don't need many of the traditional features of a version control system

Version control systems protect your work, help you review what you've done, help you share code if needed, work like a massive undo buffer when necessary and can help you keep your code tidy. Always use one.

Setting up git on your Mac

I recommend you use git for version control. Most modern, distributed, version control systems share a pretty similar feature and command set. The advantage with git is really that it's enjoying a lot of popularity at the moment and that popularity means there's plenty of documentation and how-to guides around to help out if you get lost. There are also some good tools around which make git use on the Mac more enjoyable — particularly GitX.

Installation

Download the git installer (as I write this, the current version is 1.7.3.3). Run the installer package.

Once that's done, you should set your username and email address (these will be tagged on all changes you make). Do this by opening the terminal and running the following commands:

git config --global user.name "My name in git"
git config --global user.email "myemailname@myemailaddress.com"

Just replace "My name in git" and "myemailname@myemailaddress.com" with the name and email address you want to use.

GitX

I prefer to use GitX instead of git on the command-line where possible.

I've discussed this before but I consider the command-line and a terminal window a poor way of gathering structured information and getting feedback about multi-part tasks.

GitX is a good example of how a program can improve upon the information structure available on the command-line: it shows nice graphical diffs whenever you're browsing the repository or committing new changes, making browsing and committing much faster and easier.

Download GitX from here

Of course, this doesn't mean that all graphical user-interfaces are always better than the underlying command-line. I consider the Xcode 3 version control integration to be worse than the command-line because it simply isn't informative or robust enough.

Making your project into a git repository

As soon as you've created your Xcode project from the template, the next step should be creating the repository. To do this correctly involves the following three steps.

Add a .gitignore file

The following webpage:

https://github.com/github/gitignore/blob/master/Objective-C.gitignore

Gives a ".gitignore" file suitable for use with Xcode. This will tell git to ignore build products and Xcode user-settings files that you don't really need to commit into your repository. You will need to save this file with the name ".gitignore" in the top level folder of your new Xcode project. Since you can't rename files to start with a "." in the Finder, you'll need to set the name using another program (i.e. rename from the Terminal or save from Xcode or TextEdit).

If you don't have a global .gitigore file set up, then you'll probably want to add the content of this file to your .gitignore as well:

https://github.com/github/gitignore/blob/master/Global/OSX.gitignore

The current version of this .gitignore file contains the line ".DS_Store?". This doesn't work for me unless I remove the question mark.

If you did want to set this up as a global .gitignore file, save it to ~/.gitignore and run the following in the Terminal:

git config --global core.excludesfile ~/.gitignore

Since Xcode projects are inherently Mac-only though, I prefer to put the Mac global ignore settings into the project's .gitignore so that any machine using this repository will automatically have all of these settings.

Create the repository

In GitX, select "New..." from the File menu and then choose the top level folder of your Xcode project. This will create the repository. It's as simple as that.

Outside of GitX, you can create a new repository with the following command in the Terminal:

git init

All files for tracking the repository are kept at the top-level of the repository (unlike older version control systems like svn or cvs which littered files in every directory). Most git files are kept in the .git directory.

Add all your files to the repository

Open the project's folder in GitX. The toolbar contains a two segment "View" button. The left side is the "Browse" mode, the right side is the "Commit" mode. Set the view mode to "Commit".

The window in GitX should look something like this screenshot. The bottom-left panel shows all the changes you haven't added to the repository.

To "stage" your changes (get them ready for a commit) select and double-click all the files you want to stage as a batch. In this case, select everything and double click. The files will all move to the "Staged Changes" area.

In the "Commit Message" in the center, enter a message describing this change. In this case: "Created new project from Xcode template." would be a good message. Hit the "Commit" button and these files will all be added to the repository with the commit message provided.

You can then use the "View" button in the toolbar again to select the "Browse" mode. You should now have one update in the project's history on the "Master" branch, with you as the "Author". The two segment control in the bottom-center of the window in Browse mode will allow you to switch between a "diff" of changes in the selected update (left side of the segment) and browsing the state of the repository as it was in the selected version (right side of the segment).

In the Terminal, you can stage new additions and removals with the following commands:

git add [path to file or files to add to the repository]
git rm [path to file or files to remove from the repository]

And you can commit additions and removals and commit other changes with the following command:

git commit -m "Commit message here" [path to file or files whose changes you want to commit]

Keep it up-to-date

The remaining step required once your project is in a repository, is to keep it up-to-date. You do this by committing changes on a regular basis.

How often should you commit changes? As often as you can. At a minimum, you should commit, when any of the following happens:

You finish a feature
You fix a bug
When you get up for lunch or at the end of the day
When you distribute a release to anyone else

It's helpful to have your processes for marking bugs as fixed or deploying code for distribution contain the requirement that related changes be committed and tagged in your repository. This ensures that you can check the exact code state at the time you fixed any bug or made any distribution.

For any other type of commit, don't be worried about committing bad or partially functional changes; remember, this is your own repository and you're not going to interfere with anyone else by committing a half-implemented feature (just don't push these changes to another computer). If you plan to make big changes that may leave the code non-functional for the duration of the changes, create a branch, check out the branch and commit your incremental implementation on the branch.

Updating the repository works exactly like the original add shown above but it is here where GitX begins to really help the commit process:

When you select the changed files during the commit process, the changes since the last commit are shown in the panel above. Here, I've added some interface outlets to the header file.

Depending on whether or not you have any formal feature list, development roadmap or bug tracking system, the commit message should now reflect who requested this change and why. For example, if the behavior of "myButton", "someTextField" and "arrayController" are described in items 1, 5 and 25 of your Feature List, then the commit message for the above changes might read: "Features 1, 5, 25: added interface outlets between the window controller and views".

The message for your commit message should always answer the question: "What was I thinking at the time? What problem was I trying to solve?"

Cloning this repository on another computer

Eventually, you'll run into a situation where you'll need to build and test on another machine. For the Mac you want to use as the source of the clone, make sure that "Remote Login" sharing is enabled in the "System Preferences".

Assuming the destination computer correctly has git installed and configured, open a Terminal window on the destination and enter the following command:

git clone ssh://username.on.source.computer@ip.address.of.source.computer/full/path/to/project/directory

This will completely clone the repository and its history for use on the destination computer.

Once you've cloned in this way, the source computer's address is given the name "origin". This means that if you need to pull new changes from the source to the destination again, you can use the following command:

git pull origin master

This will pull all changes on the "master" branch (the default or trunk branch). Similarly you can push to send changes back again:

git push origin master

If you're using a number of different computers and you want to push and pull between them, you can either use the full ssh address again or you can give your different "remote" computers names:

git remote add anotherremote ssh://username.on.remote.computer@ip.address.of.remote.computer/full/path/to/project/directory

Once you've done this, the name "anotherremote" will be usable within the current repository where any remote address is required (e.g. for push and pull commands).

Working with third-party projects

Do you need to include a third-party git sub-project in your project? Clone the third-party git repository into a subfolder of your repository. Git will refuse to commit a sub-repository into a parent repository. That's okay, just add the sub-project's folder name to your respository's .gitignore file. If you make change to this third-party repository, you will need to commit those separately by opening the third-party repository's folder instead of your own top-level folder.

Once you pull a third-party's repository, it's a good idea to immediately branch it and checkout under your new branch (you should never work on anyone else's master branch).

You can branch and checkout the new branch in GitX. While in "Browse" mode, hit the "Create Branch" button. Give you branch a name. Your new branch will appear as a tag on the most recent version in the History. To check out this new branch (so all your changes will appear on it) you need to right-click the branch's tag in the History display and select "Checkout branch". The title of the window will be updated to reflect the new current branch.

The advantage with keeping the third-party's repository is that if you make any changes, it is easy to see exactly what you've changed. You can also pull more changes from the master branch and then merge them with your own branch if you want to get updates for the project in future.

If you want this third-party project to be checked out automatically every time you clone your own repository, you can add it using the git "submodule" command:

git submodule add -b branchname third-party-repository-url destination_path

This will add a .gitmodules file to the top of the repository. Commit this file and "third-party-repository-url" will be automatically cloned at "destination_path", checked out on the branch "branchname" when this repository is cloned.

You can pull and push changes from svn repositories using git-svn, which is part of git by default. Have a look at this if you need cross repository support. There's also a third-party project named git-hg for cloning Mercurial repositories into git (although it is a one-way sync and may not be highly robust at this time).

Other git features

This is really on the tip of what you can do in git. I haven't even touched on restoring a previous version, merging between branches or rolling back changes and undoing commits.

I don't have an encyclopedic knowledge of git commands. If I need to do anything more than what's listed in this post, I normally need to look up the correctly commands to handle it properly. That's not such a bad thing: but be aware of the sorts of action that git can handle for you so you don't end up manually doing something that should be automatic.

In any case, I think I've listed all of the operations you're likely to need on a daily basis. It should be a good start.

Developers who still don't use version control?

Many small developers still neglect to use version control for many of their projects. It's clear that the importance of good code management is not universal.

I realize that it's easy to learn the mechanics of writing code and building programs without learning much about the profession of being a software developer, so let me add here: you should consider a version control system an essential part of being a software developer.

This may seem a little strange to say, since it is obviously possible to create, build and release programs without using a version control system. In many respects, you may think that the features offered by a traditional version control system aren't really needed by a solo developer working on a small project. Reasons some developers give why they don't need version control:

They already have backups made of your main development machine (Time Machine plus periodic, permanent, offsite backups)
Are the only person working on a project so they don't need to share and integrate with other developers
They don't have formal releases or regression tests that require regenerating output from earlier versions

However, there are some serious reasons why every developer should use version control.

More precise than Time Machine

If you rely on Time Machine to give you an archive of changes to your code, you'll fall victim to the limit resolution of Time Machine. While Time Machine has hourly backups for 24 hours, it only has daily backups for the next month and after a month it only has weekly backups.

If the build or feature you'd like to restore or re-instate falls in the gap between updates, you might not be able to pull it out of Time Machine. Worse still, your Time Machine volume will eventually run out of free space, so the oldest versions will start being removed. This will never happen in a version control system.

Additionally, a version control system contains a log for all changes, making them easier to find. You can also use tags to find important changes quickly.

You should use Time Machine too. Ultimately, your code is safest if your repositories are backed up to another hard drive. Additionally, you should make regular snapshots (as CDs/DVDs, encrypted disk images) of your repositories and store these offsite. For CDs/DVDs, store them in a fireproof safe, offsite somewhere. If you use encrypted disk images, upload them to an online storage location that guarantees high data integrity (uptime is not as critical as data integrity). If a fire burns down your home/office, it should never put more than 1 week's work at risk.

Provides a way of reviewing your own code changes

As a solo developer, you don't often have other developers who you can ask to review your code to ensure that all the changes make sense and nothing is accidentally deleted, removed or changed.

Reviewing the changes every time you need to make a commit allows you to do this for yourself.

As I said: every commit message should answer the question "What was I thinking at the time? What problem was I trying to solve?" If you can't actually answer this question, if you're not sure why the code changed, then this gives you the opportunity to work out what you were thinking and either remind yourself about the importance of the change or allow you to eliminate the change because it's unneeded.

Makes it easy to change to another machine for testing and then change back

If you ever need to test your code on another machine, it is quicker and more reliable to clone the repository on the new machine, make any changes you may require and then push them back to your primary machine.

Makes pulling the latest updates from a third-party much easier

As I mentioned, keeping third-party code in its repository makes pulling new changes to that third-party code and merging these updates with any changes of your own a lot easier.

Further, if these changes are to a GPL project and you need to make your own modifications publicly available, you can simply provide a diff from the repository as an easy way of publishing your changes.

Conclusion

Distributed version control systems like git make managing your own repositories easier than ever. You don't need a central location. You don't need administration.

Visual tools like GitX are also fantastic: you can easily track your changes and see what you've deliberately or accidentally done and commit or undo as appropriate.

Being a software developer (as opposed to a casual coder) is about managing the software development project and its assets over its lifecycle. Your version control system is one of the most important tools for doing this.

Even if you're only a casual developer, not a full-time developer, the logging, merging and tracking facilities offered by version control will save you effort over the course of any project with more than one edit. Use it.

Back to the Mac? 12 features from iOS I'd like to see in Lion

2010-11-20T00:54:00.001-08:00

A few user-features of Mac OS X Lion have been announced but no Cocoa API changes have been publicly announced. However, I think there are dozens of non-user areas where the Cocoa Mac APIs could be improved by integrating approaches from Cocoa Touch APIs. What follows are a dozen areas where I'd like to see a more iOS approach in Mac OS X Lion.

Introduction

The changes I'm going to discuss fall four basic categories:

simplifying common tasks
making important classes simpler to customize
updating APIs on the Mac that seem to have been ignored since iOS appeared
making CoreAnimation good enough to be used for all views on the Mac

1. Converting NSColor to CGColor

This first point is a minor simplification of a common task but I think it illustrates the fact that iOS integrates CoreGraphics and other forms of drawing well, where this integration seems to be lacking on the Mac.

On iOS, converting a UIColor to a Core Graphics CGColor is a basic property accessor:

CGColor myCGColor = myUIColor.cgColor;

It's as simple as can be. On the Mac, it's as convoluted as I could have imagined:

// Ensure that the color is in the "generic" RGB space so we can safely get the components
NSColor *rgbColor = [self colorUsingColorSpaceName:NSCalibratedRGBColorSpace];

// Get the r, g, b, a components
CGFloat colorComponents[4];
[rgbColor getComponents:colorComponents];

// Create the CGColor
CGColorRef myCGColor =
    (CGColorRef)[(id)CGColorCreateGenericRGB(
        colorComponents[0],
        colorComponents[1],
        colorComponents[2],
        colorComponents[3])
    autorelease];

While I'm on the topic of colors, I don't think the documentation for NSColor is clear enough about the choice between "Device" colors or "Calibrated" colors in an application user-interface. On iOS, there are only device colors — so there's no question — but on the Mac, you can create a white NSColor as either:

NSColor *calibratedColor = [NSColor colorWithCalibratedWhite:1.0 alpha:1.0];

NSColor *deviceColor = [NSColor colorWithDeviceWhite:1.0 alpha:1.0];

The User Interface Guidelines, NSColorSpace and the NSColor documentation offer no information about which should be the default choice in an arbitrary application. It'd be nice to have a clearer statement about when each is appropriate.

Edit: as pointed out in the comments, Apple do have a line in the Color Programming Topics documentation that suggests that you use calibrated color spaces where possible.

2. A constructor for NSTextField that constructs it as a static label

Another simplification of a common task that I'd like to see is the ability to create a static text label in a single statement. On iOS, we have the UILabel subclass of NSView for non-editable text display.

UILabel *label = [[UILabel alloc] initWithFrame:labelFrame];

On the Mac, the editable NSTextField can be configured to handle non-editable display. Unfortunately, while there is an efficient way to construct NSTextField as a static text label in Interface Builder, there is no similarly efficient way in code:

NSTextView *label = [[NSTextField alloc] initWithFrame:labelFrame];
[label setEditable:NO];
[label setBezeled:NO];

Not a huge gripe but if you're constructing a view in code, the two extra lines for every label can become tiresome. An -initStaticLabelWithFrame: or +staticLabelWithFrame: method would be nice.

3. Simplified methods for common actions, e.g. -[UIImage drawInRect:]

A final type of common task I'd like to see simplified is offering simpler methods for common cases.

One of the most prominent examples of simpler methods that I'd like to see is for drawing an image. To draw a UIImage in iOS we use a simple method:

[myImage drawInRect:someRect];

On the Mac:

[myImage
    drawInRect:someRect
    fromRect:NSZeroRect
    operation:NSCompositeSourceOver
    fraction:1.0
    respectFlipped:YES
    hints:nil];

I realize that in both cases it's only one method. I also realize that the Mac example is significantly more capable. However, the functionality of the iOS method is overwhelming the common case and I think that this option should be added to the Mac as well, to recognize that this is the common path.

4. Resizable NSImage

Another NSImage/UIImage point — but now in the topic area of making important classes easier to customize — it would be really good to see the method:

- (UIImage *)stretchableImageWithLeftCapWidth:(NSInteger)leftCapWidth
    topCapHeight:(NSInteger)topCapHeight

brought from iOS to the Mac. If you've never used this method before, it allows you to take a square image — like a button image — and label and specify the boundary of the image (the left and top "caps") so that when the image is stretched to fit a new size, the cap areas are preserved and only the middle of the image is stretched.

On the Mac, you can use the function NSDrawNinePartImage() but while this function is significantly more configurable, it lacks the ability to be used anywhere you use an NSImage — so you can't use it as the background to an NSButton, you must subclass NSButtonCell and handle the drawing manually.

5. Setting the text color on an NSButton

The second "making important classes easier to customize" point is setting text color on a button. For UIButton it looks like this:

button.titleLabel.textColor = [UIColor whiteColor];

On the Mac there are no standard methods and you have to change the attributed string for the NSButton's title:

NSMutableAttributedString *title =
    [[[NSMutableAttributedString alloc] 
        initWithAttributedString:[button attributedTitle]]
    autorelease];
[title
    addAttribute:NSForegroundColorAttributeName 
    value:[NSColor whiteColor]
    range:NSMakeRange(0, [title length])];
[title fixAttributesInRange:range];
[button setAttributedTitle:title];

Not only is this ugly, but you may have to redo it if the title changes.

6. Support for white on black in other controls

It should be much easier is changing the color of other standard controls too. Specifically, I think it should be possible to place any control on a black background and make it visible.

Do you want a white "spinner" (indeterminate progress indicator) to go on a black background? On iOS, all you need is:

UIActivityIndicatorView *indicator =
    [[[UIActivityIndicatorView alloc]
        initWithActivityIndicatorStyle:UIActivityIndicatorViewStyleWhite]
    autorelease];

If you want to make the NSProgressIndicator on the make white... you can't. You need to draw the entire control yourself.

7. An NSTableView equivalent that uses NSView for rows

The final "making important classes easier to customize" point is about NSTableView: we need an NSTableView like class on the Mac that handles the same column and row operations but contains proper NSViews instead of NSCell.

I've spoken about this desire before. The idea is pretty straightforward: UITableView creates a proper UITableViewCell (a subclass of UIView) for every row — this means that rows in a UITableView can behave like any UIView — they can be loaded from a NIB by a UIViewController, they can receive touches, contain buttons and be animated.

The iOS UITableView lacks bindings and doesn't have columns at all but in nearly every other respect, it is superior to the options on the Mac.

The NSCell that draws an NSTableView on the Mac is just limited. It can't animate, it can't contain regular views or buttons or receive clicks independent of the NSTableView. While using just one lightweight cell object per column may have made sense in the 1990's, it seems unnecessarily limiting in 2010.

There is certainly NSCollectionView which handles grids of actual NSViews but this class would need some work in terms of efficiency if it is to replace an NSTableView.

What's wrong with NSCollectionView? Simple: it constructs every view, including those that aren't visible. If your NSCollectionView contains 1 million views, this isn't going to work well. Further: NSCollectionView doesn't handle table-like interaction (you can't use column or row operations by default).

The reality is that NSCollectionView is designed to fill a slightly different niche; what we really need is a better NSTableView.

More generally than NSTableView: the entire NSCell concept seems dated. I would not be sad to see Apple deprecate them entirely. In some respects: leaving them out of UIKit is a mild form of deprecation. Now they just need to take the next step and start offering a way to use AppKit without NSCells.

8. Get rid of NSNib

Now to the first of the APIs that I think were updated when they were implemented in iOS but these updates never seemed to make it into Mac OS itself.

The first is a fairly mild point: what is the purpose of the NSNib class on the Mac? Technically, the answer is "it loads and instantiates NIB files". It also provides the ability to cache the loaded NIB for faster instantiation. In reality though, iOS does all of this work without needing a new class.

Specifically in this case, I'm looking at loading a NIB file and getting the array of top level objects.

Both iOS and Mac OS X can load a NIB through NSBundle without getting the top level array but on Mac OS X (connecting only to the "owner" object) but getting full access to the created objects requires using NSNib. In iOS though, you can do this directly from NSBundle, making the existence of the NSNib class seem a little pointless.

On iOS:

contentArray =
    [[[NSBundle mainBundle]
        loadNibNamed:nibName
        owner:self
        options:nil]
    retain];

On the Mac:

NSNib *nib =
    [[[NSNib alloc]
        initWithNibNamed:nibName
        bundle:[NSBundle mainBundle]]
    autorelease];
[nib instantiateNibWithOwner:self
    topLevelObjects:&contentArray];
[contentArray retain];

You could probably argue that the Mac implementation lets you cache the NSNib and reinstantiate again later. The reality is: the iOS version seems to handle this cacheing behind the scenes, automatically. Less code, more powerful; it's better. We can get rid of NSNib on the Mac.

Edit: it appears I overlooked the fact that iOS introduced UINib in 4.0 — so Apple are bringing the Mac approach to iOS instead of the other way around. So I guess this is a point where I simply disagree; I think that the cacheing should be done automatically in NSBundle (so that the simplest approach is also the best). This could be combined with optional cache/don't cache flags passed into the "options" parameter if you need finer control.

9. Language Rotor for Text-To-Speech

This is probably the most "user" feature of the points in this post but iOS has had dramatic improvements in text-to-speech relative to the Mac.

On iOS devices that support VoiceOver, the voice in Australia (where I live and work) has an Australian accent. This is due to the "Language Rotor" settings on iOS.

Now, I realize that I'm not blind and the only time I ever need to turn on VoiceOver is when I'm testing the UIAccessibility/NSAccessibility protocol implementations in my applications but whenever I do this on the Mac the voice doesn't sound right.

10. Update OpenGL!

Do I need to explain this one?

In iOS, you have access to OpenGL ES 2.0 — the current version of the OpenGL ES standard.

I realize that OpenGL on the Mac is not the OpenGL ES version. I also realize that it's version number is OpenGL 2.1 which is 0.1 higher than the iOS version. Obviously, I'm not suggesting that the Mac adopt exactly the same version of OpenGL that iOS uses.

What I mean is that iOS is using the up-to-date, relevant version of OpenGL whereas the OpenGL 2.1 standard on the Mac was superceeded 2 and a half years ago but Apple have not updated to support it. It is a complete embarrassment to the Mac as a platform. The current version of OpenGL for computers, OpenGL 4.1, was released in July this year. There are already cards available for the Mac that support OpenGL 4.1 on other operating systems but can't due so on the Mac because the OS does not support it.

11. Integration between CoreAnimation and standard views

The last two features from iOS I'd like to see both relate to making CALayer-backed views useable by default on the Mac.

Major views should offer animated changes for common actions. If you want to animate a new row into a UITableView on iOS, you only need one line:

[myTableView
    insertRowsAtIndexPaths:someIndexPath
    withRowAnimation:UITableViewRowAnimationLeft];

On the Mac — there certainly isn't a single line option. In fact, there's no easy solution at all, since rows are drawn by NSCell and don't generally have CALayers of their own (even when CoreAnimation is enabled for the NSTableView).

12. Fix the horrible text rendering when CoreAnimation is enabled

The following image shows Helvetica Bold 18pt, rendered on the Mac in two different ways.

Both are an NSTextField over a custom drawn gradient but where the top row uses a regular, non-CALayer-backed view, the bottom row uses CALayer-backed views for the entire window.

At first glance, the second row may simply look less fat but if you look closely, you'll see that it is more irregular, less proportionate, badly kerned and far less smooth.

This horrible text rendering affects all text in CALayer-backed views.

On iOS, which always uses CoreAnimation, the text rendering looks very similar to the top example (except that iOS doesn't use sub-pixel antialiasing). Clearly, there is a way to improve the situation with CALayers.

This text quality problem with CoreAnimation has been a burden since CoreAnimation first appeared in Mac OS X 10.5 and it remains the biggest disincentive towards using it on the Mac. It really needs to be addressed.

Conclusion

These points illustrate my feeling that the Mac Cocoa APIs, AppKit in particular, need some general tidying up (and in some cases, a major refresh) if they are to feel anything other than dated with respect to their iOS equivalents.

While some of these features would be major changes, many simply reflect the fact that AppKit could do with a well-applied coat of paint in many areas. These minor changes can already be addressed by each programmer (a category or a little extra code) but if these sorts of additions are considered commonplace, I think it's an indication that they should be rolled into the default API.

Some of these features might require deprecating major classes in favor of more modern implementations — possibly NSTableView and all NSCells. I wouldn't be sad to see them replaced by something that feels more up-to-date.

A Cocoa application for running scripts

2010-11-12T04:25:00.001-08:00

Last week, I showed a bash script that you can use to build, tag and package a Mac application. As I'll show you this time though, I prefer to use a compiled Mac application to do the same thing. The important code here is a set of classes that support script-like invocations of other programs and support for a structured build-log based on the results of each step.

Introduction

There are lots of different reasons to run scripts — configuring some open source project, packaging applications for deployment, arranging windows in your Xcode workspace, processing metadata from your iTunes collection, generating signatures for files, processing crash logs, etc.

But every time I'm forced to use a command-line script, I feel a little sad inside. I'm an application developer (at least some of the time) and a small, cramped, single-font, single-spaced, text-filled box seems like the wrong way to interact with anything that isn't a text editor. If I'm writing unformatted text, then an unformatted text window is the right interaction metaphor. For every other action, it reminds me that programmers often solve a whole world of construction problems using a toolbox filled entirely with hammers.

Another random wall of text. Everything must be fine. Or broken. What's going on?

When running a script — particularly one that can cause large numbers of errors or one that I might need to re-run repeatedly — the progress information, results presentation and error handling of a command-line script is truly sub-par.

IDE build logs do a much better job in this regard. As an example, here's Xcode building the same code as the previous Terminal screenshot:

Oh! I was building ffmpeg. Badly.

With a build log approach to display, you can see all the steps involved. The steps themselves are shown in a compact form.

Running a script in a compiled application

This is the key rationale behind this week's variation on the build script: a structure log with errors and warnings.

The Cocoa Build Script application showing the display with progress, errors and error highlighting.

You can download the complete sample project used in this post here CocoaScript.zip (255kb)

This program runs a generic series of steps and captures their standard output and standard error (or for non-process steps, whatever they choose to emit as their output and error).

In the sample application, the steps executed by the script are largely the same as last week's bash script — it's a build, version, commit, package script for deploying a basic Mac application. Yes, the application is entirely capable of packaging itself.

However, running a deployment script is not the only possible use for the classes in this project. The step classes are generic enough that most common script-like operations can be handled or you can choose to run standard Cocoa code as a step. I use variations of these classes as a lightweight job running framework for a number of different (mostly in-house) purposes.

To be clear: when I use the word "script" in this post, I'm referring to a series of steps that are largely invocations of other utility programs (the role that "shell scripts" normally fullfil). I am not using the word script to mean an interpreted programming language. The steps are not extracted by interpreting a text file at runtime — the actual program is compiled Cocoa/Objective-C.

Please don't confuse this with efforts like F-Script that actually execute an interpreted script within the Cocoa runtime.

Explaining the design of the application

The script itself is contained in the Script.m file (top of the Group Tree in the Xcode project).

Document and top level control

Since this application is a single window application, most of the application is controlled from the CocoaScriptWindowController. On construction, this window controller constructs the ScriptQueue (which is a subclass of NSOperationQueue). This ScriptQueue will run the step pipeline during the application.

When the queue is started (as happens automatically on startup or when the user restarts the application), the CocoaScriptWindowController calls the ScriptSteps() function to get the array of steps from the Script.m file and inserts the steps into the queue.

This steps array is the document of the application.

Observers

While the queue is running, the controllers observe progress in the following ways:

the CocoaScriptWindowController observes the number of items left in the queue
the NSArrayController (connected to the steps array in Interface Builder) observes the original steps in the queue
the array of ScriptStepCollectionViewItems (which are constructed automatically by the NSCollectionView due to its binding with the NSArrayController) observe the selected status of each step and the completion/error status of each step

Views

The ScriptStepView draws each row in the NSCollectionView on the left. Each ScriptStepView is bound to some data through the ScriptStepCollectionViewItem and other data (like step completion status) is pushed at it by the ScriptStepCollectionViewItem.

A standard NSTextView draws the text on the right. Its content is switched by the CocoaScriptWindowController based on the current selection and whether the Step Output or the Step Error is selected. The steps themselves generate their output as an NSTextStorage object which can be easily and efficiently connected to the NSTextView in this manner.

ScriptQueue and ScriptSteps

The queue and steps handle the functional pipeline of the application.

The queue is an NSOperationQueue and runs all steps in the global concurrent thread pool. However, unlike a standard NSOperationQueue, it makes all tasks dependent on the immediately preceding step by default (so steps are not concurrent by default). Steps can override this behavior by setting their concurrentStep (a step with which they are allowed to run in parallel). If steps set themselves as their concurrentStep, then they will have no dependencies.

The queue also has a list of cleanupSteps. These are a series of steps that are run if the queue is cancelled or terminates with an error (in the current version, they are not run if the script completes normally). You can push cancel steps on to the start or end of this list.

Of the ScriptSteps themselves, the most common is probably the TaskStep. This runs a process with an array of arguments and captures the standard output and standard error. You can pipe the output of one TaskStep into another (destinations of a pipe must be inserted into the array of steps after their source for the automatic concurrency between source and destination to work). You can also set regular expressions for the standard output or standard error which, if matched, will mark the step as having warnings or errors.

Most of the other steps are based on either BlockStep or ConditionalStep. BlockStep runs a C block for the step (so you can execute arbitrary Objective-C code). ConditionalStep does the same but returns a YES/NO condition. If a ConditionalStep returns NO, it will cancel any step that is "predicated" on the condition.

Threading notes

The steps run in the global concurrent queue (i.e. various threads). For the most part, they are not thread-safe while they are running and do not expect to be accessed after they are added to the queue. If you need to communicate between steps, you'll need to handle concurrency issues (have a look at the taskStartedCondition used in TaskStep to allow one TaskStep to pipe data to another for an example).

The textual output and error output from each step is an NSTextStorage object. These may only be accessed from the main thread (NSTextStorage requirement). If you look at ScriptStep.m, you'll notice that most of the code in this file is actually focussed on letting the ScriptStep (which runs from the global concurrent thread pool) post text changes (append, replace, change attributes) to the main thread.

State values and ScriptValues

Inside a step, you can access state values. This key value storage on the ScriptQueue acts as the variable storage during execution. If a step needs to pass data to another step, it can do so by storing data in a state value.

Looking through the Script.m file, it is important to remember that all code inside each step happens at script execution time — which happens some time after the ScriptSteps() function returns. However, you can only access the state values while the script is executing. When you're still assembling the array of steps in the ScriptSteps() function, the ScriptQueue state storage is not accessible.

To allow you to pass runtime state values into a step, many steps will accept ScriptValue objects instead of NSStrings for some parameters. A ScriptValue object is a placeholder for a state value. At execution time it is resolved to the actual state value.

Conclusion

You can download the complete sample project used in this post here CocoaScript.zip (255kb)

The steps used in this sample application's script are largely the same as last week's bash script. You can read the two side-by-side to see how different operations are done in each.

The Script.m file is about 3 times longer than the bash script was last week (550 versus 160 lines). While Cocoa is slightly wordier than bash, about 30% of the line difference is actually just whitespace due to my code formatting style. In this version, I also configure each step to have careful error handling and user feedback which extends the length of the script somewhat. There's also more commenting in this version.

The entire project is a little under 5000 lines (including comments and whitespace), which I think makes it one of the largest projects I've presented in a post. It's a little hard to cover all the aspects but there's plenty of code snippets inside to look at (it's all at least partially commented). If you're looking for an example on NSCollectionView and NSCollectionViewItem, NSOperationQueue and NSOperation, NSTextStorage and NSTextView, NSTask or NSPredicate, then there's code to be found within.

I'm not entirely sure whether other people are likely to enjoy the idea of running script-like tasks in a compiled Cocoa application as much as I do — I realize I'm probably pretty strange in this regard. However, I think there's merit in considering the presentation of results as part of the expectations of a script; especially where you want clear feedback about how a process is progressing or why a step failed. That's the real strength of this approach: highly configurable error checking and structured feedback for all steps.

A deployment script for a generic Cocoa Mac application

2010-11-05T20:07:00.001-07:00

Deployment for a Cocoa Mac application normally involves a few common steps: committing code into a repository, updating version numbers and packaging the application as a DMG disk image. In this post, I'll show you a combination bash/perl/Applescript to handle all these tasks in a single script.

Deployment steps

Standard Xcode build templates will build your code but don't really offer any help beyond that point. Deploying your application normally requires a few extra steps beyond what the standard templates provide.

While you can simply make a ZIP archive out of the application in your Release directory and call it done, there's normally a few more steps that you should take when deploying an application.

1. Update your version number

Obviously, this isn't a hard step but it is easy to forget since the user-facing version number (build numbers not included) must be deliberately updated when you decide a build is ready.

2. Commit your code into a version control system

This step should be obvious: it protects your time investment by ensuring that your code doesn't disappear.

And yet I still visit small or single-programmer offices where all the code is just kept in a directory and the whole directory is duplicated from version to version or to play with features. Seriously, that is not how you should manage things. You may have your disk backed up, you may keep copies of your builds but these things are only complimentary to maintaining your repository.

How did we implement this feature in version 1.2 (and where's the old code)? Why was this code changed and what did it do before? Do we have a copy of version 3.5 of the application anywhere?

These are the questions that are best answered by not only having a code repository but having it properly tagged for every build. I won't get into philosophies about how frequently you should commit between releases or how you should tag bug fixes and feature changes but the absolute minimum for any system should be that you tag your releases. Your deployment script should make this mandatory.

Incidentally, newer distributed repository version control programs like git make creating a repository for your code so much simpler. Instead of needing to set up a centralized location, you can casually make any folder its own local repository (i.e. just run "git init" in the directory) and worry about whether and where to locate an official or shared repository later.

Frustrated at Xcode's horrible version control system support? Can't remember all the git commands? Don't like git's command-line interface? I certainly don't. Fortunately, Mac apps like GitX are simple, pretty and work well.

3. Make certain you have a clean build

From time-to-time, you will encounter problems with builds that are only fixed by cleaning and rebuilding. One of the biggest examples of this are assets that you deliberately remove from the build — these never get removed from the build directory unless you clean first, then build. Without a step to clean the directory first, your build may not be exactly what you think it should be.

4. Package the application in a DMG file

Mostly for reasons of aesthetic presentation, Mac applications that don't require an installer are normally deployed as DMG disk images. These can be a little fiddly to create, adjust aesthetically and then create a compressed version for distribution.

Fortunately, with a little Applescripting, we can automate this process too.

A big ole Bash script

Here then is a bash script to handle all of the above steps. It's an annoying diversion into another language for a C/Obj-C/C++ programmer but some things (especially setting folder view options) need to be done a specific way.

A script of this sort is the traditional way that this type of deployment is handled. However, it is actually not how I handle my deployments (but I'm a little weird in this respect). Next week, I'll show you the code I use for deployment.

Assumptions in this script

There's a few assumptions here. While they are normally valid assumptions if you create your project using default Cocoa Mac Application template, there are certainly cases where they won't apply and you'll need to tweak the script a little.

This script requires 1 parameter: the .xcodeproj file you want to build.
The target you want to build must have the same name as the project (minus the .xcodeproj extension).
The Info.plist for the application must have the same name as the project (minus the .xcodeproj extension) with the suffix "-Info.plist".
The application build has the same name as the project (minus the .xcodeproj extension).
The deployment build is the "Release" build and the build project directory is the build/Release directory.
You use git for your repository (although this script will continue if git is not installed).
The background image for your DMG folder is a 400x300px PNG named background.png in the same folder as the .xcodeproj file (although this script will skip background image steps if the background.png is missing).
The deployment DMG file will be saved to the Desktop with the same name as the project (minus the .xcodeproj extension) with the suffix ".dmg" (build will fail if there's already something at this location).

The script

#!/bin/bash

if [ ! "${1}" ]; then
    echo "usage: $0 xcode_project_path"
    exit
fi

XCODE_PROJECT_PATH=$1
XCODE_DIRECTORY="`dirname "$1"`"
XCODE_PROJECT_NAME="`basename -s .xcodeproj "${XCODE_PROJECT_PATH}"`"

# xcodebuild needs to run from the project's directory so we'll move there
# and stay for the duration of this script
cd "${XCODE_DIRECTORY}"

# Check if git is installed
if [ `which git` ]; then
    echo "git is installed on this computer"

    # If git is installed, then require that the code be committed
    if [ "`git status -s 2>&1 | egrep '^\?\?|^ M|^A |^ D|^fatal:'`" ] ; then
        echo "Code is not committed into git. Commit into git before deployment."
        exit
    fi
    echo "Repository up-to-date."
fi

# !! Update: Changed from using the Perl Cocoa bridge to using PlistBuddy !!
# Use the perl to Objective-C bridge to get the version from the Info.plist
# You could easily use the python or ruby bridges to do the same thing
#CURRENT_VERSION="`echo 'use Foundation;
#$file = "'"${XCODE_PROJECT_NAME}"'-Info.plist";
#$plist = NSDictionary->dictionaryWithContentsOfFile_($file);
#$value = $plist->objectForKey_("CFBundleVersion");
#print $value->description()->UTF8String() . "\n";' | perl`"

# Use PlistBuddy instead of the perl to Cocoa bridge
CURRENT_VERSION="`/usr/libexec/PlistBuddy -c 'Print CFBundleVersion' \
    "${XCODE_PROJECT_NAME}-Info.plist"`"

# Report the current version
echo "Current version is ${CURRENT_VERSION}"

# Prompt for a new version
read -p "Please enter the new version:
" NEW_VERSION

# !! Update: Changed from using the Perl Cocoa bridge to using PlistBuddy !!
# Use the bridge again to write the updated version back to the Info.plist
#echo 'use Foundation;
#$version = "'$NEW_VERSION'";
#$file = "'"${XCODE_PROJECT_NAME}"'-Info.plist";
#$plist = NSDictionary->dictionaryWithContentsOfFile_($file);
#$plist->setObject_forKey_($version, "CFBundleVersion");
#$plist->writeToFile_atomically_($file, "YES");' | perl

# Use PlistBuddy instead of the perl to Cocoa bridge
/usr/libexec/PlistBuddy -c "Set CFBundleVersion ${NEW_VERSION}" \
    "${XCODE_PROJECT_NAME}-Info.plist"

# Commit the updated Info.plist
if [ `which git` ]; then
    git commit -m "Updated Info.plist to version ${NEW_VERSION}" \
        "${XCODE_PROJECT_NAME}-Info.plist"
fi

# Clean the Release build
xcodebuild -configuration Release -target "${XCODE_PROJECT_NAME}" clean

# Build the Release build
if [ "`xcodebuild -configuration Release -target "${XCODE_PROJECT_NAME}" build \
     | egrep ' error:'`" ] ; then
    echo "Build failed."
    exit
fi

# Tag the repository now that we have a successful build
git tag "version-${NEW_VERSION}"

#########
# From this point onwards, the script is all about DMG packaging
#########

# Create a temporary directory to work in
TEMP_DIR="`mktemp -d "${TMPDIR}${XCODE_PROJECT_NAME}.XXXXX"`"

# Create the folder from which we'll make the disk image
DISK_IMAGE_SOURCE_PATH="${TEMP_DIR}/${XCODE_PROJECT_NAME}"
mkdir "${DISK_IMAGE_SOURCE_PATH}"

# Copy the application into the folder
cp -R "build/Release/${XCODE_PROJECT_NAME}.app" \
    "${DISK_IMAGE_SOURCE_PATH}/${XCODE_PROJECT_NAME}.app"

# Make a symlink to the Applications folder
# (so we can prompt the user to install the application)
ln -s "/Applications" "${DISK_IMAGE_SOURCE_PATH}/Applications"

# If a "background.png" file is present in the Xcode project directory,
# we'll use that for the background of the folder.
# An assumption is made in this script that the background image is 400x300px
# If you are using a different sized image, you'll need to adjust the
# placement and sizing parameters in the Applescript below
if [ -e "background.png" ]; then
    cp "background.png" \
        "${DISK_IMAGE_SOURCE_PATH}/background.png"
fi


# Create the read-write version of the disk image from the folder
# Also note the path at which the disk is mounted so we can open the disk
# to adjust its attributes
DISK_IMAGE_READWRITE_PATH="${DISK_IMAGE_SOURCE_PATH}-rw.dmg"
VOLUME_MOUNT_PATH="`hdiutil create -srcfolder "${DISK_IMAGE_SOURCE_PATH}" \
    -format UDRW -attach "${DISK_IMAGE_READWRITE_PATH}" | \
    sed -n 's/.*\(\/Volumes\/.*\)/\1/p'`"


# Now we use Applescript to tell the Finder to open the disk image,
# set the view options to a bare, icon arranged view
# set the background image (if present)
# and set the icon placements
if [ -e "background.png" ]; then
    echo '
    tell application "Finder"
        open ("'"${VOLUME_MOUNT_PATH}"'" as POSIX file)
        set statusbar visible of front window to false
        set toolbar visible of front window to false
        set view_options to the icon view options of front window
        set icon size of view_options to 96
        set arrangement of view_options to not arranged
        set the bounds of front window to {100, 100, 500, 400}
        set app_icon to item "'"${XCODE_PROJECT_NAME}"'" of front window
        set app_folder to item "Applications" of front window
        set background_image to item "background.png" of front window
        set background picture of view_options to item "background.png" of front window
        set position of background_image to {200, 200}
        set position of app_icon to {120, 100}
        set position of app_folder to {280, 100}
        set current view of front window to icon view
    end tell' | osascript
else
    echo '
    tell application "Finder"
        open ("'"${VOLUME_MOUNT_PATH}"'" as POSIX file)
        set statusbar visible of front window to false
        set toolbar visible of front window to false
        set view_options to the icon view options of front window
        set icon size of view_options to 96
        set arrangement of view_options to not arranged
        set the bounds of front window to {100, 100, 500, 400}
        set app_icon to item "'"${XCODE_PROJECT_NAME}"'" of front window
        set app_folder to item "Applications" of front window
        set position of app_icon to {120, 100}
        set position of app_folder to {280, 100}
        set current view of front window to icon view
    end tell' | osascript
fi

# Make the background.png file invisible
SetFile -a V "${VOLUME_MOUNT_PATH}/background.png"

# Eject the disk image so that we can convert it to a compressed format
hdiutil eject "${VOLUME_MOUNT_PATH}"

# Create the final, compressed disk image
hdiutil convert "${DISK_IMAGE_READWRITE_PATH}" -format UDBZ \
    -o "${HOME}/Desktop/${XCODE_PROJECT_NAME}.dmg"

# Remove the temp directory
rm -Rf "${TEMP_DIR}"

Conclusion

Ergh: a code-heavy post with neither C nor Objective-C.

Next week, I'll show you how to perform the same steps in a logging, reporting, error-handling Cocoa application.

An iOS tone generator (an introduction to AudioUnits)

2010-10-20T01:00:00.001-07:00

In this post, I present a tiny iOS app that generates a continuous tone at a frequency determined by a slider. It's a small sample app intended to show the simplest way to send audio data you generate to the speaker.

Introduction

I've previously written posts on playing audio from MP3/AAC files and streams. These posts use the AudioQueue API to play audio. The AudioQueue interface can take audio data — still in compressed formats — and play it on the device output. This decoding/decompressing is the key strength of the AudioQueue APIs and it is the only way to take advantage of the hardware decoding on iOS devices.

However, if you're generating your own audio (and it is therefore already decompressed, linear PCM) you don't need to use AudioQueue. You can still play audio in this format using AudioQueue but the reality is that you'll have more control and be able to do much more if you use the lowest level audio API (lowest in iOS, anyway): the AudioUnit.

Sample application: ToneGenerator

The sample application for this post is really simple: a slider to control frequency and a play button.

The tone is generated continuously while you change the frequency so you can play with the tone generator like a slide whistle for hours of neighbour-annoying fun.

You can download the ToneGenerator and the complete sample project used in this post here ToneGenerator.zip (25kb)

Audio Units

AudioUnits are lowest level of sound generation on iOS and the lowest hardware abstracted layer commonly used on the Mac. They generate raw audio samples when requested and place them into output buffers. That's their entire function.

An AudioUnit generates these samples in its render function. The render function is invoked to generate samples on a dedicated audio thread.

In an effort to keep the code as focussed as possible on the basics of AudioUnits, I will be showing you how to create a single AudioUnit and use it on its own to output sound. Ordinarily though, AudioUnits are used as part of an AUGraph which chains a few different units together for feeding in sound data, mixing, effects and other purposes. Perhaps I'll show more about that in a future post but for now, the aim is to keep it simple.

Generating your own audio samples

Generating audio samples means that we must calculate the values of an audio waveform at the required time locations (sample points).

In this sample application, we're going to use 32-bit floating point values for each sample (since that's the easiest). This is for convenience, it's not the best format for performance on iOS — that would be the canonical sample format of 8.24 signed, fixed-point samples (that's 32-bits per sample with 24 bits of that used as the fractional component). But convenience is more important than raw efficiency in this sample application so floats are good enough.

The values can vary between -1.0 and +1.0 but we're going to limit our samples to a smaller range than that to keep the volume to a reasonable level.

Our generated tone is a basic sine wave (a pure tone). The value at each sample point will then be determined by the following equation:

f(n) = a sin ( θ(n) )

where n is the index of the current sample, a is the amplitude and the current angle of the waveform, θ(n) is given by:

θ(n) = 2πƒ n / r

where ƒ is the frequency of the tone we want to generate and r is the sample rate of the audio we're generating.

Implementing this in our AudioUnit's render function, gives us a function that looks like this:

OSStatus RenderTone(
    void *inRefCon, 
    AudioUnitRenderActionFlags *ioActionFlags, 
    const AudioTimeStamp *inTimeStamp, 
    UInt32 inBusNumber, 
    UInt32 inNumberFrames, 
    AudioBufferList *ioData)

{
    // Fixed amplitude is good enough for our purposes
    const double amplitude = 0.25;

    // Get the tone parameters out of the view controller
    ToneGeneratorViewController *viewController =
        (ToneGeneratorViewController *)inRefCon;
    double theta = viewController->theta;
    double theta_increment =
        2.0 * M_PI * viewController->frequency / viewController->sampleRate;

    // This is a mono tone generator so we only need the first buffer
    const int channel = 0;
    Float32 *buffer = (Float32 *)ioData->mBuffers[channel].mData;
    
    // Generate the samples
    for (UInt32 frame = 0; frame < inNumberFrames; frame++) 
    {
        buffer[frame] = sin(theta) * amplitude;
        
        theta += theta_increment;
        if (theta > 2.0 * M_PI)
        {
            theta -= 2.0 * M_PI;
        }
    }
    
    // Store the updated theta back in the view controller
    viewController->theta = theta;

    return noErr;
}

Creating an AudioUnit for outputting audio

AudioUnit is a low-level API, so there are many settings you can configure — and you have to configure a lot of them to get playback to work at all. Fortunately, it's all pretty straightforward.

Here's the code to create and configure an output audio unit (toneUnit) for playing 32 bit, single channel, floating point, linear PCM sound that generates its audio using the function RenderTone.

// Configure the search parameters to find the default playback output unit
// (called the kAudioUnitSubType_RemoteIO on iOS but
// kAudioUnitSubType_DefaultOutput on Mac OS X)
AudioComponentDescription defaultOutputDescription;
defaultOutputDescription.componentType = kAudioUnitType_Output;
defaultOutputDescription.componentSubType = kAudioUnitSubType_RemoteIO;
defaultOutputDescription.componentManufacturer = kAudioUnitManufacturer_Apple;
defaultOutputDescription.componentFlags = 0;
defaultOutputDescription.componentFlagsMask = 0;

// Get the default playback output unit
AudioComponent defaultOutput = AudioComponentFindNext(NULL, &defaultOutputDescription);
NSAssert(defaultOutput, @"Can't find default output");

// Create a new unit based on this that we'll use for output
OSErr err = AudioComponentInstanceNew(defaultOutput, &toneUnit);
NSAssert1(toneUnit, @"Error creating unit: %ld", err);

// Set our tone rendering function on the unit
AURenderCallbackStruct input;
input.inputProc = RenderTone;
input.inputProcRefCon = self;
err = AudioUnitSetProperty(toneUnit, 
    kAudioUnitProperty_SetRenderCallback, 
    kAudioUnitScope_Input,
    0, 
    &input, 
    sizeof(input));
NSAssert1(err == noErr, @"Error setting callback: %ld", err);

// Set the format to 32 bit, single channel, floating point, linear PCM
const int four_bytes_per_float = 4;
const int eight_bits_per_byte = 8;
AudioStreamBasicDescription streamFormat;
streamFormat.mSampleRate = sampleRate;
streamFormat.mFormatID = kAudioFormatLinearPCM;
streamFormat.mFormatFlags =
    kAudioFormatFlagsNativeFloatPacked | kAudioFormatFlagIsNonInterleaved;
streamFormat.mBytesPerPacket = four_bytes_per_float;
streamFormat.mFramesPerPacket = 1;    
streamFormat.mBytesPerFrame = four_bytes_per_float;        
streamFormat.mChannelsPerFrame = 1;    
streamFormat.mBitsPerChannel = four_bytes_per_float * eight_bits_per_byte;
err = AudioUnitSetProperty (toneUnit,
    kAudioUnitProperty_StreamFormat,
    kAudioUnitScope_Input,
    0,
    &streamFormat,
    sizeof(AudioStreamBasicDescription));
NSAssert1(err == noErr, @"Error setting stream format: %ld", err);

Start it playing

Once you've got an output AudioUnit created, you need to initialize it using AudioUnitInitialize (which verifies that all the parameters are valid) and then you can start it running using AudioOutputUnitStart. Once an AudioUnit is initialized, you can't change further parameters, so if you need to change parameters again, you'll need to use AudioUnitUninitialize.

In the sample program, toggling playback performs a full teardown and recreation of the AudioUnit as follows:

- (IBAction)togglePlay:(UIButton *)selectedButton
{
    if (!toneUnit)
    {
        // Create the audio unit as shown above
        [self createToneUnit];
        
        // Finalize parameters on the unit
        OSErr err = AudioUnitInitialize(toneUnit);
        NSAssert1(err == noErr, @"Error initializing unit: %ld", err);
        
        // Start playback
        err = AudioOutputUnitStart(toneUnit);
        NSAssert1(err == noErr, @"Error starting unit: %ld", err);
        
        [selectedButton setTitle:NSLocalizedString(@"Stop", nil) forState:0];
    }
    else
    {
        // Tear it down in reverse
        AudioOutputUnitStop(toneUnit);
        AudioUnitUninitialize(toneUnit);
        AudioComponentInstanceDispose(toneUnit);
        toneUnit = nil;
        
        [selectedButton setTitle:NSLocalizedString(@"Play", nil) forState:0];
    }
}

Conclusion

You can download the ToneGenerator and the complete sample project used in this post here ToneGenerator.zip (25kb)

The aim in this post was to present a sample iOS application that shows AudioUnits in the simplest way possible. Most of the Apple sample projects are considerably more elaborate, involve complex AUGraphs or can't be used on iOS because they use Mac-only APIs.

However, this sample application is a little atypical because of this simplification. In more complex applications, you'll probably want an AUGraph to chain an input node fed from a file, possibly a mixer and effects nodes, then an output node together.

Testing if an arbitrary pointer is a valid object pointer

2010-10-06T21:06:00.001-07:00

In this post, I look at an approach for testing if an arbitrary pointer is a pointer to a valid Objective-C object. The result from the test is not absolutely accurate and can interfere with gdb debugging if the pointer isn't a valid memory location, so this is not something you'd want to do often (and certainly not in production code). But it can be a handy debugging tool for when you're staring blindly at memory you didn't allocate.

Introduction

I originally wrote this code when I was looking through all the notifications from the local CFNotificationCenter, trying to work out where I was making mistakes in some AVFoundation video code (AVFoundation produces a lot of notifications when media playback is happening).

The callback function for these notifications has the following prototype:

void MyNotificationCallBack (
   CFNotificationCenterRef center,
   void *observer,
   CFStringRef name,
   const void *object,
   CFDictionaryRef userInfo
);

The object associated with the notification is passed as a void *. Most of the time, the value in object will be an Objective-C object but for the few times when it isn't, simply passing the result into NSLog can cause your program to crash.

What do you need to test?

Again, this comes back to the question: what is a valid Objective-C object?

For the purpose of sending a message to an object, all you need is for the value pointed to by the object pointer (i.e. the isa pointer) to be a registered Class value. This is the most important point to test — the chance of an arbitrary memory value being a valid Class by chance is fairly low (although certainly not zero).

But there is another requirement to be a usable object: the memory space following the isa pointer must be valid. This is not an easy thing to test, but it is possible to test if the object itself was allocated at least as large as the class' instance size.

However, this allocation test does not need to return positive for any object that wasn't heap allocated. The most common example of non-heap allocated objects in Objective-C are compiler created strings. So while appropriate heap allocation for a block of memory that starts with an isa pointer is a near guarantee that the object is a valid Objective-C object, failure of this test does not eliminate the possibility that it's a valid object.

Finally, while all of this is happening, there remains the possibility that the pointer you're testing doesn't point to a valid memory location at all. If you're interested in handling this situation, you need to set up a signal handler (or Mach exception handler) to catch SIGBUS and SIGSEGV signals (or EXC_BAD_ACCESS if you go the Mach exceptions route).

The code

#import <malloc/malloc.h>
#import <objc/runtime.h>

static sigjmp_buf sigjmp_env;

void
PointerReadFailedHandler(int signum)
{
    siglongjmp (sigjmp_env, 1);
}

BOOL IsPointerAnObject(const void *testPointer, BOOL *allocatedLargeEnough)
{
    *allocatedLargeEnough = NO;
    
    // Set up SIGSEGV and SIGBUS handlers
    struct sigaction new_segv_action, old_segv_action;
    struct sigaction new_bus_action, old_bus_action;
    new_segv_action.sa_handler = PointerReadFailedHandler;
    new_bus_action.sa_handler = PointerReadFailedHandler;
    sigemptyset(&new_segv_action.sa_mask);
    sigemptyset(&new_bus_action.sa_mask);
    new_segv_action.sa_flags = 0;
    new_bus_action.sa_flags = 0;
    sigaction (SIGSEGV, &new_segv_action, &old_segv_action);
    sigaction (SIGBUS, &new_bus_action, &old_bus_action);

    // The signal handler will return us to here if a signal is raised
    if (sigsetjmp(sigjmp_env, 1))
    {
        sigaction (SIGSEGV, &old_segv_action, NULL);
        sigaction (SIGBUS, &old_bus_action, NULL);
        return NO;
    }
    
    Class testPointerClass = *((Class *)testPointer);

    // Get the list of classes and look for testPointerClass
    BOOL isClass = NO;
    NSInteger numClasses = objc_getClassList(NULL, 0);
    Class *classesList = malloc(sizeof(Class) * numClasses);
    numClasses = objc_getClassList(classesList, numClasses);
    for (int i = 0; i < numClasses; i++)
    {
        if (classesList[i] == testPointerClass)
        {
            isClass = YES;
            break;
        }
    }
    free(classesList);

    // We're done with the signal handlers (install the previous ones)
    sigaction (SIGSEGV, &old_segv_action, NULL);
    sigaction (SIGBUS, &old_bus_action, NULL);
    
    // Pointer does not point to a valid isa pointer
    if (!isClass)
    {
        return NO;
    }
    
    // Check the allocation size
    size_t allocated_size = malloc_size(testPointer);
    size_t instance_size = class_getInstanceSize(testPointerClass);
    if (allocated_size > instance_size)
    {
        *allocatedLargeEnough = YES;
    }
    
    return YES;
}

Results from the function

Running this test program:

void LogPointerInformation(const void *somePointer)
{
    BOOL allocatedLargeEnough;
    BOOL isMessageableObject = IsPointerAnObject(somePointer, &allocatedLargeEnough);
    NSLog(@"The pointer %p is %@ and is %@.",
        somePointer,
        isMessageableObject ?
            @"a valid object" :
            @"not a valid object",
        allocatedLargeEnough ?
            @"allocated at least as large as the required instance size" :
            @"not a known allocation");
}

int main (int argc, const char * argv[]) {
    NSAutoreleasePool * pool = [[NSAutoreleasePool alloc] init];

    LogPointerInformation(@"");
    LogPointerInformation([[[NSObject alloc] init] autorelease]);
    LogPointerInformation(LogPointerInformation);
    LogPointerInformation(0x12345678);

    [pool drain];
    return 0;
}

Gives the following results (I've chopped off the NSLog times for brevity):

The pointer 0x100001130 is a valid object and is not a known allocation.
The pointer 0x10011e940 is a valid object and is allocated at least as large as the required instance size.
The pointer 0x100000c0d is not a valid object and is not a known allocation.
The pointer 0x12345678 is not a valid object and is not a known allocation.

Limitations of this approach

The most serious limitation of this approach is that it can never guarantee anything. For this reason, it is important that you never use this in production code.

The most obvious situation where the function will fail completely is when testing a malloc'd C array of Objective-C class pointers. This memory block definitely starts with a valid Class value and may even have a malloc_size greater than that class' instance size — but the block was never truly allocated as an object and if any instance values are important to the class, they are all likely to be invalid.

Objects that are not heap allocated are difficult to guarantee that their instance memory will be within addressable memory. This means that you could raise SIGSEGV or SIGBUS signals.

Still on the topic of signals, while I've included signal handling in this code, it's unlikely you'll ever want it to be invoked as it stops gdb dead.

While ordinarily, you can give gdb a handle signal nostop noprint pass to continue after the signal, that won't work here. There are issues getting the Mac version of gdb to proceed after an EXC_BAD_ACCESS. It is actually easier to let gdb catch the signal, then drag the program execution point in Xcode to the top of the sigsetjmp block manually.

As a final caveat: the signal handling code that I've written is strictly not thread-safe and non-reentrant.

Conclusion

The result is more of a heuristic than an absolute verdict.

However, the approach is a useful tool to give an "acceptable" verification that a value is a valid object for debugging purposes. It is certainly good enough to test before sending values to NSLog.

The issues with gdb when an invalid memory access signal is raised are annoying. I'd be interested to see if there's a way to avoid this. It certainly provides an added disincentive to using this code on truly arbitrary values.

A ZoomingViewController to animate a UIView to fullscreen

2010-09-26T22:04:00.001-07:00

ZoomingViewController is a class you can attach to any existing view that will let you zoom the view to fullscreen with a single tap, rotate the view while in fullscreen by rotating the device and tap to return to the original inline state.

Introduction

The ZoomingViewController class in this week's sample project handles the zooming in the following sample app:

The animation between the inline and fullscreen states is smooth and you can rotate the device in fullscreen to rotate the view.

You can attach the ZoomingViewController to any view to add this behavior.

You can download the ZoomingViewController and the complete sample project used in this post here TapZoomRotate.zip (160kb)

Requirements

The ZoomingViewController has three primary requirements:

Respond to tap actions
Smoothly zoom between different superviews
Allow the view to rotate in fullscreen

Responding to tap actions

Most of the time, you don't need to handle tap actions yourself — controls like buttons or table view cells all have built-in tap detection.

Prior to iOS 3.2, detecting a tap meant implementing touchesBegan:withEvent: and touchesEnded:withEvent: in the view or responder chain. This was fiddly since you had to perform time and location based calculations yourself to determine if the tap completed validly. Further, it would not have worked for this ZoomingViewController class, which only attaches to the view rather than being part of the the view or responder chain implementation.

Fortunately, the gesture recognizers introduced in iOS 3.2 make this trivially easy:

singleTapGestureRecognizer =
    [[UITapGestureRecognizer alloc]
        initWithTarget:self action:@selector(toggleZoom:)];
singleTapGestureRecognizer.numberOfTapsRequired = 1;

[self.view addGestureRecognizer:singleTapGestureRecognizer];

Smoothly zooming between different superviews

First, we need to remember the old superview and location within it. We do this by inserting a proxy view into the hierarchy at the view's location — this way, it will also track the autoresized location of the view if the window rotates.

proxyView = [[UIView alloc] initWithFrame:self.view.frame];
proxyView.hidden = YES;
proxyView.autoresizingMask = self.view.autoresizingMask;
[self.view.superview addSubview:proxyView];

Then, we need to calculate our current position in the coordinate space of the target view (the target view is the window itself for animating to fullscreen). With this location calculated, we switch superview to the target view and set the frame to this calculated position.

CGRect frame =
    [self.view.window
        convertRect:self.view.frame
        fromView:proxyView.superview];
[self.view.window addSubview:self.view];
self.view.frame = frame;

Then, we animate from this calculated position to actually fill the screen:

[UIView
    animateWithDuration:0.2
    animations:^{
        self.view.frame = self.view.window.bounds;
    }];
[[UIApplication sharedApplication]
    setStatusBarHidden:YES
    withAnimation:UIStatusBarAnimationFade];

Allowing the view to rotate in fullscreen

ZoomingViewController is not actually a subclass of UIViewController. Even though it "controls" a view for the purpose of zooming in and out, it doesn't require any of the behavior from UIViewController to do this.

Even if you did make the class a UIViewController subclass, it still wouldn't let you use the auto rotate behavior built into UIViewController. The reason is that shouldAutorotateToInterfaceOrientation: is only invoked on the first UIViewController found in the window. Since the fullscreen view will always be the second view in the window (after the inline view from which it zoomed), the UIViewController auto rotate behavior won't be able to satisfy our rotation needs.

So we need to implement rotation ourselves. This requires 3 steps:

Determine the correct fullscreen bounds for a given orientation
Calculate a CGAffineTransform to transform from the current bounds to the new bounds after a rotation
Listen to UIDeviceOrientationDidChangeNotification and actually apply these new values when things change

Getting the bounds for the fullscreen view based on the orientation is pretty simple too. We do need to account for the strangeness of face up and face down orientations — I do this by taking the status bar orientation in these cases instead (I don't use the status bar all the time in case it is out of sync with the actual device for some reason).

- (CGRect)rotatedWindowBounds
{
    UIDeviceOrientation orientation = [[UIDevice currentDevice] orientation];
    if (orientation == UIDeviceOrientationFaceUp ||
        orientation == UIDeviceOrientationFaceDown)
    {
        orientation = [UIApplication sharedApplication].statusBarOrientation;
    }
    
    if (orientation == UIDeviceOrientationLandscapeLeft ||
        orientation == UIDeviceOrientationLandscapeRight)
    {
        CGRect windowBounds = self.view.window.bounds;
        return CGRectMake(0, 0, windowBounds.size.height, windowBounds.size.width);
    }

    return self.view.window.bounds;
}

After a UIDeviceOrientationDidChangeNotification, we apply these new bounds.

Unfortunately, applying different bounds has the effect of changing the coordinates of view's midpoint. Since the final step of rotating the view requires applying a rotation transformation and rotations are always performed around the midpoint of the view, we must also translate the view in situations where the bounds have changed so that the midpoint is the same as it was previously.

- (CGAffineTransform)orientationTransformFromSourceBounds:(CGRect)sourceBounds
{
    UIDeviceOrientation orientation = [[UIDevice currentDevice] orientation];
    if (orientation == UIDeviceOrientationFaceUp ||
        orientation == UIDeviceOrientationFaceDown)
    {
        orientation = [UIApplication sharedApplication].statusBarOrientation;
    }
    
    if (orientation == UIDeviceOrientationPortraitUpsideDown)
    {
        return CGAffineTransformMakeRotation(M_PI);
    }
    else if (orientation == UIDeviceOrientationLandscapeLeft)
    {
        CGRect windowBounds = self.view.window.bounds;
        CGAffineTransform result = CGAffineTransformMakeRotation(0.5 * M_PI);
        result = CGAffineTransformTranslate(result,
            0.5 * (windowBounds.size.height - sourceBounds.size.width),
            0.5 * (windowBounds.size.height - sourceBounds.size.width));
        return result;
    }
    else if (orientation == UIDeviceOrientationLandscapeRight)
    {
        CGRect windowBounds = self.view.window.bounds;
        CGAffineTransform result = CGAffineTransformMakeRotation(-0.5 * M_PI);
        result = CGAffineTransformTranslate(result,
            0.5 * (windowBounds.size.width - sourceBounds.size.height),
            0.5 * (windowBounds.size.width - sourceBounds.size.height));
        return result;
    }

    return CGAffineTransformIdentity;
}

Finally, we apply alls these values in response to the UIDeviceOrientationDidChangeNotification. Listening to the notification is easy, we just add ourselves as an observer when switching into fullscreen display:

[[NSNotificationCenter defaultCenter]
    addObserver:self
    selector:@selector(deviceRotated:)
    name:UIDeviceOrientationDidChangeNotification
    object:[UIDevice currentDevice]];

The only additional point to note is that when a view rotates, it exposes the view behind its corners briefly. To avoid this potentially unappealing situation, the ZoomingViewController uses a blanking view (a basic black view) that it inserts behind the view being rotated and removes when the rotation is complete.

The implementation of deviceRotated: contains the following code that creates and inserts the blanking view and applies the rotation in response to the UIDeviceOrientationDidChangeNotification:

CGRect windowBounds = self.view.window.bounds;
UIView *blankingView =
    [[[UIView alloc] initWithFrame:
        CGRectMake(-0.5 * (windowBounds.size.height - windowBounds.size.width),
            0, windowBounds.size.height, windowBounds.size.height)] autorelease];
blankingView.backgroundColor = [UIColor blackColor];
[self.view.superview insertSubview:blankingView belowSubview:self.view];

[UIView animateWithDuration:0.25 animations:^{
    self.view.bounds = [self rotatedWindowBounds];
    self.view.transform = [self orientationTransformFromSourceBounds:self.view.bounds];
} completion:^(BOOL complete){
    [blankingView removeFromSuperview];
}];

Conclusion

You can download the ZoomingViewController and the complete sample project used in this post here TapZoomRotate.zip (160kb)

ZoomingViewController is as simple to use as possible: create it, set its view and the view will immediately start responding to taps, zooming to fullscreen and rotating in fullscreen mode. You can apply it to any view in your hierarchy at any time where you need fullscreen display behavior.

Minimalist Cocoa programming

2010-09-20T06:51:00.001-07:00

In this post, I build and run a Cocoa Mac application on the command-line. This might not sound like a very difficult goal but I'll attempt to follow an additional constraint: use as few tools, components, classes and even lines of code as possible; truly minimalist Cocoa programming. The goal is to create an application that qualifies as a proper Mac application (including a menubar and a window) but without using Xcode, without an Info.plist file, without NIB files, without Interface Builder and without even using a text editor other than the Terminal itself.

Introduction

For this post, I was inspired (in a somewhat tangential way) by Amit Singh's Crafting a Tiny Mach-O Executable. In his article, Amit Singh crafts a 248 byte Mach-O executable in an effort to make the smallest executable possible on Mac OS X (he also presents a 165 byte version but this no longer runs in Snow Leopard).

A Cocoa application would never really get this small since "Cocoa" implies a large amount of linkage and runtime overhead in the executable (and I don't really want to start coding any of that by hand in assembly). But it inspired me to consider how you might reduce scale and complexity for a Cocoa App; what would be a minimalist Cocoa Mac application?

Of course, the answer in this case is entirely dependent on what criteria you require for a program to be considered a "Cocoa Mac application". I decided that a Cocoa Mac application must:

Use NSApplication to run the main event loop
Display a menubar with an application menu and a quit item which must correctly terminate the application
Display an NSWindow-based window
Bring the main window to the front on startup like a normal application
Code and program should raise no warnings or errors (preferrably no poor coding practices either but that's subjective)

Ordinarily, these aren't difficult objectives — they are part of the standard Xcode Cocoa application template — but there's actually a huge amount of content described in the default template. Just because you didn't add the different pieces yourself doesn't make it minimalist.

Starting small

If you're extreme enough to believe that you could program directly in hex, then you might consider the following to be the baseline for minimalist Mac OS X programming:

echo "CEFAEDFE07000000030000000200000002000000CC00000000000000010000007C0000005F5F5445585400000000000000000000001000000010000000000000F8000000070000000500000001000000000000005F5F74657874000000000000000000005F5F5445585400000000000000000000E810000010000000E80000000200000000000000000000000000000000000000000000000500000050000000010000001000000000000000000000000000000000000000000000000000000000000000000000000000000000000000E8100000000000000000000000000000000000000000000031C040682A00000081EC04000000CD80" | xxd -r -p - tiny; chmod a+x tiny; ./tiny; echo $?

That's Amit Singh's 248-byte program in raw hex, saved to a file by "xxd", marked as executable using "chmod", run and the result displayed (it returns the exit condition 42).

Realistically though, all I can read are the first 5 bytes "CEFAEDFE07" which are the magic value for a Mach-O executable plus the CPU type for X86 CPUs. While historically, people certainly have programmed in hex, I would never write a Mac OS X program like this and I doubt anyone else would either. So piping Amit's actual assembly directly through nasm is probably a more realistic baseline for minimalist Mac OS X programming.

I'm not going to fight through this in assembly though (it's an Objective-C blog, after all), so I'm going to need a compiler to progress from here.

Creating, building and running the smallest possible C program looks something like this:

echo "main(){}" | gcc -x c - ; ./a.out; echo $?

The options used with gcc might look a bit odd but they are: "-x c" (build as C code) and "-" (take input on standard in). The default output file name of "a.out" is acceptable for now.

While technically this builds a valid program and looks simpler than the block of hex up above, it actually does less than the previous program did — it doesn't even deliberately return a specific value (instead I get 252 which is probably just junk from the stack since main implicitly returns an int that we aren't returning).

It's a little better to actually return a value. While it's not much, you can at least claim that the program "does something".

echo "int main(){return 0;}" | gcc -x c -; ./a.out ; echo $?

Great, we've returned the default success value.

Tiny Cocoa

The smallest Objective-C program is the same as the smallest C program, just change the command-line so gcc builds Objective-C:

echo "int main(){return 0;}" | gcc -x objective-c -; ./a.out ; echo $?

but the gcc output is literally the same. I'll need to use at least one class to truly claim this is Objective-C:

echo "#import <objc/Object.h>
int main(){return [Object class]==nil;}" | gcc -x objective-c -lobjc -; ./a.out ; echo $?

Making a Foundation program is no harder, we just link against the Foundation framework instead of libobjc. I could use literally the same program but here's one with a proper NSAutoreleasePool, logging and process information:

echo '#import <Foundation/Foundation.h>
int main(){
    id pool=[NSAutoreleasePool new];
    NSLog(@"%@", [[NSProcessInfo processInfo] arguments]);
    [pool drain];
    return 0;
}' | gcc -framework Foundation -x objective-c - ; ./a.out ; echo $?

Notice that NSProcessInfo has no problems getting the command-line arguments without main needing to handle them.

With an AppKit application, the main function looks a little simpler because -[NSApplication run] creates its own autorelease pool (although I'll need to bring it back again later to work outside -[NSApplication run]):

echo '#import <Cocoa/Cocoa.h>
int main(){
    [[NSApplication sharedApplication] run];
    return 0;
}' | gcc -framework Cocoa -x objective-c - ; ./a.out ; echo $?

Unfortunately, while this AppKit program runs, it doesn't present a user-interface and doesn't quit unless we kill it. Not very satisfying.

Satisfying the requirements

In Snow Leopard, programs without application bundles and Info.plist files don't get a menubar and can't be brought to the front unless the presentation option is changed:

[NSApp setActivationPolicy:NSApplicationActivationPolicyRegular];

Next, we need to create the menu bar. You don't need to give the first item in the menubar a name (it will get the application's name automatically):

id menubar = [[NSMenu new] autorelease];
id appMenuItem = [[NSMenuItem new] autorelease];
[menubar addItem:appMenuItem];
[NSApp setMainMenu:menubar];

Then we add the quit item to the menu. Fortunately the action is simple since terminate: is already implemented in NSApplication and the NSApplication is always in the responder chain.

id appMenu = [[NSMenu new] autorelease];
id appName = [[NSProcessInfo processInfo] processName];
id quitTitle = [@"Quit " stringByAppendingString:appName];
id quitMenuItem = [[[NSMenuItem alloc] initWithTitle:quitTitle
    action:@selector(terminate:) keyEquivalent:@"q"] autorelease];
[appMenu addItem:quitMenuItem];
[appMenuItem setSubmenu:appMenu];

Finally, all we need to do is create a window and activate the application:

id window = [[[NSWindow alloc] initWithContentRect:NSMakeRect(0, 0, 200, 200)
    styleMask:NSTitledWindowMask backing:NSBackingStoreBuffered defer:NO]
        autorelease];
[window cascadeTopLeftFromPoint:NSMakePoint(20,20)];
[window setTitle:appName];
[window makeKeyAndOrderFront:nil];
[NSApp activateIgnoringOtherApps:YES];

In keeping with the pattern of the rest of the post, here's the entire program as a single, command-line executable statement:

echo '#import <Cocoa/Cocoa.h>
int main ()
{
    [NSAutoreleasePool new];
    [NSApplication sharedApplication];
    [NSApp setActivationPolicy:NSApplicationActivationPolicyRegular];
    id menubar = [[NSMenu new] autorelease];
    id appMenuItem = [[NSMenuItem new] autorelease];
    [menubar addItem:appMenuItem];
    [NSApp setMainMenu:menubar];
    id appMenu = [[NSMenu new] autorelease];
    id appName = [[NSProcessInfo processInfo] processName];
    id quitTitle = [@"Quit " stringByAppendingString:appName];
    id quitMenuItem = [[[NSMenuItem alloc] initWithTitle:quitTitle
        action:@selector(terminate:) keyEquivalent:@"q"] autorelease];
    [appMenu addItem:quitMenuItem];
    [appMenuItem setSubmenu:appMenu];
    id window = [[[NSWindow alloc] initWithContentRect:NSMakeRect(0, 0, 200, 200)
        styleMask:NSTitledWindowMask backing:NSBackingStoreBuffered defer:NO]
            autorelease];
    [window cascadeTopLeftFromPoint:NSMakePoint(20,20)];
    [window setTitle:appName];
    [window makeKeyAndOrderFront:nil];
    [NSApp activateIgnoringOtherApps:YES];
    [NSApp run];
    return 0;
}' | gcc -framework Cocoa -x objective-c -o MinimalistCocoaApp - ; ./MinimalistCocoaApp

That's an entire Cocoa Mac application that you can copy onto the clipboard, paste directly at the prompt in Terminal, hit return and it'll run.

Conclusion

At 9352 bytes when compiled (exact size may change from computer to computer), my simple Cocoa program is nowhere near as small as the assembly written Mac OS X baseline of 248 bytes. At 27 lines long, it might not immediately seem "minimalist", either. However, it does satisfy the requirements I set for being a proper Cocoa Mac application.

The reality is that the things done under-the-hood by the default application templates, by the Xcode build system, by Interface Builder and by NSApplication itself in conjunction with the Info.plist file are significant. To replicate the required subset of their functionality requires at least some work. Compared to the standard Xcode Cocoa application template's 85782 bytes for the entire compiled bundle, my app's goal of Cocoa minimalism seems far more successful.

Reducing the size of the executable wasn't my primary goal, though. I was aiming to reduce the number of tools, components, files and classes required for a genuine Cocoa Mac application. Relative to the standard suite of tools and collection of files involved in building a Cocoa Mac app, 27 lines of code processed using echo, gcc and a bash terminal represents a significant simplification.

I welcome further suggestions about how to satisfy the same requirements with less.

The overhead of spawning threads (a performance experiment)

2010-09-14T23:51:00.001-07:00

In this post, I take a casual look at the relative performance overheads handling tasks in different ways: performing all tasks in the main thread, sending tasks to a single worker thread, spawning new threads for every task, and using Grand Central Dispatch (GCD). This won't be a particularly advanced investigation, simply a quick overview of simplicity versus performance in job management.

Introduction

I have a number of projects that need to support Mac OS X Leopard and iOS 3.x, so these projects cannot use libdispatch (aka Grand Central Dispatch).

In these GCD-free situations, I was curious to know what was the difference in overhead between properly setting up dedicated CFRunLoop-based worker threads and using a more haphazard spawn-a-new-NSThread-for-every-task approach. This post presents the results of that investigation.

I also included GCD results to compare with these traditional Cocoa threading approaches. There should be no surprises that GCD is much faster than any of the other threaded approaches. However there is also some interesting information regarding GCD queue configurations that can affect performance on different computers.

Test setup

The test is relatively straightforward:

A number of job queues need to run.
Each queue runs a number of jobs serially.
The complete set of jobs are not known in advance — as each job completes, it adds the next job to the queue.

In the code, I've called the number of jobs that run on each queue "iterations" because there is actually only one job object per queue and it adds itself back to the queue as the next job.

The jobs themselves have no work to perform (other than decrementing the iteration count). The purpose here is purely to test the overhead of different job queuing and management approaches.

Queue implementations

SingleThreadedQueue

The single threaded queue simply adds all jobs to an NSMutableArray and runs them in the current thread in the order added.

This test involves no worker thread at all and is really the "control" case.

Running all the jobs involves looping until the queue is empty and running one job per iteration.

- (void)queueJob:(Job *)aJob
{
    if (!jobQueue)
    {
        jobQueue = [[NSMutableArray alloc] init];
        [jobQueue addObject:aJob];
        
        while ([jobQueue count] > 0)
        {
            Job *nextJob = [jobQueue objectAtIndex:0];
            [jobQueue removeObjectAtIndex:0]; 
            [nextJob performIterationAndRequeueInJobRunner:self];
        }
        
        [jobQueue release];
        jobQueue = nil;
    }
    else
    {
        [jobQueue addObject:aJob];
    }
}

The if (!jobQueue) condition around the other work exists to avoid recursion on the stack when the performIterationAndRequeueInJobRunner: method invokes queueJob: again to queue the next job.

RunLoopQueue

Running a dedicated worker thread is involves creating and starting an NSThread but then once the thread is started, you can add jobs to it with performSelector:

- (void)queueJob:(Job *)aJob
{
    [aJob
        performSelector:@selector(performIterationAndRequeueInJobRunner:)
        onThread:runLoopThread 
        withObject:self
        waitUntilDone:NO];
}

DetachThreadQueue

The main point here is that we create a new thread for every job. We also need to have a thread entry point that puts an NSAutoreleasePool up (or other thread context that we may require) and runs the actual job itself.

- (void)queueJob:(Job *)aJob
{
    [NSThread detachNewThreadSelector:@selector(threadEntry:)
        toTarget:self withObject: aJob];
}

- (void)threadEntry:(Job *)aJob
{
    NSAutoreleasePool *pool = [[NSAutoreleasePool alloc] init];
    [aJob performIterationAndRequeueInJobRunner:self];
    [pool release];
}

DetachThreadWithVerificationQueue

However, when experimenting with this test, I ran into an issue I'd never encountered before: the Mac OS X thread limit. According to the command line function sysctl kern.maxfiles my thread limit is around 12288 for the whole operating system (the limit is RAM dependent) — you do have to be pretty reckless to use them all but it's not impossible.

The annoying point here is that you don't get an error when NSThread fails to start an actual thread — instead, the thread never starts and you're left wondering why nothing happened.

So I introduced a little extra code to ensure that the thread started correctly. This code passes an NSCondition into the detached thread and if this condition isn't signalled within 10 seconds, it is assumed that the thread failed to launch.

- (void)queueJob:(Job *)aJob
{
    NSCondition *startedCondition = [[NSCondition alloc] init];
    NSDictionary *threadParameters =
        [NSDictionary dictionaryWithObjectsAndKeys:
            aJob, @"job",
            startedCondition, @"condition",
        nil];
    
    [startedCondition lock];
    
    [NSThread detachNewThreadSelector:@selector(threadEntry:)
        toTarget:self withObject:threadParameters];
    
    if (![startedCondition waitUntilDate:[NSDate dateWithTimeIntervalSinceNow:10.0]])
    {
        NSLog(@"Thread creation failed.");
        [aJob killJob];
    }
    
    [startedCondition unlock];
    [startedCondition release];
}

- (void)threadEntry:(id)threadParameters
{
    NSAutoreleasePool *pool = [[NSAutoreleasePool alloc] init];
    NSCondition *startedCondition = [threadParameters objectForKey:@"condition"];
    Job *aJob = [threadParameters objectForKey:@"job"];
    
    [startedCondition lock];
    [startedCondition signal];
    [startedCondition unlock];
    
    [aJob performIterationAndRequeueInJobRunner:self];
    [pool release];
}

GCD Dedicated Queue

Once you've created a queue using dispatch_queue_create, sending a job to it is very simple:

- (void)queueJob:(Job *)aJob
{
	dispatch_async(queue, ^{
		[aJob performIterationAndRequeueInJobRunner:self];
	});
}

DispatchGlobalConcurrentQueue

The implementation of queueJob is identical here, the only difference is that the queue is obtained using dispatch_get_global_queue(DISPATCH_QUEUE_PRIORITY_DEFAULT, 0).

- (void)queueJob:(Job *)aJob
{
	dispatch_async(queue, ^{
		[aJob performIterationAndRequeueInJobRunner:self];
	});
}

Results

My computer is a 4 core Mac Pro with HyperThreading. This is particularly relevant for these tests because it should be able to support 8 threads in hardware. Let's see how it goes.

In the following table of timing results, the following abbreviations are used:

Single — SingleThreadedQueue
RunLoop — RunLoopQueue
Detach — DetachThreadQueue
Detach w/ Ver. — DetachThreadWithVerificationQueue
GCD-DQ — DispatchDedicatedQueue
GCD-GCQ — DispatchGlobalConcurrentQueue

Configuration	Single	RunLoop	Detach	Detach w/ Ver.	GCD-DQ	GCD-GCQ
1 Queue, 100k iterations	0.035990	0.776727	6.356978	7.166419	0.052294	0.102622
4 Queues, 25k iterations	0.036177	0.243689	4.513922	4.643964	0.038666	0.044127
8 Queues, 12.5k iterations	0.036134	0.199367	13.750981	11.947684	0.025748	0.046173
16 Queues, 6.25k iterations	0.036132	0.200769	40.493681	30.934207	0.025616	0.046114

All times are in seconds. Iterations are per queue (total iterations is always 100,000).

Visually comparing all except the Detach Thread approaches:

The vertical axis is in seconds.

I deliberately cut the top of the graph off but the RunLoop version took 0.776727 in the first test — more than three times above the top of this graph.

I've placed the Detach Thread approaches on their own graph because they're more than an order of magnitude slower. Again, the vertical axis is in seconds.

Analysis

Since these tests were intended to test job queue overhead, and the SingleThreadedQueue had no threading overhead and only need to perform NSArray operations, it is unsurprising that it was generally the fastest — except in the 8 and 16 queue cases where the DispatchDedicatedQueue was faster (likely because the little overhead it actually has is absorbed by the multiple cores in my computer).

My computer can run 8 threads in hardware. This likely explains why 8 queues is the optimum number of RunLoops to spawn and GCD dedicated queues. However — the GCD global concurrent queue never used all 8 possible threads (it peaked at 59% total CPU usage which is approximately 4 threads used), so it peaked in performance at 4 concurrent queues.

The DetachThread queues actually used twice as many threads as queues (the previous and next jobs' queues are both present at the same time) so these queues peaked at 4 queues. Interestingly, the "with verification" version started to exceed the performance of the "without" version after 4 queues — I suspect this is because the mutex used in the verification actually reduced the active thread count slightly.

Clearly, detaching threads has a very high overhead — around 1 second per 12,000 threads spawned. This isn't going to be an issue if you're only spawning 20 or 30 threads but spawning hundreds or thousands is a complete waste of time — and it only gets worse as the number of active threads at any given time increases.

Conclusion

You can download the code used in this post ThreadingOverheads.zip (14kb)

While it is valid to detach new threads for infrequent tasks (as many as dozens per second), the overhead on a completely new thread is non-trivial so if your tasks are small and numerous, a solution that reuses threads is pretty important. Even the overhead of a RunLoop solution (which was the traditional worker thread approach in Cocoa prior to GCD) is noticeable once the number of tasks reaches the tens of thousands.

It is easy to see why Apple chose to introduce Grand Central Dispatch — it lowers the overhead on job queues by an order of magnitude relative to a typical RunLoop-based worker thread — and they're easier to create and use as well.

Substituting local data for remote UIWebView requests

2010-09-06T05:22:00.001-07:00

In this post, I'll show you how you can load a webpage in a UIWebView in iOS while using a modified NSURLCache to substitute local copies of resources within the webpage for the remote copies referred to by the actual page.

Introduction

Normally if you're writing an iOS app with network connectivity, you'll want to put a native iOS interface on all data received over the network.

However, there are always scheduling and other constraints on a project that limit what you can implement and sometimes you may simply choose to show a regular, webpage to the user.

If you choose to take this approach, it is best to make sure the web interface feels as smooth as possible. One of the steps you can take to ensure this is to include local copies of all image and other non-updating resources within the application itself.

To use a local resource in an iOS webpage loaded from a remote location, either the remote page must refer to the local resource in some way (e.g. through a custom URL scheme) or you must swap a local location in place of a remote locations.

In this post, I'll look at how we can substitute a local resource when the webpage contains references to remote resources.

NSURLCache

On the Mac, you could use a range of different approaches in the WebViewDelegate to do this, including implementing webView:resource:willSendRequest:redirectResponse:fromDataSource: to substitute one NSURLRequest for another. Unfortunately, the UIWebViewDelegate in iOS is not nearly as capable so we need to do this another way.

Fortunately, there is one point you can hook into that is invoked for (almost) every request: the NSURLCache.

Normally, very little is actually cached in the NSURLCache, particularly on older iOS devices where the cache size is downright miniscule. Even if you use the setMemoryCapacity: method to increase the size of the cache, it seems significantly less likely to store resources than the NSURLCache on the Mac.

Of course that doesn't matter in this case, since we're going to subclass NSURLCache and implement our own version that will be guaranteed to hold all the resources we need and won't need pre-caching (all the resources will be there before the program is started).

cachedResponseForRequest:

The only important method we need to override is cachedResponseForRequest:. This will allow us to examine every request before it is sent and return local data if we prefer.

For this code, I'll use a dictionary that maps remote URLs to local file names in the Resources folder of the application bundle. If any request is made for the specified URLs, the contents of the local file will be returned instead.

So given the following dictionary containing a single path for substitution:

- (NSDictionary *)substitutionPaths
{
    return
        [NSDictionary dictionaryWithObjectsAndKeys:
            @"fakeGlobalNavBG.png",
            @"http://images.apple.com/global/nav/images/globalnavbg.png",
        nil];
}

The following cachedResponseForRequest: implementation will substitute the contents of the fakeGlobalNavBG.png file in the Resources folder any time the URL http://images.apple.com/global/nav/images/globalnavbg.png is requested.

- (NSCachedURLResponse *)cachedResponseForRequest:(NSURLRequest *)request
{
    // Get the path for the request
    NSString *pathString = [[request URL] absoluteString];
    
    // See if we have a substitution file for this path
    NSString *substitutionFileName = [[self substitutionPaths] objectForKey:pathString];
    if (!substitutionFileName)
    {
        // No substitution file, return the default cache response
        return [super cachedResponseForRequest:request];
    }
    
    // If we've already created a cache entry for this path, then return it.
    NSCachedURLResponse *cachedResponse = [cachedResponses objectForKey:pathString];
    if (cachedResponse)
    {
        return cachedResponse;
    }
    
    // Get the path to the substitution file
    NSString *substitutionFilePath =
        [[NSBundle mainBundle]
            pathForResource:[substitutionFileName stringByDeletingPathExtension]
            ofType:[substitutionFileName pathExtension]];
    NSAssert(substitutionFilePath,
        @"File %@ in substitutionPaths didn't exist", substitutionFileName);
    
    // Load the data
    NSData *data = [NSData dataWithContentsOfFile:substitutionFilePath];
    
    // Create the cacheable response
    NSURLResponse *response =
        [[[NSURLResponse alloc]
            initWithURL:[request URL]
            MIMEType:[self mimeTypeForPath:pathString]
            expectedContentLength:[data length]
            textEncodingName:nil]
        autorelease];
    cachedResponse =
        [[[NSCachedURLResponse alloc] initWithResponse:response data:data] autorelease];
    
    // Add it to our cache dictionary for subsequent responses
    if (!cachedResponses)
    {
        cachedResponses = [[NSMutableDictionary alloc] init];
    }
    [cachedResponses setObject:cachedResponse forKey:pathString];
    
    return cachedResponse;
}

Setting our cache as the shared cache

A UIWebView will try to use the current +[NSURLCache sharedURLCache]. To get our code called, you'll need to create an instance of our NSURLCache subclass and invoke +[NSURLCache setSharedURLCache:].

A big warning here: once you set a new web cache, you probably want to leave it set until your program exits.

When the UIWebView requests resources from your NSURLCache, it assumes that the NSURLCache retains the NSCachedURLResponse. If you release the NSCachedURLResponse while any UIWebView is using it, it will probably crash your app.

Unfortunately, it is pretty hard to force WebKit to let go of its references — it can hold onto them indefinitely in some cases. Until WebKit itself chooses to invoke removeCachedResponseForRequest: to tell you that you can throw away the resource you must hold onto it.

What this means is that you should only have one NSURLCache in your program. Set it in your application:didFinishLaunchingWithOptions: method and never remove it.

A limitation...

Obviously, if you're overriding the cache to substitute local data, it will only work if the request actually looks at the cache.

This means that if the URL is requested with requestWithURL:cachePolicy:timeoutInterval: with a cache policy of NSURLRequestReloadIgnoringCacheData, the the request will bypass this local substitution.

By default, NSURLRequests have a cache policy of NSURLRequestUseProtocolCachePolicy. The HTTP cache policy is pretty complicated and while I've never actually seen a normal NSURLRequest actually bypass the cache, the number of rules involved create a situation where it seems like it may be possible in some situations. Your app should not misbehave if this were to happen for some reason.

The LocalSubstitutionCache sample app

You can download the LocalSubstitutionCache.zip (66kb) sample project

Here's a small screenshot of today's http://www.apple.com running in a UIWebView:

After invoking +[NSURLCache setSharedURLCache:] with our NSURLCache subclass, the gray links bar across the top are replaced with a blue graphic stored in the app's bundle:

Conclusion

The purpose of this work is to allow UIWebViews to feel more responsive and a bit more like native user-interfaces.

In reality, a UIWebView will never feel as responsive or integrated as a native user-interface but sometimes making one screen of your app a remote webpage is a big enough saving in developer resources that you're prepared to make the sacrifice in user quality. Making sure as many resources as possible are stored locally will help make any negative impact on user quality as minor as possible.

Alternative Objective-C object allocation for large arrays

2010-08-30T05:49:00.001-07:00

In this post, I'll show you how you can create objects without using the standard instance allocation process (either +[NSObject alloc] or class_createInstance()). I'll also explain why you might do this — the benefits and drawbacks to a custom object creation process.

Introduction to object allocation

The first point to understand when looking at Objective-C object allocation is what is an Objective-C object?

The answer is pretty simple: any block of data that starts with an Objective-C Class pointer can be treated as an Objective-C object. This pointer is normally called the isa pointer and allows the block of memory to be used in the Objective-C message sending system.

Normally, Objective-C objects are individually allocated on the malloc heap using malloc_zone_calloc from within the +[NSObject alloc] or class_createInstance() implementation. These allocation approaches automatically set the isa pointer for the object once it is allocated.

Alternative object allocation

Since any block of memory that starts with an isa pointer can be treated as an object, then there are numerous ways you could actually allocate objects. I'm going to consider just one alternative approach: malloc'ing a single large block of data, treating this single block as a C array of Objective-C objects and manually setting the isa pointer at the start of each of these objects.

The approach is fairly simple. Step one, allocate the C array (using calloc to obey Objective-C conventions):

const NSInteger arrayLength = /* some array length */;
Class someClass = [SomeClass class];
NSInteger runtimeInstanceSize = class_getInstanceSize(someClass);
char *instanceArray = calloc(
    runtimeInstanceSize,
    arrayLength);

Notice that we use the runtime size of the instance, not a compile-time value. This is because the instance size may change if a superclass adds extra instance variables at runtime (see my previous post on Dynamic Ivars). If your class doesn't have a superclass or you're otherwise cavalier enough to ignore this possibility, then you could use a fixed or compile-time size value.

Once the block is allocated, we need to set all the isa pointers:

for (NSInteger instanceIndex = 0; instanceIndex < arrayLength; instanceIndex++)
{
    Class *currentInstanceIsa =
        (Class *)(instanceArray + (runtimeInstanceSize * instanceIndex));
    *currentInstanceIsa = someClass;
}

Then if desired, you can invoke the init method or otherwise initialize each object some other way.

Reasons for using alternative allocation approaches

The reason to avoid standard allocation is generally because malloc_zone_calloc does not offer the memory efficiency or performance required.

I've previously examined how malloc works on the Mac. This post briefly looked at two of the limitations with malloc:

malloc allocations have an "allocation resolution" (objects not a multiple of the resolution will result in wasted space)
malloc must maintain metadata on allocated objects and this imposes an additional memory overhead

The biggest malloc limitation however is simply the fact that it imposes a per-object CPU overhead on allocations.

Finally, there is one other advantage associated with using alternative allocation approaches: it is lower level. This is not an advantage in all situations — low level implementations can be fussy and prone to errors. But low-level C implementations can be easier to join with other low-level C implementations, so if much of your program is already a low-level C implementation, it may end up being an advantage to have low-level access to your object's allocation.

Drawbacks to alternative object allocation

Alternative object allocation should not be used lightly. First of all: it is simply more work as a programmer, so you need to be sure it's work the effort.

But the biggest problem it creates is the fact that individual objects cannot be retained beyond lifetime of the larger block in which they're allocated. To address this, you must either

Give the containing block a global lifetime (never released) like a singleton or other permanent instance
Carefully manage all retains and releases to ensure that no object is retained beyond the containing block's lifetime
Make retains illegal (use a retain implementation that throws an exception).

This limitation can be justified but only if the efficiency benefits are significant. On the iPhone, you may be able to justify it for a few 10s of thousands but on the Mac, your block should contain hundreds of thousands before you'd bother.

An example: loading the "/usr/share/dict/words" file

To illustrate how you can use alternative allocation, I'm going to show a traditional Objective-C approach for reading, parsing and storing the contents of the "/usr/share/dict/words" file as an array of NSStrings. I will compare the time taken and memory used by this approach with an approach that uses the alternate allocation approach.

The traditional Objective-C approach:

words = [[NSString
        stringWithContentsOfFile:@"/usr/share/dict/words"
        encoding:NSASCIIStringEncoding
        error:NULL]
    arrayBySeparatingIntoParagraphs];

where arrayBySeparatingIntoParagraphs is an NSString category method that uses getParagraphStart:end:contentsEnd:forRange: to divide the NSString into lines.

The alternative approach uses a custom NSString class, allocated as described in the "Alternative object allocation" section above. This NSString stores a fixed length 24 character ASCII character string (24 characters is the maximum length of a line in the words file). The string storage is not actually a C string; if the stored string is 24 characters long, it isn't null terminated.

@interface CustomAsciiString : NSString
{
    char value[CUSTOM_ASCII_STRING_LENGTH];
}
@end

The allocation itself happens in the init method of a custom NSArray subclass.

@interface CustomAsciiStringArray : NSArray
{
    NSInteger count;
    char *stringArray;
}
@end

This custom array subclass is used to provide NSArray-compatible access to the C array of CustomAsciiString.

The array of CustomAsciiString is actually referenced here as a char* because at compile time we don't presume to know the allocated size of the CustomAsciiString so we'll need to offset into the array by bytes (i.e. chars).

The code for all of this is too big to include here but you can download the CustomObjectCreation.zip for the complete code.

Results

There are 234936 words in the dictionary with a maximum length of 24 characters and an average length of 9.6 characters.

The "traditional" Objective-C approach took 3.12 seconds to load, parse and store the file in the string array 20 times. Memory usage after the final iteration (all other iterations were released) was 16.5 MB.

The "alternative allocation" approach took 0.49 seconds to load, parse and store the file in the string array 20 times. Memory usage after the final iteration was 8MB.

Final result: 6 times faster using half the memory.

Potential issues with the methodology behind these numbers

Based on these numbers, the "alternative allocation" would appear to be more than 6 times faster and more than twice as memory efficient.

This isn't an "apples to apples" comparison though.

The "alternative allocation" approach is storing ASCII strings (which are half the size, character-for-character compared to typical unichar NSStrings). However, this is largely compensated by the fact that every one of the ASCII strings is 24 characters long — significantly more than twice the average length of the strings, so the useful memory allocated here is actually greater. Even if you double the ASCII string length to 48 characters, the memory usage is only 13.4MB — still 20% less than the traditional allocation approach. The "alternative allocation" approach is also allocating a fixed 250000 entry array (even though only 234936 are used).

The parsing used by each approach is radically different. However, this is related to my earlier statement that lower-level allocation lends itself to integration with lower-level parsing and handling. I have not attempted to make the parsing more comparable between the two approaches because I believe the different parsing approaches are correctly matched to the different allocation approaches.

The biggest problem that I would have liked to address better — but I don't really know how I would — is that simply reading memory usage from getrusage is not a highly precise way of determining memory used by the test. The getrusage results count allocated memory pages whether they're truly in use or not. It also can't separate memory that may have been allocated by the runtime for different purposes. Due to the difficulty of measuring memory, I've had to assume that getrusage is sufficient but there is certainly a margin for error in the numbers.

Conclusion

You can download the CustomObjectCreation.zip (20kB) which contains all the code used in the test project for this post.

For very large arrays of Objective-C objects, it is certainly more efficient to allocate them yourself within C-style arrays. It is faster (on the order of 6 times faster) and more memory efficient (between 20% and 60% lower memory usage).

However, it is not something you should do for all arrays. There's a lot of extra code — any part of which could introduce issues — and it introduces object-lifetime issues but for very large arrays, the advantages (especially in CPU or memory constraint scenarios) could be worth the effort.

Is a virtual machine for Cocoa programming inevitable?

2010-07-15T23:58:00.001-07:00

Recent articles by John Siracusa and Jesper have re-ignited some discussion about whether Apple might be working on another programming language to replace Objective-C. Neither of these articles closely examined a related but possibly more important question: is Apple planning to move application development to a virtual machine? In this article, I'll look at why I think moving to a virtual machine might happen along with a possible language transition.

Disclaimer: this entire post is either a) speculation, b) aspiration or c) incrimination.

Introduction: criticisms of Objective-C

Programmers, onlookers and pundits have criticised Objective-C for longer than Apple has been using it.

If the criticisms were valid and pressing, most could actually be addressed without replacing Objective-C/Cocoa.

Fixable complaints in the language and APIs include the lack of tuples, slices, maps or associations at a syntax level; the lack of template programming; the lack of namespaces; the lack of default parameters to methods; the lack of operator overrides/overloading; leaks and premature collection by the garbage collector (or lack of garbage collection on iOS platforms); the wordy, camel-coded naming conventions; the lack of package management; the lack of out-of-the-box support for "business" APIs like REST, SOAP, SQL, etc. Even the commonly mocked square bracket method invocation syntax could be changed (or supplemented) if the need existed.

None of these criticisms in isolation is a reason to replace Objective-C. All you could argue is that if Objective-C actually needed to change all of these points, then perhaps you might as well replace the entire language.

But replacing the primary application programming language is a jarring task for a development community (especially one that has only just given up on Carbon) and Apple wouldn't do it to address aesthetic issues or minor features. The reasons for replacing a language would need to be more pragmatic and functional.

More relevant in the long term is the one feature that Objective-C can't remove or fix: complaints about C itself, in particular C pointers.

While code level compatibility with C is arguably Objective-C's best feature, it is also the source of Objective-C's most unpopular feature: the direct memory model.

Direct access memory models are a shrinking market

You can't stop the shift away from direct access memory models like the one use in C language; they're simply losing popularity.

According to this list of top 20 most popular programming languages (not exactly a scientific source but it will suffice) only 32% of people still use a language with a direct memory model (C, C++, Objective-C, Pascal and Delphi). In 10 years time, you probably won't see direct memory models used in new projects outside of kernels, drivers, computer games and low-level embedded software.

This means that whether or not Apple deprecate their direct memory model APIs (they probably won't), and whether or not they introduce a new language, Apple will introduce an official application environment with an abstracted memory model.

The role of an application virtual machine in memory abstraction

Technically, Objective-C's current garbage collector is an abstracted memory model. But I'm excluding it from consideration because it's not a complete abstraction and it never will be while Objective-C contains C pointers.

Just because you don't need to release your memory, doesn't mean there aren't other memory problems. You still have pointers. These pointers can still point to anything. You still have C arrays that you can overrun. You can still have buffer overflows. You can still accidentally overwrite sections of memory. There are even situations where you can get the garbage collector to collect memory that you're still using.

That's a pretty leaky abstraction.

It is possible to create a memory model abstraction without using a genuine virtual machine (see A Different Path, below) but a virtual machine allows you to lock down the abstraction so that there aren't any accidental loop holes. You no longer need pointers. You can't simply overwrite memory. You can't overrun arrays. You can't overflow buffers.

The virtual machine does this by removing instructions that offer direct access to memory. Instead, the instructions on the machine relate to objects, properties and values — you cannot access the wrong piece of memory and garbage collection can be precise rather than conservative because all memory references are known absolutely.

Clarification on what I mean by virtual machine: A virtual machine is a description of a computer that is not directly tied to any specific computer implementation but instead can be mapped onto an actual machine. This mapping is normally either through runtime interpretation (like a scripting language), runtime simulation (like a computer emulator) or just-in-time compilation into native machine code (like Java's JVM). Regardless of how the virtual machine is run, the point is that the programmer only ever deals with this virtual scenario and the exact architecture and behaviors of the target machine are never directly accessed.

Platform independence

A second argument for a virtual machine is actually unrelated to the language considerations: platform independence.

Apple have already switched CPU architectures twice in 17 years. It will almost certainly happen again. While the transition to Intel CPUs was unbelievably smooth (I remain stunned about how seamless it was) there was still a significant wait for Intel-native versions of many programs and significant cost to Apple and other developers to make the whole transition work.

With Apple's additional focus on iOS devices, it's also possible to imagine a range of different CPUs could be used across a single lineup and fat binaries (such as the existing armv6/armv7 iOS binaries) are only convenient for a small number of CPUs. If Apple wanted to use a dozen different CPUs, a single bytecode runtime would be the only way.

Wherever possible, good programming generally avoids coding to specific hardware components. Abstracting the CPU and the platform away from our programs is simply a logical step along the same lines.

On the topic of running across different CPUs, an interesting point to consider is that Apple actually did recently introduce a new, platform independent language that runs in JIT compiled virtual machine: OpenCL. I don't foresee any push to re-implement Cocoa in OpenCL (it's way more cryptic than Objective-C) but the technology to do these things certainly exists.

Virtual machine without a new language

An important point to note is that the introduction of a virtual machine could preceed a new language.

If Apple decided that fear of manual memory management was keeping good programmers away but wasn't ready to actually transition to a new language in one leap, it would be possible to transition to the virtual machine first (and gain many of the memory abstraction advantages) while keeping the code-level changes relatively minor.

While this might seem like a thoroughly strange thing to do, it does have a couple advantages.

The first is that an implementation of Objective-C adapted to run inside a virtual machine would be easier to bridge to native Objective-C outside the virtual machine. If you remember Apple's retired effort at bridging Java and Objective-C, the biggest technical difficulty was that Java's view of an object is less runtime dynamic than that of Objective-C and Java had difficulty keeping track of method and isa pointer changes on the Objective-C side. Bridging a virtual machine language to its non-virtual machine equivalent would be easier on this modelling level.

The second advantage of keeping Objective-C during the transition to a virtual machine is that Cocoa is currently written to match Objective-C's feature set. Cocoa might be able to remain substantially similar, making Apple's work upfront much easier.

Update: Jesper has responded to this point and explained why virtualizing Objective-C while keeping some level of compatibility with non-virtualized Objective-C is probably not a good idea.

In short: a virtualized version of Objective-C would (like C++.NET before it) need to have a number of language features removed (to the point where it is not source compatible enough to matter) or it would need to throw runtime exceptions all over the place if your code violated a long list of rules (which doesn't solve the memory abstraction problem it just hurts you if you get it wrong).

A different path

Of course, just because the above advantages exist, doesn't mean that a virtual machine environment is a guaranteed next step in Mac programming evolution.

There do exist compiled, garbage collected, memory safe languages that don't require virtual machines but would satisfy the requirement of a totally abstracted memory model. Google's Go language is one example.

It is unlikely Apple would literally adopt Go. Aside from the fact that Go is still a work in progress, there is also the problem that Go (and most other languages) are not interoperable or bridgeable with Objective-C classes (again this is why bridging Java to Objective-C was problematic — the runtimes need to be significantly compatible). In fact, Go does not yet easily bridge to C or C++, yet.

Actually moving to a Go-like language would require a clean break with no backwards compatibility. While a clean break is not impossible (Carbon to Cocoa was a clean break), I think it more likely that Apple would choose to keep some amount of interoperability by either using a custom language — or a custom variation of an existing language — that uses a runtime closer to Objective-C. The reason why I suspect this is that Apple have already had the chance to replace Cocoa (with iOS) but chose to keep largely the same design — I suspect that they'd choose to keep Cocoa into the future on the Mac, even if the language or environment changes.

The greater possibilities of backwards compatibility, bridging and portability afforded by virtual machines, and the excellent performance of modern JIT implementations, lend me to think that a non-virtual machine option doesn't provide enough flexibility and advantages for the next isn't a compelling enough to warrant the pain of a language transition.

Conclusion

Obviously, I like Objective-C and Cocoa; I'm sure that much is clear from the existence of this blog and my posts defending its traits. I don't agree with most of the criticisms that I've listed in this article — for the most part, I think the criticisms are either trivialities or they're philosophically and technically misguided.

But Mac programmers can't fight against an overwhelming trend towards totally abstracted memory models that's largely happening outside the borders of Mac programming.

Furthermore, I don't think the eventual move towards an application virtual machine is a change that needs to be fought. Most of what currently defines Cocoa and Mac programming — the attention to detail, the way widgets, methods, classes and APIs all work well together won't change. In fact most of Cocoa might actually stay the same.

Eventually though, I'm sure Apple will switch to a new programming language; fashions change and a new language is always refreshing (if a little weird in the beginning).

There really isn't a rush to do this though. Certainly iOS devices don't need the performance hit right now. But even on the Mac I think there will be a few years warning before anything happens and no forced transition when it finally does.

When I say there isn't a rush: I mean it. I think its probable that you will still be able to release new, non-virtual-machine, Cocoa/Objective-C programs for the Mac OS du jour in 10 years time (in the same way that you can still write Carbon programs today if you choose). I just don't think it will be the most common choice.

Tips & Tricks for conditional iOS3, iOS3.2 and iOS4 code

2010-07-06T21:17:00.001-07:00

In this post, I'll show you ways to determine which version of iOS you are running on and show you how to write a macro that can both conditionally compile and runtime switch between the code for different versions of iOS.

A project or target that supports multiple versions of iOS

To make an application target that runs on multiple versions of iOS is relatively simple:

Set the "Base SDK" in your projects settings to the newest version number of iOS whose features you may want.
Set the "iPhone OS Deployment Target" to the oldest version number of iOS that you will support

However, getting the target settings correct is the easy part of the problem. The hard part is using new features on newer iOS versions without breaking the app on older versions.

Running in the 3.1.3 simulator

Before getting to the actual code, it might be worthwhile to discuss how to run your projects in older versions of the simulator.

The simulator is an important part of iOS development (since it is much faster and simpler than running your code on the device). But Apple have removed SDK versions earlier than 3.2 from the current Xcode builds. This makes it hard to verify your apps on earlier devices unless you install on a physical device.

Support for 3.1.3 is relatively important since it is the last version of iOS supported by the original iPhone and iPod Touch and it will be a few months before iOS 4 exceeds 80% of the remaining iPhone and iPod Touch market.

To allow simulation in 3.1.3, you must install an old version of Xcode. If you are a registered iPhone developer, you can download Xcode 3.1.4 for Leopard with iPhone SDK 3.1.3 or Xcode 3.1.4 for Snow Leopard with iPhone SDK 3.1.3. Be careful to install these in a different location to your Xcode 3.2.3 with iOS3.2/iOS4 (either select a different hard disk or rename your existing /Developer directory before you install).

Once you've got an old version of Xcode, you'll want to duplicate your main target and set the Base SDK to 3.1.3 in this duplicate (because it won't exist in this version of Xcode). You should use a second target for this because you shouldn't risk messing with your main target just to run code in the simulator.

Using features from newer iOS versions while supporting older iOS versions

For example, if you want to start an iOS4 background task in an application that you want to run on earlier versions of iOS, then you'll need to use code like this:

#if __IPHONE_OS_VERSION_MAX_ALLOWED >= 40000
    if ([[UIApplication sharedApplication]
        respondsToSelector:@selector(beginBackgroundTaskWithExpirationHandler:)])
    {
        UIBackgroundTaskIdentifier bgTask = [[UIApplication sharedApplication]
            beginBackgroundTaskWithExpirationHandler:^{}];

        // Perform work that should be allowed to continue in background

        [[UIApplication sharedApplication] endBackgroundTask:bgTask];
    }
#endif

There are three important components:

The #if __IPHONE_OS_VERSION_MAX_ALLOWED >= 40000 compile-time conditional. This ensures that if we choose to build this project with a Base SDK lower than 4.0, then it won't cause compile problems. This is essential for running in older versions of the simulator.
The runtime check that UIApplication supports the beginBackgroundTaskWithExpirationHandler method. Since the final release build will be built against the 4.0 SDK (even if users install on SDK 3.0) this runtime check ensures that the method we need is available.
Everything else between the #if __IPHONE_OS_VERSION_MAX_ALLOWED >= 40000 and the #endif is the iPhone OS 4 code.

Making the conditional work less ugly

The problem with the previous code is the compile-time conditional and the runtime check for the presence of methods is cumbersome since you must remember to to both.

If you want to integrate both a compile-time check and a runtime check, a better approach would look like this:

IF_IOS4_OR_GREATER
(
    UIBackgroundTaskIdentifier bgTask = [[UIApplication sharedApplication]
        beginBackgroundTaskWithExpirationHandler:^{}];

    // Perform work that should be allowed to continue in background

    [[UIApplication sharedApplication] endBackgroundTask:bgTask];
);

We can implement this macro as follows:

#ifndef kCFCoreFoundationVersionNumber_iPhoneOS_4_0
#define kCFCoreFoundationVersionNumber_iPhoneOS_4_0 550.32
#endif

#if __IPHONE_OS_VERSION_MAX_ALLOWED >= 40000
#define IF_IOS4_OR_GREATER(...) \
    if (kCFCoreFoundationVersionNumber >= kCFCoreFoundationVersionNumber_iPhoneOS_4_0) \
    { \
        __VA_ARGS__ \
    }
#else
#define IF_IOS4_OR_GREATER(...)
#endif

If we want to include something only in OS versions prior to a a specific version, then we don't need the conditional compilation (since we still want the code to appear when compiled in a later version. In this case, only a runtime check is required. You can either do this directly, or for symmetry with other macros, you could use:

#define IF_PRE_IOS4(...) \
    if (kCFCoreFoundationVersionNumber < kCFCoreFoundationVersionNumber_iPhoneOS_4_0) \
    { \
        __VA_ARGS__ \
    }

Three interesting points to note about these macros:

I use the kCFCoreFoundationVersionNumber to determine the iPhone OS at runtime. There are many examples on the web using [[UIDevice currentDevice] systemVersion] but that method requires a string comparison and potentially handling of major and minor numbers within the string components. A single double comparison is far more straightforward.
I have not used the typical do { x } while (0) wrapper around the macro, so you can simply tack an else onto the end if you choose (and it doesn't need conditional compilation of its own).
I use a variable argument list for the macro. This is so that any number of commas may appear in the contents without causing problems.

A final point... the kCFCoreFoundationVersionNumber definitions may not be in every version of the SDK (each SDK normally contains definitions for versions up to but not including itself), so you should conditionally define them yourself in case they're missing. Here's a handy list:

#ifndef kCFCoreFoundationVersionNumber_iPhoneOS_2_0
#define kCFCoreFoundationVersionNumber_iPhoneOS_2_0 478.23
#endif

#ifndef kCFCoreFoundationVersionNumber_iPhoneOS_2_1
#define kCFCoreFoundationVersionNumber_iPhoneOS_2_1 478.26
#endif

#ifndef kCFCoreFoundationVersionNumber_iPhoneOS_2_2
#define kCFCoreFoundationVersionNumber_iPhoneOS_2_2 478.29
#endif

#ifndef kCFCoreFoundationVersionNumber_iPhoneOS_3_0
#define kCFCoreFoundationVersionNumber_iPhoneOS_3_0 478.47
#endif

#ifndef kCFCoreFoundationVersionNumber_iPhoneOS_3_1
#define kCFCoreFoundationVersionNumber_iPhoneOS_3_1 478.52
#endif

#ifndef kCFCoreFoundationVersionNumber_iPhoneOS_3_2
#define kCFCoreFoundationVersionNumber_iPhoneOS_3_2 478.61
#endif

#ifndef kCFCoreFoundationVersionNumber_iPhoneOS_4_0
#define kCFCoreFoundationVersionNumber_iPhoneOS_4_0 550.32
#endif

Better still: solutions that don't require macros

Better than a simple macro is a simple function. This is a valid solution where the contents of your conditional code does not itself contain OS specific code (only the condition itself requires OS specific logic).

A common example is handing separate layout for iPad and iPhone versions. Ordinarily, if you're compiling for iPad 3.2 and iPhone 3.1.3, you need the following code:

#if __IPHONE_OS_VERSION_MAX_ALLOWED >= 30200
    if ([[UIDevice currentDevice] respondsToSelector:@selector(userInterfaceIdiom)] &&
        [[UIDevice currentDevice] userInterfaceIdiom] == UIUserInterfaceIdiomPad)
    {
        // iPad specific layout changes
    }
    else
#endif
    {
        // iPhone layout
    }

You can handle this with a conditional macro like the IF_IOS4_OR_GREATER but a far better solution is:

if (isIPad())
{
    // iPad specific layout changes
}
else
{
    // iPhone layout
}

Where all the conditional pollution is tidily kept in your isIPad() function:

BOOL isIPad()
{
    IF_3_2_OR_GREATER
    (
        if ([[UIDevice currentDevice] userInterfaceIdiom] == UIUserInterfaceIdiomPad)
        {
            return YES;
        }
    );
    
    return NO;
}

Conclusion

Apple doesn't exactly make it easy to support old versions of the iPhone SDK. I'm sure they want everyone to keep up to date or buy new devices if their current device can't be updated.

That's not always a realistic attitude for App Store developers. You can't expect all your customers to upgrade as soon as possible.

The important point when writing for multiple versions of the SDK is to keep as few conditionals as possible. You don't want to have thousands of conditionals in your code for supporting different versions. Every conditional is extra testing work since different behaviors must be fully exercised on all different platforms.

While the conditionals and functions I've talked about here will help, if you find yourself needing a lot of conditionals you may also want to consider design changes like instantiating different subclasses for different OS versions.

Assign, retain, copy: pitfalls in Obj-C property accessors

2010-06-30T05:52:00.001-07:00

In this post, I'll look at some very subtle problems that can occur if a getter or setter method chooses the wrong memory management pattern and in the process, explain why NSDictionary copies its keys rather than simply retains them.

Scope of this article: in this post I'll be discussing basic memory and mutability considerations in Objective-C accessor methods. If you're interested in atomicity and thread safety issues in accessor methods, please read my earlier post on Memory and thread-safe custom property methods. This post will only look at non-atomic accessors.

Why implement your own accessors?

If you know about Objective-C's properties, you may already be asking, "Why implement your own accessors at all?". For simple accessors, you can (and probably should) use the synthesized @property accessors and not worry about the implementation. The reason for this post is that you will often need to implement accessor methods yourself to attach additional behaviors to the get or set action, so you always need to know how the accessor should work.

The one you already know: the assign pattern

Since you're reading this blog, it's probably safe to assume that you already know how a basic assign accessor looks:

- (SomeVariable)someValue
{
    return someValue;
}

and a setter method looks like this:

- (void)setSomeValue:(SomeVariable)aSomeVariableValue
{
    someValue = aSomeVariableValue;
}

For most non-object data, that's all you need. This is the implementation you'd get with a non-atomic assign synthesized @property.

Retain: first opportunities for failure

If you're working with retain/released objects in Objective-C, your object will become invalid if your setter does not retain it, so the setter must handle this.

The most completely thorough, all purpose way of handling retain and release issues in a setter looks like this:

- (void)setSomeInstance:(SomeClass *)aSomeInstanceValue
{
    if (someInstance == aSomeInstanceValue)
    {
        return;
    }
    SomeClass *oldValue = someInstance;
    someInstance = [aSomeInstanceValue retain];
    [oldValue release];
}

This is obviously much more complicated than a simple assignment.

The biggest point that stands out i the weird retain/release dance occupying the last three lines of this code block. We do this to avoid problems where the object pointed to by aSomeInstanceValue and someInstance is the same. Imagine the following:

- (void)setSomeInstance:(SomeClass *)aSomeInstanceValue
{
    [someInstance release]; // <-- original value is released
    someInstance = [aSomeInstanceValue retain];
}

If aSomeInstanceValue and someInstance are the same object, then the first line could release the underlying object before the second line retains it — meaning that the object is destroyed and invalid by the time it is retained again.

You'll notice that we use the C equality operator to compare the two objects instead of the isEqual: method. Normally, this is a bad idea (Objective-C objects may be "equal" even if they do not point to the same location in memory) but in this case, we are specifically interested in cases where the memory location (and hence the retain counts) are identical. The comparison is not strictly necessary to prevent premature release (since the retain precedes the release) but it's an optimization and safety measure.

In reality though, all this is a bit painful to write: the comparison, the annoying temporary value and the careful ordering of everything. In practice, we normally use a shorter version of the setter method that is basically just as good and is certainly far easier to write:

- (void)setSomeInstance:(SomeClass *)aSomeInstanceValue
{
    [someInstance autorelease];
    someInstance = [aSomeInstanceValue retain];
}

In this case, we don't care about the comparison optimisation and we use the autorelease pool to temporarily hold the original value instead of our own stack value.

This method has the same safety as the retain/release dance but requires an autorelease pool and is marginally slower if someInstance and aSomeInstanceValue are actually the same. In reality, there's almost always an autorelease pool in a Cocoa application and the performance difference is more theoretical than real (you'd have difficulty constructing a test program to ever show a difference) until you start creating copy setters (see below).

Not all Objective-C setters should retain: There are some situations where a setter method that takes an Objective-C object should not retain its parameter. Specifically: objects in a hierarchy should not normally retain their parents. Look at Rules to avoid retain cycles for more on this topic.

The other half of the retain access pattern

In reality, even if you forget to perform the if (newInstance == oldInstance) return; check in your accessor method, you are highly unlikely to see a problem even if you actually do pass the current value to a setter method.

The reason why you are normally safe, even if you make a mistake, is because the parameter you pass into a method normally has another retain count held elsewhere.

Specifically: most objects you access on the stack have an autoreleased retain count held by an autorelease pool on the stack or a longer lived object somewhere in the heap.

Theoretically, you could help this idea along by implementing your getter methods like this for retained objects:

- (SomeClass *)someInstance
{
    return [[someInstance retain] autorelease];
}

This will ensure that if your object is used like this:

SomeClass *stackInstance = [anObject someInstance];
[anObject release]; // anObject releases its someInstance ivar in its dealloc method
[stackInstance doSomething];

Then the stackInstance variable will still be valid when doSomething is invoked on it.

Generally though, I don't bother doing this in non-atomic getter methods.

Why not? Speed, redundancy and common sense.

While retaining and autoreleasing something is not a gigantic overhead, it is normally just not needed for a get accessor method. The programmer using the get accessor should understand that the lifetime is bound to the source object.

However, you may want to use this pattern in a situation where it is not immediately clear that the value returned is a getter method. For example:

@implementation ThisClassIsReallyJustAString

- (NSString *)description
{
    return [[internalValue retain] autorelease];
}

@end

The description method (which returns an NSString representation of an object) does not normally return an instance variable directly so it would not ordinarily be considered an accessor method. In this situation, it is implemented as an accessor but due to the expectation that the description is a generated value, we need to retain and autorelease the returned value.

Any instance variable returned from a method where the method is not obviously an accessor method should always go through a retain/autorelease since it is not immediately obvious that its lifetime would be bound to the lifetime of the source object.

Copy accessors

The reason why retain accessors exist is obvious — you don't want the value to be deallocated while it is set on the object.

The reason for the final accessor pattern in Objective-C — copy accessors — is less broadly understood but nonetheless relevant.

You should use a copy accessor when the setter parameter may be mutable but you can't have the internal state of a property changing without warning. Consider the following example:

NSMutableString *mutableString = [NSMutableString stringWithString:@"initial value"];
[someObject setStringValue:mutableString];
[mutableString setString:@"different value"];

In this situation, if the setStringValue: method followed the retain pattern, then the setString: method invoked on the next line would change the internal value of this property without warning someObject.

Sometimes, you don't care if the internal state of a property change without warning. However, if you do care about the internal state of a property changing, then you'll want to use a copy setter.

The implementation of a non-atomic copy setter is as simple as you'd imagine:

- (void)setStringValue:(NSString *)aString
{
    if (stringValue == aString)
    {
        return;
    }
    NSString *oldValue = stringValue;
    stringValue = [aString copy];
    [oldValue release];
}

Correction: I had previously stated that you don't need the equality comparison for a copy (since I wrongly claimed the copy would ensure you always have a different block of memory). I was wrong, of course. As was immediately pointed out in the comments: copy does not always return a copy; for immutable objects, copy can return the same object. I forgot about this, even though I've certainly written copy setters that work this way (see the SynthesizeSingleton code). The result is that we still need the comparison to ensure that setting the property to the same value doesn't cause the same potential release problems that the previous retain pattern had. Did I mention it is possible to screw up property accessors?

This finally explains why NSDictionary copies its keys.

NSDictionary stores all its value objects in locations according to the result of each corresponding key object's hash method.

If a key object were to change in such a way that the hash method result changed, then the NSDictionary would not be able to find the corresponding value object any more.

Key objects are not set by a property accessor on an NSDictionary but the effect is the same: the copy pattern is used to ensure that outside objects cannot change the internal state of the dictionary without warning.

Of course, the downside to properties that follow the copy pattern is speed. It's not normally an issue for objects up to a few kilobytes but beyond that point, you'll need to consider whether copy is the right pattern for the resources involved.

Conclusion

Getter and setter methods are frequently given as the simplest kind of method to implement. But you can see that even within this very simple kind of method, there are subtle ways that they can go wrong.

Overall, this post is a much simpler level than my typical posts but that doesn't mean its only for novice Objective-C developers. Experienced programmers are far from immune to mistakes in this area. Some of the potential quirks with getter and setter methods are so rare you may never see a problem (even if your code is doing things in an unsafe manner) so learning from experience can take time in this area.

Of course, if you don't need any customization in your accessor methods, you should simply use a synthesized @property implementation. This will avoid any possibility of introducing mistakes.