iOS Developer Library

Developer

Foundation Framework Reference NSAutoreleasePool Class Reference

Options
Deployment Target:

On This Page

NSAutoreleasePool

Inherits From


Conforms To


Import Statement


Not Applicable

Objective-C

@import Foundation;

Availability


Available in iOS 2.0 and later

The NSAutoreleasePool class is used to support Cocoa’s reference-counted memory management system. An autorelease pool stores objects that are sent a release message when the pool itself is drained.

In a reference-counted environment (as opposed to one which uses garbage collection), an NSAutoreleasePool object contains objects that have received an autorelease message and when drained it sends a release message to each of those objects. Thus, sending autorelease instead of release to an object extends the lifetime of that object at least until the pool itself is drained (it may be longer if the object is subsequently retained). An object can be put into the same pool several times, in which case it receives a release message for each time it was put into the pool.

In a reference counted environment, Cocoa expects there to be an autorelease pool always available. If a pool is not available, autoreleased objects do not get released and you leak memory. In this situation, your program will typically log suitable warning messages.

The Application Kit creates an autorelease pool on the main thread at the beginning of every cycle of the event loop, and drains it at the end, thereby releasing any autoreleased objects generated while processing an event. If you use the Application Kit, you therefore typically don’t have to create your own pools. If your application creates a lot of temporary autoreleased objects within the event loop, however, it may be beneficial to create “local” autorelease pools to help to minimize the peak memory footprint.

You create an NSAutoreleasePool object with the usual alloc and init messages and dispose of it with drain (or release—to understand the difference, see Garbage Collection). Since you cannot retain an autorelease pool (or autorelease it—see retain and autorelease), draining a pool ultimately has the effect of deallocating it. You should always drain an autorelease pool in the same context (invocation of a method or function, or body of a loop) that it was created. See Using Autorelease Pool Blocks for more details.

Each thread (including the main thread) maintains its own stack of NSAutoreleasePool objects (see Threads). As new pools are created, they get added to the top of the stack. When pools are deallocated, they are removed from the stack. Autoreleased objects are placed into the top autorelease pool for the current thread. When a thread terminates, it automatically drains all of the autorelease pools associated with itself.

Threads

If you are making Cocoa calls outside of the Application Kit’s main thread—for example if you create a Foundation-only application or if you detach a thread—you need to create your own autorelease pool.

If your application or thread is long-lived and potentially generates a lot of autoreleased objects, you should periodically drain and create autorelease pools (like the Application Kit does on the main thread); otherwise, autoreleased objects accumulate and your memory footprint grows. If, however, your detached thread does not make Cocoa calls, you do not need to create an autorelease pool.

Garbage Collection

In a garbage-collected environment, there is no need for autorelease pools. You may, however, write a framework that is designed to work in both a garbage-collected and reference-counted environment. In this case, you can use autorelease pools to hint to the collector that collection may be appropriate. In a garbage-collected environment, sending a drain message to a pool triggers garbage collection if necessary; release, however, is a no-op. In a reference-counted environment, drain has the same effect as release. Typically, therefore, you should use drain instead of release.

  • Releases and pops the receiver.

    Declaration

    Objective-C

    - (void)release

    Discussion

    In a reference-counted environment, since an autorelease pool cannot be retained (see retain), this method causes the receiver to be deallocated. When an autorelease pool is deallocated, it sends a release message to all its autoreleased objects. If an object is added several times to the same pool, when the pool is deallocated it receives a release message for each time it was added.

    In a garbage-collected environment, this method is a no-op.

    Special Considerations

    You should typically use drain instead of release.

    See Also

    – drain

  • In a reference-counted environment, releases and pops the receiver; in a garbage-collected environment, triggers garbage collection if the memory allocated since the last collection is greater than the current threshold.

    Declaration

    Objective-C

    - (void)drain

    Discussion

    In a reference-counted environment, this method behaves the same as release. Since an autorelease pool cannot be retained (see retain), this therefore causes the receiver to be deallocated. When an autorelease pool is deallocated, it sends a release message to all its autoreleased objects. If an object is added several times to the same pool, when the pool is deallocated it receives a release message for each time it was added.

    Special Considerations

    In a garbage-collected environment, release is a no-op, so unless you do not want to give the collector a hint it is important to use drain in any code that may be compiled for a garbage-collected environment.

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in iOS 2.0 and later

  • Raises an exception.

    Declaration

    Objective-C

    - (id)autorelease

    Return Value

    self.

    Discussion

    In a reference-counted environment, this method raises an exception.

  • Raises an exception.

    Declaration

    Objective-C

    - (id)retain

    Return Value

    self.

    Discussion

    In a reference-counted environment, this method raises an exception.

  • Adds a given object to the active autorelease pool in the current thread.

    Declaration

    Objective-C

    + (void)addObject:(id)object

    Parameters

    object

    The object to add to the active autorelease pool in the current thread.

    Discussion

    The same object may be added several times to the active pool and, when the pool is deallocated, it will receive a release message for each time it was added.

    Normally you don’t invoke this method directly—you send autorelease to object instead.

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in iOS 2.0 and later

    See Also

    – addObject:

  • Adds a given object to the receiver

    Declaration

    Objective-C

    - (void)addObject:(id)object

    Parameters

    object

    The object to add to the receiver.

    Discussion

    The same object may be added several times to the same pool; when the pool is deallocated, the object will receive a release message for each time it was added.

    Normally you don’t invoke this method directly—you send autorelease to object instead.

    Import Statement

    Objective-C

    @import Foundation;

    Availability

    Available in iOS 2.0 and later

    See Also

    + addObject: