Key–value coding lies at the basis of how outlet connections work. I said in Chapter 7 that the name of the outlet in the nib is matched to the name of an instance variable, but I waved my hands over how this matching is performed. The truth is that key–value coding is used. The name of the outlet in the nib is a string. Key–value coding turns the string into a hunt for appropriate accessors.

Suppose you have a class MyClass with an instance variable myVar, and you’ve drawn a myVar outlet from that class’s representative in the nib to an OtherClass nib object. When the nib loads, the outlet name myVar is translated to the method name setMyVar:, and your MyClass instance’s setMyVar: method, if it exists, is called with the OtherClass instance as its parameter, thus setting the value of your MyClass instance’s instance variable to the OtherClass instance (Figure 7.5).

By the same token, you should not use accessor names for methods that aren’t accessors! For example, you probably would not want MyClass to have a method called setMyVar: if it is not the accessor for myVar. If it did have such a method, it would be called when the nib loads, the OtherClass instance would be passed to it, and the OtherClass instance would not be assigned to the myVar instance variable! As a result, references in your code to myVar would be references to nil.

On the other hand, an attempt to access a nonexistent key through key–value coding will result, by default, in a crash at runtime, with an error message of this form: “This class is not key value coding-compliant for the key myKey.” The lack of quotation marks around the word after “the key” has misled many a beginner, so remember: the last word in that error message is the name of the key that gave Cocoa trouble. A common way to encounter this error message is to change the name of an instance variable so that the name of an outlet in a nib no longer matches it; at runtime, when the nib loads, Cocoa will attempt to use key–value coding to set a value in your object based on the name of the outlet, will fail (because there is no longer an instance variable or accessor by that name), and will generate this error.

A key path allows you to chain keys in a single expression. If an object is key–value coding compliant for a certain key, and if the value of that key is itself an object that is key–value coding compliant for another key, you can chain those keys by calling valueForKeyPath: and setValue:forKeyPath:. A key path string looks like a succession of key names joined with a dot (.). For example, valueForKeyPath:@"key1.key2" effectively calls valueForKey: on the message receiver, with @"key1" as the key, and then takes the object returned from that call and calls valueForKey: on that object, with @"key2" as the key.

To illustrate this shorthand, imagine that our object myObject has an instance variable theData which is an array of dictionaries such that each dictionary has a name key and a description key. I’ll show you the actual value of theData as displayed by NSLog:

(
    {
        description = "The one with glasses.";
        name = Manny;
    },
    {
        description = "Looks a little like Governor Dewey.";
        name = Moe;
    },
    {
        description = "The one without a mustache.";
        name = Jack;
    }
)

Then [myObject valueForKeyPath: @"theData.name"] returns an array consisting of the strings @"Manny", @"Moe", and @"Jack". If you don’t understand why, review what I said a few paragraphs ago about how NSArray and NSDictionary implement valueForKey:.

Key–value coding also allows an object to implement a key as if its value were an array (or a set), even if it isn’t. This is similar to what I said earlier about how accessors function as a façade, putting an instance variable name in front of hidden complexities. To illustrate, I’ll add these methods to the class of our object myObject:

- (NSUInteger) countOfPepBoys {
    return [self.theData count];
}

- (id) objectInPepBoysAtIndex: (NSUInteger) ix {
    return (self.theData)[ix];
}

By implementing countOf... and objectIn...AtIndex:, I’m telling the key–value coding system to act as if the given key (@"pepBoys" in this case) existed and were an array. An attempt to fetch the value of the key @"pepBoys" by way of key–value coding will succeed, and will return an object that can be treated as an array, though in fact it is a proxy object (an NSKeyValueArray). Thus we can now say [myObject valueForKey: @"pepBoys"] to obtain this array proxy, and we can say [myObject valueForKeyPath: @"pepBoys.name"] to get the same array of strings as before. This particular example may seem a little silly because the underlying implementation is already an array instance variable, but you can imagine an implementation whereby the result of objectInPepBoysAtIndex: is obtained through some completely different sort of operation.

The proxy object returned through this sort of façade behaves like an NSArray, not like an NSMutableArray. If you want the caller to be able to manipulate the proxy object provided by a KVC façade as if it were a mutable array, you must implement two more methods, and you must obtain a different proxy object by calling mutableArrayValueForKey:. So, for example:

- (void) insertObject: (id) val inPepBoysAtIndex: (NSUInteger) ix {
    [self.theData insertObject:val atIndex:ix];
}

- (void) removeObjectFromPepBoysAtIndex: (NSUInteger) ix {
    [self.theData removeObjectAtIndex: ix];
}

Now you can call [myObject mutableArrayValueForKey: @"pepBoys"] to obtain something that acts like a mutable array. (The true usefulness of mutableArrayValueForKey: will be clearer when we talk about key–value observing in Chapter 13.)

A complication for the programmer is that none of these methods can be looked up directly in the documentation, because they involve key names that are specific to your object. You can’t find out from the documentation what removeObjectFromPepBoysAtIndex: is for; you have to know, in some other way, that it is part of the implementation of key–value coding compliance for a key @"pepBoys" that can be obtained as a mutable array. Be sure to comment your code so that you’ll be able to understand it later. Another complication, of course, is that getting a method name wrong can cause your object not to be key–value coding compliant. Figuring out why things aren’t working as expected in a case like that can be tricky.

The reason why memory must be managed at all is that object references are pointers. As I explained in Chapter 1, the pointers themselves are simple C values (basically they are just integers) and are managed automatically, whereas what an object pointer points to is a hunk of memory that must explicitly be set aside when the object is brought into existence and that must explicitly be freed up when the object goes out of existence. We already know how the memory is set aside — that is what alloc does. But how is this memory to be freed up, and when should it happen?

At the very least, an object should certainly go out of existence when no other objects exist that have a pointer to it. An object without a pointer to it is useless; it is occupying memory, but no other object has, or can ever get, a reference to it. This is a memory leak. Many computer languages solve this problem through a policy called garbage collection. Simply put, the language prevents memory leaks by periodically sweeping through a central list of all objects and destroying those to which no pointer exists. But affixing a form of garbage collection to Objective-C would be an inappropriately expensive strategy on an iOS device, where memory is strictly limited and the processor is relatively slow (and may have only a single core). Thus, memory in iOS must be managed more or less manually.

But manual memory management is no piece of cake, because an object must go out existence neither too late nor too soon. Suppose we endow the language with the ability for one object to command that another object go out of existence now, this instant. But multiple objects can have a pointer (a reference) to the very same object. If both the object Manny and the object Moe have a pointer to the object Jack, and if Manny tells Jack to go out of existence now, poor old Moe is left with a pointer to nothing (or worse, to garbage). A pointer whose object has been destroyed behind the pointer’s back is a dangling pointer. If Moe subsequently uses that dangling pointer to send a message to the object that it thinks is there, the app will crash.

To prevent both dangling pointers and memory leakage, Objective-C and Cocoa implement a policy of manual memory management based on a number, maintained by every object, called its retain count. Other objects can increment or decrement an object’s retain count. As long as an object’s retain count is positive, the object will persist. No object has the direct power to tell another object to be destroyed; rather, as soon as an object’s retain count is decremented to zero, it is destroyed automatically.

By this policy, every object that needs Jack to persist should increment Jack’s retain count, and should decrement it once again when it no longer needs Jack to persist. As long as all objects are well-behaved in accordance with this policy, the problem of manual memory management is effectively solved:

Obviously, all of this depends upon all objects cooperating in obedience to this memory management policy. Cocoa’s objects (objects that are instances of built-in Cocoa classes) are well-behaved in this regard, but you must make sure your objects are well-behaved. Before ARC, ensuring that your objects were well-behaved was entirely up to you and your explicit code; under ARC, your objects will be well-behaved more or less automatically, provided you understand how to cooperate with ARC’s automated behavior.

An object is well-behaved with respect to memory management as long as it adheres to certain very simple rules in conformity with the basic concepts of memory management outlined in the previous section.

Before I tell you the rules, it may help if I remind you (because this is confusing to beginners) that a variable name, including an instance variable, is just a pointer. When you send a message to that pointer, you are really sending a message through that pointer, to the object to which it points. The rules for memory management are rules about objects, not names, references, or pointers. You cannot increment or decrement the retain count of a pointer; there is no such thing. The memory occupied by the pointer is managed automatically (and is tiny). Memory management is concerned with the object to which the pointer points.

