1.12 Memory Management

The liveness of an object—whether or not it is referenced by other objects currently in use—is inherently a global property. This means that keeping track of object usage tempts you to breach the encapsulation and modularity of your program. There are several approaches you can use with Objective-C to help manage object lifecycles:

• Manual memory management, using the free functions provided by the Objective-C runtime

• Semi-automatic memory management, using root class reference-counting methods

• Automatic memory management, using third-party garbage collector tools

The programming tools and libraries you use may constrain you toward or away from some strategies. For example, the Cocoa class library uses reference counting; if your code uses Cocoa objects it will have to be written to manage those objects with reference counting, even if your own objects use a different mechanism.

1.12.1 Manual Memory Management

You can explicitly release the memory held by an object by calling its -free method (if it inherits from Object) or its -dealloc method (if it inherits from NSObject). It will be your responsibility to ensure that your program no longer needs the object.

In classes you write, the deallocation method should release any objects managed by the receiver, as well as any other kinds of resources (such as network sockets) the receiver holds. As with deciding to deallocate the receiver itself, it is your responsibility to ensure that your program no longer needs the objects the receiver will release. This is difficult enough that automatic management systems are becoming more prevalent.

1.12.2 Reference Counting

The Cocoa framework supports reference counting: a technique that associates with an object a count that describes how many references there are to the object in other code. When this count is positive, the object is in use; when the count reaches zero the object can be discarded and its memory reclaimed.

The count doesn't specify the users of the object. When an object has a reference count of one it means some other code uses it. If you release one object from memory but forget that it was maintaining a counted reference to another object, the runtime will never notice a discrepancy. For reference counting to be effective you must observe some conventions or design patterns when using its methods. This section gives guidelines for using the reference counting methods.

The techniques described in this section apply to objects that are used in a single thread. If you share objects between multiple threads you will have to take more care in retaining and releasing objects, and possibly create per-thread autorelease pools. Multithreaded memory management is a complex topic outside the scope of this handbook.

1.12.2.1 Maintaining an object's reference count

Cocoa provides four root class methods, -retain, -release, -autorelease, and -retainCount, for using reference counting. (They are documented in Section 1.10.) You don't have to override the methods, just inherit from NSObject and use them.

An object's reference count changes in the following ways:

• When an object is created, it starts out with a reference count of one.

• When an object receives a -retain message, its reference count is incremented by one. Call this method on an object to indicate that your code is using the object.

• When an object receives an -autorelease message, the runtime schedules a -release message to be sent when the current call stack exits. Call this method in the following situations:

  • To specify early in a method that an object may be released after the method exits, while ensuring that it will remain valid throughout the method's execution. This would be difficult to arrange manually if your method may raise an exception or has several exit points.

  • To return an object to a caller and ensure that it will not be released between the exit of a method and the resumption of the calling method (between which there may be many intervening scopes).

• When an object receives a -release message, its reference count is decremented by one. Call this method to indicate that your code is done using the object.

• The -release method also tests the reference count's value. If it is zero, the method sends the object a -dealloc message. You don't call -dealloc yourself.

These rules lead to the following rule of thumb:

The sum of the count of release and autorelease messages sent by your code to an object over its full lifetime should be one more than the number of retain messages.

