In this article we will discuss the latest iteration of my Prefix.pch file. As with anything I post, it is available for you to use as you see fit.

The File

For those who don’t want to read the entire post, here is the file:

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

#ifdef DEBUG
  #define DLog(...) NSLog(@"%s %@", __PRETTY_FUNCTION__, [NSString stringWithFormat:__VA_ARGS__])
  #define ALog(...) [[NSAssertionHandler currentHandler] handleFailureInFunction:[NSString stringWithCString:__PRETTY_FUNCTION__ encoding:NSUTF8StringEncoding] file:[NSString stringWithCString:__FILE__ encoding:NSUTF8StringEncoding] lineNumber:__LINE__ description:__VA_ARGS__]
#else
  #define DLog(...) do { } while (0)
  #ifndef NS_BLOCK_ASSERTIONS
    #define NS_BLOCK_ASSERTIONS
  #endif
  #define ALog(...) NSLog(@"%s %@", __PRETTY_FUNCTION__, [NSString stringWithFormat:__VA_ARGS__])
#endif
 
#define ZAssert(condition, ...) do { if (!(condition)) { ALog(__VA_ARGS__); }} while(0)

This does not replace the Prefix.pch that comes with your project but it does go at the top of every project that I work on. The rest of this post we will review what this does.

#ifdef DEBUG

I normally run my code in one of two modes. Either I am writing and testing the code or I am compiling it to hand over to QA, a user or Apple (btw I consider all three of those to be synonymous when it comes to builds). Therefore the first line is a switch to see if we are in debug mode. I set this value in the build settings of my project. If you look under the “Preprocessor Macros” section you can set the DEBUG definition there.

#define DLog(...)

This is the most used macro I have in my Prefix.pch file. This is simply NSLog as we know it and love it. However I automatically prepend the included macro __PRETTY_FUNCTION__ so that any log statement that comes out will declare where it is being called from. Personally I hate having to track down which “Fix Me” just spit out to the Console.

The nice thing about DLog over NSLog is that in the other branch this is a no-op that will be removed by the compiler. Therefore when I do a client build they won’t see the debug statements nor will their build be slowed down by any potential conditional logic around the debug statements.

#define ALog(...)

While I do not use this one very often I do like this one an awful lot. When I am in DEBUG mode it will throw an NSAssertion when it gets hit. This is similar to a common line of code that I see:

1

NSAssert(NO, @"It failed");

or if you want to see the variables:

1

NSAssert2(NO, @"It failed. Value1: %i Value2: %i", value1, value2);

My version does not have the condition before hand and can take any number of parameters.

1

ALog(@"It failed. Value1: %i Value2: %i", value1, value2);

In addition, when the DEBUG flag is not set, this assertion turns into a NSLog which remains visible. This allows me to have “This will never happen” calls in my code that will explode when I hit them but will be more polite if a user hits them but not so polite that I am left wondering what happened. They won’t intentionally crash the application but they will leave a fingerprint in the output from the application so that I can discover what happened.

NS_BLOCK_ASSERTIONS

I am of the school of thought that believes you should never throw an assertion in production code. If your code cannot handle that part of your app being hit and survive in some form or another then it is not production ready. Simple as that. Therefore I turn them off in production builds.

However, some other people who write libraries that I depend upon also feel this way. Therefore I need to check to see if it is already defined so that I can avoid a warning about resetting it. Since I have warnings set as errors in my code this is needed.

#define ZAssert(condition, ...)

The final gem in this collection is ZAssert. This is my personal favorite and it lets me clean up my code very nicely. First, ZAssert is a condition check. If you pass the check nothing happens. If you fail the check, bad things happen. This is just like NSAssert except for one big difference. When you turn off assertions, NSAssert goes away completely. This is not what I want to happen in my code. Instead, when assertions are turned off, I want a failure of this check to turn into an NSLog. That is what ZAssert does for us. In this way, we can clean up our code very nicely. Picture this very common block of code:

1
2
3
4
5
6

NSError *error = nil;
 
if (![managedObjectContext save:&error]) {
  NSLog(@"My save failed: %@\n%@", [error localizedDescription], [error userInfo]);
  abort();
}

That is a LOT of code just to perform a save! Blocks of code like this are very common in Objective-C. Unfortunately we can’t roll this up into a NSAssert because the entire line of code will disappear when we turn them off.

With ZAssert it gets a lot cleaner:

1
2

NSError *error = nil;
ZAssert(![managedObjectContext save:&error], @"My save failed: %@\n%@", [error localizedDescription], [error userInfo]);

Because ZAssert survives when NS_BLOCK_ASSERTIONS is set and simply mutates, we can inline the save directly and make the code a lot easier to read.

Wrap Up

I am sure this code will evolve. When it has changed significantly I will do an updated post. If anyone else has some nice tips for the Prefix.pch then please share them as we all benefit.

Acknowledgements

First I would like to recognize Fraser Hess who did the original post and showed me what we can do with macros.

Second I would like to point out that the NSAssert line of code above is borrowed heavily from BareBones software. They figured out how to generate an assertion without actually using the NSAssert macros.

A situation that I believe we are going to be seeing more and more often is one where application developers are writing multiple “versions” of their applications to be used on the desktop, their iPhone and now the iPad.

Because of that situation, it is becoming even more important that we write as much portable code as possible. Fortunately, our model can be completely portable between the two platforms.

NSImage vs UIImage

The primary issue with creating a portable model and model objects is images. Now, if the images are stored on disk and only referenced in your Core Data model, then you don’t have an issue. Since you are storing the images on disk in a portable format (png, jpeg, etc.) then they will port right over to all of the platforms you are targeting.

But what happens when you are working with small images that should be stored within Core Data? Simple right, just use a transformable data type and stick the image right in there.

Unfortunately that fails in the portability department.

The issue is that on the desktop you are storing a serialized version of the NSImage instance and on the other devices you are storing an instance of UIImage. Two different data structures that are incompatible. So what is the right answer?

Store the images in a portable format even in Core Data.

But that is hard right?

Fortunately if we create concrete subclasses of any entity that needs to store images it is a small amount of code and some conditional compiling.

MyEntityWithAnImage.h

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

 
@interface MyEntityWithAnImage : NSManagedObject
{
}
 
#ifdef IPHONEOS_DEPLOYMENT_TARGET
@property (nonatomic, retain) UIImage *image;
#else
@property (nonatomic, retain) NSImage *image;
#endif
 
@end

In the header we declare the same property and the use some conditional compiling to determine which definition should be used. On the desktop the property image will return an NSImage and on the other platforms it will return a UIImage. But how do we work this magic?

MyEntityWithAnImage.m

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

#ifdef IPHONEOS_DEPLOYMENT_TARGET
 
- (void)setImage:(UIImage*)image
{
  [self willChangeValueForKey:@"image"];
 
  NSData *data = UIImagePNGRepresentation(image);
  [myManagedObject setImage:data];
  [self setPrimitiveValue:data forKey:@"image"];
  [self didChangeValueForKey:@"image"];
}
 
