gnustep/libs-base
0
0
Fork 0
mirror of https://github.com/gnustep/libs-base.git synced 2025-04-25 01:31:08 +00:00
Code Issues Projects Releases Packages Wiki Activity

Documentation improvements.

Browse source 
git-svn-id: svn+ssh://svn.gna.org/svn/gnustep/libs/base/trunk@19326 72102866-910b-0410-8b05-ffd578937521
This commit is contained in:
Richard Frith-Macdonald 2004-05-14 16:22:49 +00:00
parent a9d2de97c1
commit d0a274bd0d
3 changed files with 217 additions and 223 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

4
ChangeLog
View file

@ -1,6 +1,10 @@
2004-05-14 Richard Frith-Macdonald <rfm@gnu.org>
* Tools/autogsdoc.m: Create output directories if necessary.
* Headers/Foundation/NSAutoreleasePool.h: Rationalised a little
Moved documentation from source code.
* Source/NSAutoreleasePool.m: Rationalised a little
Moved documentation to headers.
2004-05-14 Richard Frith-Macdonald <rfm@gnu.org>

201
Headers/Foundation/NSAutoreleasePool.h
View file

@ -69,6 +69,85 @@ typedef struct autorelease_array_list
} array_list_struct;
/**
* <p>
* 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.
* </p>
* <p>
* 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:].<br />
* 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.
* </p>
* <p>
* The NSAutoreleasePool class maintains a separate stack of
* autorelease pools objects in each thread.
* </p>
* <p>
* When an autorelease pool is created, it is automatically
* added to the stack of pools in the thread.
* </p>
* <p>
* When a pool is destroyed, it (and any pool later in
* the stack) is removed from the stack.
* </p>
* <p>
* 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.
* </p>
* <p>
* 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.<br />
* The exceptions to this are those object returned by -
* </p>
* <deflist>
* <term>[NSObject+alloc], [NSObject+allocWithZone:]</term>
* <desc>
* Methods whose names begin with alloc return an uninitialised
* object, owned by the caller.
* </desc>
* <term>[NSObject-init]</term>
* <desc>
* Methods whose names begin with init return an initialised
* version of the receiving object, owned by the caller.<br />
* NB. The returned object may not actualy be the same as the
* receiver ... sometimes an init method releases the original
* receiver and returns an alternative.
* </desc>
* <term>[NSObject+new]</term>
* <desc>
* Methods whose names begin with new combine the effects of
* allocation and initialisation.
* </desc>
* <term>[NSObject-copy], [(NSCopying)-copyWithZone:]</term>
* <desc>
* Methods whose names begin with copy create a copy of the receiver
* which is owned by the caller.
* </desc>
* <term>[NSObject-mutableCopy], [(NSMutableCopying)-mutableCopyWithZone:]</term>
* <desc>
* Methods whose names begin with mutableCopy create a copy of the receiver
* which is owned by the caller.
* </desc>
* </deflist>
*/
@interface NSAutoreleasePool : NSObject
{
/* For re-setting the current pool when we are dealloc'ed. */
@ -85,22 +164,120 @@ typedef struct autorelease_array_list
void (*_addImp)(id, SEL, id);
}
/**
* Adds anObj to the current autorelease pool.<br />
* If there is no autorelease pool in the thread,
* a warning is logged and the object is leaked (ie it will not be released).
*/
+ (void) addObject: (id)anObj;
/**
* Allocate and return an autorelease pool instance.<br />
* If there is an already-allocated NSAutoreleasePool available,
* save time by just returning that, rather than allocating a new one.<br />
* The pool instance becomes the current autorelease pool for this thread.
*/
+ (id) allocWithZone: (NSZone*)zone;
/**
* Adds anObj to this autorelease pool.
*/
- (void) addObject: (id)anObj;
#ifndef NO_GNUSTEP
+ (void) enableRelease: (BOOL)enable;
+ (void) freeCache; /* Free cache of unused pools in this thread. */
+ (void) setPoolCountThreshhold: (unsigned)c;
+ (unsigned) autoreleaseCountForObject: (id)anObject;
+ (void) _endThread: (NSThread*)thread; /* Don't call this directly. */
/*
* The next two methods have no effect unless you define COUNT_ALL to be
* 1 in NSAutoreleasepool.m - doing so incurs a thread lookup overhead
* each time an object is autoreleased.
/**
* Raises an exception - pools should not be autoreleased.
*/
+ (void) resetTotalAutoreleasedObjects;
+ (unsigned) totalAutoreleasedObjects;
- (id) autorelease;
/**
* Destroys the receiver (calls -dealloc).
*/
- (oneway void) release;
/**
* Raises an exception ... pools should not be retained.
*/
- (id) retain;
#ifndef NO_GNUSTEP
/**
* <p>
* Counts the number of times that the specified object occurs
* in autorelease pools in the current thread.
* </p>
* <p>
* This method is <em>slow</em> and should probably only be
* used for debugging purposes.
* </p>
*/
+ (unsigned) autoreleaseCountForObject: (id)anObject;
/**
* Return the currently active autorelease pool.
*/
+ (id) currentPool;
/**
* <p>
* Specifies whether objects contained in autorelease pools are to
* be released when the pools are deallocated (by default YES).
* </p>
* <p>
* You can set this to NO for debugging purposes.
* </p>
*/
+ (void) enableRelease: (BOOL)enable;
/**
* <p>
* 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.
* </p>
* <p>
* This method may be used to empty that cache, ensuring that
* the minimum memory is used by the application.
* </p>
*/
+ (void) freeCache;
/**
* <p>
* 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.
* </p>
* <p>
* You can set this to a smallish value to catch problems with code
* that autoreleases too many objects to operate efficiently.
* </p>
* <p>
* Default value is maxint.
* </p>
*/
+ (void) setPoolCountThreshhold: (unsigned)c;
/**
* Destroys all the autorelease pools in the thread.<br />
* You should not call this directly, it's called automatically
* when a thread exits.
*/
+ (void) _endThread: (NSThread*)thread;
/**
* Return the number of objects in this pool.
*/
- (unsigned) autoreleaseCount;
/**
* 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.<br />
* 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.
*/
- (void) emptyPool;
#endif
@end