(That is why I’ve referred to my example objects by proper names — Manny, Moe, and Jack — and not by variable names. The question of who has retained Jack has nothing to do with the name by which any particular object refers to Jack.)

The two things are easily confused, especially because — as I’ve often pointed out in earlier chapters — the variable name pointing to an object is so often treated as the object that there is a tendency to think that it is the object. It’s clumsy, in fact, to distinguish the name from the object it points to. But in discussing memory management, I’ll try to maintain that distinction.

Here, then, are the golden rules of Cocoa memory management:

A general way of understanding the golden rules of Cocoa memory management is to think in terms of ownership. If Manny has said alloc, retain, or copy with regard to Jack, Manny has asserted ownership of Jack. More than one object can own Jack at once, but each such object is responsible only for managing its own ownership of Jack correctly. It is the responsibility of an owner of Jack eventually to release Jack, and a nonowner of Jack must never release Jack. As long as all objects that ever take ownership of Jack behave this way, Jack will not leak nor will any pointer to Jack be left dangling.

Now, under ARC, as I shall explain presently in more detail, these rules remain exactly the same, but they are obeyed for you in an automated fashion by the compiler. In an ARC-based app, you never say retain or release — in fact, you’re not allowed to. Instead, the compiler says retain or release for you, using exactly the principles you would have had to use if you had said them (the golden rules of Cocoa memory management)! Since the compiler is smarter (or at least more ruthlessly tenacious) than you are about this sort of nit-picky rule-based behavior, it won’t make any of the mistakes you might have made due to carelessness or confusion.

The moment an object is released, there is a chance it will be destroyed. Before ARC, this fact was a big worry for programmers. In a non-ARC program, you must take care not to send any messages subsequently through any pointer to an object that has been destroyed — including the pointer you just used to release the object. In effect, you’ve just turned your own pointer into a possible dangling pointer! If there is any danger that you might accidentally attempt to use this dangling pointer, a wise policy is to nilify the pointer — that is, to set the pointer itself to nil. A message to nil has no effect, so if you do send a message through that pointer, it won’t do any good, but at least it won’t do any harm (kind of like chicken soup).

In an ARC-based program, this policy, too, is strictly followed: ARC will nilify for you any pointer to whose object it has just sent the last balancing release message (meaning that the object might now have gone out of existence). Since, as I mentioned in Chapter 3, ARC also sets an instance pointer to nil when you declare it (if you don’t initialize it yourself, there and then, to point to an actual instance), there follows as the night the day the following delightful corollary: under ARC, every instance pointer either points to an actual instance or is nil. This fact alone should send you rushing to convert all your existing non-ARC apps to ARC if you possibly can.

When you create a new Xcode project and choose an application template, a checkbox in the second dialog lets you elect to Use Automatic Reference Counting. Automatic Reference Counting is ARC. If this checkbox is checked, then (among other things):

It is also possible to convert an existing non-ARC project to ARC; choose Edit → Refactor → Convert to Objective-C ARC for assistance with the necessary code changes. You do not have to adopt ARC for an entire project; if you have old non-ARC code, possibly written by someone else, you may wish to incorporate that code into your ARC-based project without substantially altering the non-ARC code. To do so, confine all non-ARC code to its own files, and for each of those files, edit the target, switch to the Build Phases tab, and in the Compile Sources section, double-click the non-ARC file’s listing and type -fno-objc-arc in the box (to enter it in the Compiler Flags column).

When you compile an ARC-based project, the compiler will treat any explicit retain or release commands as an error, and will instead, behind the scenes, insert its own commands that effectively do the exact same work as retain and release commands. Your code is thus manually memory-managed, in conformity with the principles and golden rules of manual memory management that I’ve already described, but the author of the manual memory-management code is the compiler (and the memory-management code itself is invisible, unless you feel like reading assembly language).

ARC does its work of inserting retain and release commands in two stages:

So, for example, consider the following code:

- (void) myMethod {
    NSArray* myArray = [NSArray array];
    NSArray* myOtherArray = myArray;
}

Now, in actual fact, no additional memory management code is needed here (for reasons that I’ll clarify in the next section). But in its first pass, we may imagine that ARC will behave very, very conservatively: it will ensure that every variable is nil or points to an object, and it will retain every value as it is assigned to a variable, at the same time releasing the value previously pointed to by the variable being assigned to, on the assumption that it previously retained that value when assigning it to that variable as well. So we may imagine (though this is unlikely to be exactly correct) a scenario where ARC compiles that code at first into the equivalent of Example 12.1.

- (void) myMethod {
    // create all new object pointers as nil
    NSArray* myArray = nil;
    // retain as you assign, release the previous value
    id temp1 = myArray;
    myArray = [NSArray array];
    [myArray retain];
    [temp1 release]; // (no effect, it's nil)
    // create all new object pointers as nil
    NSArray* myOtherArray = nil;
    // retain as you assign, release the previous value
    id temp2 = myOtherArray;
    myOtherArray = myArray;
    [myOtherArray retain];
    [temp2 release]; // (no effect, it's nil)
    // method is ending, balance out retains on local variables
    [myArray release];
    myArray = nil;
    [myOtherArray release];
    myOtherArray = nil;
}

The ARC optimizer will then come along and reduce the amount of work being done here. For example, it may observe that myArray and myOtherArray turn out to be pointers to the same object, so it may therefore remove some of the intermediate retains and releases. And it may observe that there’s no need to send release to nil. But retains and releases are so efficient under ARC that it wouldn’t much matter if the optimizer didn’t remove any of the intermediate retains and releases.

But there’s more to the manual memory management balancing act than matching retain and release: in particular, I said earlier that alloc and copy yielded objects whose retain count had already been incremented, so that they, too, must be balanced by release. In order to obey this part of the golden rules of Cocoa memory management, ARC resorts to assumptions about how methods are named. This means that you had better conform, in your code, to the same assumptions about how methods are named, or you can accidentally cause ARC to do the wrong things (although, as it turns out, there are ways out of this predicament if you have a wrongly-named method whose name you absolutely can’t change).

In particular, when your code receives an object as the returned value of a method call, ARC looks at the opening word (or words) of the camelCased method name. (The term camelCased describes a compound word whose individual words are demarcated by internal capitalization, like the words “camel” and “Cased” in the word “camelCased.”) If the opening word of the name of that method is alloc, init, new, copy, or mutableCopy, ARC assumes that the object it returns comes with an incremented retain count that will need to be balanced with a corresponding release.

So, in the preceding example, if the array had been received from a call to [NSArray new] instead of [NSArray array], ARC would know that an extra release will be needed, to balance the incremented retain count of the object returned from a method whose name begins with new.

Your own responsibility in this regard, then, is not to name any of your methods inappropriately in such a way as to set off that sort of alarm bell in ARC’s head. The easiest approach is not to start any of your own method names with alloc, init (unless you’re writing an initializer, of course), new, copy, or mutableCopy. Doing so might not cause any damage, but it is better not to take the risk: obey the ARC naming conventions if you possibly can.

Built-in Cocoa objects will take ownership of objects you hand them, by retaining them, if it makes sense for them to do so. (Indeed, this is so generally true that if a Cocoa object is not going to retain an object you hand it, there will be a note to that effect in the documentation.) Thus, you don’t need to worry about managing memory for an object if the only thing you’re going to do with it is hand it over to a Cocoa object.

A good example is an NSArray. Consider the following minimal example:

NSString* s = [[NSDate date] description];
NSArray* arr = [NSArray arrayWithObject: s];

When you hand the string to the array, the array retains the string. As long as the array exists and the string is in the array, the string will exist. When the array goes out of existence, if the string is still in the array, the array will also release the string; if no other object is retaining the string, the string will then go out of existence in good order, without leaking, and all will be well. All of this is right and proper; the array could hardly “contain” the string without taking ownership of it.

An NSMutableArray works the same way, with additions. When you add an object to an NSMutableArray, the array retains it. When you remove an object from an NSMutableArray, the array releases it. Again, the array is always doing the right thing.

Thus you should stay out of, and not worry yourself about, memory management for objects you don’t own; the right thing will happen all by itself. For instance, look back at Example 10.2. Here it is again:

