Memory leak improvments

Headers/Foundation/NSDebug.h

@@ -40,6 +40,9 @@
 #  endif
 #endif
 
+@class  NSArray;
+@class  NSMapTable;
+
 #if	defined(__cplusplus)
 extern "C" {
 #endif
@@ -97,12 +100,14 @@ extern "C" {
  * hopeless about actually finding out where the leak is, the
  * following functions could come handy as they allow you to find
  * exactly *what* objects you are leaking (warning! these functions
- * could slow down your system appreciably - use them only temporarily
+ * eill slow down your system appreciably - use them only temporarily
  * and only in debugging systems):
  *
+ *  GSDebugAllocationRecordAndTrace()
  *  GSDebugAllocationRecordObjects()
  *  GSDebugAllocationListRecordedObjects() 
  *  GSDebugAllocationTagRecordedObject()
+ *  GSDebugAllocationTaggedObjects()
  */
 
 /**
@@ -238,31 +243,37 @@ GS_EXPORT const char*	GSDebugAllocationList(BOOL changeFlag);
  */
 GS_EXPORT const char*	GSDebugAllocationListAll(void);
 
-/**
- * DEPRECATED ... use GSDebugAllocationRecordObjects instead.
- */
-GS_EXPORT void     GSDebugAllocationActiveRecordingObjects(Class c);
-
 /**
  * This function activates (or deactivates) tracking all allocated
  * instances of the specified class c.<br />
  * Turning on tracking implicitly turns on memory debug (counts)
  * for all classes (GSAllocationActive()).<br />
- * Deactivation of tracking releases all currently tracked instances
+ * Deactivation of tracking removes all currently tracked instances
  * of the class (but deactivation of general counting does not).<br />
- * The previous tracking state as reported as the return value of
+ * If a trace function is supplied, it takes the object to be recorded
+ * as an argument and either returns a value used as the tag for the
+ * object to be recorded, or nil to prevent the recording of that
+ * particular object.<br />
+ * As a special case the trace function may be the integer 1
+ * (cast to a function) to tag recorded objects by stack trace.  This
+ * allows you to see where each leaked object was allocated.<br />
+ * The previous tracking state is reported as the return value of
  * this function.<br />
- * This tracking can slow your application down, so you should use it
+ * This tracking will slow your application down, so you should use it
  * only when you are into serious debugging.
  * Usually, you will monitor your application by using the functions
- * GSDebugAllocationList() and similar, which do not slow things down
- * much and return * the number of allocated instances; when
+ * GSDebugAllocationList() and similar (which do not slow things down
+ * much) and return the number of allocated instances; when
  * (if) by studying the reports generated by these functions
  * you have found a leak of objects of a certain class, and
  * if you can't figure out how to fix it by looking at the
  * code, you can use this function to start tracking
- * allocated instances of that class, and the following one
- * can sometime allow you to list the leaked objects directly.
+ * allocated instances of that class.
+ */
+GS_EXPORT BOOL  GSDebugAllocationRecordAndTrace(
+  Class c, BOOL record, NSObject* (*traceFunction)(id));
+
+/** Calls GSDebugAllocationRecordAndTrace() with a null trace function.
  */
 GS_EXPORT BOOL  GSDebugAllocationRecordObjects(Class c, BOOL newState);
 
@@ -270,7 +281,7 @@ GS_EXPORT BOOL  GSDebugAllocationRecordObjects(Class c, BOOL newState);
  * This function returns an array
  * containing all the allocated objects of a certain class
  * which have been recorded ... to start the recording, you need
- * to invoke GSDebugAllocationRecordObjects().
+ * to invoke GSDebugAllocationRecordAndTrace().
  * Presumably, you will immediately call [NSObject-description] on them
  * to find out the objects you are leaking.  The objects are
  * returned in an autoreleased array, so until the array is deallocated,
@@ -278,6 +289,14 @@ GS_EXPORT BOOL  GSDebugAllocationRecordObjects(Class c, BOOL newState);
  */
 GS_EXPORT NSArray *GSDebugAllocationListRecordedObjects(Class c);
 
+/** Returns a map containing recorded objects as keys and their corresponding
+ * tags as values. This does not return any objects which do not have tags,
+ * and returns nil if there are no tagged objects to report.  The returned
+ * map table is autoreleased and will retain the objects and their tags
+ * until it is deallocated.
+ */
+GS_EXPORT NSMapTable *GSDebugAllocationTaggedObjects(Class c);
+
 /**
  * This function associates the supplied tag with a recorded
  * object and returns the tag which was previously associated
@@ -286,8 +305,7 @@ GS_EXPORT NSArray *GSDebugAllocationListRecordedObjects(Class c);
  * The tag is retained while it is associated with the object.<br />
  * If the tagged object is deallocated, the tag is released
  * (so you can track the lifetime of the object by having the tag
- * perform some operation when it is released).<br />
- * See also the NSDebugFRLog() and NSDebugMRLog() macros.
+ * perform some operation when it is released).
  */
 GS_EXPORT id GSDebugAllocationTagRecordedObject(id object, id tag);