gcc/testsuite/objc-obj-c++-shared/GNUStep/Foundation/NSAutoreleasePool.h

   1 /* Interface for NSAutoreleasePool for GNUStep
   2    Copyright (C) 1995, 1996, 1997 Free Software Foundation, Inc.
   3
   4    Written by:  Andrew Kachites McCallum <mccallum@gnu.ai.mit.edu>
   5    Date: 1995
   6
   7    This file is part of the GNUstep Base Library.
   8
   9    This library is free software; you can redistribute it and/or
  10    modify it under the terms of the GNU Lesser General Public
  11    License as published by the Free Software Foundation; either
  12    version 2 of the License, or (at your option) any later version.
  13
  14    This library is distributed in the hope that it will be useful,
  15    but WITHOUT ANY WARRANTY; without even the implied warranty of
  16    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  17    Library General Public License for more details.
  18
  19    You should have received a copy of the GNU Lesser General Public
  20    License along with this library; if not, write to the Free
  21    Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  22    Boston, MA 02111 USA.
  23    */
  24
  25 #ifndef __NSAutoreleasePool_h_GNUSTEP_BASE_INCLUDE
  26 #define __NSAutoreleasePool_h_GNUSTEP_BASE_INCLUDE
  27 #import "../GNUstepBase/GSVersionMacros.h"
  28
  29 #import "NSObject.h"
  30
  31 #if     defined(__cplusplus)
  32 extern "C" {
  33 #endif
  34
  35 @class NSAutoreleasePool;
  36 @class NSThread;
  37
  38 \f
  39 /**
  40  * Each thread has its own copy of these variables.
  41  <example>
  42 {
  43   NSAutoreleasePool *current_pool; // current pool for thread
  44   unsigned total_objects_count;    // total #/autoreleased objects over thread's lifetime
  45   id *pool_cache;                  // cache of previously-allocated pools,
  46   int pool_cache_size;             //  used internally for recycling
  47   int pool_cache_count;
  48 }
  49  </example>
  50 */
  51 typedef struct autorelease_thread_vars
  52 {
  53   /* The current, default NSAutoreleasePool for the calling thread;
  54      the one that will hold objects that are arguments to
  55      [NSAutoreleasePool +addObject:]. */
  56   __unsafe_unretained NSAutoreleasePool *current_pool;
  57
  58   /* The total number of objects autoreleased since the thread was
  59      started, or since -resetTotalAutoreleasedObjects was called
  60      in this thread. (if compiled in) */
  61   unsigned total_objects_count;
  62
  63   /* A cache of NSAutoreleasePool's already alloc'ed.  Caching old pools
  64      instead of deallocating and re-allocating them will save time. */
  65   __unsafe_unretained id *pool_cache;
  66   int pool_cache_size;
  67   int pool_cache_count;
  68 } thread_vars_struct;
  69
  70 /* Initialize an autorelease_thread_vars structure for a new thread.
  71    This function is called in NSThread each time an NSThread is created.
  72    TV should be of type `struct autorelease_thread_vars *' */
  73 #define init_autorelease_thread_vars(TV) \
  74 memset (TV, 0, sizeof (__typeof__ (*TV)))
  75
  76
  77 \f
  78 /**
  79  *  Each pool holds its objects-to-be-released in a linked-list of
  80     these structures.
  81     <example>
  82 {
  83   struct autorelease_array_list *next;
  84   unsigned size;
  85   unsigned count;
  86   id objects[0];
  87 }
  88     </example>
  89  */
  90 typedef struct autorelease_array_list
  91 {
  92   struct autorelease_array_list *next;
  93   unsigned size;
  94   unsigned count;
  95   __unsafe_unretained id objects[0];
  96 } array_list_struct;
  97
  98 \f
  99
 100 /**
 101  * <p>
 102  *   The standard OpenStep system of memory management employs retain counts.
 103  *   When an object is created, it has a retain count of 1.  When an object
 104  *   is retained, the retain count is incremented.  When it is released the
 105  *   retain count is decremented, and when the retain count goes to zero the
 106  *   object gets deallocated.
 107  * </p>
 108  * <p>
 109  *   A simple retain/release mechanism has problems with passing objects
 110  *   from one scope to another,
 111  *   so it's augmented with autorelease pools.  You can use the
 112  *   AUTORELEASE() macro to call the [NSObject-autorelease]
 113  *   method, which adds an object to the current autorelease pool by
 114  *   calling [NSAutoreleasePool+addObject:].<br />
 115  *   An autorelease pool simply maintains a reference to each object
 116  *   added to it, and for each addition, the autorelease pool will
 117  *   call the [NSObject-release] method of the object when the pool
 118  *   is released.  So doing an AUTORELEASE() is just the same as
 119  *   doing a RELEASE(), but deferred until the current autorelease
 120  *   pool is deallocated.
 121  * </p>
 122  * <p>
 123  *   The NSAutoreleasePool class maintains a separate stack of
 124  *   autorelease pools objects in each thread.
 125  * </p>
 126  * <p>
 127  *   When an autorelease pool is created, it is automatically
 128  *   added to the stack of pools in the thread.
 129  * </p>
 130  * <p>
 131  *   When a pool is destroyed, it (and any pool later in
 132  *   the stack) is removed from the stack.
 133  * </p>
 134  * <p>
 135  *   This mechanism provides a simple but controllable and reasonably
 136  *   efficient way of managing temporary objects.  An object can be
 137  *   autoreleased and then passed around and used until the topmost
 138  *   pool in the stack is destroyed.
 139  * </p>
 140  * <p>
 141  *   Most methods return objects which are either owned by autorelease
 142  *   pools or by the receiver of the method, so the lifetime of the
 143  *   returned object can be assumed to be the shorter of the lifetime
 144  *   of the current autorelease pool, or that of the receiver on which
 145  *   the method was called.<br />
 146  *   The exceptions to this are those object returned by -
 147  * </p>
 148  * <deflist>
 149  *   <term>[NSObject+alloc], [NSObject+allocWithZone:]</term>
 150  *   <desc>
 151  *     Methods whose names begin with alloc return an uninitialised
 152  *     object, owned by the caller.
 153  *   </desc>
 154  *   <term>[NSObject-init]</term>
 155  *   <desc>
 156  *     Methods whose names begin with init return an initialised
 157  *     version of the receiving object, owned by the caller.<br />
 158  *     NB. The returned object may not actually be the same as the
 159  *     receiver ... sometimes an init method releases the original
 160  *     receiver and returns an alternative.
 161  *   </desc>
 162  *   <term>[NSObject+new]</term>
 163  *   <desc>
 164  *     Methods whose names begin with new combine the effects of
 165  *     allocation and initialisation.
 166  *   </desc>
 167  *   <term>[NSObject-copy], [(NSCopying)-copyWithZone:]</term>
 168  *   <desc>
 169  *     Methods whose names begin with copy create a copy of the receiver
 170  *     which is owned by the caller.
 171  *   </desc>
 172  *   <term>
 173  *     [NSObject-mutableCopy], [(NSMutableCopying)-mutableCopyWithZone:]
 174  *   </term>
 175  *   <desc>
 176  *     Methods whose names begin with mutableCopy create a copy of the receiver
 177  *     which is owned by the caller.
 178  *   </desc>
 179  * </deflist>
 180  */
 181 NS_AUTOMATED_REFCOUNT_UNAVAILABLE
 182 @interface NSAutoreleasePool : NSObject
 183 {
 184 #if     GS_EXPOSE(NSAutoreleasePool) && !__has_feature(objc_arc)
 185   /* For re-setting the current pool when we are dealloc'ed. */
 186   NSAutoreleasePool *_parent;
 187   /* This pointer to our child pool is  necessary for co-existing
 188      with exceptions. */
 189   NSAutoreleasePool *_child;
 190   /* A collection of the objects to be released. */
 191   struct autorelease_array_list *_released;
 192   struct autorelease_array_list *_released_head;
 193   /* The total number of objects autoreleased in this pool. */
 194   unsigned _released_count;
 195   /* The method to add an object to this pool */
 196   void  (*_addImp)(id, SEL, id);
 197 #endif
 198 #if     GS_NONFRAGILE
 199 #else
 200   /* Pointer to private additional data used to avoid breaking ABI
 201    * when we don't have the non-fragile ABI available.
 202    * Use this mechanism rather than changing the instance variable
 203    * layout (see Source/GSInternal.h for details).
 204    */
 205   @private id _internal GS_UNUSED_IVAR;
 206 #endif
 207 }
 208
 209 /**
 210  * Adds anObj to the current autorelease pool.<br />
 211  * If there is no autorelease pool in the thread,
 212  * a warning is logged and the object is leaked (ie it will not be released).
 213  */
 214 + (void) addObject: (id)anObj;
 215
 216 /**
 217  * Allocate and return an autorelease pool instance.<br />
 218  * If there is an already-allocated NSAutoreleasePool available,
 219  * save time by just returning that, rather than allocating a new one.<br />
 220  * The pool instance becomes the current autorelease pool for this thread.
 221  */
 222 + (id) allocWithZone: (NSZone*)zone;
 223
 224 /**
 225  * Adds anObj to this autorelease pool.
 226  */
 227 - (void) addObject: (id)anObj;
 228
 229 /**
 230  * Raises an exception - pools should not be autoreleased.
 231  */
 232 - (id) autorelease;
 233
 234 #if OS_API_VERSION(MAC_OS_X_VERSION_10_4, GS_API_LATEST)
 235 /**
 236  * Intended to trigger a garbage collection run (if needed) when called in
 237  * a garbage collected environment.<br />
 238  * In a non-garbage collected environment, this method implements the
 239  * undocumented MacOS-X behavior, and releases the receiver.
 240  */
 241 - (void) drain;
 242 #endif
 243
 244 /**
 245  * Destroys the receiver (calls -dealloc).
 246  */
 247 - (oneway void) release;
 248
 249 /**
 250  * Raises an exception ... pools should not be retained.
 251  */
 252 - (id) retain;
 253
 254 #if OS_API_VERSION(GS_API_NONE, GS_API_NONE)
 255 /**
 256  * <p>
 257  *   Counts the number of times that the specified object occurs
 258  *   in autorelease pools in the current thread.
 259  * </p>
 260  * <p>
 261  *   This method is <em>slow</em> and should probably only be
 262  *   used for debugging purposes.
 263  * </p>
 264  */
 265 + (unsigned) autoreleaseCountForObject: (id)anObject;
 266
 267 /**
 268  * Return the currently active autorelease pool.
 269  */
 270 + (id) currentPool;
 271
 272 /**
 273  * <p>
 274  *   Specifies whether objects contained in autorelease pools are to
 275  *   be released when the pools are deallocated (by default YES).
 276  * </p>
 277  * <p>
 278  *   You can set this to NO for debugging purposes.
 279  * </p>
 280  */
 281 + (void) enableRelease: (BOOL)enable;
 282
 283 /**
 284  * <p>
 285  *   When autorelease pools are deallocated, the memory they used
 286  *   is retained in a cache for re-use so that new polls can be
 287  *   created very quickly.
 288  * </p>
 289  * <p>
 290  *   This method may be used to empty that cache, ensuring that
 291  *   the minimum memory is used by the application.
 292  * </p>
 293  */
 294 + (void) freeCache;
 295
 296 /**
 297  * <p>
 298  *   Specifies a limit to the number of objects that may be added to
 299  *   an autorelease pool.  When this limit is reached an exception is
 300  *   raised.
 301  * </p>
 302  * <p>
 303  *   You can set this to a smallish value to catch problems with code
 304  *   that autoreleases too many objects to operate efficiently.
 305  * </p>
 306  * <p>
 307  *   Default value is maxint.
 308  * </p>
 309  */
 310 + (void) setPoolCountThreshold: (unsigned)c;
 311
 312 /**
 313  * Return the number of objects in this pool.
 314  */
 315 - (unsigned) autoreleaseCount;
 316
 317 /**
 318  * Empties the current pool by releasing all the autoreleased objects
 319  * in it.  Also destroys any child pools (ones created after
 320  * the receiver in the same thread) causing any objects in those pools
 321  * to be released.<br />
 322  * This is a low cost (efficient) method which may be used to get rid of
 323  * autoreleased objects in the pool, but carry on using the pool.
 324  */
 325 - (void) emptyPool;
 326 #endif
 327 @end
 328
 329 #if     defined(__cplusplus)
 330 }
 331 #endif
 332
 333 #endif /* __NSAutoreleasePool_h_GNUSTEP_BASE_INCLUDE */