NSString* f = [[NSBundle mainBundle] pathForResource:@"index" ofType:@"txt"];
NSError* err = nil;
NSString* s = [NSString stringWithContentsOfFile:f
                                        encoding:NSUTF8StringEncoding
                                           error:&err];
// error-checking omitted
NSMutableDictionary* d = [NSMutableDictionary dictionary];
for (NSString* line in [s componentsSeparatedByString:@"\n"]) {
    NSArray* items = [line componentsSeparatedByString:@"\t"];
    NSInteger chnum = [items[0] integerValue];
    NSNumber* key = @(chnum);
    NSMutableArray* marr = d[key];
    if (!marr) { // no such key, create key–value pair
        marr = [NSMutableArray array];
        d[key] = marr;
    }
    // marr is now a mutable array, empty or otherwise
    NSString* picname = items[1];
    [marr addObject: picname];
}

No explicit memory management is happening here, and no additional memory management needs to happen (even if you aren’t using ARC). We’re generating a lot of objects, but never do we say alloc (or copy), so we have no ownership, and memory management is therefore not our concern. Moreover, no bad thing is going to happen between one line and the next while this code is running. The mutable dictionary d, for example, generated by calling [NSMutableDictionary dictionary], is not going to vanish mysteriously before we can finish adding objects to it. (I’ll say a bit more, later in this chapter, about why I’m so confident of this.)

On the other hand, it is possible (if you aren’t using ARC) to be tripped up by how Cocoa objects manage memory. Consider the following:

NSString* s = myMutableArray[0];
[myMutableArray removeObjectAtIndex: 0]; // bad idea! (but just fine under ARC)

Here we remove a string from an array, keeping a reference to it ourselves as s. But, as I just said, when you remove an object from an NSMutableArray, the array releases it. So the commented line of code in the previous example involves an implicit release of the string in question, and if this reduces the string’s retain count to zero, it will be destroyed. In effect, we’ve just done the thing I warned you about earlier: we’ve turned our own pointer s into a possible dangling pointer, and a crash may be in our future when we try to use it as if it were a string.

The way to ensure against such possible destruction in non-ARC code is to retain the object before doing anything that might destroy it (Example 12.2).

NSString* s = myMutableArray[0];
[s retain]; // this is non-ARC code
[myMutableArray removeObjectAtIndex: 0];

Of course, now you have made management of this object your business; you have asserted ownership of it, and must make sure that this retain is eventually balanced by a subsequent release, or the string object may leak.

However, the very same code works perfectly under ARC:

NSString* s = myMutableArray[0];
[myMutableArray removeObjectAtIndex: 0]; // Just fine under ARC

The reason is that, as I mentioned earlier, ARC is insanely conservative at the outset. Just as in Example 12.1, ARC retains on assignment, so we may imagine that ARC will operate according to something like the imaginary scenario shown in Example 12.3.

NSString* s = nil;
// retain as you assign, release the previous value
id temp = s;
s = myMutableArray[0];
[s retain];
[temp release]; // (no effect, it's nil)
// and now this move is safe
[myMutableArray removeObjectAtIndex: 0];
// ... and later ...
[s release];
s = nil;

This turns out to be exactly the right thing to do! When the call to removeObjectAtIndex: comes along, the retain count of the object received from the array is still incremented, exactly as in our non-ARC Example 12.2.

When you call a method and receive as a result what Chapter 5 calls a ready-made instance, how does memory management work? Consider, for example, this code:

NSArray* myArray = [NSArray array];

According to the golden rules of memory management, the object now pointed to by myArray doesn’t need memory management. You didn’t say alloc in order to get it, so you haven’t claimed ownership of it and you don’t need to release it (and shouldn’t do so). But how is this possible? How is the NSArray class able to vend an array that you don’t have to release without also leaking that object?

If you don’t see why this is mysterious, pretend that you are NSArray. How would you implement the array method so as to generate an array that the caller doesn’t have to memory-manage? Don’t say that you’d just call some other NSArray method that vends a ready-made instance; that merely pushes the same problem back one level. You are NSArray. Sooner or later, you must somehow supply this magical instance. Ultimately you will have to generate the instance from scratch, and then how will you manage its memory? You can’t do it like this:

- (NSArray*) array {
    NSArray* arr = [[NSArray alloc] init];
    return arr; // hmmm, not so fast...
}

This, it appears, can’t work. On the one hand, we generated arr’s value by saying alloc. This means we must release the object pointed to by arr. On the other hand, when are we going to do this? If we do it just before returning arr, arr will be pointing to garbage and we will be vending garbage. We cannot do it just after returning arr, because our method exits when we say return. This is a puzzle. It is our job, if we are to be a good Cocoa citizen and follow the golden rules of memory management, to decrement the retain count of this object. We need a way to vend this object without decrementing its retain count now (so that it stays in existence long enough for the caller to receive and work with it), yet ensure that we will decrement its retain count (to balance our alloc call and fulfill our own management of this object’s memory).

The solution, which is explicit in pre-ARC code, is autorelease:

- (NSArray*) array {
    NSArray* arr = [[NSArray alloc] init];
    [arr autorelease];
    return arr;
}

Or, because autorelease returns the object to which it sent, we can condense that:

- (NSArray*) array {
    NSArray* arr = [[NSArray alloc] init];
    return [arr autorelease];
}

Here’s how autorelease works. Your code runs in the presence of something called an autorelease pool. (If you look in main.m, you can actually see an autorelease pool being created.) When you send autorelease to an object, that object is placed in the autorelease pool, and a number is incremented saying how many times this object has been placed in this autorelease pool. From time to time, when nothing else is going on, the autorelease pool is automatically drained. This means that the autorelease pool sends release to each of its objects, the same number of times as that object was placed in this autorelease pool, and empties itself of all objects. If that causes an object’s retain count to be zero, fine; the object is destroyed in the usual way. So autorelease is just like release — effectively, it is a form of release — but with a proviso, “later, not right this second.”

You don’t need to know exactly when the current autorelease pool will be drained; indeed, you can’t know (unless you force it, as we shall see). The important thing is that in a case like our method array, there will be plenty of time for whoever called array to retain the vended object if desired.

The vended object in a case like our method array is called an autoreleased object. The object that is doing the vending has in fact completed its memory management of the vended object. The vended object thus potentially has a zero retain count. But it doesn’t have a zero retain count just yet. The vended object is not going to vanish right this second, just after your call to [NSArray array], because your code is still running and so the autorelease pool is not going to be drained right this second. The recipient of such an object needs to bear in mind that this object may be autoreleased. The object won’t vanish while the code that called the method that vended the object is running, but if the receiving object wants to be sure that the vended object will persist later on, it should retain it.

This explains why there’s no explicit memory management in Example 10.2 (cited earlier in this chapter): we don’t madly retain every object we obtain in that code, even in non-ARC code, because those objects will all persist long enough for our code to finish. This fits with the golden rules of memory management. An object you receive by means other than those listed among the golden rules as asserting ownership (alloc or copy) isn’t under your ownership. The object will either be owned and retained by some other persistent object, in which case it won’t vanish while the other object persists, or it will be independent but autoreleased, in which case it will at least persist while your code continues to run. If you want it to persist and you’re afraid it might not, you should take ownership of it by retaining it.

Under ARC, as you might expect, all the right things happen of their own accord. You don’t have to say autorelease, and indeed you cannot. Instead, ARC will say it for you. And it says it in accordance with the method naming rule I described earlier. A method called array, for example, does not start with a camelCase unit new, init, alloc, copy, or mutableCopy. Therefore it must return an object whose memory management is balanced, using autorelease for the last release. ARC will see to it that this is indeed the case. On the other side of the ledger, the method that called array and received an array in return must assume that this object is autoreleased and could go out of existence if we don’t retain it. That’s exactly what ARC does assume.

Sometimes you may wish to drain the autorelease pool immediately. Consider the following:

for (NSString* aWord in myArray) {
    NSString* lowerAndShorter = [[aWord lowercaseString] substringFromIndex:1];
    [myMutableArray addObject: lowerAndShorter];
}

