NSAutoreleasePool

NSAutoreleasePool Mac OS X 10.0

This class is used by Cocoa's memory management system to store objects that have been sent autorelease messages until the end of the current event-loop. At the end of the each pass through the event-loop the autorelease pool is deallocated, thereby releasing any objects referenced by the pool. At the beginning of each pass through the run-loop, a new instance of NSAutoreleasePool is created.

For Cocoa's memory management system to function properly there must be an autorelease pool present. If there is no autorelease pool present then your code will begin to leak memory, as objects will not be released. In this same vein, when you detach a new thread, that thread is responsible for creating its own autorelease pool. Autorelease pools are created just like any other object, using alloc and init. Multiple autorelease pools in a single thread of execution are maintained in a stack whereby objects being autoreleased are sent to the pool at the top of the stack.

The operational method of NSAutoreleasePool is addObject:, which adds the specified object to the pool, causing the object to be released when the pool is itself released. If an object is added multiple times, it will be sent a release message for each time it was added to the pool. You should never have to invoke addObject: yourself; that's the purpose of NSObject's autorelease method.

figs/cocn_1310.gif

@interface NSAutoreleasePool : NSObject
 // Class Methods
   + (void)addObject:(id)anObject;
   + (unsigned int)autoreleasedObjectCount;
   + (void)enableFreedObjectCheck:(BOOL)enable;
   + (void)enableRelease:(BOOL)enable;
   + (unsigned int)poolCountHighWaterMark;
   + (unsigned int)poolCountHighWaterResolution;
   + (void)resetTotalAutoreleasedObjects;
   + (void)setPoolCountHighWaterMark:(unsigned int)count;
   + (void)setPoolCountHighWaterResolution:(unsigned int)res;
   + (void)showPools;
   + (unsigned int)topAutoreleasePoolCount;
   + (unsigned)totalAutoreleasedObjects;
 // Instance Methods
   - (void)addObject:(id)anObject;



    Part II: API Quick Reference
    Chapter 13. Foundation Classes