home *** CD-ROM | disk | FTP | other *** search
/ OpenStep (Enterprise) / OpenStepENTCD.toast / OEDEV / DEV.Z / NSDebug.h < prev    next >
Encoding:
C/C++ Source or Header  |  1996-09-11  |  17.7 KB  |  443 lines
  1. /*    NSDebug.h
  2.     Debug utilities - do not depend on this in production code
  3.     Copyright 1994-1996, NeXT Software, Inc.  All rights reserved.
  4. */
  5.  
  6. #if !defined(STRICT_OPENSTEP)
  7.  
  8. /**************************************************************************
  9. WARNING: Unsupported API.
  10.  
  11. This module contains material that is only partially supported -- if
  12. at all.  Do not depend on the existance of any of these symbols in your
  13. code in future releases of this software.  Certainly, do not depend on
  14. the symbols in this header in production code.  The format of any data
  15. produced by the functions in this header may also change at any time.
  16.  
  17. However, it should be noted that the features in this file have been
  18. found to be generally useful, and in some cases invaluable, and are not
  19. likely to go away anytime soon. Some of these facilities, unfortunately,
  20. are oriented towards most convenient use on a UNIX-like platform.
  21. **************************************************************************/
  22.  
  23. #import <Foundation/NSObject.h>
  24. #import <Foundation/NSAutoreleasePool.h>
  25.  
  26. /* The environment component of this API
  27.  
  28. The boolean- and integer-valued variables declared in this header,
  29. plus some values set by methods, read starting values from the
  30. process's environment at process startup.  This is mostly a benefit
  31. if you need to initialize these variables to some non-default value
  32. before your program's main() routine gets control, but it also
  33. allows you to change the value without modifying your program's
  34. source. (Variables can be set and methods called around specific
  35. areas within a program, too, of course.)
  36.  
  37. This opens the door to various possibilites, such as a
  38. statistics-gathering application which spawns off the process to
  39. be measured, providing a custom environment.  The parent process
  40. could then read the output of the statistics from the file
  41. descriptor it had opened, and specified in the environment.
  42.  
  43. In sh/ksh/zsh or other sh-influenced shell, you can set the value in
  44. the environment like this:
  45. % export NSKeepAllocationStatistics=YES
  46. % myProg
  47.  
  48. or for just that process:
  49. % NSKeepAllocationStatistics=YES myProg
  50.  
  51. In a csh/tcsh or other csh-influenced shell, you do this:
  52. > setenv NSKeepAllocationStatistics YES
  53. > myProg
  54.  
  55.  
  56. The initialization from the environment happens very early, but may
  57. not have happened yet at the time of a +load method statically linked
  58. into an application (as opposed to one in a dynamically loaded module). 
  59. But as noted in the "Foundation Release Notes", +load methods that are
  60. statically linked into an application are tricky to use and are not
  61. recommended.
  62.  
  63. Here is a table of the variables/values initialized from the environment
  64. at startup.  Some of these just set variables, others call methods to
  65. set the values.
  66.  
  67. NAME OF ENV. VARIABLE            DEFAULT        SET IT TO...
  68. NSDebugEnabled                  NO        "YES"
  69. NSZombieEnabled                  NO        "YES"
  70. NSDeallocateZombies              NO        "YES"
  71. NSHangOnMallocError              NO        "YES"
  72.  
  73. NSEnableAutoreleasePool              YES        "NO"
  74. NSAutoreleaseFreedObjectCheckEnabled      NO        "YES"
  75. NSAutoreleaseHighWaterMark          0        non-negative integer
  76. NSAutoreleaseHighWaterResolution      0        non-negative integer
  77.  
  78. NSKeepZoneStatistics              NO        "YES"
  79. NSZoneStatisticsFD              file in /tmp    open file descriptor number
  80. NSKeepAllocationStatistics          NO        "YES"
  81. NSAllocationStatisticsFD          file in /tmp    open file descriptor number
  82. NSKeepNotificationStatistics          NO        "YES"
  83. NSNotificationStatisticsFD          file in /tmp    open file descriptor number
  84.  
  85. */
  86.  
  87. /****************    General        ****************/
  88.  
  89. FOUNDATION_EXPORT BOOL NSDebugEnabled;
  90.     // Mostly used to turn on the stack-processing and recording facility.
  91.     // The 'oh' command can be used to most easily access this facility.
  92.     // The default is NO. ('oh' is currently available only on MACH.)
  93.  
  94. FOUNDATION_EXPORT BOOL NSZombieEnabled;
  95.     // Enable object zombies. When an object is deallocated, its isa
  96.     // pointer is modified to be that of a "zombie" class (whether or
  97.     // not the storage is then freed can be controlled by the
  98.     // NSDeallocateZombies variable). Messages sent to the zombie
  99.     // object cause logged messages and can be broken on in a debugger.
  100.     // The default is NO.
  101.  
  102. FOUNDATION_EXPORT BOOL NSDeallocateZombies;
  103.     // Determines whether the storage of objects that have been
  104.     // "zombified" is then freed or not. The default value (NO)
  105.     // is most suitable for debugging messages sent to zombie
  106.     // objects. And since the memory is never freed, storage
  107.     // allocated to an object will never be reused, either (which
  108.     // is sometimes useful otherwise).
  109.  
  110. FOUNDATION_EXPORT BOOL NSHangOnMallocError;
  111.     // MACH only: Cause the process to hang after printing out the
  112.     // "Malloc-related error detected with code N" message to stderr.
  113.     // A backtrace can be gotten from the process with the 'sample'
  114.     // utility. The default is NO. Has no effect on non-MACH platforms.
  115.  
  116.  
  117. /****************    Stack processing/recording    ****************/
  118.  
  119. FOUNDATION_EXPORT void NSDebugRecordObjectAndStack(id self);
  120.     // Used with NSDebugEnabled to record object history. In a
  121.     // method, use like:
  122.     //     if (NSDebugEnabled) NSDebugRecordObjectAndStack(self);
  123.     // The 'oh' command can be used to dump the recorded information.
  124.     // ('oh' is currently available only on MACH.)
  125.  
  126. #if !defined(STRICT_40)
  127.  
  128. FOUNDATION_EXPORT void *NSFrameAddress(unsigned frame);
  129. FOUNDATION_EXPORT void *NSReturnAddress(unsigned frame);
  130.     // Returns the value of the frame pointer or return address,
  131.     // respectively, of the specified frame. Frames are numbered
  132.     // sequentially, with the "current" frame being zero, the
  133.     // previous frame being 1, etc. The current frame is the
  134.     // frame in which either of these functions is called. For
  135.     // example, NSReturnAddress(0) returns an address near where
  136.     // this function was called, NSReturnAddress(1) returns the
  137.     // address to which control will return when current frame
  138.     // exits, etc. If the requested frame does not exist, then
  139.     // NULL is returned. The behavior of these functions is
  140.     // undefined in the presence of code which has been compiled
  141.     // without frame pointers. Currently only information about
  142.     // the first 160 frames (0 <= frame <= 160) can be computed.
  143.  
  144. FOUNDATION_EXPORT unsigned NSCountFrames(void);
  145.     // Returns the number of call frames on the stack. The behavior
  146.     // of this functions is undefined in the presence of code which
  147.     // has been compiled without frame pointers.
  148.  
  149. #endif
  150.  
  151. /****************    Autorelease pool debugging    ****************/
  152.  
  153. @interface NSAutoreleasePool (NSAutoreleasePoolDebugging)
  154.  
  155. // Functions used as interesting breakpoints in a debugger
  156. FOUNDATION_EXPORT void _NSAutoreleaseNoPool(void *object);
  157.     // Called to log the "Object X of class Y autoreleased with no
  158.     // pool in place - just leaking" message.
  159.  
  160. FOUNDATION_EXPORT void _NSAutoreleaseFreedObject(void *freedObject);
  161.     // Called when a previously freed object would be released
  162.     // by an autorelease pool. See +enableFreedObjectCheck: below.
  163.  
  164. FOUNDATION_EXPORT void _NSAutoreleaseHighWaterLog(unsigned int count);
  165.     // Called whenever a high water mark is reached by a pool.
  166.     // See +setPoolCountHighWaterMark: below.
  167.  
  168. + (void)enableRelease:(BOOL)enable;
  169.     // Enables or disables autorelease pools; that is, whether or
  170.     // not the autorelease pools send the -release message to their
  171.     // objects when each pool is released. This message affects only
  172.     // the pools of the autorelease pool stack of the current thread
  173.     // (and any future pools in that thread). The "default default"
  174.     // value can be set in the initial environment when a program
  175.     // is launched with the NSEnableAutoreleasePool environment
  176.     // variable (see notes at the top of this file) -- as thread
  177.     // pool-stacks are created, they take their initial enabled
  178.     // state from that environment variable.
  179.  
  180. + (void)showPools;
  181.     // Displays to stderr the state of the current thread's
  182.     // autorelease pool stack.
  183.  
  184. + (void)resetTotalAutoreleasedObjects;
  185. + (unsigned)totalAutoreleasedObjects;
  186.     // Returns the number of objects autoreleased (in ALL threads,
  187.     // currently) since the counter was last reset to zero with
  188.     // +resetTotalAutoreleasedObjects.
  189.  
  190. + (void)enableFreedObjectCheck:(BOOL)enable;
  191.     // Enables or disables freed-object checking for the pool stack
  192.     // of the current thread (and any future pools in that thread).
  193.     // When enabled, an autorelease pool will call the function
  194.     // _NSAutoreleaseFreedObject() when it is about to attempt to
  195.     // release an object that the runtime has marked as freed (and
  196.     // then it doesn't attempt to send -release to the freed storage).
  197.     // The pointer to the freed storage is passed to that function.
  198.     // The "default default" value can be set in the initial
  199.     // environment when a program is launched with the
  200.     // NSAutoreleaseFreedObjectCheckEnabled environment variable
  201.     // (see notes at the top of this file) -- as thread pool-stacks
  202.     // are created, they take their initial freed-object-check state
  203.     // from that environment variable.
  204.  
  205. + (unsigned int)autoreleasedObjectCount;
  206.     // Returns the total number of autoreleased objects in all pools
  207.     // in the current thread's pool stack.
  208.  
  209. + (unsigned int)topAutoreleasePoolCount;
  210.     // Returns the number of autoreleased objects in top pool of
  211.     // the current thread's pool stack.
  212.  
  213. + (unsigned int)poolCountHighWaterMark;
  214. + (void)setPoolCountHighWaterMark:(unsigned int)count;
  215.     // Sets the pool count high water mark for the pool stack of
  216.     // the current thread (and any future pools in that thread). When
  217.     // 'count' objects have accumulated in the top autorelease pool,
  218.     // the pool will call _NSAutoreleaseHighWaterLog(), which
  219.     // generates a message to stderr. The number of objects in the
  220.     // top pool is passed as the parameter to that function. The
  221.     // default high water mark is 0, which disables pool count
  222.     // monitoring. The "default default" value can be set in the
  223.     // initial environment when a program is launched with the
  224.     // NSAutoreleaseHighWaterMark environment variable (see notes at
  225.     // the top of this file) -- as thread pool-stacks are created,
  226.     // they take their initial high water mark value from that
  227.     // environment variable. See also +setPoolCountHighWaterResolution:.
  228.  
  229. + (unsigned int)poolCountHighWaterResolution;
  230. + (void)setPoolCountHighWaterResolution:(unsigned int)res;
  231.     // Sets the pool count high water resolution for the pool stack of
  232.     // the current thread (and any future pools in that thread). A
  233.     // call to _NSAutoreleaseHighWaterLog() is generated every multiple
  234.     // of 'res' objects above the high water mark. If 'res' is zero
  235.     // (the default), only one call to _NSAutoreleaseHighWaterLog() is
  236.     // made, when the high water mark is reached. The "default default"
  237.     // value can be set in the initial environment when a program is
  238.     // launched with the NSAutoreleaseHighWaterResolution environment
  239.     // variable (see notes at the top of this file) -- as thread
  240.     // pool-stacks are created, they take their initial high water
  241.     // resolution value from that environment variable. See also
  242.     // +setPoolCountHighWaterMark:.
  243.  
  244.  
  245. // Obsolete API.  Use the methods above instead.
  246. + (void)enableDoubleReleaseCheck:(BOOL)enable;
  247.     // Use +enableFreedObjectCheck:
  248. + (void)showPoolsWithObjectIdenticalTo:(id)object;
  249.     // Use +showPools
  250. + (void)setPoolCountThreshold:(unsigned)count;
  251.     // Equivalent to:
  252.     //    [NSAutoreleasePool setPoolCountHighWaterMark:count];
  253.     //    [NSAutoreleasePool setPoolCountHighWaterResolution:count];
  254.  
  255. @end
  256.  
  257.  
  258. /****************    Statistics-keeping    ****************/
  259.  
  260. // The statistics-keeping facilities generate output on various
  261. // types of events. Currently, output logs can be generated for
  262. // use of the zone allocation functions (NSZoneMalloc(), etc.),
  263. // allocation and deallocation of objects (and other types of
  264. // lifetime-related events), and for use of the notification
  265. // facilities (NSNotificationCenter). Currently, also, the output
  266. // generated is in a columnar ASCII form, to make it most
  267. // convenient to use command-line data processing utilities,
  268. // like 'awk', 'grep', and 'sed'.
  269.  
  270. // The boolean enabling variables can be set in a program, perhaps
  271. // "around" a section of code that is of interest, and the values
  272. // can also be given a non-default initial state by placing special
  273. // environment variables into a process's initial environment (see
  274. // notes at the top of this file). The names of those environment
  275. // variables are the same as the names of the enabling variables.
  276.  
  277. // The destination of the output can be controlled somewhat by
  278. // setting the values of the "FD" variables below, either at runtime
  279. // or in the environment, as described above.
  280.  
  281. FOUNDATION_EXPORT BOOL NSKeepZoneStatistics;
  282.     // Default is NO.
  283.  
  284. FOUNDATION_EXPORT int NSZoneStatisticsFD;
  285.     // Number of open file descriptor to which output will be
  286.     // written, currently using write(). By default, a file
  287.     // called "zone_stats_<name>_<pid>" (where <name> is the
  288.     // process name and <pid> is the process id) is created in
  289.     // the platform's temporary directory when first needed.
  290.  
  291. FOUNDATION_EXPORT int NSZoneStatisticsOutputVersion;
  292.     // Not currently used.
  293.  
  294.  
  295. FOUNDATION_EXPORT BOOL NSKeepAllocationStatistics;
  296.     // Default is NO.
  297.  
  298. FOUNDATION_EXPORT int NSAllocationStatisticsFD;
  299.     // Number of open file descriptor to which output will be
  300.     // written, currently using write(). By default, a file
  301.     // called "alloc_stats_<name>_<pid>" (where <name> is the
  302.     // process name and <pid> is the process id) is created in
  303.     // the platform's temporary directory when first needed.
  304.  
  305. FOUNDATION_EXPORT int NSAllocationStatisticsOutputVersion;
  306.     // Not currently used.
  307.  
  308.  
  309. FOUNDATION_EXPORT BOOL NSKeepNotificationStatistics;
  310.     // Default is NO.
  311.  
  312. FOUNDATION_EXPORT int NSNotificationStatisticsFD;
  313.     // Number of open file descriptor to which output will be
  314.     // written, currently using write(). By default, a file
  315.     // called "note_stats_<name>_<pid>" (where <name> is the
  316.     // process name and <pid> is the process id) is created in
  317.     // the platform's temporary directory when first needed.
  318.  
  319. FOUNDATION_EXPORT int NSNotificationStatisticsOutputVersion;
  320.     // Not currently used.
  321.  
  322.  
  323.  
  324. /* NOTE: The information below is somewhat incomplete and contains
  325.  * inaccuracies, and has not been updated since the prerelease(s).
  326.  * The OpenStep Conversion Guide contains additional information
  327.  * which may be more accurate. Note, too, that there is no information
  328.  * here on the format of the notification statistics output at this
  329.  * time (but the format is similar to that of the zone and allocation
  330.  * statistics output).
  331.  */
  332.  
  333. /***********    Zone allocation statistics        ***********/
  334.  
  335. /* All output lines begin with 5 fields:
  336.     TIME FRAME RETURN PTRADDR OP
  337. where TIME is the time in seconds since the reference date for NSDate,
  338. FRAME is the value of the frame pointer register for the function/method
  339. that called one of the instrumented functions, RETURN is the return
  340. address back to the function that called one of the instrumented functions,
  341. PTRADDR is the address of the object being manipulated/allocated, and
  342. finally OP is the event being recorded:
  343. MALLOC (NSZoneMalloc()),
  344. CALLOC (NSZoneCalloc()),
  345. REALLOC (NSZoneRealloc()),
  346. MFREE (NSZoneFree()),
  347. VALLOC (NSAllocateMemoryPages()),
  348. VFREE (NSDeallocateMemoryPages()),
  349. VCOPY (NSCopyMemoryPages()),
  350. CREATE (NSCreateZone()),
  351. RECYCLE (NSRecycleZone()),
  352. SETNAME (NSSetZoneName()),
  353. GETNAME (NSZoneName()),
  354. GETZONE (NSZoneFromPointer()),
  355. DEFAULT (NSDefaultMallocZone()),
  356. INVALID (some unknown OP; bug).
  357.  
  358. For the operations FREE, VMFREE, DEFAULT, RECYCLE, and GETNAME, that's it.
  359. The other operations have this additional information:
  360. MALLOC
  361. CALLOC
  362.     ZONE SIZE
  363.  
  364. REALLOC
  365.     ZONE SIZE RESPTR
  366.  
  367. VALLOC
  368.     SIZE
  369.  
  370. VCOPY
  371.     SIZE DSTPTR
  372.  
  373. CREATE
  374.     SIZE GRAN CANFREE
  375.  
  376. SETNAME
  377.     NAME
  378.  
  379. GETZONE
  380.     ZONE
  381.  
  382. INVALID
  383.     OP#
  384.  
  385. where ZONE is the address of the zone from which the object was allocated,
  386. SIZE is the number of bytes requested, RESPTR is the result pointer from
  387. reallocation, DSTPTR is the destination pointer for copying, GRAN is the
  388. granularity of a new zone, CANFREE is YES or NO depending on whether or
  389. not memory is really freed from the zone, NAME is the name assigned to a
  390. zone, and OP# is the internal integer used to represent an event.
  391. */
  392.  
  393. /***********    Allocation statistics        ***********/
  394.  
  395. /* All output lines begin with 6 fields:
  396.     TIME FRAME RETURN OBJADDR CLASS OP
  397. where TIME is the time in seconds since the reference date for NSDate,
  398. FRAME is the value of the frame pointer register for the function/method
  399. that called one of the instrumented functions, RETURN is the return
  400. address back to the function that called one of the instrumented functions,
  401. OBJADDR is the address of the object being manipulated/allocated, CLASS is
  402. the classname of the object, and finally OP is the event being recorded:
  403. ALLOC (NSAllocateObject()),
  404. FREE (NSDeallocateObject()),
  405. COPY (NSCopyObject()),
  406. AUTO (-autorelease),
  407. REF+ (NSIncrementExtraRefCount() after increment),
  408. REF- (NSDecrementExtraRefCountWasZero() before decrement),
  409. IREF+ (_NSIncrementInternalRefCount() after increment),
  410. IREF- (_NSDecrementInternalRefCountWasZero() before decrement),
  411. INVALID (some unknown OP; bug).
  412.  
  413. Note that not all classes use _NSIncrementInternalRefCount() and
  414. _NSDecrementInternalRefCountWasZero() to implement their internal
  415. reference counting.  Note also that IREF+/- do not include value
  416. of internal reference count -- that has be computed by some post-
  417. processing program.
  418.  
  419. For the operations AUTO, FREE, and REF?, that's it.  The other
  420. operations have this additional information:
  421. ALLOC
  422.     ZONE ISIZE ESIZE ASIZE
  423. COPY
  424.     COPYADDR COPYCLASS COPYZONE COPYISIZE COPYESIZE COPYASIZE
  425. REF+
  426.     POSTREFCNT
  427. REF-
  428.     PREREFCNT
  429. INVALID
  430.     OP#
  431.  
  432. where ZONE is the name of the zone from which the object was allocated,
  433. ISIZE is the instance_size of the object's class, ESIZE is the number
  434. of extra bytes requested for the object, ASIZE is the actual size of
  435. the block of memory allocated by the malloc() system, COPY* are the
  436. corresponding items for the created copy, POSTREFCNT is the external
  437. retain count of the object after incrementing, PREREFCNT is the external
  438. retain count of the object before decrementing, and OP# is the internal
  439. integer used to represent an event.
  440. */
  441.  
  442. #endif /* !STRICT_OPENSTEP */
  443.