Every time through that loop, two objects are added to the autorelease pool: the lowercase version of the string we start with, and the shortened version of that. The first object, the lowercase version of the string, is purely an intermediate object: as the current iteration of the loop ends, no one except the autorelease pool has a pointer to it. If this loop had very many repetitions, or if these intermediate objects were themselves very large in size, this could add up to a lot of memory. These intermediate objects will all be released when the autorelease pool drains, so they are not leaking; nevertheless, they are accumulating in memory, and in certain cases there could be a danger that we will run out of memory before the autorelease pool drains. The problem can be even more acute than you know, because you might repeatedly call a built-in Cocoa method that itself accumulates a lot of intermediate objects.

The solution is to intervene in the autorelease pool mechanism by supplying your own autorelease pool. This works because the autorelease pool used to store an autoreleased object is the most recently created pool. So you can just create an autorelease pool at the top of the loop and drain it at the bottom of the loop, each time through the loop. In modern Objective-C, the notation for doing this is to surround the code that is to run under its own autorelease pool with the directive @autoreleasepool{}, like this:

for (NSString* aWord in myArray) {
    @autoreleasepool {
        NSString* lowerAndShorter =
            [[aWord lowercaseString] substringFromIndex:1];
        [myMutableArray addObject: lowerAndShorter];
    }
}

Many classes provide the programmer with two equivalent ways to obtain an object: either an autoreleased object or an object that you create yourself with alloc and some form of init. So, for example, NSArray supplies both the class method arrayWithObjects: and the instance method initWithObjects:. Which should you use? Before ARC, Apple stated that they would prefer you to lean toward initWithObjects:. In general, where you can generate an object with alloc and some form of init, they’d like you to do so. That way, you are in charge of releasing the object. This policy prevents your objects from hanging around in the autorelease pool and keeps your use of memory as low as possible. Under ARC, I still tend to adhere to this policy from force of habit, but in fact the ARC autorelease pool architecture is so efficient that the old policy may no longer provide any advantage.

Before ARC, the main place for the programmer to make a memory management mistake was with respect to instance variables. Memory management of temporary variables within a single method is pretty easy; you can see the whole method at once, so now just follow the golden rules of memory management, balancing every retain, alloc, or copy with a release (or, if you’re returning an object with an incremented retain count, autorelease). But instance variables make things complicated, for many reasons:

To see what I mean, return once more to Example 10.2. As I have already explained, there was no need to worry about memory management during this code, even without ARC. We have a mutable dictionary d, which we acquired as a ready-made instance by calling [NSMutableDictionary dictionary], and it isn’t going to vanish while we’re working with it. Now, however, suppose that in the next line we propose to assign d to an instance variable of ours:

self->_theData = d; // in non-ARC code this would be a bad idea!

Before ARC, that code constituted a serious potential mistake. If our code now comes to a stop, we’re left with a persistent pointer to an object over which we have never asserted ownership; it might vanish, leaving us with a dangling pointer. The solution, obviously, is to retain this object as we assign it to our instance variable. You could do it like this:

[d retain];
self->_theData = d;

Or you could do it like this:

self->_theData = d;
[self->_theData retain];

Or, because retain returns the object to which it sent, you could actually do it like this:

self->_theData = [d retain];

So which should you use? Probably none of them. Consider what a lot of trouble it will be if you ever want to assign a different value to self->_theData. You’re going to have to remember to release the object already pointed to (to balance the retain you’ve used here), and you’re going to have to remember to retain the next value as well. It would be much better to encapsulate memory management for this instance variable in an accessor (a setter). That way, as long as you always pass through the accessor, memory will be managed correctly. A standard template for such an accessor might look like Example 12.4.

- (void) setTheData: (NSMutableArray*) value {
    if (self->_theData != value) {
        [self->_theData release];
        self->_theData = [value retain];
    }
}

In Example 12.4, we release the object currently pointed to by our instance variable (and if that object is nil, no harm done) and retain the incoming value before assigning it to our instance variable (and if that value is nil, no harm done either). The test for whether the incoming value is the very same object already pointed to by our instance variable is not just to save a step; it’s because if we were to release that object, it could vanish then and there, instantly turning value into a dangling pointer — which we would then, horribly, assign to self->_theData.

The setter accessor now manages memory correctly for us; provided we always use it to set our instance variable, all will be well. This is one of the main reasons why accessors are so important! So the assignment to the instance variable in our original code should now look like this:

[self setTheData: d];

Observe that we can also use this setter subsequently to release the value of the instance variable and nilify the instance variable itself, thus preventing a dangling pointer, all in a single easy step:

[self setTheData: nil];

So there’s yet another benefit of using an accessor to manage memory.

Our memory management for this instance variable is still incomplete, however. We (meaning the object whose instance variable this is) must also remember to release the object pointed to by this instance variable at the last minute before we ourselves go out of existence. Otherwise, if this instance variable points to a retained object, there will be a memory leak. The “last minute” is typically dealloc, the NSObject method (Chapter 10) that is called as an object goes out of existence.

In dealloc, there is no need to use accessors to refer to an instance variable, and in fact it’s not a good idea to do so, because you never know what other side effects an accessor might have. And (under non-ARC code) you must always call super last of all. So here’s our implementation of this object’s dealloc:

- (void) dealloc {
    [self->_theData release];
    [super dealloc];
}

That completes the memory management for one instance variable. In general, if you are not using ARC, you will need to make sure that every object of yours has a dealloc that releases every instance variable whose value has been retained. This, obviously, is one more very good opportunity for you to make a mistake.

Just as it’s not a good idea to use your own accessors to refer to your own instance variable in dealloc, so you should not use your own accessors to refer to your own instance variables in an initializer (see Chapter 5). The reason is in part that the object is not yet fully formed, and in part that an accessor can have other side effects. Instead, you will set your instance variables directly, but you must also remember to manage memory.

To illustrate, I’ll rewrite the example initializer from Chapter 5 (Example 5.3). This time I’ll allow our object (a Dog) to be initialized with a name. The reason I didn’t discuss this possibility in Chapter 5 is that a string is an object whose memory must be managed! So, imagine now that we have an instance variable _name whose value is an NSString, and we want an initializer that allows the caller to pass in a value for this instance variable. It might look like Example 12.5.

- (id) initWithName: (NSString*) s {
    self = [super init];
    if (self) {
        self->_name = [s retain];
    }
    return self;
}

Actually, it is more likely in the case of an NSString that you would copy it rather than merely retain it. The reason is that NSString has a mutable subclass NSMutableString, so some other object might call initWithName: and hand you a mutable string to which it still holds a reference — and then mutate it, thus changing this Dog’s name behind your back. So the initializer would look like Example 12.6.

- (id) initWithName: (NSString*) s {
    self = [super init];
    if (self) {
        self->_name = [s copy];
    }
    return self;
}

In Example 12.6, we don’t bother to release the existing value of _name; it is certainly not pointing to any previous value (because there is no previous value), so there’s no point.

Thus, memory management for an instance variable may take place in as many as three places: the initializer, the setter, and dealloc. This is a common architecture. It is a lot of work, and a common source of error, having to look in multiple places to check that you are managing memory consistently and correctly, but that’s what you must do if you aren’t using ARC (though, as I’ll point out later in this chapter, Objective-C has the ability to write your accessors for you).

If you’re using ARC, ARC will manage your instance variable memory for you; you needn’t (and, by and large, you can’t) do it for yourself. By default, ARC will treat an instance variable the same way it treats any variable: on assignment to that instance variable, it creates a temporary variable, retains the assigned value in it, releases the current value of the instance variable, and performs the assignment. Thus, you write this code:

self->_theData = d; // an NSMutableDictionary

ARC, in effect, in accordance with its rule that it retains on assignment and releases the old value, substitutes something like this scenario:

// imaginary scenario: retain on assignment, release the previous value
id temp = self->_theData;
self->_theData = d;
[self->_theData retain];
[temp release];

This is exactly the right thing to have happened; in fact, it will not have escaped your attention that it is virtually the same code you would have written for a formal accessor such as Example 12.4. So much for worrying about release and retain on assignment! If you did want to write a setter, it might consist of no more than a direct assignment:

- (void) setTheData: (NSMutableArray*) value {
    self->_theData = value;
}

Moreover, when your object goes out of existence, ARC releases its retained instance variable values. So much for worrying about releasing in dealloc! You may still need, under ARC, to implement dealloc for other reasons — for example, it could still be the right place to unregister for a notification (Chapter 11) — but you won’t call release on any instance variables there, and you won’t call super. At the time dealloc is called, your instance variables have not yet been released, so it’s fine to refer to them in dealloc.