- (UIImage*)image
{
  [self willAccessValueForKey:@"image"];
  UIImage *image = [UIImage imageWithData:[self primitiveValueForKey:@"image"];
  [self didAccessValueForKey:@"image"];
  return image;
}
 
#else
 
- (void)setImage:(NSImage*)image
{
  [self willChangeValueForKey:@"image"];
  NSBitmapImageRep *bits = [[image representations] objectAtIndex: 0];
 
  NSData *data = [bits representationUsingType:NSPNGFileType properties:nil];
  [myManagedObject setImage:data];
  [self setPrimitiveValue:data forKey:@"image"];
  [self didChangeValueForKey:@"image"];
}
 
- (NSImage*)image
{
  [self willAccessValueForKey:@"image"];
  NSImage *image = [[NSImage alloc] initWithData:[self primitiveValueForKey:@"image"]];
  [self didAccessValueForKey:@"image"];
  return [image autorelease];
}
 
#endif
 
@end

Here we are overriding the dynamic accessors and implementing our own. We are fully KVO compliant and notify when we are accessing or changing the image value.

In the desktop version we grab the bitmap image representation and then get the PNG representation of it and store that representation into Core Data as NSData.

In the Cocoa Touch version we are using the C function which returns the PNG representation of the UIImage instance directly. We are again storing that as NSData into our image property.

In both cases the getter reverses the process by loading the NSData back into the appropriate image instance.

Wrap Up

This makes the code external to our NSManagedObject completely unaware of the actual data storage and they just know that they are getting back the object they need to work with.

BTW, if anyone knows of another pre-processor variable that I should be using for this instead of IPHONEOS_DEPLOYMENT_TARGET please let me know. I am not 100% confident that IPHONEOS_DEPLOYMENT_TARGET is the best variable to be testing against.

Do you like this idea, hate it? Tell me in person at NSConferenceUSA! Tickets are still available and it will be great to see you there.

If that is too soon then please catch me at 360 iDev in April!

A Cocoa framework is another project type in Xcode. The end result is a bundle, similar to an application bundle. Inside of this bundle is the compiled code you wrote and any headers that you want exposed. The headers are important. Without them, just like any other piece of Objective-C code, it is very hard to code against.

Building a Framework in Xcode

Building a framework within Xcode is straight-forward. There is already a project template specifically for Cocoa frameworks so that is where we will start.

Once the framework is build, the rest of the code development is almost identical to an application bundle. C, C++ and Objective-C files can be included along with nibs, xibs, images and just about anything else we would stick into an application bundle. When the code is complied, the end result is also a bundle, again very similar to an application. The bundle structure, however, is a bit different and will be discussed in detail below.

Care must be given to the headers that we write and that we expose as part of that framework. In general, we really only want to expose the headers that users of the framework are going to interact with. If a header is completely internal to the framework then do not plan on exposing it. In addition, it is a good idea to have a wrapper header that users can import and gain references to all of the public headers. Since a framework will undoubtably contain more than one class file, how do we roll all of that up into one header? One solution I have seen is to create a separate header file and copy all of the interfaces into it. Unfortunately that solution can become unwieldy very quickly. My preferred solution is to build a “wrapper” header file that imports all of the headers that you want exposed. This is demonstrated in Code Sample 1.

Code Sample 1: Example.h

#import "ExampleOne.h"
#import "ExampleTwo.h"

Once the framework is built but before we distribute it, there are a few tweaks we need to deal with. First, we need to declare which headers are public and which are project. There is also an option for private but honestly I cannot see the logic behind them. If we flag a header as private it gets included in the resulting framework in a directory called “PrivateHeaders”. However, if we flag a header as “project” then it is correctly not included in the framework. Public headers are naturally included in the framework under the Headers directory.

Which headers should be included

<

p>For some headers, the answer to that question is easy. However, there are some gotchas that need to be planned around. If an object is referenced in one of the public headers then its header must also be public. Therefore if we want an object to be private/hidden/internal then we need to make sure there are no public references to it anywhere in any of the exposed headers. For example, if we had a an internal object called InternalObject and we referenced it in our header, the header for InternalObject would need to be public. See See Image 2.

<

p>However, if the reference is an id instead, we can keep the InternalObject private and its header un-exposed. See Image 3.

On thing to note is that in both cases, the AbstractExample is public even though we do not want anyone extending it. Because both ExampleOne and ExampleTwo are subclasses of AbstractExample its header must therefore be included in the framework. To make this a little confusing, this is NOT the case if the application and the framework both exist in the same project! If we look at the included project (called Example), and turn AbstractExample to project, everything will work just fine. However, if we take that compiled framework and use it in the second included project (called Test), it will fail. Therefore depending on how we are going to use the framework, superclasses will probably need to be included.

Using the framework

Now that we have our framework built, how do we use it? There are three places we can put this framework. We can make it system accessible, user accessible or application accessible.

System Accessible

System accessible frameworks are just like the frameworks that come with OS X. They can be imported into any application. For this magic to work, however, they need to be installed in a system level folder; specifically /Library/Frameworks. Go ahed and look in that directory now. If your system is anything like mine it is empty. Why? Because system level frameworks require root access to be installed and therefore require privilege escalation to get them there. Generally this is a BAD IDEA and there are few frameworks that follow this path.

User Accessible

User accessible frameworks are very similar to System accessible frameworks. However they are stored in a user writable location instead; ~/Library/Frameworks. Go ahead and look for this directory also. Chances are the directory itself does not even exist. This is safer than a system accessible framework and if we have a framework that is going to be used by multiple applications then this might be a logical place for it. But both user accessible frameworks and system frameworks have the same technical challenge discussed below.

Application Accessible

Outside of Apple this is the most common usage of a framework. It is bundled with the application and only the application can access it. Both of the other locations for frameworks have one issue; how do you get them there? The answer? You include them with the application of course! However, if you have to include them with the application (and you will need to include them with EVERY application that uses them) then what exactly is the point of putting them somewhere else? This is one of the main reasons that System and User accessible frameworks really don’t have a point; again outside of Apple.

Setting the installation directory

Since it only really makes sense to have our framework be application accessible, we need to tell it that when we build it. While this is not important for an application that has the framework included in its build cycle, if we want our application to be used by other applications, it becomes critical. When an application links to a framework, it needs to know where the final resting place of that framework is going to be. The default for the framework template is ~/Library/Frameworks. Clearly this needs to change.

To get a framework to acknowledge that it will be used inside of an application, we have to set the installation directory to a relative path. That relative path is:

@executable_path/../Frameworks

Once we have the installation directory set, it is time to include it in our application.

Setting up the targets for our application

Looking in the Example project, there are two targets, one for the framework and one for the application. Opening the application’s target we can see that the framework is a dependency of the application. This will insure that the framework will be built whenever we build the application. In addition, the framework is also in the “Link Binary With Libraries” build phase so that our application can build against it.

There are also two new build steps for this application that are directly related to the framework. First, is a Copy Frameworks phase. This was added using the Project -> New Build Phase -> New Copy Files Build Phase. I then renamed it to Copy Frameworks for clarity. Selecting Show Info on the Copy Frameworks build phase will show that its directory is set to “Frameworks”. This will create a Frameworks directory inside of our application build and copy our framework into it. This is how we distribute a framework with the application.

<

p>The other additional build phase is called “Clean Framework Headers” and is a script build phase. The purpose behind this phase is to delete all of the header files out of the application bundle once everything is finished. Why? Because they are not needed at runtime and there is no point in distributing them. When we distribute the framework on its own we definitely need to leave them but for the included framework they are just wasted bits. Therefore the script removes them as the final build phase for the application only. See Code Sample 2.

echo "build path ${TARGET_BUILD_DIR}"
cd ${TARGET_BUILD_DIR}/${FULL_PRODUCT_NAME}/Contents/Frameworks 
rm -rf */Headers 
rm -rf */Versions/*/Headers 
rm -rf */Versions/*/PrivateHeaders 
rm -rf */Versions/*/Resources/*/Contents/Headers

Framework Structure

<

p>For the curious, the internal structure of a framework is similar to an application. There is a compiled binary and a Resources directory that contains all of the xib, nibs, etc. There is also a Headers directory (and in some cases a PrivateHeaders directory) that contains all of the exposed header files. Where things chance is that a framework is versionable. The actual headers, resources and binary are actually stored in the Versions/${VERSION} subdirectory. From that directory there are sym-links up to the root directory of the bundle and also to the Versions/Current subdirectory.

${compiled_binary} -> Versions/Current/Example
Headers -> Versions/Current/Headers
Resources -> Versions/Current/Resources
Versions/A/${compiled_binary}
Versions/A/Headers
Versions/A/Resources
Versions/Current -> A

The purpose of this is to allow multiple versions of a framework to be stored within one bundle. However it is unlikely you will ever see more than one version in a bundle. It is a manual process to combine the versions and each version has to be kept in its own xcode project and merged by hand. In addition, since it really only makes sense to have frameworks inside of application bundles, it does not make much sense to have multiple versions of the framework. Nevertheless the functionality is there for those pesky edge cases.

Conclusion

Frameworks definitely have their place. They are very useful when writing a plugin architecture, etc. However, since they only make sense to include them in an application, unless you are sharing the framework or doing plugins, chances are it is better to just include the source code and be done with it.

Example Project

Test Project

As memory serves the only time I’ve used version control in a meaningful way the system I was using was Visual SourceSafe from Microsoft. I know. Blech! It’s awful! I’ve pulled code from many a CVS or Subversion repository, but I’ve never really used them in the way they are intended to be used. Now, thanks to Marcus, I realize that version control isn’t just about versioning any more. It’s a whole methodology/ideology that makes better programmers. Here is what I mean.

Branching Inspires Wild Experimentation

Have you ever been so far down a path in your code that you just think, though you probably should, there is no way you would take a chance to re-factor due to looming deadlines or even just a simple fear that you might mess up so badly you couldn’t recover? Well, fear no more! Git provides such a simple way to create a branch of your code in which you can experiment, you won’t even give it a second thought. I won’t go into the whole setup and how to get going with Git as this is done very well elsewhere including a previous post from Marcus. I just want to point out how easy it is to branch with a single command. In Terminal.app, cd to the directory of a project you have under Git source control and enter the following command.

bash$ git branch experimental

bash$ git checkout experimental

bash$ git checkout master

bash$ git checkout master
bash$ git merge experimental

If you found, conversely, that your ideas were purely delusional–a characteristic of your over-achieving sense of hubris–you can blow them away by simply typing:

bash$ git branch -d experimental

Now the idea is just a bad memory and not something you ever need worry about (or mention to your programming peers) again. Your code on the master branch is still as it was when you first started the branch. Hallelujah!

Note: The word ‘experimental’ I’ve used in these command line examples is simply a tag. You can call your branch whatever you like. Call it ‘hubris’ if you like. Depending on your personality, this may be more appropriate.

The chance to experiment so easily and without fear will make you a better programmer. You will venture into areas that you would have never tried before and will likely become more bold in what you’re willing to attempt. This can only be a good thing in the long run.

Collaboration

The Tutorial introduction to git provides a good example of how to collaborate when multiple people are working on the same computer, but where Git’s real power comes in is in its ability to enable collaboration. If you’re familiar with extreme programming or pair programming then you are already aware of how collaboration will make you a better programmer. The learning curve for developing applications for the Macintosh for me has been significantly leveled as Marcus has shown me how to do things in the context of real code. You can learn things in many different ways, but sharing code has got to be one of the strongest means of gaining deeper understanding. This can only make you a better programmer.

While not a direct feature of Git itself, you can share your repository over the many file sharing web applications out there. Marcus and I use Dropbox for our projects that we collaborate on. Here are the steps you take to collaborate remotely using Git and Dropbox.

1. Sign up and install Dropbox from http://www.getdropbox.com.
   
   This will create a folder in your home directory under ~/Dropbox.
2. Have the person you want to collaborate with do the same and then create a shared folder that both of you can access through the Dropbox web interface.
   
   
3. From the project directory of the project you want to share, type:

   bash$ git clone --bare . ~/Dropbox/Shared/MySharedProject.git
   

   Note: Keep in mind that I’m assuming you already have this project under Git version control. If not you first need to run init like so in the root of your project directory.

   bash$ git init
   

   The –bare keyword we used in the clone command means that we simply want to create a directory that contains the contents of the .git directory in your project directory and not the actual workspace. The .git directory contains all of your code and changes to everything you need is there–it’s just not the actual workspace where xcode works from.
4. Create a remote (alias) for the newly cloned project by typing:

   bash$ git remote add sharedproject ~/Dropbox/Shared/MySharedProject.git
   



5. Now you can push any code changes from your working directory to the cloned directory, which, since it is in your Dropbox will automatically be uploaded to the drop box and downloaded by any other computers you have that can access Dropbox. First you need to commit any changes in your working directory with the following command.

   bash$ git commit -a -m "Commit message"
   

   Then you need to push the changes to the remote with the following.

   bash$ git push sharedproject master
   

   This pushes your changes to the cloned repository which is in your Dropbox directory. As soon as you do this, you should see the Dropbox icon in your menu bar change to the ‘synchronizing’ icon. If your change is small, it will only change for a split second so you’ll have to watch it closely to see that happen.

Once your files are committed and have been pushed to your cloned repository, you can now pull the project from another computer. I’m assuming you have Git and Dropbox set up on the second computer. Here are the steps you take to get the code into Git.

1. In Terminal.app on your other computer, create a new directory where you want your project to be stored with a working directory. Now run the following command.

   bash$ git clone ~/Dropbox/Shared/MySharedProject.git
   

   Notice that we didn’t use the –bare keyword this time. This is because we want our cloned copy to also setup a working directory since we’ll be accessing it from xcode on the second computer as well.
2. Now create a remote (alias) to reference the project like you did on the other computer using the following.

   bash$ git remote add sharedproject ~/Dropbox/Shared/MySharedProject.git
   

   Note: This step is optional as your clone will do this automatically. The difference, however, is that the clone will create a remote called ‘origin’ by default where you can name it whatever you want (sharedproject in the example) if you do run it.

3. Now you can pull the code at any time with the following command.

   bash$ git pull sharedproject master
   

   You won’t need to do that at this point as your code is fresh from the clone, however, should you make any changes on the originating computer that have been pushed, you could now pull those changes from this secondary computer.

If you now make changes to the code on the second computer, you can use the exact same command you used on the first computer to push the changes. First commit the changes with:

bash$ git commit -a -m "Commit message"

bash$ git push sharedproject master

And now you’re up to date. The changes are ready to be downloaded from the first computer.

The Urge To Merge

Nothing like sexual inuendo (urge to merge, hint hint, wink wink) on a site called ‘Cocoa is my Girlfriend’ to get a geek going, but that’s not what I mean. Settle down. Take it easy…

In the end, Git’s greatest feature is its ability to merge code changes.

There are times when you have fairly complex code merges that are necessary and systems such as CVS or SVN (Subversion) will simply choke and give up leaving the messy merging process to your weak manual merging skills. This is a shame and not necessary any more as it is rare for Git to be unable to successfully merge code. Again, this probably its biggest strength. When you don’t have to worry about merging your code, you can do whatever you like in your branch with little fear that merging in your changes are going to conflict with someone else’s. This merging power comes from Git’s unique philosophy of source code management which sees changes as individual code additions and deletions rather than complete file changes.

Conclusion

There will remain naysayers who have “always done it this way” and will remain in the realm of central repositories for version control. However, if you can think outside of tradition and see the power that comes from a good source control system, you will become a better programmer. I will submit that simply starting to use any version control when you haven’t before will make you a better programmer, however, using Git for your version control system, will make it infinitely easier to become so.

Apple writes some amazing code. Unfortunately a lot of their templates demonstrate simply terrible coding practices. What is worse, people take these templates and assume that they are the proper practice for coding in Objective-C and propagate that poor code into their own projects.

The first example I am going to tackle is the AppDelegate class that is auto generated in the Core Data template. This is not the Core Data Document template but the standard application template.

persistentStoreCoordinator

This method is not the worst in the list but will help us get into the flow of things. The original method:

- (NSPersistentStoreCoordinator *) persistentStoreCoordinator {
 
    if (persistentStoreCoordinator != nil) {
        return persistentStoreCoordinator;
    }
 
    NSFileManager *fileManager;
    NSString *applicationSupportFolder = nil;
    NSURL *url;
    NSError *error;
 
    fileManager = [NSFileManager defaultManager];
    applicationSupportFolder = [self applicationSupportFolder];
    if ( ![fileManager fileExistsAtPath:applicationSupportFolder isDirectory:NULL] ) {
        [fileManager createDirectoryAtPath:applicationSupportFolder attributes:nil];
    }
 
    url = [NSURL fileURLWithPath: [applicationSupportFolder stringByAppendingPathComponent: @"CD_Cleanup.xml"]];
    persistentStoreCoordinator = [[NSPersistentStoreCoordinator alloc] initWithManagedObjectModel: [self managedObjectModel]];
    if (![persistentStoreCoordinator addPersistentStoreWithType:NSXMLStoreType configuration:nil URL:url options:nil error:&error]){
        [[NSApplication sharedApplication] presentError:error];
    }    
 
    return persistentStoreCoordinator;
}

Could be worse. There is a lot of wasted whitespace in the method itself but the majority of the problems are error checking. Here is the cleaned up method.

- (NSPersistentStoreCoordinator*)persistentStoreCoordinator
{
  if (persistentStoreCoordinator) return persistentStoreCoordinator;
  NSError *error = nil;
 
  NSManagedObjectModel *mom = [self managedObjectModel];
  if (!mom) {
    NSAssert(NO, @"NSManagedObjectModel is nil");
    NSLog(@"%@:%s No model to generate a store from", [self class], _cmd);
    return nil;
  }
 
  NSFileManager *fileManager = [NSFileManager defaultManager];
  NSString *applicationSupportFolder = [self applicationSupportFolder];
  if ( ![fileManager fileExistsAtPath:applicationSupportFolder isDirectory:NULL] ) {
    if (![fileManager createDirectoryAtPath:applicationSupportFolder attributes:nil]) {
      NSAssert(NO, ([NSString stringWithFormat:@"Failed to create App Support directory %@", applicationSupportFolder]));
      NSLog(@"Failed to create application directory: %@", applicationSupportFolder);
      return nil;
    }
  }
 
  NSURL *url = [NSURL fileURLWithPath: [applicationSupportFolder stringByAppendingPathComponent: @"CD_Cleanup.xml"]];
  persistentStoreCoordinator = [[NSPersistentStoreCoordinator alloc] initWithManagedObjectModel:mom];
  if (![persistentStoreCoordinator addPersistentStoreWithType:NSXMLStoreType 
                                                configuration:nil 
                                                          URL:url 
                                                      options:nil 
                                                        error:&error]) {
    [[NSApplication sharedApplication] presentError:error];
    [persistentStoreCoordinator release], persistentStoreCoordinator = nil;
    return nil;
  }    
 
  return persistentStoreCoordinator;
}

The first change I made is in the conditional check for nil on the persistentStoreCoordinator. This can be cleaned up to make it a simple one line of code rather than three. It is a waste of whitespace and makes the line look far more complicated than it is. Its simple, make it look simple.

Next I changed the order of things by getting a reference to the NSManagedObjectModel first. If the model is nil then the rest is a waste of time. Log the error and assert it as this is a show stopper in every core data application that I can think of.

When building the application support folder, check to make sure it succeeds! The original code just assumes that the directory creation will work. If it doesn’t for whatever reason is a failure and stops everything coming after it.

At this point you might wonder why I have both an assertion and a log statement. I do this because I turn off assertions in the production code. I would rather have a softer failure in production than a hard crash. However in Development I want the code to slap me in the face when something goes wrong.

The last change is if there is an issue with adding the store to the coordinator. In this case the error is presented to the user but I added a release to the coordinator. If this doesn’t happen, any re-entrant to this method is going to be in for a nasty surprise when they get back an empty coordinator!

Last piece of advice on this code. If you release an object, set its pointer to nil! You released it, your done with it. Why have it hang around and potentially crash your code. Point to nil and let the failure of accessing it later be much softer.

managedObjectContext

Next up on the block is the context generation code itself. This one is also not that bad other than some back-ass-wards logic statements and no error handling. First the original code:

- (NSManagedObjectContext *) managedObjectContext {
 
    if (managedObjectContext != nil) {
        return managedObjectContext;
    }
 
    NSPersistentStoreCoordinator *coordinator = [self persistentStoreCoordinator];
    if (coordinator != nil) {
        managedObjectContext = [[NSManagedObjectContext alloc] init];
        [managedObjectContext setPersistentStoreCoordinator: coordinator];
    }
 
    return managedObjectContext;
}

And the revised code:

- (NSManagedObjectContext*)managedObjectContext
{
  if (managedObjectContext) return managedObjectContext;
 
  NSPersistentStoreCoordinator *coordinator = [self persistentStoreCoordinator];
  if (!coordinator) {
    NSMutableDictionary *dict = [NSMutableDictionary dictionary];
    [dict setValue:@"Failed to initialize the store" forKey:NSLocalizedDescriptionKey];
    [dict setValue:@"There was an error building up the data file.  Please contact support." forKey:NSLocalizedFailureReasonErrorKey];
    NSError *error = [NSError errorWithDomain:@"Zarra" code:8001 userInfo:dict];
    [[NSApplication sharedApplication] presentError:error];
    return nil;
  }
  managedObjectContext = [[NSManagedObjectContext alloc] init];
  [managedObjectContext setPersistentStoreCoordinator: coordinator];
 
  return managedObjectContext;
}

The first thing I did (and always do) is reverse and clean up the conditionals. Putting the happy path inside of the conditional is just dumb. Makes the code damn hard to read and maintainability goes out the window also.

The other change was to present an error to the user if something went wrong. This is the single point that every other piece of code has to touch to use Core Data so it makes sense to present the error here. As discussed in other articles, I am using an NSError to scream about the failure and then return a nil.

applicationShouldTerminate:

Here is the last one I will touch on today and I have definitely saved the worst for last!

- (NSApplicationTerminateReply)applicationShouldTerminate:(NSApplication *)sender {
 
    NSError *error;
    int reply = NSTerminateNow;
 
    if (managedObjectContext != nil) {
        if ([managedObjectContext commitEditing]) {
            if ([managedObjectContext hasChanges] && ![managedObjectContext save:&error]) {
 
                // This error handling simply presents error information in a panel with an 
                // "Ok" button, which does not include any attempt at error recovery (meaning, 
                // attempting to fix the error.)  As a result, this implementation will 
                // present the information to the user and then follow up with a panel asking 
                // if the user wishes to "Quit Anyway", without saving the changes.
 
                // Typically, this process should be altered to include application-specific 
                // recovery steps.  
 
                BOOL errorResult = [[NSApplication sharedApplication] presentError:error];
 
                if (errorResult == YES) {
                    reply = NSTerminateCancel;
                } 
 
                else {
 
                    int alertReturn = NSRunAlertPanel(nil, @"Could not save changes while quitting. Quit anyway?" , @"Quit anyway", @"Cancel", nil);
                    if (alertReturn == NSAlertAlternateReturn) {
                        reply = NSTerminateCancel;	
                    }
                }
            }
        } 
 
        else {
            reply = NSTerminateCancel;
        }
    }
 
    return reply;
}

This one just makes me want to cry. Follow that happy path, go ahead, I’ll wait.

Not very clean cut is it? It goes in and out of several conditions, else statements, an error and finally an alert panel. Code like this makes people think that Objective-C is hard! Try this version instead:

- (NSApplicationTerminateReply)applicationShouldTerminate:(NSApplication*)sender
{
  if (!managedObjectContext) return NSTerminateNow;
 
  if (![managedObjectContext commitEditing]) {
    NSLog(@"%@:%s unable to commit editing to terminate", [self class], _cmd);
    return NSTerminateCancel;
  }
 
  if (![managedObjectContext hasChanges]) return NSTerminateNow;
 
  NSError *error = nil;
  if (![managedObjectContext save:&error]) {
    BOOL result = [sender presentError:error];
    if (result) return NSTerminateCancel;
 
    NSString *question = NSLocalizedString(@"Could not save changes while quitting.  Quit anyway?", @"Quit without saves error question message");
    NSString *info = NSLocalizedString(@"Quitting now will lose any changes you have made since the last successful save", @"Quit without saves error question info");
    NSString *quitButton = NSLocalizedString(@"Quit anyway", @"Quit anyway button title");
    NSString *cancelButton = NSLocalizedString(@"Cancel", @"Cancel button title");
    NSAlert *alert = [[NSAlert alloc] init];
    [alert setMessageText:question];
    [alert setInformativeText:info];
    [alert addButtonWithTitle:quitButton];
    [alert addButtonWithTitle:cancelButton];
 
    int answer = [alert runModal];
    [alert release], alert = nil;
    if (answer == NSAlertAlternateReturn) return NSTerminateCancel;
 
  }
 
  return NSTerminateNow;
}

In this revised method, all of the logic is reversed. The happy path is now along the left edge of the method and much easier to follow. First, if there is no context, terminate now. If we cannot commit any active editing, give up. If there are no changes, terminate now. All of those are now extremely easy to follow and the bulk of the situations are taken care of. This leaves us with only one issue remaining, an actual honest failure.

When we try to save we look at the result. If there is a failure in the save we present it to the application that is passed (why not, its there!) to the method. After that we give the user a choice, just like in the original method to quit anyway or abort the application termination. You might notice that my alert message is a lot more code than the original. That is for two reasons. First I do not like to use the C calls and second, my message is localized. Always, always, always localize any strings that are going to be presented to the user. Even if the application will never, ever be localized, do it anyway. You will thank me down the road when that never ever turns into now!

Conclusion

Now I doubt that Apple is using code like this themselves. It is clearly quick and dirty code that they put together and never went back to revisit it. I get that and totally understand. However WE should never use code like this in our applications. It is asking for trouble and people will laugh at us when they see it.

There is a taste of my coding style. I like the happy path to be on the left; I think the “single return” mythology is a bunch of crap and you should failure early and return often.

Comments? I would love to hear them. If you are going to comment on the multiple returns, don’t bother, you will be ignored.

Per bbum’s suggestion this new code is filed under radar #5972712

The Conflict With NSUndoManager

For those familiar with the inner workings of Cocoa’s undo support (and if you are not familiar with it, check out the April edition of MacTech ;-) , all of the undo events are registered with an NSUndoManager. In a normal document model application, the window controller (or the window’s delegate if set to something other than the controller) will supply an NSUndoManager for all of the text fields and other editable bits in the window.

This works fine until Core Data comes along. The reason for this is that the NSManagedObjectContext has its own NSUndoManager that is registering those same events and can easily get out of sync.

What I prefer to do is avoid the double NSUndoManager and just use the one included with the NSManagedObjectContext. This can be done by implementing one of the window delegate methods:

1
2
3
4
5
6
7
8
9

- (NSUndoManager *)windowWillReturnUndoManager:(NSWindow *)window
{
  return [self undoManager];
}
 
- (NSUndoManager*)undoManager
{
  return [[self managedObjectContext] undoManager];
}

By utilizing the NSUndoManager that is included in the context, some very powerful features are enabled.

Grouping sheet modifications

A common UI design is to allow the editing of an object in a sheet. The user double clicks on the item or otherwise indicates that they want to edit it and a sheet drops down allowing them to change the values. Naturally, that sheet has an NSUndoManager attached to it (can even use the one from Core Data) and each individual field can be undone. However, how to do we handle the cancel button or the ability to undo the entire sheet?

Both of the above can be handled with groupings inside of the NSManagedObjectContext object’s NSUndoManager. The methods would work as follows:

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

- (void)presentEditSheet:(id)sender
{
  [[self undoManager] beginUndoGrouping];
  [NSApp beginSheet:[self editSheet] 
     modalForWindow:[self window] 
      modalDelegate:nil 
     didEndSelector:NULL 
        contextInfo:nil];
}
 
- (void)acceptChanges:(id)sender
{
  [[self editSheet] orderOut:sender];
  [NSApp endSheet:[self editSheet]];
  [[self undoManager] endUndoGrouping];
  [[self undoManager] setActionName:@"Object edit"];
}
 
- (void)cancelChanges:(id)sender
{
  [[self editSheet] orderOut:sender];
  [NSApp endSheet:[self editSheet]];
  [[self undoManager] endUndoGrouping];
  [[self undoManager] undo];
}

In this example I have started an undo group before presenting the sheet. After the sheet is closed I then end the grouping and if the sheet was not cancelled I give the group a name. This name will display in the menu and allow all of the changes inside of the sheet to be undone in one stroke. If the sheet is cancelled then the group is still closed but I immediately call undo instead and everything that occurred within the sheet is wiped clean.

Conclusion

By only using one NSUndoManager it makes life a lot simplier and gives consistent results to the user. This technique can also be used in a document model application but each document will have to reference the appropriate NSUndoManager that is associated with its own NSManagedObjectContext.

Feedback

If you have some other interesting ways to use the NSUndoManager I would love to hear about them either here in the comments or you can email me directly at marcus at cimgf.com.

NSDecimalNumber, an immutable subclass of NSNumber, provides an object-oriented wrapper for doing base-10 arithmetic. An instance can represent any number that can be expressed as mantissa x 10^exponent where mantissa is a decimal integer up to 38 digits long, and exponent is an integer from –128 through 127.

NSDecimalNumber

If you are dealing with currency at all, then you should be using NSDecimalNumber. However, since it is immutable and definitely not a primitive then it is difficult to use right? Well — yes — a bit. But if you do not want to see your $9.50 item displayed as $9.49999994 or something then you are better off using NSDecimalNumber right from the beginning. Otherwise you are going to be converting to it later and that is a LOT more painful.

To create an NSDecimalNumber there are a few helper class methods:

• +decimalNumberWithDecimal:

• +decimalNumberWithMantissa:exponent:isNegative:

• +decimalNumberWithString:

• +deicmalNumberWithString:locale:

• +one

• +zero

• +notANumber

The two methods that I ended up using the most are +decimalNumberWithDecimal: and +decimalNumberWithMantissa:exponent:isNegative: If you already have the number stored as an NSNumber then [NSDecimalNumber decimalNumberWithDecima:[yourNumber decimalValue]] is the easiest way to convert it. If the number is a primitive then [NSDecimalNumber decimalNumberWithMantissa:(yourPrimitive * precision) exponent:-(precision) isNegative:(yourPrimitive < 0 ? YES : NO)] will convert it.

Math functions

So now you have your number as an NSDecimalNumber. How do you do anything with it? Specifically how do you add, divide, multiple and subtract an immutable number? Fortunately the class has methods to handle all of these:

• -decimalNumberByAdding:

• -decimalNumberBySubtracting:

• -decimalNumberByMultiplingBy:

• -decimalNumberByDividingBy:

• -decimalNumberByRaisingToPower:

• -decimalNumberByMultiplyingByPowerOf10:

With these methods you can do all of the math functions and create a new NSDecimalNumber with each call. Naturally these can even be chained together to make a deliciously convoluted method call.

Rounding

So what happens when you need to control the decimal precision of an NSDecimalNumber? Specifically what happens when you multiply 9.49 * 10% and what only two decimal points left over? That is where the NSDecimalNumberBehaviors come in. The NSDecimalNumberBehaviors protocol is defined as:

The NSDecimalBehaviors protocol declares three methods that control the discretionary aspects of working with NSDecimalNumber objects.

The scale and roundingMode methods determine the precision of NSDecimalNumber’s return values and the way in which those values should be rounded to fit that precision. The exceptionDuringOperation:error:leftOperand:rightOperand: method determines the way in which an NSDecimalNumber object should handle different calculation errors.

For an example of a class that adopts the NSDecimalBehaviors protocol, see the specification for NSDecimalNumberHandler.

This protocol is implemented in the NSDecimalNumberHandler class. By constructing an NSDecimalNumberHandler and passing it in as part of the math call you can control the rounding applied to the math function. Even better, you can reuse the handler class as often as you want. Therefore to perform the calculation above:

NSDecimalNumber *price = [NSDecimalNumber decimalNumberWithMantissa:949
                                                           exponent:-2
                                                         isNegative:NO];

NSDecimalNumber *percent = [NSDecimalNumber decimalNumberWithMatissa:10
                                                            exponent:-2
                                                          isNegative:NO];

NSDecimalNumberHandler *handler = [NSDecimalNumberHandler decimalNumberHandlerWithRoundingMode:NSRoundPlain
                                                                                         scale:-2
                                                                              raiseOnExactness:NO
                                                                               raiseOnOverflow:NO
                                                                              raiseOnUnderflow:NO
                                                                           raiseOnDivideByZero:NO];
NSDecimalNumber *result = [price decimalNumberByMultiplyingBy:percent
                                                 withBehavior:handler];

Note that instead of using -decimalNumberByMultiplyingBy: I used a similar method which adds withBehavior: on the end of it. Each of the math functions listed above includes a companion method which allows you to pass in the behavior. Also note that the NSDecimalNumberHandler class allows you to raise exceptions in several circumstances. You can review Apple’s documentation on each of these exceptions if you find a need for them.

Core Data

So how does Core Data handle NSDecimalNumber(s)? In a word — perfectly. In your Core Data model simply define the attribute as “decimal” instead of double or another primitive and you can store the NSDecimalNumber directly in the repository and retrieve it as an NSDecimalNumber. You can also retrieve it as an NSNumber if needed since NSDecimalNumber is a subclass of NSNumber.

Formatting

All of the number formatters will handle NSDecimalNumber perfectly with no loss of precision. If you pass it to a currency formatter you will get back the number you expect unlike passing a double and hoping for the best.

Conclusion

So is NSDecimalNumber harder to use than primitives? Absolutely. Compared to primitives it is a lot harder to code, maintain and read. Is it worth it? Depends.

If you are dealing with currency then there is no question — use NSDecimalNumber and avoid doubles like the plague. Spend the time, learn the API. Otherwise you will end up having to migrate over to them later when you discover that $9.49 * 10% may not equal $0.95.

If you are not dealing with currency or another number that requires absolute precision (such as screen drawing, et al) then you probably do not need to deal with the pain.

So why did I title this article with the words “Like Me”? Take a good guess…

There are a few scripts floating around that perform this trick for subversion, but git handles build numbers a bit differently and it appears that no one has bothered to publish one. As is known, subversion uses an incrementing integer for build numbers. This makes it very easy to determine which build number came first and makes it very useful for a non-public version number. Git, however, uses a hash for each build number which is not incrementing and therefore not very useful for determining version numbers. However, it is still very useful for pulling up a specific build when a crash report is received, etc.

Therefore, with the help of Matt Long’s perl-fu, I have updated Daniel Jalkut’s subversion perl script to work with git. Since the build numbers are not sequential, I would not recommend using them for Sparkle. Therefore, in my own build process for iWeb Buddy, I hand select the version number (for example 1.0.4) and then use the short hash from git as the CFBundleVersion number. Normally this number is displayed in parens after the primary build number but, at least in iWeb Buddy, I have removed it from the display entirely. Since it is no longer a sequential number it would only potentially confuse users and it displays in the crash reports anyway.

The updated script is as follows:

# Xcode auto-versioning script for Subversion by Axel Andersson
# Updated for git by Marcus S. Zarra and Matt Long
 
use strict;
 
# Get the current git commit hash and use it to set the CFBundleVersion value
my $REV = `/opt/local/bin/git show --abbrev-commit | grep "^commit"`;
my $INFO = "$ENV{BUILT_PRODUCTS_DIR}/$ENV{WRAPPER_NAME}/Contents/Info.plist";
 
my $version = $REV;
if( $version =~ /^commit\s+([^.]+)\.\.\.$/ )
{ 
	$version = $1;
}
else
{
	$version = undef;
}
die "$0: No Git revision found" unless $version;
 
open(FH, "$INFO") or die "$0: $INFO: $!";
my $info = join("", <FH>);
close(FH);
 
$info =~ s/([\t ]+<key>CFBundleVersion<\/key>\n[\t ]+<string>).*?(<\/string>)/$1$version$2/;
 
open(FH, ">$INFO") or die "$0: $INFO: $!";
print FH $info;
close(FH);

Since git is distributed, there is no need to be online to produce a build. The script will grab the current abbrev-commit hash and will inject it into the current build’s Info.plist file.

Try/Catch

I truly dislike using try/catch. It indents my code all to hell, is difficult to follow and even more difficult to debug. Anyone who has written Java code for any length of time knows the true hell that is try/catch. Therefore I try to avoid this method of error handling if at all possible. I find that it interrupts the logical flow of the code and is just plain rude.

Return Codes

This is probably the more common method of handling errors. Return an integer and let the calling code decide how to handle it. This is definitely better than the try/catch solution as it does not indent the code badly and does not interrupt the logic flow. However, I find that return codes are harder to maintain than they should be. What was 1? What about 2? And 12342 was what again?!?

And worse, what happens when everything goes right and I need to return an object? Oops…

Introduction to NSError

Fortunately, there is a better solution. NSError allows me to return whatever I want, handles errors without breaking the logic flow, and has quite a few other features. First some code to demonstrate how Apple uses NSError:

1
2
3
4
5
6
7

NSError *error = nil;
BOOL success = [myContext save:&error];
if (!success) {
  [NSApp presentError:error];
  return;
}
//Continue processing

In this simple example, I am calling save on my NSManagedObjectContext and I am passing in an NSError pointer. If there is an issue, then that pointer will reference an NSError object that I can then utilize however I need. In this case I am simply passing it off to the NSApp to be displayed to the user. However, I could just as easily have done this:

1
2
3
4

if (!success) {
  NSLog(@"%@:%s Error saving context: %@", [self class], _cmd, [error localizedDescription]);
  return;
}

I suggest reviewing Apple’s Documentation on NSError to discover all of the information that is available.

Passing Pointers to Pointers

Using the NSError class in the above example is quite simple. I just pass it in and if the call failed for whatever reason I have an NSError object to explain what the problem was. But how does the other side of that call work?

The first part of this is to understand the concept of passing a pointer to a pointer rather than a pointer to an object. Normally when a message is sent, a pointer to the object is being passed in the message. This is denoted with the single asterisk(*) in the method signature such as

-(void)appendString:(NSString*)newString

This is different then passing a pointer to a pointer. First, that type of argument is denoted with two asterisk(**) such as:

-(BOOL)save:(NSError**)error

Second, the other difference is this allows the receiving method to control what the pointer (that the pointer is pointing to) is referencing. This is arguably one of the more confusing parts of pointer programming but once you get it, it is a very powerful tool. To put it another way, by passing a pointer to the pointer, the receiving method can decide what your variable’s value is. As you can see in my code above, I initialized the error variable to nil. However, if the save call fails, that variable will no longer be nil but will reference an actual NSError object which I can than interrogate.

If you wish to understand how this works, I would suggest the double indirection wikipedia article as a great starting point.

Using NSError Handling in My Code

With a firm understanding of double indirection pointers </smile> I am now able to build my own methods that accept a pointer to an NSError object and I can utilize that pointer if anything goes wrong. Consider the following code:

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

- (id)fetchDocument:(NSURL*)url error:(NSError**)error
{
  NSString *myString = [[NSString alloc] initWithContentsOfURL:url];
 
  //start to do something wickedly cool with the data
  if (YES) {
    //An error occurred
    NSMutableDictionary *errorDetail = [NSMutableDictionary dictionary];
    [errorDetail setValue:@"Failed to do something wicked" forKey:NSLocalizedDescriptionKey];
    *error = [NSError errorWithDomain:@"myDomain" code:100 userInfo:errorDetail];
    return nil;
  }
  //Finish doing something wicked
  return [[[NSObject alloc] init] autorelease];
}

In this example, I have passed in an NSURL. Using that NSURL object I have populated a string with it and the “do something wicked” with the contents of the NSString. However, there is an error in the processing and therefore I want to notify the calling code that it failed. To do this I first constructed an NSMutableDictionary that contains all of the information about the failure. In this example I only populated the localized description key but I could have put a lot more in there.

Once the dictionary is populated, I then initialized an NSError object using the helper method that gives me back an auto-released object. I then assigned that object back to the pointer that was passed in. The interesting piece of code here is how I am referencing the passed in pointer. To update the pointer that the passed in pointer is pointing to I need to include an asterisk before the name of the variable. This tells the compiler that I want to change what the pointer to pointer is pointing to. Yes — it is a bit confusing but the end result is that the NSError reference in the calling method will reference the NSError object that has been constructed in the called method and thus allowing me to pass information back to the calling method along a second path.

By utilizing an NSError in this manner, I am able to return anything I need when the method is successful and still able to send back all of the error information required when something goes wrong.

Displaying NSError Objects

Once you get an NSError object back from a method there are a lot of things that can be done with it. Since Apple uses them so often in their own code, a way to present them to the User has been included in the Cocoa APIs.

1
2
3
4
5
6
7
8
9
10

- (IBAction)thrower:(id)sender;
{
  NSError *error = nil;
  id result = [self fetchDocument:[NSURL URLWithString:@"http://www.apple.com"] error:&error];
  if (error) {
    [NSApp presentError:error];
    return;
  }
  NSLog(@"Result received: %@", result);
}

In this example, I am checking to see if the error is still nil after my message call. If it is no longer nil I know that an error occurred and that I need to display it to the user. Apple provides a built in method to do this with a call to presentError: on the NSApplication instance. If you run the example project included you will see that this presents a dialog window to the user with the localized description displayed.

Conclusion

This article will be followed up with another one detailing some of the more interesting things that you can do with NSError objects. Hopefully this taste will highlight the usefulness of this method of error handling and how it is an improvement over both try/catch blocks and return codes.

Download the Example Project

As usual, I’ve created a demo application that will allow you to see how things work. You can download it here: Leaky Demo Application. In this post I am simply going to show you how to use Instruments to detect memory leaks. It’s pretty straightforward, but there are few little nuances you may not be familiar with that once you understand will help you feel comfortable using this powerful tool.

Running Instruments From XCode

You can start Instruments directly and then navigate to your project build, however, it’s much quicker and simpler to start Instruments from XCdoe. To do so , open the demo project or a project of your own in XCode and select Run | Start With Performance Tool | Leaks.

While working on this project, Marcus and I discovered a few things that you should keep in mind while you are using Instruments.

• Breakpoints Do Not Break. Instruments utilizes debug information from your debug build, however, it does not stop at break points you set. This is because while you are loading your application into Instruments from the menu in XCode, Instruments simply uses the path of the current executable as its start path and loads it externally from XCode. The menu in XCode is really there as a convenience mechanism. This is not a big deal as you can always run again in Debug mode after your instruments session should you want your application to break. It’s just something to make a note of.


• NSLog Statements Do Not Show In The Debugger Console. If you want to see your NSLog statements, you will need to load the system Console application (/Applications/Utilities/Console).

Leaking Like A Sieve… Or Not

Our expectation was that when we allocated memory for a new NSString* object we would see it leak right away. This was, after all, our intention. Things, however, don’t always work the way you might expect. This code would not leak in our tests no matter what we tried.

1

NSString *string = [[NSString alloc] initWithString:@"Leaker"];

And here’s why. It turns out that since NSString(s) are immutable and since we are allocating the string using the @ operator, the compiler is making things more efficient for us. Strings with the same contents are given the same memory address. Here is a comment from the CocoaDev site that clarifies what I mean.

The nice thing about using the @”" notation for initializing NSString objects is that if you create two of them and their content is the same, the runtime uses the same storage for them. (Note, this is not guaranteed and certainly may not be the case across compilation unit or library boundaries. It is a performance optimization and the fact that it happens sometimes should not lead you to believe that you can safely, for example, use “==” to compare strings if you know they’re both from string constants.) (Ref. CocoaDev NSString)

In the example code, the NSString objects never leak and so they weren’t very useful. This isn’t to say that they never will leak, so you should be in the habit of calling release on your NSString(s), however, for our example project at least, the NSString leaks were never detected. We instead switched over to using NSMutableString at which point the application began to leak as desired.

Detecting Leaks

When instruments loads your application, you will see the ObjectAlloc track start to fill in. To detect the leaks in your project, click on the Leaks track and then watch the Leak Status category which will detect leaks after the current timeout value. Alternatively, you can just click the Check For Leaks Now button under the Check Manually category.

Once the leak detection process has occurred you will see a list of objects that are currently leaking. To get details for any leaks in the list, click the object in the list and then click the Extended Detail button at the bottom of the Instruments screen.

Once you have clicked the Extended Detail button, you will see the stack trace list on the right side of the Instruments window. Look through the stack and locate any code highlighted with the color #CCFFFF which looks like this.

Note: This is actually inaccurate. The color may be different on your machine than on mine. Instead of looking for a color, look for your applications name and path and double-click that instead.
Thanks to Jason for pointing out the error.

Once you find the leak in your application, simply double click it and Instruments will return you to the exact line in XCode where the leak is happening.

To fix the leak, you need to make sure that you release the object. For more information and basic guidelines on memory allocation and deallocation, do a Google search. You can start with sites like this one: Very simple rules for memory management in Cocoa.

Conclusion

Finding and fixing issues is not the most glamorous aspect of application development, however, when done, the results are very rewarding. Instruments provides a streamlined way to track everything you would care about in your application. Watch this site for more tutorials on how to use other components available in Instruments. If you want to get an idea of what’s available, click on the Library button in Instruments and scroll through the ensuing list. It’s impressive.

One of those areas is the initialization and callbacks from the nib files to my code. Normally, when I want a controller to do something after the NIB/XIB has loaded, I add the method -(void)awakeFromNib and know that I will receive a call when all of the connections into the NIB/XIB are complete. But on what object does this get called and how?

In another case, I can be notified when the application has finished launching. This method, -(void)applicationDidFinishLaunching:(NSNotification*)aNotification gets called after the MainMenu.[nib|xib] has finished loading. How does this method get called and on who does it get called?

And the third question. If I am using both of these spells above, which gets called first and why?

awakeFromNib

awakeFromNib is called on every object that is initialized or referenced from within a nib file. For example, take a look at the following nib file:

Image 1

In this nib file, I have references to two pieces of custom code: The Window Controller and the Window itself. So which of these two gets the awakeFromNib call? Both do.

Specifically, when a nib file has completed initializing all of the objects, it then loops back through every object referenced in the nib and if the object responds to awakeFromNib, it calls awakeFromNib on the object. Therefore, you can have logic in any or all of your objects in the awakeFromNib call.

applicationDidFinishLaunching:

In the nib above, which object would receive a applicationDidFinishLaunching: call? None of them. The nib in that example is not set up to be the primary nib for an application. When a nib is designed to be the primary or initial nib for an application it will have a reference to NSApplication in it.

Image 2

In this example you can see the reference to the NSApplication in the nib. This nib is designed to be the initial nib loaded by the application. This can be confirmed by looking at the File’s Owner class type and see that it points to NSApplication rather than an NSObject or some custom controller class (Image 3). So who gets the applicationDidFinishLaunching: call? While you cannot see it in the image above, the object ‘AppDelegate’ is referenced as the delegate for the NSApplication.

Image 3

Image 4

Therefore, when the application has indeed finished launching, then this method on the AppDelegate and only the AppDelegate will be called. Only one object gets this method per application launch.

Call order

In the second example above, it is possible to have an awakeFromNib method and an applicationDidFinishLaunching: method in the AppDelegate. Which would be called first and why?

The answer is that the awakeFromNib will be called first. When the nib file has been initialized, each object referenced in the nib will be looped through and they will all receive an awakeFromNib call if they respond to the message. After all of that is done then the Application’s delegate will receive the applicationDidFinishLaunching: call. This is the notice that everything is loaded and that the application is ready to start receiving user input.

Conclusion

If your code is localized to only the object you are working with then putting the code in the awakeFromNib is the perfect place for it. However, if your code is going to be manipulating more than one object in the nib then it is probably safer to put it in the applicationDidFinishLaunching: instead. This will insure that everything is loaded, referenced and ready to go.

One of the things about Objective-C that I find extremely useful is the ability to resolve a method call at runtime. In addition this same functionality allows us to do some fairly creative things with callbacks, passing messages between threads, etc.

However there is a bit of a trick when it comes to passing primitives though some of these methods. For example, one method that I use quite frequently is performSelectorOnMainThread:withObject:waitUntilDone:. How exactly does one pass a BOOL or an int to this method?

Fortunately, this is actually very simple. While Objective-C does not have the ability to autobox primitives, it will unbox them in this situation. For example, if you had the following method:

1
2
3
4

- (void)updateCounter:(int)counter
{
    //Do something clever
}

And you needed to call it from a background thread but it needed to be performed on the main thread, all you need to do is:

1
2
3
4
5
6
7

-(void)aMethodOnABackgroundThread
{
    int myInt = 12;
    [self performSelector:@selector(updateCounter:)
               withObject:[NSNumber numberWithInt:myInt]
            waitUntilDone:NO];
}

As you can see, we are passing a NSNumber object into the method. So what is the method actually receiving? It will receive a primitive int just as it expects to. No additional work is required in the receiving method.

This same unboxing can be performed with any primitive including BOOL. Simply wrap them in a NSNumber and pass the NSNumnber through the method call.

As always, there is an exception to the rule. When you are building your own NSInvocation (the magic Class behind these callbacks) you do not need to pass it an object for a primitive.

1
2
3
4
5
6
7
8
9
10
11

-(void)aMethodOnABackgroundThread
{
    int myInt = 12;
    SEL sel = @selector(updateCounter:);
    NSMethodSignature *sig = [self methodSignatureForSelector:sel];
    NSInvocation *invocation = [NSInvocation invocationWithMethodSignature:];
    [invocation setTarget:self];
    [invocation setSelector:sel];
    [invocation setArgument:&myInt atIndex:2];
    [invocation invoke];
}

In this example, the NSNumber wrapper/boxing is unnecessary as the invocation accepts anything.

This post is in response to a few queries that I have received regarding my last post showing an NSOperation example. One of the questions raised that I will focus on is my -(void)dealloc method in the NSOperation subclass. The questions boiled down to:

Why are you using releases at all. Garbage collection is the future!

and

You should be just doing [self setVar:nil] instead of that [var release], var = nil; crap.

Garbage Collection

Regarding garbage collection–currently I am not using it in any of my production code. seSales is still backwards compatible with Tiger and will remain so for now. iWebBuddy, however, uses the dotMac SDK quite heavily and therefore it cannot use garbage collection since that SDK is not compatible (yet). Even if I were to start using garbage collection tomorrow I would still be writing dealloc methods, adding autorelease to temporary variables, etc.

The reason for this is simple–it makes the code compatible with both garbage collected and non-garbage collected compiles. I can turn gc on and off without having to go through my code and re-adding all of the memory management. Since Apple was wise enough to make all of the memory calls no-ops with gc turned on it does not hurt anything to leave them in! Since I am a former Java developer, I do not trust garbage collection yet. That may and probably will change in the future but for now, I am watching it very closely.

dealloc and releasing objects

For the second question regarding how I handle my dealloc methods. This requires a little bit more explanation but the short answer is — I am used to doing them that way.

For the longer answer, we have to look at what Objective-C is synthesizing my @property(retain) NSURL *targetURL; into. The resulting setter for this property is something very similar to:

1
2
3
4
5
6
7

- (void)setTargetURL:(NSURL*)url
{
    if (url == targetURL) return;
    [url retain];
    [targetURL release];
    targetURL = url;
}

If that looks familiar to you, it should. We have been writing setter methods like that for years. So when I call [self setTargetURL:nil] from my dealloc method, it is really doing 3 message calls, an assignment and a conditional–as opposed to my normal release code which is:

1
2
3
4
5

- (void)dealloc
{
    [targetURL release], targetURL = nil;
    [super dealloc];
}

In my release there is one message and one assignment. So it is shorter and faster. Of course with modern hardware the difference between these two is negligible.

Conclusion

So which way is better? Neither and both. My coding style is born out of years of habit. To change it now for no gain is a waste of energy and risks introducing bugs into my code that would not otherwise be there. If there was something to be gained from changing the way I handle memory or the way I release my objects then I would absolutely relearn it. While the upgrades to Objective-C in Leopard are great, and I use many of them, they do not force me to change my habits with regard to memory management. And that, in my opinion, is a great thing.