(The releases outnumber the retains because an object's reference count starts at one, not zero.)

Using reference counting correctly calls for coordination when passing objects as parameters between scopes or threads. You need to know when the methods are called for you implicitly, and when to call them yourself. The following sections describe some of the most common situations and how to handle them.

1.12.2.2 Creating a new object

When you create the object yourself, by using an +alloc, -copy, or -mutableCopy method, you've already implicitly called -retain. The question then is when to release the object. Following are some common alternatives:

• You are immediately giving the object up (passing it back to a caller) and never getting it back again. Call -autorelease before returning it.

• You are storing it in a field or global. Call -release in the owning object's -dealloc method.

1.12.2.3 Receiving an object from another scope

You get an object as a parameter in a method, or from a class method whose name starts with the class name. In both cases, some other code is the owner, and may call -release based on criteria hidden from you. How you manage the object's reference depends on how you use it:

• You use the object only locally and do not expect it to become invalid. This will be the case with objects that aren't shared, for example new strings you get from NSString's method +stringWithString:. You don't need to retain or release it.

• You use the object locally, but some calls you make may indirectly cause it to be released. (For example, the owner of the object may replace it with a new object.) Call -retain and then -autorelease on the object before using it.

• You are storing it in a field or global. See the upcoming section Section 1.12.2.5.

1.12.2.4 Returning an already-stored object

You are returning a value you didn't just create, for example, in a method that returns a field (a "getter"). In this case, you have the following choices for returning the object:

• If speed is critical and you know that there is only one autorelease pool in your thread, you can return the value directly.

• A more generally safe approach is to call -retain and then -autorelease on the field, and then return it. This prevents the object from being released as a side-effect of code that executes after the getter exits but before the caller has a chance to retain it.

1.12.2.5 Replacing an already-stored object

You are provided with a new object to replace an existing one, for example, in a method that sets a field (a "setter"). There are a few equally safe solutions:

• Call -autorelease on the existing object, then retain the provided one, and assign the retained or copied value to the field.

• Compare the provided object with the existing one. If they are equal (as pointers) do nothing. Otherwise release the existing object, retain the provided one, and assign it to the field.

• Call -retain on the provided object, -release on the existing one, then assign the retained or copied value to the field.

For example, to use the third approach for a setter for a field named ownedObj, your setter will look like:

-(void )setOwnedObj :(id )newObj  {
  [newObj  retain];
  [ownedObj  release];
  ownedObj  = newObj ;
}

Don't call -copy instead of -retain in a setter. It is safe as far as memory usage goes, but prevents your caller from sharing the value; by contrast, when you use -retain a caller can copy the new object explicitly and pass the copy to the setter.

1.12.2.6 Deallocating an object

When a call to -release sets your object's reference count to zero, the -release method will also call the object's -dealloc method. In that method, you should release all other objects (e.g., fields) and resources that your object is retaining. If other code that shares those objects is retaining them (as it should), this will be safe.

You can make your -dealloc method safer in the face of outside code that may have bugs by calling -autorelease on your retained objects. This leaves the autoreleased objects still available until the current call stack finishes. However, it is probably a design mistake if code remaining in the call stack depends on these objects, and using -autorelease may just hide this rather than solve it.

1.12.2.7 Retain cycles

Reference counting can break down when there is a closed loop in the graph of object references. In this case a group of mutually referent objects may be garbage (i.e., unreachable from your program) but with positive reference counts. You don't have to avoid such structures, but make sure that you only apply the counting in one direction. When two objects refer to each other, decide which is the "owner" and let it retain the other object, but not vice versa.

1.12.3 Garbage Collection

Garbage collection is a memory management technique that fully automates the release and reuse of object memory. A garbage collector keeps track of which objects are reachable from running code; unreachable objects (those with no references, direct or indirect) are released.

The gcc compiler emits code that can be linked with the Boehm garbage collector (an open source garbage collector for C-based languages). This library augments the standard C function malloc( ) with code that sets up tracking information for object pointers, and replaces the function free( ) with an empty body. The garbage collector runs concurrently in your program, releasing objects only when they are no longer reachable by executing code. The Boehm garbage collector will even correctly deal with cycles of mutually-referring but unreachable objects.

To use the garbage collector, you download and compile it as a library for your platform, and link it with your Objective-C program. You can get the code, and instructions on how to install it, at http://www.hpl.hp.com/personal/Hans_Boehm/gc/.

Garbage collection and reference counting can't run in the same program. The Cocoa library is built around the retain/release reference counting design, so you can't use a garbage collector in Cocoa-based programs.