At this point you may be imagining that, under ARC, you might be able to live without any accessors at all: instead, you can just assign directly to your instance variables and all the right memory-management things will happen, so who needs a formal setter? However, a formal accessor, as I’ll explain later, can do things above and beyond ARC’s automated insertion of release-and-retain, such as copying instead of retaining, dealing with multithreading, and adding your own custom behaviors. Also, obviously, accessors can be made public and so available to other objects, whereas an instance variable is not public.

You may be wondering about ARC’s implications for the way you’ll write an initializer that involves setting object instance variable values, as in Example 12.5 and Example 12.6. The code for these initializers will be just the same under ARC as under non-ARC, except that you needn’t (and can’t) say retain. So Example 12.5 under ARC would look like Example 12.7.

- (id) initWithName: (NSString*) s {
    self = [super init];
    if (self) {
        self->_name = s;
    }
    return self;
}

Example 12.6 under ARC will be unchanged, as shown in Example 12.8; you can still say copy under ARC, and ARC understands how to manage the memory of an object returned from a method whose camelCased name starts with (or simply is) copy.

- (id) initWithName: (NSString*) s {
    self = [super init];
    if (self) {
        self->_name = [s copy];
    }
    return self;
}

ARC’s behavior is automatic and mindless; it knows nothing of the logic of the relationships between objects in your app. Sometimes, you have to provide ARC with further instructions to prevent it from doing something detrimental. Typically, this detrimental thing will be the creation of a retain cycle.

A retain cycle is a situation in which object A and object B are each retaining one another. This can arise quite innocently, because relationships in an object graph can run both ways. For example, in a system of orders and items, an order needs to know what its items are and an item might need to know what orders it is a part of, so you might be tempted to let it be the case both that an order retains its items and that an item retains its orders. That’s a retain cycle, with object A (an order) retaining object B (an item) and vice versa. Such a situation, if allowed to persist, will result in a leak of both objects, as neither object’s retain count can decrement to zero. Another way of looking it is to say that object A, by retaining object B, is also retaining itself, and thus preventing its own destruction.

To illustrate the problem, I’ll suppose a simple class MyClass with a single ivar _thing and a single public setter setThing:, with logging in dealloc, like this:

@implementation MyClass {
    id _thing;
}

- (void) setThing: (id) what {
    self->_thing = what;
}

-(void)dealloc {
    NSLog(@"%@", @"dealloc");
}
@end

We now run this code:

MyClass* m1 = [MyClass new];
MyClass* m2 = [MyClass new];
m1.thing = m2;
m2.thing = m1;

Under ARC, unless you take steps to the contrary, this will be a retain cycle; by default, m1 and m2 are now retaining one another, because by default, ARC retains on assignment. When the code runs, dealloc is never called for either of our MyClass instances. They have leaked.

You can prevent an instance variable from retaining the object assigned to it by specifying that the instance variable should be a weak reference. You can do this with the __weak qualifier in the instance variable’s declaration:

@implementation MyClass {
    __weak id _thing;
}

Now there is no retain cycle. In our example, since both m1 and m2 exist only as automatic variables in the scope of the code that creates them, they will both go out of existence instantly when that code comes to an end and ARC releases them both (to balance the new calls that created them).

In real life, a weak reference is most commonly used to connect an object to its delegate (Chapter 11). A delegate is an independent entity; there is usually no reason why an object needs to claim ownership of its delegate. The object should have no role in the persistence of its delegate; and it could even be that the delegate might for some reason retain the object, causing a retain cycle. Therefore, most delegates should be declared as weak references. For example, in an ARC project created from Xcode’s Utility Application project template, you’ll find this line:

@property (weak, nonatomic) id <FlipsideViewControllerDelegate> delegate;

(The delegate may also be tagged as an IBOutlet.) The keyword weak in the property declaration, as I’ll explain more fully later in this chapter, is equivalent to declaring the _delegate instance variable as __weak.

In non-ARC code, a reference can be prevented from causing a retain cycle merely by not retaining when assigning to that reference; the reference isn’t memory-managed at all. You will see this referred to as a weak reference; it is not, however, quite the same thing as an ARC weak reference. A non-ARC weak reference risks turning into a dangling pointer when the instance to which it points is released. Thus it is possible for the reference to be non-nil and pointing to garbage, so that a message sent to it can have mysteriously disastrous consequences. Amazingly, however, this cannot happen with an ARC weak reference: the instance to which it points can be released and have its retain count reach zero and vanish, but when it does, any ARC weak reference that was pointing to it is set to nil! This amazing feat is accomplished by some behind-the-scenes bookkeeping: when an object is assigned to a weak reference, ARC in effect notes this fact on a scratchpad list. When the object is released, ARC consults the scratchpad list and discovers the existence of the weak reference to it, and assigns nil to that weak reference. This is yet another reason for preferring to use ARC wherever possible! ARC sometimes refers to non-ARC weak references, disdainfully but accurately, as “unsafe.” (Non-ARC weak references are in fact the __unsafe_unretained references I mentioned a moment ago.)

Unfortunately, large parts of Cocoa don’t use ARC. Most properties of built-in Cocoa classes that keep weak references are non-ARC weak references (because they are old and backwards-compatible, whereas ARC is new). Such properties are declared using the keyword assign. For example, UINavigationController’s delegate property is declared like this:

@property(nonatomic, assign) id<UINavigationControllerDelegate> delegate

This means that if you assign some object to a UINavigationController as its delegate, and if that object is about to go out of existence at a time when this UINavigationController still exists, you have a duty (regardless of whether you’re using ARC) to set that UINavigationController’s delegate property to some other object, or to nil; otherwise, it might try to send a message to its delegate at some future time, when the object no longer exists and its delegate property is a dangling pointer, and the app will then crash — and, since this happens at some future time, figuring out the cause of the crash can be quite difficult. (This is the sort of situation in which you might need to turn on zombies in order to debug, as described earlier in this chapter.)

NSNotificationCenter presents some curious memory management features. As you are likely to want to use notifications (Chapter 11), you’ll need to know about these.

If you registered with the notification center using addObserver:selector:name:​object:, you handed the notification center a reference to yourself as the first argument; the notification center’s reference to you is a non-ARC weak reference, and there is a danger that after you go out of existence the notification center will try to send a notification to whatever is referred to, which, if it isn’t you (because you no longer exist), will be garbage. That is why you must unregister yourself before you go out of existence. By unregistering yourself, you remove the notification center’s reference to you, so there’s no chance it will ever again try to send you a notification. This is similar to the situation with delegates that I was talking about a moment ago.

If you registered with the notification center using addObserverForName:object:​queue:usingBlock:, memory management can be quite tricky, under ARC in particular. Here are the key facts to know:

Consider, for example, this code, in which we register for a fictitious notification:

self->_observer = [[NSNotificationCenter defaultCenter]
    addObserverForName:@"heyho"
    object:nil queue:nil usingBlock:^(NSNotification *n) {
        NSLog(@"%@", self);
    }];

Our intention is eventually to unregister the observer; that’s why we’re keeping a reference to it:

[[NSNotificationCenter defaultCenter] removeObserver:self->_observer];

But there are two problems:

In effect, we have retained ourselves twice, once by virtue of being registered with the notification center, and again by virtue of retaining the observer token. I will present three solutions to this problem, in what I take to be the order of increasing goodness:

How can you prevent the block from retaining self? You use a technique demonstrated in Apple’s WWDC 2011 videos, commonly called “the weak–strong dance” (Example 12.9).

__weak MyClass* wself = self; ❶
self->observer = [[NSNotificationCenter defaultCenter]
    addObserverForName:@"heyho"
    object:nil queue:nil usingBlock:^(NSNotification *n) {
        MyClass* sself = wself; ❷
        if (sself) {
            NSLog(@"%@", sself); ❸
        }
    }];

The weak–strong dance works like this:

The weak–strong dance may seem elaborate, but it’s worth learning to do. It is, as I said, the only one of the three proposed solutions that allows dealloc to be called before you unregister the observer. Thus, it is the only solution that allows you to unregister the observer in your dealloc implementation, which is typically just where you’d prefer to do it.

