mccallum@gnu.ai.mit.edu
)rfm@gnu.org
)Version: 1.52
Date: 2003/07/31 23:49:31
Copyright: (C) 1995, 1996, 1997 Free Software Foundation, Inc.
- Declared in:
- Foundation/NSAutoreleasePool.h
Standards:
- MacOS-X
- OpenStep
- GNUstep
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 is not very interesting
... so it's spiced up 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 -
Warning the underscore at the start of the
name of this method indicates that it is private, for
internal use only, and you should not use the
method in your code.
Destroys all the
autorelease pools in the thread. You
should not call this directly, it's called
automatically when a thread exits.
Adds the specified object 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).
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.
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.
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.
Resets (to zero) the count of autoreleased objects in the current thread.
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.
Returns the number of objects which have been
autoreleased in the current thread since the
last call to
+resetTotalAutoreleasedObjects
.
NB. This is not normally supported... enable it
as a compile time option by editing NSAutoreleasePool.m
when building the base library.
Adds the specified object to this autorelease pool.