mirror of
https://github.com/gnustep/libs-base.git
synced 2025-05-31 08:41:03 +00:00
Header reorganizsateion - Please refer to ChangeLog
git-svn-id: svn+ssh://svn.gna.org/svn/gnustep/libs/base/trunk@17407 72102866-910b-0410-8b05-ffd578937521
This commit is contained in:
ayers
parent
15430c49b1
commit
73dc4cb9f6
238 changed files with 694 additions and 544 deletions
374
Headers/Foundation/NSDebug.h
Normal file
374
Headers/Foundation/NSDebug.h
Normal file
|
|
@ -0,0 +1,374 @@
|
|||
/* Interface to debugging utilities for GNUStep and OpenStep
|
||||
Copyright (C) 1997,1999 Free Software Foundation, Inc.
|
||||
|
||||
Written by: Richard Frith-Macdonald <richard@brainstorm.co.uk>
|
||||
Date: August 1997
|
||||
Extended by: Nicola Pero <n.pero@mi.flashnet.it>
|
||||
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 Library 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 Library General Public
|
||||
License along with this library; if not, write to the Free
|
||||
Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111 USA.
|
||||
*/
|
||||
|
||||
#ifndef __NSDebug_h_GNUSTEP_BASE_INCLUDE
|
||||
#define __NSDebug_h_GNUSTEP_BASE_INCLUDE
|
||||
|
||||
#include <errno.h>
|
||||
#include <Foundation/NSObject.h>
|
||||
|
||||
|
||||
/*
|
||||
* 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()
|
||||
*
|
||||
* 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.<br />
|
||||
* 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);
|
||||
|
||||
/**
|
||||
* Used to produce a format string for logging a message with function
|
||||
* location details.
|
||||
*/
|
||||
GS_EXPORT NSString* GSDebugFunctionMsg(const char *func, const char *file,
|
||||
int line, NSString *fmt);
|
||||
/**
|
||||
* Used to produce a format string for logging a message with method
|
||||
* location details.
|
||||
*/
|
||||
GS_EXPORT NSString* GSDebugMethodMsg(id obj, SEL sel, const char *file,
|
||||
int line, NSString *fmt);
|
||||
#endif
|
||||
|
||||
/**
|
||||
* Enable/disable zombies.
|
||||
* <p>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.
|
||||
* </p>
|
||||
* <p>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, intead 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.
|
||||
* </p>
|
||||
* 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.
|
||||
* <p>If zombies are enabled, objects are by default <em>not</em>
|
||||
* deallocated, and memory leaks. The NSDeallocateZombies variable
|
||||
* lets you say that the the memory used by zombies should be freed.
|
||||
* </p>
|
||||
* <p>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.
|
||||
* </p>
|
||||
* The default value of this boolean is NO, but this can be controlled
|
||||
* by the NSDeallocateZombies environment variable.
|
||||
*/
|
||||
GS_EXPORT BOOL NSDeallocateZombies;
|
||||
|
||||
|
||||
|
||||
#ifdef GSDIAGNOSE
|
||||
#include <Foundation/NSObjCRuntime.h>
|
||||
#include <Foundation/NSProcessInfo.h>
|
||||
|
||||
/**
|
||||
<p>NSDebugLLog() is the basic debug logging macro used to display
|
||||
log messages using NSLog(), if debug logging was enabled at compile
|
||||
time and the appropriate logging level was set at runtime.
|
||||
</p>
|
||||
<p>Debug logging which can be enabled/disabled by defining GSDIAGNOSE
|
||||
when compiling and also setting values in the mutable set which
|
||||
is set up by NSProcessInfo. GSDIAGNOSE is defined automatically
|
||||
unless diagnose=no is specified in the make arguments.
|
||||
</p>
|
||||
<p>NSProcess initialises a set of strings that are the names of active
|
||||
debug levels using the '--GNU-Debug=...' command line argument.
|
||||
Each command-line argument of that form is removed from NSProcessInfos
|
||||
list of arguments and the variable part (...) is added to the set.
|
||||
This means that as far as the program proper is concerned, it is
|
||||
running with the same arguments as if debugging had not been enabled.
|
||||
</p>
|
||||
<p>For instance, to debug the NSBundle class, run your program with
|
||||
'--GNU-Debug=NSBundle'
|
||||
You can of course supply multiple '--GNU-Debug=...' arguments to
|
||||
output debug information on more than one thing.
|
||||
</p>
|
||||
<p>NSUserDefaults also adds debug levels from the array given by the
|
||||
GNU-Debug key ... but these values will not take effect until the
|
||||
+standardUserDefaults method is called ... so they are useless for
|
||||
debugging NSUserDefaults itsself or for debugging any code executed
|
||||
before the defaults system is used.
|
||||
</p>
|
||||
<p>To embed debug logging in your code you use the NSDebugLLog() or
|
||||
NSDebugLog() macro. NSDebugLog() is just NSDebugLLog() with the debug
|
||||
level set to 'dflt'. So, to activate debug statements that use
|
||||
NSDebugLog(), you supply the '--GNU-Debug=dflt' argument to your program.
|
||||
</p>
|
||||
<p>You can also change the active debug levels under your programs control -
|
||||
NSProcessInfo has a [-debugSet] method that returns the mutable set that
|
||||
contains the active debug levels - your program can modify this set.
|
||||
</p>
|
||||
<p>Two debug levels have a special effect - 'dflt' is the level used for
|
||||
debug logs statements where no debug level is specified, and 'NoWarn'
|
||||
is used to *disable* warning messages.
|
||||
</p>
|
||||
<p>As a convenience, there are four more logging macros you can use -
|
||||
NSDebugFLog(), NSDebugFLLog(), NSDebugMLog() and NSDebugMLLog().
|
||||
These are the same as the other macros, but are specifically for use in
|
||||
either functions or methods and prepend information about the file, line
|
||||
and either function or class/method in which the message was generated.
|
||||
</p>
|
||||
*/
|
||||
#define NSDebugLLog(level, format, args...) \
|
||||
do { if (GSDebugSet(level) == YES) \
|
||||
NSLog(format , ## args); } while (0)
|
||||
|
||||
/**
|
||||
* This macro is a shorthand for NSDebugLLog() using then default debug
|
||||
* level ... 'dflt'
|
||||
*/
|
||||
#define NSDebugLog(format, args...) \
|
||||
do { if (GSDebugSet(@"dflt") == YES) \
|
||||
NSLog(format , ## args); } while (0)
|
||||
|
||||
/**
|
||||
* This macro is like NSDebugLLog() but includes the name and location
|
||||
* of the function in which the macro is used as part of the log output.
|
||||
*/
|
||||
#define NSDebugFLLog(level, format, args...) \
|
||||
do { if (GSDebugSet(level) == YES) { \
|
||||
NSString *fmt = GSDebugFunctionMsg( \
|
||||
__PRETTY_FUNCTION__, __FILE__, __LINE__, format); \
|
||||
NSLog(fmt , ## args); }} while (0)
|
||||
|
||||
/**
|
||||
* This macro is a shorthand for NSDebugFLLog() using then default debug
|
||||
* level ... 'dflt'
|
||||
*/
|
||||
#define NSDebugFLog(format, args...) \
|
||||
do { if (GSDebugSet(@"dflt") == YES) { \
|
||||
NSString *fmt = GSDebugFunctionMsg( \
|
||||
__PRETTY_FUNCTION__, __FILE__, __LINE__, format); \
|
||||
NSLog(fmt , ## args); }} while (0)
|
||||
|
||||
/**
|
||||
* This macro is like NSDebugLLog() but includes the name and location
|
||||
* of the <em>method</em> in which the macro is used as part of the log output.
|
||||
*/
|
||||
#define NSDebugMLLog(level, format, args...) \
|
||||
do { if (GSDebugSet(level) == YES) { \
|
||||
NSString *fmt = GSDebugMethodMsg( \
|
||||
self, _cmd, __FILE__, __LINE__, format); \
|
||||
NSLog(fmt , ## args); }} while (0)
|
||||
|
||||
/**
|
||||
* This macro is a shorthand for NSDebugMLLog() using then default debug
|
||||
* level ... 'dflt'
|
||||
*/
|
||||
#define NSDebugMLog(format, args...) \
|
||||
do { if (GSDebugSet(@"dflt") == YES) { \
|
||||
NSString *fmt = GSDebugMethodMsg( \
|
||||
self, _cmd, __FILE__, __LINE__, format); \
|
||||
NSLog(fmt , ## args); }} while (0)
|
||||
#else
|
||||
#define NSDebugLLog(level, format, args...)
|
||||
#define NSDebugLog(format, args...)
|
||||
#define NSDebugFLLog(level, format, args...)
|
||||
#define NSDebugFLog(format, args...)
|
||||
#define NSDebugMLLog(level, format, args...)
|
||||
#define NSDebugMLog(format, args...)
|
||||
#endif
|
||||
|
||||
|
||||
|
||||
#ifdef GSWARN
|
||||
#include <Foundation/NSObjCRuntime.h>
|
||||
|
||||
/**
|
||||
<p>NSWarnLog() is the basic debug logging macro used to display
|
||||
warning messages using NSLog(), if warn logging was not disabled at compile
|
||||
time and the disabling logging level was not set at runtime.
|
||||
</p>
|
||||
<p>Warning messages which can be enabled/disabled by defining GSWARN
|
||||
when compiling.
|
||||
</p>
|
||||
<p>You can also disable these messages at runtime by supplying a
|
||||
'--GNU-Debug=NoWarn' argument to the program, or by adding 'NoWarn'
|
||||
to the user default array named 'GNU-Debug'.
|
||||
</p>
|
||||
<p>These logging macros are intended to be used when the software detects
|
||||
something that it not necessarily fatal or illegal, but looks like it
|
||||
might be a programming error. eg. attempting to remove 'nil' from an
|
||||
NSArray, which the Spec/documentation does not prohibit, but which a
|
||||
well written progam should not be attempting (since an NSArray object
|
||||
cannot contain a 'nil').
|
||||
</p>
|
||||
<p>NB. The 'warn=yes' option is understood by the GNUstep make package
|
||||
to mean that GSWARN should be defined, and the 'warn=no' means that
|
||||
GSWARN should be undefined. Default is to define it.
|
||||
</p>
|
||||
<p>To embed debug logging in your code you use the NSWarnLog() macro.
|
||||
</p>
|
||||
<p>As a convenience, there are two more logging macros you can use -
|
||||
NSWarnLog(), and NSWarnMLog().
|
||||
These are specifically for use in either functions or methods and
|
||||
prepend information about the file, line and either function or
|
||||
class/method in which the message was generated.
|
||||
</p>
|
||||
*/
|
||||
|
||||
#define NSWarnLog(format, args...) \
|
||||
do { if (GSDebugSet(@"NoWarn") == NO) { \
|
||||
NSLog(format , ## args); }} while (0)
|
||||
|
||||
/**
|
||||
* This macro is like NSWarnLog() but includes the name and location of the
|
||||
* <em>function</em> in which the macro is used as part of the log output.
|
||||
*/
|
||||
#define NSWarnFLog(format, args...) \
|
||||
do { if (GSDebugSet(@"NoWarn") == NO) { \
|
||||
NSString *fmt = GSDebugFunctionMsg( \
|
||||
__PRETTY_FUNCTION__, __FILE__, __LINE__, format); \
|
||||
NSLog(fmt , ## args); }} while (0)
|
||||
|
||||
/**
|
||||
* This macro is like NSWarnLog() but includes the name and location of the
|
||||
* <em>method</em> in which the macro is used as part of the log output.
|
||||
*/
|
||||
#define NSWarnMLog(format, args...) \
|
||||
do { if (GSDebugSet(@"NoWarn") == NO) { \
|
||||
NSString *fmt = GSDebugMethodMsg( \
|
||||
self, _cmd, __FILE__, __LINE__, format); \
|
||||
NSLog(fmt , ## args); }} while (0)
|
||||
#else
|
||||
#define NSWarnLog(format, args...)
|
||||
#define NSWarnFLog(format, args...)
|
||||
#define NSWarnMLog(format, args...)
|
||||
#endif
|
||||
|
||||
/* Getting stack information. Use caution with this. It uses builtin
|
||||
gcc functions and currently only works up to 100 frames
|
||||
*/
|
||||
GS_EXPORT void *NSFrameAddress(int offset);
|
||||
GS_EXPORT void *NSReturnAddress(int offset);
|
||||
GS_EXPORT unsigned NSCountFrames(void);
|
||||
|
||||
#endif
|
||||
Loading…
Add table
Add a link
Reference in a new issue