Another unusual case is NSTimer (Chapter 10). The NSTimer class documentation says that “run loops retain their timers”; it then says of scheduledTimerWithTimeInterval:target:selector:userInfo:repeats: that “The target object is retained by the timer and released when the timer is invalidated.” This means that as long as a repeating timer has not been invalidated, the target is being retained by the run loop; the only way to stop this is to send the invalidate message to the timer. (With a non-repeating timer, the problem doesn’t arise, because the timer invalidates itself immediately after firing.)

When you called scheduledTimerWithTimeInterval:target:selector:userInfo:repeats:, you probably supplied self as the target: argument. This means that you (self) are being retained, and cannot go out of existence until you invalidate the timer. You can’t do this in your dealloc implementation, because as long as the timer is repeating and has not been sent the invalidate message, dealloc won’t be called. You therefore need to find another appropriate moment for sending invalidate to the timer. There’s no good way out of this situation; you simply have to find such a moment, and that’s that.

A block-based alternative to a timer is available through GCD. The timer “object” is a dispatch_source_t, and must be retained, typically as an instance variable (which ARC will manage for you, even though it’s a pseudo-object). The timer will fire repeatedly after you initially “resume” it, and will stop firing when it is released, typically by nilifying the instance variable. But you must still take precautions to prevent the timer’s block from retaining self and causing a retain cycle, just as with notification observers. Here’s some typical skeleton code:

@implementation OtherViewController {
    dispatch_source_t _timer; // ARC will manage this pseudo-object
}

- (IBAction)doStart:(id)sender {
    self->_timer = dispatch_source_create(
        DISPATCH_SOURCE_TYPE_TIMER,0,0,dispatch_get_main_queue());
    dispatch_source_set_timer(
        self->_timer, dispatch_walltime(NULL, 0),
        1 * NSEC_PER_SEC, 0.1 * NSEC_PER_SEC);
    dispatch_source_set_event_handler(self->_timer, ^{
        NSLog(@"%@", self); // retain cycle
    });
    dispatch_resume(self->_timer);
}

- (IBAction)doStop:(id)sender {
    self->_timer = nil;
}

-(void)viewWillDisappear:(BOOL)animated {
    [super viewWillDisappear:animated];
    self->_timer = nil; // break retain cycle
}
@end

In general, you must be on the lookout for Cocoa objects with unusual memory management behavior. Such behavior will usually be called out clearly in the documentation. For example, the UIWebView documentation warns: “Before releasing an instance of UIWebView for which you have set a delegate, you must first set its delegate property to nil.” And a CAAnimation object retains its delegate; this is exceptional and can cause trouble if you’re not conscious of it.

There are also situations where the documentation fails to warn of any special memory management considerations, but ARC itself will warn of a possible retain cycle due to the use of self in a block. Again, the weak–strong dance is likely to be your best defense. An example is the completion handler of UIPageViewController’s instance method setViewControllers:direction:animated:completion:, where the compiler will warn, “Capturing ‘self’ strongly in this block is likely to lead to a retain cycle.” Using the weak–strong dance, you capture self weakly instead.

On iOS, when a nib loads, the top-level nib objects that it instantiates are autoreleased. So if someone doesn’t retain them, they’ll quickly vanish in a puff of smoke. There are two primary strategies for preventing that from happening:

Figure 12.1. An outlet graph with retain

Objects in the nib that are not top-level objects are already part of a memory management object graph, so there’s no need for you to retain them directly. For example, if you have a top-level UIView in the nib, and it contains a UIButton, the UIButton is the UIView’s subview — and a view retains its subviews and takes ownership of them. Thus, it is sufficient to manage the UIView’s memory and to let the UIView manage the UIButton. If you have an outlet to this button, you typically don’t have to retain the button, because it is retained by the UIView as long as the UIButton is inside it (though you would want to retain the button in the rare case where you are planning at some point in your code to remove the button from its superview while keeping it on hand for later use).

In C, and therefore in Objective-C, it is permitted to declare a variable outside of any method. K&R (Chapter 1) calls this an external variable (see K&R 4.3); I call it a global variable. It is common practice, though not strictly required, to qualify such a variable’s declaration as static; such qualification is a technical matter of scope and has no effect on the variable’s persistence or its global nature.

Global variables are a C variable type, defined at file level; they know nothing of instances. Insofar as they have any relation to object-based programming, they may be defined in a class file so they are effectively class-level variables.

In Objective-C code, a global variable is not uncommonly used as a constant. You can sometimes initialize it as you declare it:

NSString* g_myString = @"my string";

If the value you want to assign to a global isn’t itself a constant, you’ll have to assign the value in actual code; the question is then where to put that code. Since a global variable is effectively a class-level variable, it makes sense to initialize it early in the lifetime of the class, namely in initialize (see Chapter 11).

The upshot is that a global variable is a class-level value and thus persists for the lifetime of the program. It has no memory management connected with instances, because it itself is not connected with instances. Thus in some sense it leaks, but deliberately so, in the same innocuous sense that a class object leaks.

On the other hand, you might have to use a tiny bit of explicit memory management in order to initialize a global variable in the first place. For example, suppose you’re not using ARC and you initialize a global variable in initialize to an autoreleased value. Clearly you’ll have to retain it, or it will just vanish out from under you. But you’ll never bother to release it; there’s no need, and no place where it would make sense to do so.

A number of Cocoa methods take an optional parameter typed as void*, and often called context:. You might think that void*, the universal pointer type, would be the same as id, the universal object type, because a reference to an object is a pointer. But an id is a universal object type; void* is just a C pointer. This means that Cocoa won’t treat this value as an object. So the use of the void* type is a clue to you that Cocoa won’t do any memory management on this value. Thus, making sure that it persists long enough to be useful is up to you.

The big change wrought by ARC in this regard has to do, not with memory management, but with “crossing the bridge” between an id and a void*. Before ARC, these two types were treated as equivalent, in the sense that you could supply one where the other was expected. But ARC is not so sanguine. ARC manages memory for objects only. Thus, it manages memory for something typed as id, but not for something typed as void*. Therefore, if you want to use an object where a void* is expected, or a void* where an object is expected, you must reassure ARC that you know what you’re doing.

When an object comes into existence by instantiation under ARC, it is memory-managed by ARC from birth to death, as it were. But when an object is cast to a void*, it passes out of the realm of ARC memory management, and ARC will not let go without more information, because it doesn’t understand what its memory management responsibilities should be at this moment. Similarly, when a non-object (a void*) is cast to an object type, it passes ready-made into the realm of ARC memory management, and ARC will not accept it without more information.

When you pass value in as a context: argument, your purpose is to get it back out again later; it’s an identifier, or a carrier of extra information or data. For example, when you pass a context: value as you send addObserver:forKeyPath:options:context: to some object (see on key–value observing in Chapter 13), this is so that you can obtain that same value when Cocoa later sends observe⁠Value⁠For⁠Key⁠Path:⁠of⁠Ob⁠ject:​change:⁠con⁠text: back to you. Cocoa isn’t going to retain the value for you, but on the other hand the value needs to exist only as long as you are likely to be called back in this way.

Thus it will make the most sense if you simply keep a reference to that value and manage its memory through that reference. The context: value itself is just a pointer. As a result, as the context: argument passes out of ARC’s purview, and later as it passes back in again, ARC has no memory management responsibilities: you just want ARC to permit the cast. The way to indicate this is to cast the value explicitly, with a __bridge qualifier.

For example, let’s say that you write this:

[someObject addObserver:self forKeyPath:@"yoho"
    options:0 context:myContext];

Before ARC, that code was legal. Under ARC, it isn’t; the compiler will stop you in your tracks with this complaint: “Implicit conversion of Objective-C pointer type ‘id’ to C pointer type ‘void *’ requires a bridged cast.” So you supply the bridged cast:

[someObject addObserver:self forKeyPath:@"yoho"
    options:0 context:(__bridge void*) myContext];

Later, when the context comes back to you in a callback, you’ll cast it back to a __bridge id so that ARC will accept it and you can continue treating it as an object.

This leaves only the question of how to manage the memory of the object that’s being handed back and forth as the context: argument. All this is happening in different methods, and the object must persist through all of them. Clearly the most sensible solution is to maintain the object through an instance variable. Under ARC, in particular, this is a lightweight approach; the object will be memory-managed with no particular effort on your part. It may persist even after it is no longer needed, but it won’t actually leak. The situation is only slightly more complicated if you’ve more than one context object to manage simultaneously; for example, you could store them all in a collection, such as an NSMutableSet instance variable.

