/* Interface to debugging utilities for GNUStep and OpenStep Copyright (C) 1997,1999 Free Software Foundation, Inc. Written by: Richard Frith-Macdonald Date: August 1997 Extended by: Nicola Pero Date: December 2000, April 2001 This file is part of the GNUstep Base Library. This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public License for more details. You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02111 USA. */ #ifndef __NSDebug_h_GNUSTEP_BASE_INCLUDE #define __NSDebug_h_GNUSTEP_BASE_INCLUDE #import #include #if !defined(NO_GNUSTEP) # if defined(GNUSTEP_BASE_INTERNAL) # import "Foundation/NSObject.h" # import "GNUstepBase/NSDebug+GNUstepBase.h" # else # import # import # endif #endif #if defined(__cplusplus) extern "C" { #endif /* * Functions for debugging object allocation/deallocation * * Internal functions: * GSDebugAllocationAdd() is used by NSAllocateObject() * GSDebugAllocationRemove() is used by NSDeallocateObject() * * Public functions: * GSDebugAllocationActive() * GSDebugAllocationCount() * GSDebugAllocationTotal() * GSDebugAllocationPeak() * GSDebugAllocationClassList() * GSDebugAllocationList() * GSDebugAllocationListAll() * GSSetDebugAllocationFunctions() * * When the previous functions have allowed you to find a memory leak, * and you know that you are leaking objects of class XXX, but you are * 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 * and only in debugging systems): * * GSDebugAllocationActiveRecordingObjects() * GSDebugAllocationListRecordedObjects() */ #ifndef NDEBUG /** * Used internally by NSAllocateObject() ... you probably don't need this. */ GS_EXPORT void GSDebugAllocationAdd(Class c, id o); /** * Used internally by NSDeallocateObject() ... you probably don't need this. */ GS_EXPORT void GSDebugAllocationRemove(Class c, id o); /** * Activates or deactivates object allocation debugging. * Returns previous state. */ GS_EXPORT BOOL GSDebugAllocationActive(BOOL active); /** * Returns the number of instances of the specified class * which are currently allocated. */ GS_EXPORT int GSDebugAllocationCount(Class c); /** * Returns the peak number of instances of the specified class * which have been concurrently allocated. */ GS_EXPORT int GSDebugAllocationPeak(Class c); /** * Returns the total number of instances of the specified class * which have been allocated. */ GS_EXPORT int GSDebugAllocationTotal(Class c); /** * Returns a NULL terminated array listing all the classes * for which statistical information has been collected. */ GS_EXPORT Class* GSDebugAllocationClassList(void); /** * Returns a newline separated list of the classes which * have instances allocated, and the instance counts. * If 'changeFlag' is YES then the list gives the number * of instances allocated/deallocated since the function * was last called. */ GS_EXPORT const char* GSDebugAllocationList(BOOL changeFlag); /** * Returns a newline separated list of the classes which * have had instances allocated at any point, and the total * count of the number of instances allocated for each class. */ GS_EXPORT const char* GSDebugAllocationListAll(void); /** * Starts recording all allocated objects of a certain class.
* Use with extreme care ... this could slow down your application * enormously. */ GS_EXPORT void GSDebugAllocationActiveRecordingObjects(Class c); /** * Returns an array containing all the allocated objects * of a certain class which have been recorded. * Presumably, you will immediately call [NSObject-description] on * them to find out the objects you are leaking. * Warning - the objects are put in an array, so until * the array is autoreleased, the objects are not released. */ GS_EXPORT NSArray *GSDebugAllocationListRecordedObjects(Class c); /** * This function associates the supplied tag with a recorded * object and returns the tag which was previously associated * with it (if any).
* If the object was not recorded, the method returns nil
* The tag is retained while it is associated with the object.
* See also the NSDebugFRLog() and NSDebugMRLog() macros. */ GS_EXPORT id GSDebugAllocationTagRecordedObject(id object, id tag); /** * This functions allows to set own function callbacks for debugging allocation * of objects. Useful if you intend to write your own object allocation code. */ GS_EXPORT void GSSetDebugAllocationFunctions( void (*newAddObjectFunc)(Class c, id o), void (*newRemoveObjectFunc)(Class c, id o)); #endif /** * Enable/disable zombies. *

When an object is deallocated, its isa pointer is normally modified * to the hexadecimal value 0xdeadface, so that any attempt to send a * message to the deallocated object will cause a crash, and examination * of the object within the debugger will show the 0xdeadface value ... * making it obvious why the program crashed. *

*

Turning on zombies changes this behavior so that the isa pointer * is modified to be that of the NSZombie class. When messages are * sent to the object, instead of crashing, NSZombie will use NSLog() to * produce an error message. By default the memory used by the object * will not really be freed, so error messages will continue to * be generated whenever a message is sent to the object, and the object * instance variables will remain available for examination by the debugger. *

* The default value of this boolean is NO, but this can be controlled * by the NSZombieEnabled environment variable. */ GS_EXPORT BOOL NSZombieEnabled; /** * Enable/disable object deallocation. *

If zombies are enabled, objects are by default not * deallocated, and memory leaks. The NSDeallocateZombies variable * lets you say that the the memory used by zombies should be freed. *

*

Doing this makes the behavior of zombies similar to that when zombies * are not enabled ... the memory occupied by the zombie may be re-used for * other purposes, at which time the isa pointer may be overwritten and the * zombie behavior will cease. *

* The default value of this boolean is NO, but this can be controlled * by the NSDeallocateZombies environment variable. */ GS_EXPORT BOOL NSDeallocateZombies; /** * Retrieve stack information. Use caution: uses built-in gcc functions * and currently only works up to 100 frames. */ GS_EXPORT void *NSFrameAddress(NSUInteger offset); /** * Retrieve stack information. Use caution: uses built-in gcc functions * and currently only works up to 100 frames. */ GS_EXPORT void *NSReturnAddress(NSUInteger offset); /** * Retrieve stack information. Use caution: uses built-in gcc functions * and currently only works up to 100 frames. */ GS_EXPORT NSUInteger NSCountFrames(void); #if defined(__cplusplus) } #endif #endif