235
Source/NSAutoreleasePool.m
View file

@ -33,11 +33,6 @@
#include "Foundation/NSZone.h"
#include <limits.h>
/*
* Set to 1 to count all autoreleases
*/
#define COUNT_ALL 0
/* When this is `NO', autoreleased objects are never actually recorded
in an NSAutoreleasePool, and are not sent a `release' message.
Thus memory for objects use grows, and grows, and... */
@ -56,10 +51,7 @@ static unsigned pool_count_warning_threshhold = UINT_MAX;
@interface NSAutoreleasePool (Private)
- (id) _parentAutoreleasePool;
- (unsigned) autoreleaseCount;
- (unsigned) autoreleaseCountForObject: (id)anObject;
+ (unsigned) autoreleaseCountForObject: (id)anObject;
+ (id) currentPool;
- (void) _reallyDealloc;
- (void) _setChildPool: (id)pool;
@end
@ -120,84 +112,6 @@ pop_pool_from_cache (struct autorelease_thread_vars *tv)
}
/**
* <p>
* 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.
* </p>
* <p>
* 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:].<br />
* 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.
* </p>
* <p>
* The NSAutoreleasePool class maintains a separate stack of
* autorelease pools objects in each thread.
* </p>
* <p>
* When an autorelease pool is created, it is automatically
* added to the stack of pools in the thread.
* </p>
* <p>
* When a pool is destroyed, it (and any pool later in
* the stack) is removed from the stack.
* </p>
* <p>
* 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.
* </p>
* <p>
* 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.<br />
* The exceptions to this are those object returned by -
* </p>
* <deflist>
* <term>[NSObject+alloc], [NSObject+allocWithZone:]</term>
* <desc>
* Methods whose names begin with alloc return an uninitialised
* object, owned by the caller.
* </desc>
* <term>[NSObject-init]</term>
* <desc>
* Methods whose names begin with init return an initialised
* version of the receiving object, owned by the caller.<br />
* NB. The returned object may not actualy be the same as the
* receiver ... sometimes an init method releases the original
* receiver and returns an alternative.
* </desc>
* <term>[NSObject+new]</term>
* <desc>
* Methods whose names begin with new combine the effects of
* allocation and initialisation.
* </desc>
* <term>[NSObject-copy], [(NSCopying)-copyWithZone:]</term>
* <desc>
* Methods whose names begin with copy create a copy of the receiver
* which is owned by the caller.
* </desc>
* <term>[NSObject-mutableCopy], [(NSMutableCopying)-mutableCopyWithZone:]</term>
* <desc>
* Methods whose names begin with mutableCopy create a copy of the receiver
* which is owned by the caller.
* </desc>
* </deflist>
*/
@implementation NSAutoreleasePool
static IMP allocImp;
@ -212,11 +126,6 @@ static IMP initImp;
}
}
/**
* Allocate and return an autorelease pool instance.<br />
* If there is an already-allocated NSAutoreleasePool available,
* save time by just returning that, rather than allocating a new one.
*/
+ (id) allocWithZone: (NSZone*)zone
{
struct autorelease_thread_vars *tv = ARP_THREAD_VARS;
@ -284,9 +193,6 @@ static IMP initImp;
return _parent;
}
/*
* Return the number of objects in this pool.
*/
- (unsigned) autoreleaseCount
{
unsigned count = 0;
@ -299,16 +205,6 @@ static IMP initImp;
return count;
}
/**
* <p>
* Counts the number of times that the specified object occurs
* in autorelease pools in the current thread.
* </p>
* <p>
* This method is <em>slow</em> and should probably only be
* used for debugging purposes.
* </p>
*/
- (unsigned) autoreleaseCountForObject: (id)anObject
{
unsigned count = 0;
@ -325,16 +221,6 @@ static IMP initImp;
return count;
}
/**
* <p>
* Counts the number of times that the specified object occurs
* in autorelease pools in the current thread.
* </p>
* <p>
* This method is <em>slow</em> and should probably only be
* used for debugging purposes.
* </p>
*/
+ (unsigned) autoreleaseCountForObject: (id)anObject
{
unsigned count = 0;
@ -347,19 +233,11 @@ static IMP initImp;
return count;
}
/**
* Return the currently active autorelease pool.
*/
+ (id) currentPool
{
return ARP_THREAD_VARS->current_pool;
}
/**
* 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).
*/
+ (void) addObject: (id)anObj
{
NSAutoreleasePool *pool = ARP_THREAD_VARS->current_pool;
@ -386,9 +264,6 @@ static IMP initImp;
}
}
/**
* Adds the specified object to this autorelease pool.
*/
- (void) addObject: (id)anObj
{
/* If the global, static variable AUTORELEASE_ENABLED is not set,
@ -430,19 +305,10 @@ static IMP initImp;
_released->objects[_released->count] = anObj;
(_released->count)++;
#if COUNT_ALL
/* Keep track of the total number of objects autoreleased across all
pools. */
ARP_THREAD_VARS->total_objects_count++;
#endif
/* Keep track of the total number of objects autoreleased in this pool */
_released_count++;
}
/**
* Raises an exception ... pools should not be retained.
*/
- (id) retain
{
[NSException raise: NSGenericException
@ -450,9 +316,6 @@ static IMP initImp;
return self;
}
/**
* Destroys the receiver (calls -dealloc).
*/
- (oneway void) release
{
[self dealloc];
@ -484,19 +347,6 @@ static IMP initImp;
for (i = 0; i < released->count; i++)
{
id anObject = released->objects[i];
#if 0
/* There is no general method to find out whether a memory
chunk has been deallocated or not, especially when
custom zone functions might be used. So we #if this
out. */
if (!NSZoneMemInUse(anObject))
[NSException
raise: NSGenericException
format: @"Autoreleasing deallocated object.\n"
@"Suggest you debug after setting [NSObject "
@"enableDoubleReleaseCheck:YES]\n"
@"to check for release errors."];
#endif
released->objects[i] = nil;
[anObject release];
}
@ -521,6 +371,30 @@ static IMP initImp;
}
}
- (void) emptyPool
{
struct autorelease_array_list *released;
unsigned int i;
if (_child)
{
[_child dealloc];
}
released = _released_head;
while (released)
{
for (i = 0; i < released->count; i++)
{
id anObject = released->objects[i];
released->objects[i] = nil;
[anObject release];
}
released->count = 0;
released = released->next;
}
}
- (void) _reallyDealloc
{
struct autorelease_array_list *a;
@ -533,9 +407,6 @@ static IMP initImp;
[super dealloc];
}
/**
* Raises an exception - pools should not be autoreleased.
*/
- (id) autorelease
{
[NSException raise: NSGenericException
@ -543,11 +414,6 @@ static IMP initImp;
return self;
}
/**
* Destroys all the autorelease pools in the thread.
* You should not call this directly, it's called automatically
* when a thread exits.
*/
+ (void) _endThread: (NSThread*)thread
{
struct autorelease_thread_vars *tv;
@ -564,69 +430,16 @@ static IMP initImp;
free_pool_cache(tv);
}
/**
* Resets (to zero) the count of autoreleased objects in the current thread.
*/
+ (void) resetTotalAutoreleasedObjects
{
ARP_THREAD_VARS->total_objects_count = 0;
}
/**
* Returns the number of objects which have been autoreleased in the
* current thread since the last call to +resetTotalAutoreleasedObjects.<br />
* NB. This is not normally supported ... enable it as a compile time option
* by editing NSAutoreleasePool.m when building the base library.
*/
+ (unsigned) totalAutoreleasedObjects
{
return ARP_THREAD_VARS->total_objects_count;
}
/**
* <p>
* Specifies whether objects contained in autorelease pools are to
* be released when the pools are deallocated (by default YES).
* </p>
* <p>
* You can set this to NO for debugging purposes.
* </p>
*/
+ (void) enableRelease: (BOOL)enable
{
autorelease_enabled = enable;
}
/**
* <p>
* 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.
* </p>
* <p>
* This method may be used to empty that cache, ensuring that
* the minimum memory is used by the application.
* </p>
*/
+ (void) freeCache
{
free_pool_cache(ARP_THREAD_VARS);
}
/**
* <p>
* 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.
* </p>
* <p>
* You can set this to a smallish value to catch problems with code
* that autoreleases too many objects to operate efficiently.
* </p>
* <p>
* Default value is maxint.
* </p>
*/
+ (void) setPoolCountThreshhold: (unsigned)c
{
pool_count_warning_threshhold = c;