Considerations of this sort do not apply to parameters that are typed as objects. For instance, when you call postNotificationName:object:userInfo:, the userInfo is typed as an NSDictionary and is retained for you by the notification center (and released after the notification is posted); its memory management behind the scenes is not your concern.

A CFTypeRef (see Chapter 3) is a value obtained through a C function that is a pointer to a struct; its type name will usually end in “Ref”. It is a kind of object, even though it isn’t a full-fledged Cocoa Objective-C object, and it must be managed in much the same way as a Cocoa object. ARC is irrelevant to this fact. ARC manages Objective-C objects; it has no concern with CFTypeRefs. You must manage the memory of CFTypeRefs manually, even if you’re using ARC. Indeed, as I shall explain, the fact that you are using ARC actually increases the degree of your memory management responsibility.

I will divide the discussion into two halves: memory management of CFTypeRefs on their own, and what happens when you “cross the bridge” between a CFTypeRef and a full-fledged Objective-C object type.

Just as, in the Objective-C world of objects, certain method names (alloc, copy, and retain) alert you to your memory management responsibilities, so too in the world of CFTypeRefs. The golden rule here is that if you obtained such an object through a function whose name contains the word Create or Copy, you are responsible for releasing it. In the case of a Core Foundation object (its type name begins with CF), you’ll release it with the CFRelease function; other object creation functions are paired with their own object release functions.

The matter is not a complicated one; it’s much simpler than memory management of Cocoa objects, and the documentation will usually give you a hint about your memory management responsibilities. As an example, here (without further explanation) is some actual code from one of my apps, strongly modeled on Apple’s own example code, in which I set up a base pattern color space (for drawing with a pattern):

- (void) addPattern: (CGContextRef) context color: (CGColorRef) incolor {
    CGColorSpaceRef baseSpace = CGColorSpaceCreateDeviceRGB();
    CGColorSpaceRef patternSpace = CGColorSpaceCreatePattern(baseSpace);
    CGContextSetFillColorSpace(context, patternSpace);
    CGColorSpaceRelease(patternSpace);
    CGColorSpaceRelease(baseSpace);
    // ...
}

Never mind exactly what that code does; the important thing here is that the values for baseSpace and patternSpace are a CFTypeRef (in particular, a CGColorSpaceRef) obtained through functions with Create in their name, so after we’re done using them, we release them with the corresponding release function (here, CGColorSpaceRelease).

Similarly, you can retain a Core Foundation object, if you are afraid that it might go out of existence while you still need it, with the CFRetain function, and you are then, once again, responsible for releasing it with the CFRelease function.

We now come to the business of “crossing the bridge.” As I explained in Chapter 3, many Core Foundation object types are toll-free bridged with a corresponding Cocoa object type. Now, from a theoretical point of view, memory management is memory management: it makes no difference whether you use Core Foundation memory management or Cocoa memory management. Thus, if you obtain a CFStringRef through a Create or Copy function and assign it to an NSString variable, sending release to it through the NSString variable is just as good as calling CFRelease on it as a CFStringRef. And before ARC, that was the end of the matter.

Under ARC, however, we face the same problem I described in the preceding section. ARC manages memory for Objective-C objects; it knows nothing of CFTypeRefs. Therefore, ARC is not going to let you hand an object into or out of its memory-management purview without explicit information about how to manage its memory. This means a little extra thought for you, but it’s a good thing, because it means you can tell ARC to do automatically what you would have done manually.

For example, a moment ago I said that, before ARC, you might obtain a CFStringRef through a Create or Copy function, cast it to an NSString, and later send release to it through the NSString. Under ARC, you can’t say release, but you can arrange for ARC to do exactly the same thing: as you “cross the bridge”, you pass the CFString through the CFBridgingRelease function. The result is an id that can be assigned to an NSString variable, and that ARC will release to balance out the incremented retain count generated by the original Create or Copy function.

You have three choices as you cross the toll-free bridge:

You may see __bridge_transfer and __bridge_retained in code written by other people, but I strongly recommend that you stick to CFBridgingRelease and CFBridgingRetain in your own code, as they are eminently clearer (and better named). Note that it is perfectly possible to pass an object out of the object world with CFBridgingRetain and back into it later with CFBridgingRelease.

The possible memory management policies correspond simply to what has already been said in this chapter about the ARC reference types and how a setter might behave:

As I’ve already said, a property’s declared memory management policy is an instruction to the compiler if the setter is synthesized. If the setter is not synthesized, the declared memory management policy is “purely conventional” (as the LLVM documentation puts it), meaning that if you write your own setter, you’d better make that setter behave the way you declared you would, but nothing is going to force you to do so.

We come now to the formal syntax for declaring a property. A property is declared in the same part of a class’s interface section where you would declare methods. Its syntax schema is as follows:

@property (attribute, attribute, ...) type name;

Here’s a real example, for the NSMutableArray instance variable we were talking about a moment ago:

@property (nonatomic, strong) NSMutableArray* theData;

The type and name will usually match the type and name of an instance variable, but what you’re really indicating here are the name of the property (as used in dot-notation) and the default names of the setter (here, setTheData:) and getter (here, theData), and the type of value to be passed to the setter and obtained from the getter.

If this property will be represented by an outlet in a nib, you can say IBOutlet before the type. This is a hint to Xcode and has no formal meaning.

The type doesn’t have to be an object type; it can be a simple type such as BOOL, CGFloat, or CGSize. Of course in that case no memory management is performed (as none is needed), and no memory management policy should be declared; but the advantages of using a property remain — the accessors can be synthesized and the instance variable declared automatically.

The possible attribute values are:

To make a property declaration private, put it in a class extension (Chapter 10). Most commonly, the class extension will be at the top of the implementation (.m) file, before the implementation section. As a result, this class can use the property or call the accessors but other classes cannot (Example 12.10).

// MyClass.m:
@interface MyClass ()
@property (nonatomic, strong) NSMutableArray* theData; // private
@end

@implementation MyClass
// other code goes here
@end

Being able to declare private properties is so useful that I find myself routinely adding a class extension to the top of any new class files (if the Xcode project template hasn’t done it for me), to make it easy to add private properties later if I need to. Note that knowledge of private properties is not inherited by subclasses; an elegant solution is to move the class extension interface section off into an isolated .h file of its own and import that into the implementation files of both the superclass and the subclass.

Another reason to put a property declaration in a class extension is so as to redeclare the property. For example, we might want our property to be readonly as far as the rest of the world knows, but readwrite for code within our class. To implement this, declare the property readonly in the interface section in the header file, which the rest of the world sees, and then redeclare it, not as readonly (in which case it will be readwrite by default), in the class extension in the implementation file, which only this class sees. All other attributes must match between both declarations.

A property declaration can also appear in a protocol or category declaration. This makes sense because, with a property declaration, you’re really just declaring accessor methods, and these are places where method declarations can go.

To request explicitly that the accessors be synthesized for you, use the @synthesize directive. It appears anywhere inside the class’s implementation section, any number of times, and takes a comma-separated list of property names. The behavior and names of the synthesized accessors will accord with the property declaration attributes I’ve just talked about. You can state that the synthesized accessors should access an instance variable whose name differs from the property name by using the syntax propertyName=ivarName in the property name list; otherwise, the instance variable will have the same name as the property. As I mentioned earlier, you don’t have to declare the instance variable; it will be declared for you automatically as part of accessor synthesis.

Thus, having declared a property theData, to request explicitly that accessors be synthesized, you’d say this in the implementation section:

@synthesize theData;

The result is that any accessors you don’t write (theData and setTheData:, unless you changed these names in the property declaration) will be written for you behind the scenes, and if you didn’t declare an instance variable theData, it will be declared for you.

The name of the automatically declared instance variable is likely to be important to you, because you’re probably going to need to access the instance variable directly, especially in an initializer (and in dealloc if you’re not using ARC), as well as in any accessors that you write yourself.

Starting in the Xcode 4.2 application templates, Apple began following a convention where a synthesized accessor would take advantage of the propertyName=ivarName syntax to give the instance variable a name different from that of the property in that the former was prefixed with an underscore. For example, the AppDelegate class’s implementation section contained this line:

@synthesize window = _window;

