I was going to get down to doing some writing, but then I got some new kit I needed to set up, so that isn’t going to happen. Besides which, I was talking to one developer about NSInvocation and writing to another about NSInvocation, then another asked about NSInvocation. So now seems like a good time to talk about NSInvocation.
What is NSInvocation?
Well, we could rely on Apple’s NSInvocation class reference to tell us that
An NSInvocation is an Objective-C message rendered static, that is, it is an action turned into an object.
This means that you can construct an invocation describing sending a particular message to a particular object, without actually sending the message. At some later point you can send the message as rendered, or you can change the target, or any of the parameters. This “store-and-forward” messaging makes implementing some parts of an app very easy, and represents a realisation of a design pattern called Command.
How is that useful?
The Gang of Four describes Command like this:
Encapsulate a request as an object, thereby letting you parameterize clients with different requests, queue or log requests, and support undoable operations.
Well, what is NSInvocation other than a request encapsulated as an object?
You can imagine that this would be useful in a distributed system, such as a remote procedure call (RPC) setup. In such a situation, code in the client process sends a message to its RPC library, which is actually acting as a proxy for the remote service. The library bundles up the invocation and passes it to the remote service, where the RPC implementation works out which object in the server process is being messaged and invokes the message on that target.
Spoiler alert: that really is how Distributed Objects on Mac OS X operates. NSInvocation instances can be serialised over a port connection and sent to remote processes, where they get deserialised and invoked.
An undo manager, similarly, works using the Command pattern and NSInvocation. Registering an undo action creates an invocation, describing what would need to be done to revert some user action. This invocation is placed on a queue, so the undo operations are all recorded in order. When the user hits Cmd-Z, the undo manager sends the most recent undo invocation to its target.
Similarly, an operation queue is just a list of requests that can be invoked later…this also sounds like it could be a job for NSInvocation (though to be sure, blocks are also used, which is another implementation of the same pattern).
The remaining common application of Command is for sending the same method to all of the objects in a collection. You would construct an invocation for the first object, then for each object in the collection change the invocation’s target before invoking it.
Got a Concrete Example?
OK, here’s one. You can use +[NSThread detachNewThreadSelector: toObject: withTarget:] to spawn a new thread. Because every thread in an iOS application needs its own autorelease pool, you need to create an autorelease pool at the beginning of the target selector’s method and release it at the end. Without using the Command pattern, this means one or more of:
- Having a memory leak, if you can’t edit the method implementation
- Having boilerplate autorelease pool code on every method that might – sometime – be called on its own thread
- Having a wrapper method for any method that might – sometime – need to be called with or without a surrounding pool.
Sucks, huh? Let’s see if we can make that any better with NSInvocation and the Command pattern.
- (id)newResultOfAutoreleasedInvocation:(NSInvocation *)inv {
id returnValue = nil;
NSAutoreleasePool *pool = [[NSAutoreleasePool alloc] init];
[inv invoke];
if ([[inv methodSignature] methodReturnLength] > 0) {
if (strncmp([[inv methodSignature] methodReturnType],@encode(id), 1)) {
char *buffer = malloc([[inv methodSignature] methodReturnLength]);
if (buffer != NULL) {
[inv getReturnValue: buffer];
returnValue = [NSValue valueWithBytes: buffer objCType: [[inv methodSignature] methodReturnType]];
free(buffer);
}
}
else {
[inv getReturnValue: &returnValue];
}
[returnValue retain];
}
[pool release];
return returnValue;
}
Of course, we have to return a retained object, because the NSAutoreleasePool at the top of the stack when the invocation is fired off no longer exists. That’s why the method name is prefixed with “new”: it’s a hint to the analyser that the method will return a retained object.
The other trick here is the mess involving NSValue. That, believe it or not, is a convenience, so that the same method can be used to wrap invocations that have non-object return values. Of course, using NSInvocation means we’re subject to its limitations: we can’t use variadic methods or those that return a union type.
Now, for any method you want to call on a separate thread (or in an operation, or from a dispatch queue, or…) you can use this wrapper method to ensure that it has an autorelease pool in place without having to grub into the method implementation or write a specific wrapper method.
A side note on doing Objective-C properly: this method compares the result of -[NSMethodSignature methodReturnType] with a specific type using the @encode() keyword. Objective-C type encodings are documented to be C strings, and there’s even a page in the documentation listing the current values returned by @encode. It’s best not to rely on those, as Apple might choose to change or extend them in the future.
