Autorelease fine control added

git-svn-id: svn+ssh://svn.gna.org/svn/gnustep/libs/base/trunk@9917 72102866-910b-0410-8b05-ffd578937521

ChangeLog

@@ -3,6 +3,10 @@
 	* Source/NSConnection.m: Use respondsToSelector rather than respondsTo
 	* Source/NSRunLoop.m: ditto ... and tidy up categories to avoid
 	compiler warnings.
+	* Source/NSAutoreleasePool.m: Add ([+freeCache]) method to clear out
+	the cache of pools in the current thread.
+	* Documentation/gsdoc/NSAutoreleasePool.gsdoc: basic class
+	documentation inlcuding normal GNUstep extensions.
 
 2001-05-08  Richard Frith-Macdonald <rfm@gnu.org>
 

Documentation/gsdoc/NSAutoreleasePool.html

@@ -21,6 +21,24 @@
 </p>
 <hr>
 
+	    <p>
+
+	      This class maintains a 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>
+
           
 <h2>Instance Variables </h2>
 <ul>
@@ -28,18 +46,112 @@
 <h2>Methods </h2>
 <ul>
 <li ><a href ="NSAutoreleasePool.html#method-0">+addObject:</a>
+<li ><a href ="NSAutoreleasePool.html#method-3">+autoreleaseCountForObject:</a>
+<li ><a href ="NSAutoreleasePool.html#method-2">+enableRelease:</a>
+<li ><a href ="NSAutoreleasePool.html#method-4">+freeCache</a>
+<li ><a href ="NSAutoreleasePool.html#method-5">+setPoolCountThreshold:</a>
 <li ><a href ="NSAutoreleasePool.html#method-1">-addObject:</a>
 </ul>
 <hr><h2>Class Methods </h2>
 <h3><a name ="method-0">addObject:</a></h3>
 + (void) <b>addObject:</b> (id)anObject;<br>
 
+	    <p>
+
+	      Adds the specified object to the current autorelease pool.
+	      If there is no autorelease pool in the thread,
+	      a warning is logged.
+	    </p>
+
+          
+ <hr>
+<h3><a name ="method-2">enableRelease:</a></h3>
++ (void) <b>enableRelease:</b> (BOOL)flag;<br>
+Standards:  GNUstep NotMacOS-X NotOpenStep<br>
+
+	    <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>
+
+          
+ <hr>
+<h3><a name ="method-3">autoreleaseCountForObject:</a></h3>
++ (unsigned) <b>autoreleaseCountForObject:</b> (id)anObject;<br>
+Standards:  GNUstep NotMacOS-X NotOpenStep<br>
+
+	    <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>
+
+          
+ <hr>
+<h3><a name ="method-4">freeCache</a></h3>
++ (void) <b>freeCache</b>;<br>
+Standards:  GNUstep NotMacOS-X NotOpenStep<br>
+
+	    <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>
+
+          
+ <hr>
+<h3><a name ="method-5">setPoolCountThreshold:</a></h3>
++ (void) <b>setPoolCountThreshold:</b> (unsigned)c;<br>
+Standards:  GNUstep NotMacOS-X NotOpenStep<br>
+
+	    <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>
+
           
  <hr>
 <hr><h2>Instances Methods </h2>
 <h3><a name ="method-1">addObject:</a></h3>
 - (void) <b>addObject:</b> (id)anObject;<br>
 
+	    <p>
+
+	      Adds the specified object to this autorelease pool.
+	    </p>
+
           
  <hr>
 </body>

Headers/gnustep/base/NSAutoreleasePool.h

@@ -90,6 +90,7 @@ struct autorelease_array_list
 
 #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. */

Source/NSAutoreleasePool.m

@@ -56,6 +56,7 @@ static unsigned pool_count_warning_threshhold = UINT_MAX;
 - (unsigned) autoreleaseCountForObject: (id)anObject;
 + (unsigned) autoreleaseCountForObject: (id)anObject;
 + (id) currentPool;
+- (void) _reallyDealloc;
 - (void) _setChildPool: (id)pool;
 @end
 
@@ -64,6 +65,25 @@ static unsigned pool_count_warning_threshhold = UINT_MAX;
    already alloc'ed.  The cache is kept in the autorelease_thread_var 
    structure, which is an ivar of NSThread. */
 
+static id pop_pool_from_cache (struct autorelease_thread_vars *tv);
+
+static inline void
+free_pool_cache (struct autorelease_thread_vars *tv)
+{
+  while (tv->pool_cache_count)
+    {
+      NSAutoreleasePool	*pool = pop_pool_from_cache(tv);
+
+      [pool _reallyDealloc];
+    }
+
+  if (tv->pool_cache)
+    {
+      NSZoneFree(NSDefaultMallocZone(), tv->pool_cache);
+      tv->pool_cache = 0;
+    }
+}
+
 static inline void
 init_pool_cache (struct autorelease_thread_vars *tv)
 {
@@ -77,7 +97,9 @@ static void
 push_pool_to_cache (struct autorelease_thread_vars *tv, id p)
 {
   if (!tv->pool_cache)
-    init_pool_cache (tv);
+    {
+      init_pool_cache (tv);
+    }
   else if (tv->pool_cache_count == tv->pool_cache_size)
     {
       tv->pool_cache_size *= 2;
@@ -372,7 +394,7 @@ static IMP	initImp;
   }
 }
 
-- (void) reallyDealloc
+- (void) _reallyDealloc
 {
   struct autorelease_array_list *a;
   for (a = _released_head; a; )
@@ -396,22 +418,15 @@ static IMP	initImp;
   struct autorelease_thread_vars *tv;
   id	pool;
 
-  tv = &(GSCurrentThread()->_autorelease_vars);
+  tv = ARP_THREAD_VARS;
   while (tv->current_pool)
     {
       [tv->current_pool release];
       pool = pop_pool_from_cache(tv);
-      [pool reallyDealloc];
+      [pool _reallyDealloc];
     }
 
-  while (tv->pool_cache_count)
-    {
-      pool = pop_pool_from_cache(tv);
-      [pool reallyDealloc];
-    }
-
-  if (tv->pool_cache)
-    NSZoneFree(NSDefaultMallocZone(), tv->pool_cache);
+  free_pool_cache(tv);
 }
 
 + (void) resetTotalAutoreleasedObjects
@@ -429,6 +444,11 @@ static IMP	initImp;
   autorelease_enabled = enable;
 }
 
++ (void) freeCache
+{
+  free_pool_cache(ARP_THREAD_VARS);
+}
+
 + (void) setPoolCountThreshhold: (unsigned)c
 {
   pool_count_warning_threshhold = c;