The evident value of following this naming convention is that we can refer in our code to the property explicitly as self.window, but if we were accidentally to refer to the instance variable directly as window, we’d get a compilation error, because there is no instance variable window (it’s called _window). The convention thus prevents accidental direct access to the instance variable without passing through the accessors, as well as just distinguishing clearly in code which names are instance variables — they’re the ones prefixed with an underscore. Moreover, this policy frees up the property name (here, window) to be used as a local variable in a method, without getting a warning from the compiler that we’re overshadowing the name of an instance variable.

Autosynthesis follows the same naming policy. If you omit the @synthesize directive, the automatically generated name of the automatically declared instance variable is the name of the property prefixed with an underscore. For example, a declared property called theData will result in an instance variable called _theData. If for some reason that isn’t what you want, then use the @synthesize directive explicitly. Remember, if you do so, that if you don’t specify the instance variable name explicitly, the default instance variable name will be the same as the property name, without any underscore.

Regardless of whether you explicitly include a @synthesize directive or you take advantage of autosynthesis, you are permitted to write one or both accessors yourself. Synthesis means that any accessors you don’t provide will be provided for you. If you use autosynthesis (no @synthesize directive) and you provide both accessors, you won’t get any automatically declared instance variable. This is a very sensible policy: you’ve surrendered your chance to dictate the instance variable’s name in the @synthesize directive, but you’re also taking complete manual control of your accessors, so you’re given complete manual control of your instance variable as well.

A useful trick is to take advantage of the @synthesize syntax propertyName=ivarName to override the synthesized accessor without losing any of its functionality. What I mean is this. Suppose you want the setter for _myIvar to do more than just set _myIvar. One possibility is to write your own setter; however, writing a setter from scratch is tedious and error-prone, whereas a synthesized setter does the job correctly and writing it is no work at all. The solution is to declare a property myIvar along with a corresponding private property (Example 12.10) — let’s call it myIvarAlias — and synthesize the private property myIvarAlias to access the _myIvar instance variable. You must then write the accessors for myIvar by hand, but all they need to do, at a minimum, is use the myIvarAlias properties to set and get the value of _myIvar respectively. The key point is that you can also do other stuff in those accessors (Example 12.11); whoever gets or sets the property myIvar will be doing that other stuff.

// In the header file:
@interface MyClass : NSObject
@property (nonatomic, strong) NSNumber* myIvar;
@end

// In the implementation file:
@interface MyClass ()
@property (nonatomic, strong) NSNumber* myIvarAlias;
@end

@implementation MyClass
@synthesize myIvarAlias=_myIvar;
- (void) setMyIvar: (NSNumber*) num {
    // do other stuff here
    self.myIvarAlias = num;
}
- (NSNumber*) myIvar {
    // do other stuff here
    return self.myIvarAlias;
}
@end

Instead of writing your own accessors or providing a @synthesize directive or using autosynthesis, you can accompany a property declaration with a @dynamic directive (in the implementation section). This tells the compiler that even though it doesn’t see any implementation of any accessors for this property, and even though it isn’t going to provide the accessors for you, it should permit the property declaration anyway, on the grounds that at runtime, when a call to one of the accessors arrives, your code will somehow magically handle it in some way that the compiler can’t grasp. Basically, you’re suppressing the compiler’s warning system; it just gives up and stands aside, and leaves you to hang yourself at runtime.

This is a rare but not unheard-of thing to do. It arises chiefly in two contexts: when defining your own animatable view property (Chapter 17), and when using managed object properties in Core Data (Chapter 36). In both of those situations, you harness the power of Cocoa to perform the magic handling of the accessor calls; you don’t know precisely how Cocoa performs this magic, and you don’t care.

But what if you wanted to perform this magic yourself? To put it another way, what sort of magic might Cocoa be using in those two limited situations? The answer lies in the power of Objective-C’s dynamic messaging. This is an advanced topic, but it’s so cool that I’ll show you an example anyway.

I propose to write a class that declares properties name (an NSString) and number (an NSNumber) but that has no accessor methods for name or number and that doesn’t use accessor synthesis. Instead, in our interface section we declare these properties dynamic. Since we’re not getting any help from synthesis, we must also declare the instance variables ourselves:

// the interface section declares properties "name" and "number"
@implementation MyClass {
    NSString* _name;
    NSNumber* _number;
}
@dynamic name, number;
// ...insert magic here...
@end

I can think of a couple of ways to concoct the necessary magic; in this example, I’m going to take advantage of a little-known NSObject class method called resolveInstanceMethod:. Recall that sending a message to an object is not the same as calling that method in that object; there are some additional steps, if that method is not found in that object, to resolve the method. One of the first of these steps, the first time a given message arrives and is found to have no corresponding method in the object’s class, is that the runtime looks for an implementation of resolveInstanceMethod in that class. If it finds it, it calls it, handing it the selector for the message that is giving us difficulty. resolveInstanceMethod: then returns a BOOL; a YES answer means, “Don’t worry, I’ve got it covered; go ahead and call that method.”

How can resolveInstanceMethod: possibly say this? What could it do, if the method doesn’t exist, to make it possible to call that method? Well, it could create that method. Objective-C is so dynamic that there’s a way to do this. And remember, resolveInstanceMethod: is called just once per method, so once it has created a method and returned YES, the problem is solved forever after for that method.

To create a method in real time, we call the class_addMethod function. (This will require importing <objc/runtime.h>.) It takes four parameters:

In our example we have four methods to cover (the two accessors for the two dynamic properties) — name, setName:, number, and setNumber:. So in order to call class_addMethod in resolveInstanceMethod:, we will also have to have written C functions to act as the IMP for each of those methods. Now, we could just write four C functions — but that would be pointless! If we were going to do that, why are we going to all the trouble of using a dynamic accessor? Instead, I propose to write just two C functions, one to handle any getter that we may care to direct at it, and one to handle any setter that we may care to direct at it.

Let’s take the getter first, as it is much the simpler case. What must a generalized getter do? It must access the corresponding instance variable. And what’s the name of the corresponding instance variable? Well, the way we’ve set things up, it’s the name of the method with an underscore prefixed to it. So, we grab the name of the method (which we can do because it has arrived as the selector, the second parameter to this function), stick an underscore on the front, and return the value of the instance variable whose name we’ve just derived. To make life simple, I’ll obtain the value of that instance variable using key–value coding; the presence of the underscore means that this won’t result in any circularity (that is, our function won’t end up calling itself in an infinite recursion):

id callValueForKey(id self, SEL _cmd) {
    NSString* key = NSStringFromSelector(_cmd);
    key = [@"_" stringByAppendingString:key];
    return [self valueForKey:key];
}

Now that we’ve done that, we can see how to write the setter. It’s just a matter of doing a slightly more elaborate manipulation of the selector’s name in order to get the name of the instance variable. We must pull the set off the front and the colon off the end, and make sure the first letter is lowercase — and then we prefix the underscore, just as before:

void callSetValueForKey(id self, SEL _cmd, id value) {
    NSString* key = NSStringFromSelector(_cmd);
    key = [key substringWithRange:NSMakeRange(3, [key length]-4)];
    NSString* firstCharLower =
        [[key substringWithRange:NSMakeRange(0,1)] lowercaseString];
    key = [key stringByReplacingCharactersInRange:NSMakeRange(0,1)
                                       withString:firstCharLower];
    key = [@"_" stringByAppendingString:key];
    [self setValue:value forKey:key];
}

Finally, we’re ready to write resolveInstanceMethod:. In my implementation, I’ve used this method as a gatekeeper, explicitly checking that the method to be called is an accessor for one of our dynamic properties:

+ (BOOL) resolveInstanceMethod: (SEL) sel {
    // this method will be called
    if (sel == @selector(setName:) || sel == @selector(setNumber:)) {
        class_addMethod([self class], sel, (IMP) callSetValueForKey, "v@:@");
        return YES;
    }
    if (sel == @selector(name) || sel == @selector(number)) {
        class_addMethod([self class], sel, (IMP) callValueForKey, "@@:");
        return YES;
    }
    return [super resolveInstanceMethod:sel];
}

You’ll just have to trust me on the encoded C string in the fourth argument to class_addMethod; if you don’t, read the documentation to see what it means. My overall implementation here is simple-minded — in particular, my use of key–value coding is sort of an easy way out, and I’ve failed to grapple with the need for copy semantics in the NSString setter — but it’s quite general, and gives you a peek under the Objective-C hood.