The exception handling mechanisms available to Objective-C programs are effective ways of dealing with exceptional conditions. They decouple the detection and handling of these conditions and automate the propagation of the exception from the point of detection to the point of handling. As a result, your code can be much cleaner, easier to write correctly, and easier to maintain.
The following sections describe how to handle exceptions using compiler directives or, for appropriate projects, the legacy mechanism of exception-handling macros.
Important: The Objective-C compiler directives discussed below were introduced in Mac OS X v10.3. An application that uses these directives for exception handling cannot run on earlier versions of the operating system.
Starting with version 3.3 of the GNU Compiler Collection (GCC), the compiler provides runtime support for exception handling. To turn on this support, make sure the -fobj-exceptions
flag is turned on; this is enabled through the Enable Objective-C Exceptions build option in Xcode.
The compiler support for exceptions is based on four compiler directives:
@try
—Defines a block of code that is an exception handling domain: code that can potentially throw an exception.
@catch()
—Defines a block containing code for handling the exception thrown in the @try
block. The parameter of @catch
is the exception object thrown locally; this is usually an NSException
object, but can be other types of objects, such as NSString
objects.
@finally
— Defines a block of related code that is subsequently executed whether an exception is thrown or not.
@throw
— Throws an exception; this directive is almost identical in behavior to the raise
method of NSException
. You usually throw NSException
objects, but are not limited to them. For more information about @throw
, see “Throwing Exceptions.”
Important: Although you can throw and catch objects other than NSException
objects, the Cocoa frameworks themselves might only catch NSException
objects for some conditions. So if you throw other types of objects, the Cocoa handlers for that exception might not run, with undefined results. (Conversely, non-NSException
objects that you throw could be caught by some Cocoa handlers.) For these reasons, it is recommended that you throw NSException
objects only, while being prepared to catch exception objects of all types..
The @try
, @catch
, and @finally
directives constitute a control structure. The section of code between the braces in @try
is the exception handling domain; the code in a @catch
block is a local exception handler; the @finally
block of code is a common “housekeeping” section. In Figure 1, the normal flow of program execution is marked by the gray arrow; the code within the local exception handler is executed only if an exception is thrown—either by the local exception handling domain or one further down the call sequence. The throwing (or raising) of an exception causes program control to jump to the first executable line of the local exception handler. After the exception is handled, control “falls through” to the @finally
block; if no exception is thrown, control jumps from the @try
block to the @finally
block.
Where and how an exception is handled depends on the context where the exception was raised (although most exceptions in most programs go uncaught until they reach the top-level handler installed by the shared NSApplication
or UIApplication
object). In general, an exception object is thrown (or raised) within the domain of an exception handler. Although you can throw an exception directly within a local exception handling domain, an exception is more likely thrown (through @throw
or raise
) indirectly from a method invoked from the domain. No matter how deep in a call sequence the exception is thrown, execution jumps to the local exception handler (assuming there are no intervening exception handlers, as discussed in “Nesting Exception Handlers”). In this way, exceptions raised at a low level can be caught at a high level.
Listing 1 illustrates how you might use the @try
, @catch
, and @finally
compiler directives. In this example, the @catch
block handles any exception thrown lower in the calling sequence as a consequence of the setValue:forKeyPath:
message by setting the affected property to nil
instead. The message in the @finally
block is sent whether an exception is thrown or not.
Listing 1 Handling an exception using compiler directives
- (void)endSheet:(NSWindow *)sheet |
{ |
BOOL success = [predicateEditorView commitEditing]; |
if (success == YES) { |
@try { |
[treeController setValue:[predicateEditorView predicate] forKeyPath:@"selection.predicate"]; |
} |
@catch ( NSException *e ) { |
[treeController setValue:nil forKeyPath:@"selection.predicate"]; |
} |
@finally { |
[NSApp endSheet:sheet]; |
} |
} |
} |
One way to handle exceptions is to “promote” them to error messages that either inform users or request their intervention. You can convert an exception into an NSError
object and then present the information in the error object to the user in an alert panel. In Mac OS X, you could also hand this object over to the Application Kit’s error-handling mechanism for display to users. You can also return them indirectly in methods that include an error parameter. Listing 2 shows an example of the latter in an Automator action’s implementation of runWithInput:fromAction:error:
(in this case the error parameter is a pointer to an NSDictionary
object rather than an NSError
object).
Listing 2 Converting an exception into an error
- (id)runWithInput:(id)input fromAction:(AMAction *)anAction error:(NSDictionary **)errorInfo { |
NSMutableArray *output = [NSMutableArray array]; |
NSString *actionMessage = nil; |
NSArray *recipes = nil; |
NSArray *summaries = nil; |
// other code here.... |
@try { |
if (managedObjectContext == nil) { |
actionMessage = @"accessing user recipe library"; |
[self initCoreDataStack]; |
} |
actionMessage = @"finding recipes"; |
recipes = [self recipesMatchingSearchParameters]; |
actionMessage = @"generating recipe summaries"; |
summaries = [self summariesFromRecipes:recipes]; |
} |
@catch (NSException *exception) { |
NSMutableDictionary *errorDict = [NSMutableDictionary dictionary]; |
[errorDict setObject:[NSString stringWithFormat:@"Error %@: %@", actionMessage, [exception reason]] forKey:OSAScriptErrorMessage]; |
[errorDict setObject:[NSNumber numberWithInt:errOSAGeneralError] forKey:OSAScriptErrorNumber]; |
*errorInfo = errorDict; |
return input; |
} |
// other code here .... |
} |
Note: For more on the Application Kit’s error-handling mechanisms, see Error Handling Programming Guide. To learn more about Automator actions, see Automator Programming Guide.
You can have a sequence of @catch
error-handling blocks. Each block handles an exception object of a different type. You should order this sequence of @catch
blocks from the most-specific to the least-specific type of exception object (the least specific type being id
), as shown in Listing 3. This sequencing allows you to tailor the processing of exceptions as groups.
Listing 3 Sequence of exception handlers
@try { |
// code that throws an exception |
... |
} |
@catch (CustomException *ce) { // most specific type |
// handle exception ce |
... |
} |
@catch (NSException *ne) { // less specific type |
// do whatever recovery is necessary at his level |
... |
// rethrow the exception so it's handled at a higher level |
@throw; |
} |
@catch (id ue) { // least specific type |
// code that handles this exception |
... |
} |
@finally { |
// perform tasks necessary whether exception occurred or not |
... |
} |
Note: You cannot use the setjmp
and longjmp
functions if the jump entails crossing an @try
block. Since the code that your program calls may have exception-handling domains within it, avoid using setjmp
and longjmp
in your application. However, you may use goto
or return
to exit an exception handling domain.
Using the exception-handling directives of Objective-C can complicate memory management, but with a little common sense you can avoid the pitfalls. To see how, let’s begin with the simple case: a method that, for the sake of efficiency, creates an object, uses it, and then releases it explicitly:
- (void)doSomething { |
NSMutableArray *anArray = [[NSMutableArray alloc] initWithCapacity:0]; |
[self doSomethingElse:anArray]; |
[anArray release]; |
} |
The problem here is obvious: If the doSomethingElse:
method throws an exception there is a memory leak. But the solution is equally obvious: Move the release
to a @finally
block:
- (void)doSomething { |
NSMutableArray *anArray = nil; |
array = [[NSMutableArray alloc] initWithCapacity:0]; |
@try { |
[self doSomethingElse:anArray]; |
} |
@finally { |
[anArray release]; |
} |
} |
This pattern of using @try...@finally
to release objects involved in an exception applies to other resources as well. If you have malloc
’d blocks of memory or open file descriptors, @finally
is a good place to free those; it’s also the ideal place to unlock any locks you’ve acquired.
Another, more subtle memory-management problem is over-releasing an exception object when there are internal autorelease
pools. Almost all NSException
objects (and other types of exception objects) are created autoreleased, which assigns them to the nearest (in scope) autorelease pool. When that pool is released, the exception is destroyed. A pool can be either released directly or as a result of an autorelease pool further down the stack (and thus further out in scope) being popped (that is, released). Consider this method:
- (void)doSomething { |
NSAutoreleasePool *pool = [[NSAutoreleasePool alloc] init]; |
NSMutableArray *anArray = [[[NSMutableArray alloc] initWithCapacity:0] autorelease]; |
[self doSomethingElse:anArray]; |
[pool release]; |
} |
This code appears to be sound; if the doSomethingElse:
message results in a thrown exception, the local autorelease pool will be released when a lower (or outer) autorelease pool on the stack is popped. But there is a potential problem. As explained in “Throwing Exceptions,” a rethrown exception causes its associated @finally
block to be executed as an early side effect. If an outer autorelease pool is released in a @finally
block, the local pool could be released before the exception is delivered, resulting in a “zombie” exception.
There are several ways to resolve this problem. The simplest is to refrain from releasing local autorelease pools in @finally
blocks. Instead let a pop of a deeper pool take care of releasing the pool holding the exception object. However, if no deeper pool is ever popped as the exception propagates up the stack, the pools on the stack will leak memory; all objects in those pools remain unreleased until the thread is destroyed.
An alternative approach would be to catch any thrown exception, retain it, and rethrow it . Then, in the @finally
block, release the autorelease pool and autorelease the exception object. Listing 4 shows how this might look in code.
Listing 4 Releasing an autorelease pool containing an exception object
- (void)doSomething { |
id savedException = nil; |
NSAutoreleasePool *pool = [[NSAutoreleasePool alloc] init]; |
NSMutableArray *anArray = [[[NSMutableArray alloc] initWithCapacity:0] autorelease]; |
@try { |
[self doSomethingElse:anArray]; |
} |
@catch (NSException *theException) { |
savedException = [theException retain]; |
@throw; |
} |
@finally { |
[pool release]; |
[savedException autorelease]; |
} |
} |
Doing this retains the thrown exception across the release of the interior autorelease pool—the pool the exception was put into on its way out of doSomethingElse:
—and ensures that it is autoreleased in the next autorelease pool outward to it in scope (or, in another perspective, the autorelease pool below it on the stack). For things to work correctly, the release of the interior autorelease pool must occur before the retained exception object is autoreleased.
An exception handler is contained within a control structure created by the macros NS_DURING
, NS_HANDLER
, and NS_ENDHANDLER
, as shown in Figure 2.
Important: The exception macros are a legacy mechanism that should only be used when binary compatibility with versions of of the operating system prior to Mac OS X v10.3 is a concern.
The section of code between NS_DURING
and NS_HANDLER
is the exception handling domain; the section between NS_HANDLER
and NS_ENDHANDLER
is the local exception handler. The normal flow of program execution is marked by the gray arrow; the code within the local exception handler is executed only if an exception is raised. Sending a raise
message to an exception object causes program control to jump to the first executable line following NS_HANDLER
.
Although you can raise an exception directly within the exception handling domain, raise
is more often invoked indirectly from a method invoked from the domain. No matter how deep in a call sequence the exception is raised, execution jumps to the local exception handler (assuming there are no intervening exception handlers, as discussed in “Nesting Exception Handlers”). In this way, exceptions raised at a low level can be caught at a high level.
For example, in the following program excerpt, the local exception handler displays an alert dialog after detecting an exception having the name MyAppException. The local exception handler has access to the raised exception object through a local variable localException
.
NS_DURING |
... |
if (someError) |
[anException raise]; |
... |
NS_HANDLER |
if ([[localException name] isEqualToString:MyAppException]) { |
NSRunAlertPanel(@"Error Panel", @"%@", @"OK", nil, nil, |
localException); |
} |
[localException raise]; /* Re-raise the exception. */ |
NS_ENDHANDLER |
You may leave the exception handling domain (the section of code between NS_DURING
and NS_HANDLER
) by:
Raising an exception.
Calling NS_VALUERETURN()
Calling NS_VOIDRETURN
“Falling off the end”
The above example raises an exception when someError
is YES
. Alternatively, you can return control to the caller from within the exception handling domain by calling either NS_VALUERETURN()
or NS_VOIDRETURN
. “Falling off the end” is simply the normal path of execution—after all statements in the exception handling domain are executed, execution continues on the line following NS_ENDHANDLER
.
Note: You cannot use goto
or return
to exit an exception handling domain—errors will result. Nor can you use the setjmp
and longjmp
functions if the jump entails crossing an NS_DURING
statement. Since the code that your program calls may have exception-handling domains within it, avoid using setjmp
and longjmp
in your application.
Similarly, you can leave the local exception handler (the section of code between NS_HANDLER
and NS_ENDHANDLER
) by raising an exception or simply “falling off the end”.
Last updated: 2010-02-24