Up

NSAutoreleasePool class reference

Authors

Andrew Kachites McCallum (mccallum@gnu.ai.mit.edu)
Richard Frith-Macdonald (rfm@gnu.org)

Version: 35795

Date: 2012-11-15 16:34:54 +0000 (Thu, 15 Nov 2012)

Copyright: (C) 1995, 1996, 1997 Free Software Foundation, Inc.

Software documentation for the NSAutoreleasePool class

NSAutoreleasePool : NSObject

Declared in:
Foundation/NSAutoreleasePool.h
Availability: OpenStep

The standard OpenStep system of memory management employs retain counts. When an object is created, it has a retain count of 1. When an object is retained, the retain count is incremented. When it is released the retain count is decremented, and when the retain count goes to zero the object gets deallocated.

A simple retain/release mechanism has problems with passing objects from one scope to another, so it's augmented with autorelease pools. You can use the AUTORELEASE() macro to call the [NSObject -autorelease] method, which adds an object to the current autorelease pool by calling [NSAutoreleasePool +addObject:] .
An autorelease pool simply maintains a reference to each object added to it, and for each addition, the autorelease pool will call the [NSObject -release] method of the object when the pool is released. So doing an AUTORELEASE() is just the same as doing a RELEASE() , but deferred until the current autorelease pool is deallocated.

The NSAutoreleasePool class maintains a separate stack of autorelease pools objects in each thread.

When an autorelease pool is created, it is automatically added to the stack of pools in the thread.

When a pool is destroyed, it (and any pool later in the stack) is removed from the stack.

This mechanism provides a simple but controllable and reasonably efficient way of managing temporary objects. An object can be autoreleased and then passed around and used until the topmost pool in the stack is destroyed.

Most methods return objects which are either owned by autorelease pools or by the receiver of the method, so the lifetime of the returned object can be assumed to be the shorter of the lifetime of the current autorelease pool, or that of the receiver on which the method was called.
The exceptions to this are those object returned by -

[NSObject +alloc] , [NSObject +allocWithZone:]
Methods whose names begin with alloc return an uninitialised object, owned by the caller.
[NSObject -init]
Methods whose names begin with init return an initialised version of the receiving object, owned by the caller.
NB. The returned object may not actually be the same as the receiver... sometimes an init method releases the original receiver and returns an alternative.
[NSObject +new]
Methods whose names begin with new combine the effects of allocation and initialisation.
[NSObject -copy] , [<NSCopying>-copyWithZone:]
Methods whose names begin with copy create a copy of the receiver which is owned by the caller.
[NSObject -mutableCopy] , [<NSMutableCopying>-mutableCopyWithZone:]
Methods whose names begin with mutableCopy create a copy of the receiver which is owned by the caller.

Instance Variables

Method summary

addObject: 

+ (void) addObject: (id)anObj;
Availability: OpenStep

Adds anObj to the current autorelease pool.
If there is no autorelease pool in the thread, a warning is logged and the object is leaked (ie it will not be released).

allocWithZone: 

+ (id) allocWithZone: (NSZone*)zone;
Availability: OpenStep

Allocate and return an autorelease pool instance.
If there is an already-allocated NSAutoreleasePool available, save time by just returning that, rather than allocating a new one.
The pool instance becomes the current autorelease pool for this thread.

autoreleaseCountForObject: 

+ (unsigned) autoreleaseCountForObject: (id)anObject;
Availability: Not in OpenStep/MacOS-X

Counts the number of times that the specified object occurs in autorelease pools in the current thread.

This method is slow and should probably only be used for debugging purposes.


currentPool 

+ (id) currentPool;
Availability: Not in OpenStep/MacOS-X

Return the currently active autorelease pool.

enableRelease: 

+ (void) enableRelease: (BOOL)enable;
Availability: Not in OpenStep/MacOS-X

Specifies whether objects contained in autorelease pools are to be released when the pools are deallocated (by default YES ).

You can set this to NO for debugging purposes.


freeCache 

+ (void) freeCache;
Availability: Not in OpenStep/MacOS-X

When autorelease pools are deallocated, the memory they used is retained in a cache for re-use so that new polls can be created very quickly.

This method may be used to empty that cache, ensuring that the minimum memory is used by the application.


setPoolCountThreshhold: 

+ (void) setPoolCountThreshhold: (unsigned)c;
Availability: Not in OpenStep/MacOS-X

Specifies a limit to the number of objects that may be added to an autorelease pool. When this limit is reached an exception is raised.

You can set this to a smallish value to catch problems with code that autoreleases too many objects to operate efficiently.

Default value is maxint.


addObject: 

- (void) addObject: (id)anObj;
Availability: OpenStep

Adds anObj to this autorelease pool.

autorelease 

- (id) autorelease;
Availability: OpenStep

Raises an exception - pools should not be autoreleased.

autoreleaseCount 

- (unsigned) autoreleaseCount;
Availability: Not in OpenStep/MacOS-X

Return the number of objects in this pool.

drain 

- (void) drain;
Availability: MacOS-X 10.4.0

Intended to trigger a garbage collection run (if needed) when called in a garbage collected environment.
In a non-garbage collected environment, this method implements the undocumented MacOS-X behavior, and releases the receiver.

emptyPool 

- (void) emptyPool;
Availability: Not in OpenStep/MacOS-X

Empties the current pool by releasing all the autoreleased objects in it. Also destroys any child pools (ones created after the receiver in the same thread) causing any objects in those pools to be released.
This is a low cost (efficient) method which may be used to get rid of autoreleased objects in the pool, but carry on using the pool.

release 

- (oneway void) release;
Availability: OpenStep

Destroys the receiver (calls -dealloc).

retain 

- (id) retain;
Availability: OpenStep

Raises an exception... pools should not be retained.



Instance Variables for NSAutoreleasePool Class

_addImp

@protected void(* _addImp;
Availability: OpenStep

Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

_child

@protected NSAutoreleasePool* _child;
Availability: OpenStep

Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

_parent

@protected NSAutoreleasePool* _parent;
Availability: OpenStep

Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

_released

@protected struct autorelease_array_list* _released;
Availability: OpenStep

Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

_released_count

@protected unsigned int _released_count;
Availability: OpenStep

Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

_released_head

@protected struct autorelease_array_list* _released_head;
Availability: OpenStep

Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.





Up