home *** CD-ROM | disk | FTP | other *** search
/ OpenStep 4.2 / Openstep-4.2-Intel-Developer.iso / NextLibrary / Frameworks / Foundation.framework / Versions / B / Headers / NSDebug.h < prev    next >
Encoding:
C/C++ Source or Header  |  1996-11-03  |  22.5 KB  |  505 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. NSNegativeRetainCheckEnabled          NO        "YES"
  74.  
  75. NSEnableAutoreleasePool              YES        "NO"
  76. NSAutoreleaseFreedObjectCheckEnabled      NO        "YES"
  77. NSAutoreleaseHighWaterMark          0        non-negative integer
  78. NSAutoreleaseHighWaterResolution      0        non-negative integer
  79.  
  80. NSKeepZoneStatistics              NO        "YES"
  81. NSZoneStatisticsFD              file in /tmp    open file descriptor number
  82. NSZoneStatisticsOutputVersion          16        16 or 18
  83. NSZoneStatisticsOutputMask          0xFFFF    16-bit decimal, hex, or octal number
  84.  
  85. NSKeepAllocationStatistics          NO        "YES"
  86. NSAllocationStatisticsFD          file in /tmp    open file descriptor number
  87. NSAllocationStatisticsOutputVersion      16        16 or 18
  88. NSAllocationStatisticsOutputMask      0xFFFF    16-bit decimal, hex, or octal number
  89.  
  90. NSKeepNotificationStatistics          NO        "YES"
  91. NSNotificationStatisticsFD          file in /tmp    open file descriptor number
  92.  
  93. */
  94.  
  95. /****************    General        ****************/
  96.  
  97. FOUNDATION_EXPORT BOOL NSDebugEnabled;
  98.     // Mostly used to turn on the stack-processing and recording facility.
  99.     // The 'oh' command can be used to most easily access this facility.
  100.     // The default is NO. ('oh' is currently available only on MACH.)
  101.  
  102. FOUNDATION_EXPORT BOOL NSZombieEnabled;
  103.     // Enable object zombies. When an object is deallocated, its isa
  104.     // pointer is modified to be that of a "zombie" class (whether or
  105.     // not the storage is then freed can be controlled by the
  106.     // NSDeallocateZombies variable). Messages sent to the zombie
  107.     // object cause logged messages and can be broken on in a debugger.
  108.     // The default is NO.
  109.  
  110. FOUNDATION_EXPORT BOOL NSDeallocateZombies;
  111.     // Determines whether the storage of objects that have been
  112.     // "zombified" is then freed or not. The default value (NO)
  113.     // is most suitable for debugging messages sent to zombie
  114.     // objects. And since the memory is never freed, storage
  115.     // allocated to an object will never be reused, either (which
  116.     // is sometimes useful otherwise).
  117.  
  118. FOUNDATION_EXPORT BOOL NSHangOnMallocError;
  119.     // MACH only: Cause the process to hang after printing out the
  120.     // "Malloc-related error detected with code N" message to stderr.
  121.     // A backtrace can be gotten from the process with the 'sample'
  122.     // utility. The default is NO. Has no effect on non-MACH platforms.
  123.  
  124.  
  125. /****************    Stack processing/recording    ****************/
  126.  
  127. FOUNDATION_EXPORT void NSDebugRecordObjectAndStack(id self);
  128.     // Used with NSDebugEnabled to record object history. In a
  129.     // method, use like:
  130.     //     if (NSDebugEnabled) NSDebugRecordObjectAndStack(self);
  131.     // The 'oh' command can be used to dump the recorded information.
  132.     // ('oh' is currently available only on MACH.)
  133.  
  134. #if !defined(STRICT_40)
  135.  
  136. FOUNDATION_EXPORT void *NSFrameAddress(unsigned frame);
  137. FOUNDATION_EXPORT void *NSReturnAddress(unsigned frame);
  138.     // Returns the value of the frame pointer or return address,
  139.     // respectively, of the specified frame. Frames are numbered
  140.     // sequentially, with the "current" frame being zero, the
  141.     // previous frame being 1, etc. The current frame is the
  142.     // frame in which either of these functions is called. For
  143.     // example, NSReturnAddress(0) returns an address near where
  144.     // this function was called, NSReturnAddress(1) returns the
  145.     // address to which control will return when current frame
  146.     // exits, etc. If the requested frame does not exist, then
  147.     // NULL is returned. The behavior of these functions is
  148.     // undefined in the presence of code which has been compiled
  149.     // without frame pointers.
  150.  
  151. FOUNDATION_EXPORT unsigned NSCountFrames(void);
  152.     // Returns the number of call frames on the stack. The behavior
  153.     // of this functions is undefined in the presence of code which
  154.     // has been compiled without frame pointers.
  155.  
  156. #endif
  157.  
  158. /****************    Autorelease pool debugging    ****************/
  159.  
  160. @interface NSAutoreleasePool (NSAutoreleasePoolDebugging)
  161.  
  162. // Functions used as interesting breakpoints in a debugger
  163. FOUNDATION_EXPORT void _NSAutoreleaseNoPool(void *object);
  164.     // Called to log the "Object X of class Y autoreleased with no
  165.     // pool in place - just leaking" message.
  166.  
  167. FOUNDATION_EXPORT void _NSAutoreleaseFreedObject(void *freedObject);
  168.     // Called when a previously freed object would be released
  169.     // by an autorelease pool. See +enableFreedObjectCheck: below.
  170.  
  171. FOUNDATION_EXPORT void _NSAutoreleaseHighWaterLog(unsigned int count);
  172.     // Called whenever a high water mark is reached by a pool.
  173.     // See +setPoolCountHighWaterMark: below.
  174.  
  175. + (void)enableRelease:(BOOL)enable;
  176.     // Enables or disables autorelease pools; that is, whether or
  177.     // not the autorelease pools send the -release message to their
  178.     // objects when each pool is released. This message affects only
  179.     // the pools of the autorelease pool stack of the current thread
  180.     // (and any future pools in that thread). The "default default"
  181.     // value can be set in the initial environment when a program
  182.     // is launched with the NSEnableAutoreleasePool environment
  183.     // variable (see notes at the top of this file) -- as thread
  184.     // pool-stacks are created, they take their initial enabled
  185.     // state from that environment variable.
  186.  
  187. + (void)showPools;
  188.     // Displays to stderr the state of the current thread's
  189.     // autorelease pool stack.
  190.  
  191. + (void)resetTotalAutoreleasedObjects;
  192. + (unsigned)totalAutoreleasedObjects;
  193.     // Returns the number of objects autoreleased (in ALL threads,
  194.     // currently) since the counter was last reset to zero with
  195.     // +resetTotalAutoreleasedObjects.
  196.  
  197. + (void)enableFreedObjectCheck:(BOOL)enable;
  198.     // Enables or disables freed-object checking for the pool stack
  199.     // of the current thread (and any future pools in that thread).
  200.     // When enabled, an autorelease pool will call the function
  201.     // _NSAutoreleaseFreedObject() when it is about to attempt to
  202.     // release an object that the runtime has marked as freed (and
  203.     // then it doesn't attempt to send -release to the freed storage).
  204.     // The pointer to the freed storage is passed to that function.
  205.     // The "default default" value can be set in the initial
  206.     // environment when a program is launched with the
  207.     // NSAutoreleaseFreedObjectCheckEnabled environment variable
  208.     // (see notes at the top of this file) -- as thread pool-stacks
  209.     // are created, they take their initial freed-object-check state
  210.     // from that environment variable.
  211.  
  212. + (unsigned int)autoreleasedObjectCount;
  213.     // Returns the total number of autoreleased objects in all pools
  214.     // in the current thread's pool stack.
  215.  
  216. + (unsigned int)topAutoreleasePoolCount;
  217.     // Returns the number of autoreleased objects in top pool of
  218.     // the current thread's pool stack.
  219.  
  220. + (unsigned int)poolCountHighWaterMark;
  221. + (void)setPoolCountHighWaterMark:(unsigned int)count;
  222.     // Sets the pool count high water mark for the pool stack of
  223.     // the current thread (and any future pools in that thread). When
  224.     // 'count' objects have accumulated in the top autorelease pool,
  225.     // the pool will call _NSAutoreleaseHighWaterLog(), which
  226.     // generates a message to stderr. The number of objects in the
  227.     // top pool is passed as the parameter to that function. The
  228.     // default high water mark is 0, which disables pool count
  229.     // monitoring. The "default default" value can be set in the
  230.     // initial environment when a program is launched with the
  231.     // NSAutoreleaseHighWaterMark environment variable (see notes at
  232.     // the top of this file) -- as thread pool-stacks are created,
  233.     // they take their initial high water mark value from that
  234.     // environment variable. See also +setPoolCountHighWaterResolution:.
  235.  
  236. + (unsigned int)poolCountHighWaterResolution;
  237. + (void)setPoolCountHighWaterResolution:(unsigned int)res;
  238.     // Sets the pool count high water resolution for the pool stack of
  239.     // the current thread (and any future pools in that thread). A
  240.     // call to _NSAutoreleaseHighWaterLog() is generated every multiple
  241.     // of 'res' objects above the high water mark. If 'res' is zero
  242.     // (the default), only one call to _NSAutoreleaseHighWaterLog() is
  243.     // made, when the high water mark is reached. The "default default"
  244.     // value can be set in the initial environment when a program is
  245.     // launched with the NSAutoreleaseHighWaterResolution environment
  246.     // variable (see notes at the top of this file) -- as thread
  247.     // pool-stacks are created, they take their initial high water
  248.     // resolution value from that environment variable. See also
  249.     // +setPoolCountHighWaterMark:.
  250.  
  251.  
  252. // Obsolete API.  Use the methods above instead.
  253. + (void)enableDoubleReleaseCheck:(BOOL)enable;
  254.     // Use +enableFreedObjectCheck:
  255. + (void)showPoolsWithObjectIdenticalTo:(id)object;
  256.     // Use +showPools
  257. + (void)setPoolCountThreshold:(unsigned)count;
  258.     // Equivalent to:
  259.     //    [NSAutoreleasePool setPoolCountHighWaterMark:count];
  260.     //    [NSAutoreleasePool setPoolCountHighWaterResolution:count];
  261.  
  262. @end
  263.  
  264. /****************    Statistics-keeping    ****************/
  265.  
  266. // The statistics-keeping facilities generate output on various
  267. // types of events. Currently, output logs can be generated for
  268. // use of the zone allocation functions (NSZoneMalloc(), etc.),
  269. // allocation and deallocation of objects (and other types of
  270. // lifetime-related events), and for use of the notification
  271. // facilities (NSNotificationCenter). Currently, also, the output
  272. // generated is in a columnar ASCII form, to make it most
  273. // convenient to use command-line data processing utilities,
  274. // like 'awk', 'grep', 'sed', or 'perl'.
  275.  
  276. // The boolean enabling variables can be set in a program, perhaps
  277. // "around" a section of code that is of interest, and the values
  278. // can also be given a non-default initial state by placing special
  279. // environment variables into a process's initial environment (see
  280. // notes at the top of this file). The names of those environment
  281. // variables are the same as the names of the enabling variables.
  282.  
  283. // The destination of the output can be controlled somewhat by
  284. // setting the values of the "FD" variables below, either at runtime
  285. // or in the environment, as described above.
  286.  
  287. FOUNDATION_EXPORT BOOL NSKeepNotificationStatistics;
  288.     // Default is NO.  NOTE:  There is no documentation on the
  289.     // format of the notification statistics output at this time
  290.     // (but the format is similar to that of the zone and
  291.     // allocation statistics output).
  292.  
  293. FOUNDATION_EXPORT int NSNotificationStatisticsFD;
  294.     // Number of open file descriptor to which output will be
  295.     // written, currently using write(). By default, a file
  296.     // called "note_stats_<name>_<pid>" (where <name> is the
  297.     // process name and <pid> is the process id) is created in
  298.     // the platform's temporary directory when first needed.
  299.     // If this variable is set to -1, no output is generated.
  300.  
  301. FOUNDATION_EXPORT unsigned int NSNotificationStatisticsOutputVersion;
  302.     // Not currently used.
  303.  
  304.  
  305. FOUNDATION_EXPORT BOOL NSKeepZoneStatistics;
  306.     // Default is NO.
  307.  
  308. FOUNDATION_EXPORT int NSZoneStatisticsFD;
  309.     // Number of open file descriptor to which output will be
  310.     // written, currently using write(). By default, a file
  311.     // called "zone_stats_<name>_<pid>" (where <name> is the
  312.     // process name and <pid> is the process id) is created in
  313.     // the platform's temporary directory when first needed.
  314.     // If this variable is set to -1, no output is generated.
  315.  
  316. #if !defined(STRICT_41) && !defined(STRICT_40)
  317.  
  318. FOUNDATION_EXPORT unsigned int NSZoneStatisticsOutputVersion;
  319.     // Specifies the output format version. The default is 16.
  320.     // Other valid values are 18 and 0.  Version 18 has the
  321.     // same format as version 16, except that a numeric
  322.     // "backtrace" of the return instruction pointers is
  323.     // appended to every output line (see detailed format
  324.     // description below for more information). Version 0
  325.     // specifies the obsolete 4.0/4.1 output version. Note
  326.     // that NSZoneStatisticsOutputMask is not used by
  327.     // version 0.
  328.  
  329. FOUNDATION_EXPORT unsigned short NSZoneStatisticsOutputMask;
  330.     // Bit-mask specifying zone events to log.  See the
  331.     // defines below. The default value is 0xFFFF.
  332.  
  333. #endif
  334.  
  335.  
  336. FOUNDATION_EXPORT BOOL NSKeepAllocationStatistics;
  337.     // Default is NO.
  338.  
  339. FOUNDATION_EXPORT int NSAllocationStatisticsFD;
  340.     // Number of open file descriptor to which output will be
  341.     // written, currently using write(). By default, a file
  342.     // called "alloc_stats_<name>_<pid>" (where <name> is the
  343.     // process name and <pid> is the process id) is created in
  344.     // the platform's temporary directory when first needed.
  345.     // If this variable is set to -1, no output is generated.
  346.  
  347. #if !defined(STRICT_41) && !defined(STRICT_40)
  348.  
  349. FOUNDATION_EXPORT unsigned int NSAllocationStatisticsOutputVersion;
  350.     // Specifies the output format version. The default is 16.
  351.     // Other valid values are 18 and 0.  Version 18 has the
  352.     // same format as version 16, except that a numeric
  353.     // "backtrace" of the return instruction pointers is
  354.     // appended to every output line (see detailed format
  355.     // description below for more information). Version 0
  356.     // specifies the obsolete 4.0/4.1 output version. Note
  357.     // that NSAllocationStatisticsOutputMask is not used by
  358.     // version 0.
  359.  
  360. FOUNDATION_EXPORT unsigned short NSAllocationStatisticsOutputMask;
  361.     // Bit-mask specifying zone events to log.  See the
  362.     // defines below. The default value is 0xFFFF.
  363.  
  364. #endif
  365.  
  366. #define NSZoneMallocEventMask            (1 << 0)
  367. #define NSZoneCallocEventMask            (1 << 1)
  368. #define NSZoneReallocEventMask            (1 << 2)
  369. #define NSZoneFreeEventMask            (1 << 3)
  370. #define NSVMAllocateEventMask            (1 << 4)
  371. #define NSVMDeallocateEventMask            (1 << 5)
  372. #define NSVMCopyEventMask            (1 << 6)
  373. #define NSZoneCreatedEventMask            (1 << 7)
  374. #define NSZoneRecycledEventMask            (1 << 8)
  375.  
  376. #define NSObjectAllocatedEventMask        (1 << 0)
  377. #define NSObjectDeallocatedEventMask        (1 << 1)
  378. #define NSObjectCopiedEventMask            (1 << 2)
  379. #define NSObjectAutoreleasedEventMask        (1 << 3)
  380. #define NSObjectExtraRefIncrementedEventMask    (1 << 4)
  381. #define NSObjectExtraRefDecrementedEventMask    (1 << 5)
  382. #define NSObjectInternalRefIncrementedEventMask    (1 << 6)
  383. #define NSObjectInternalRefDecrementedEventMask    (1 << 7)
  384. #define NSObjectPoolDeallocStartedEventMask    (1 << 8)
  385. #define NSObjectPoolDeallocFinishedEventMask    (1 << 9)
  386.  
  387.  
  388. /* The format of the zone and object allocation statistics output
  389.  
  390. The output format of versions 16 and 18 of the zone and object allocation
  391. recording facility is given by:
  392.  
  393.     TIME EVENT ZONE PTR SIZE NEWPTR|RC|DSTPTR|GRAN CLASS|CANFREE [ @ RETPCS... ]
  394.  
  395. Each column in the output is separated by whitespace.  The first 7
  396. columns are always present in the output (but may not be meaninngful).
  397. The columns are:
  398.     TIME    The time in seconds since the reference date for NSDate
  399.             (2001-01-01 00:00:00 GMT), as a floating point number.
  400.             This number is negative for dates before the reference date.
  401.  
  402.     EVENT   One of the following strings (the associated mask for the output
  403.             mask variables, described above, is given in parenthesis):
  404.     For object allocation events:
  405.             OALLOC    Object allocated (NSObjectAllocatedEventMask)
  406.             OFREE    Object deallocated (NSObjectDeallocatedEventMask)
  407.             OCOPY    Object copied with NSCopyObject() (NSObjectCopiedEventMask)
  408.             OAUTO    Object autoreleased (NSObjectAutoreleasedEventMask)
  409.             OREF+    Object external ref. count ++ (NSObjectExtraRefIncrementedEventMask)
  410.             OREF-    Object external ref. count -- (NSObjectExtraRefDecrementedEventMask)
  411.             OIREF+    Object internal ref. count ++ (NSObjectInternalRefIncrementedEventMask)
  412.             OIREF-    Object internal ref. count -- (NSObjectInternalRefDecrementedEventMask)
  413.             AFREE_START    NSAutoreleasePool dealloc start (NSObjectPoolDeallocStartedEventMask)
  414.             AFREE_END    NSAutoreleasePool dealloc end (NSObjectPoolDeallocFinishedEventMask)
  415.     For zone events:
  416.             ZMALLOC    Call to NSZoneMalloc() (NSZoneMallocEventMask)
  417.             ZCALLOC    Call to NSZoneCalloc() (NSZoneCallocEventMask)
  418.             ZREALLOC    Call to NSZoneRealloc() (NSZoneReallocEventMask)
  419.             ZFREE    Call to NSZoneFree() (NSZoneFreeEventMask)
  420.             VMALLOC    Call to NSAllocateMemoryPages() (NSVMAllocateEventMask)
  421.             VMFREE    Call to NSDeallocateMemoryPages() (NSVMDeallocateEventMask)
  422.             VMCOPY    Call to NSCopyMemoryPages() (NSVMCopyEventMask)
  423.             ZCREATE    Call to NSCreateZone() (NSZoneCreatedEventMask)
  424.             ZRECYCLE    Call to NSRecycleZone() (NSZoneRecycledEventMask)
  425.  
  426.     ZONE    The zone of the operation as a hex number for the zone events;
  427.         "0" for the VMALLOC, VMFREE, and VMCOPY events. The zone as a
  428.         hex number of the object for object allocation events.
  429.  
  430.     PTR     The pointer of the operation as a hex number for zone events. The
  431.         pointer to the object as a hex number for object allocation events.
  432.  
  433.     SIZE    The size of the memory (bytes) in the operation as a decimal
  434.         number. This field is valid for the OALLOC, OCOPY, ZMALLOC,
  435.         ZCALLOC, ZREALLOC, VMALLOC, VMFREE, VMCOPY, and ZCREATE events;
  436.         it is "0" for all other events.
  437.  
  438.         For the OALLOC and OCOPY events, it is the total size of the object
  439.         allocated (including the extra bytes requested); for the ZMALLOC
  440.         and ZCALLOC events, it is the size of the block allocated; for the
  441.         ZREALLOC event, it is the new size of the block; for the VMALLOC,
  442.         VMFREE, and VMCOPY events, this field is the number of bytes; and
  443.         for the ZCREATE events it is the starting size of the zone.
  444.  
  445.     NEWPTR|RC|DSTPTR|GRAN
  446.         Miscellaneous field. For OCOPY and ZREALLOC, this is the new
  447.         pointer; for OREF+ and OIREF+ events, this is the (external,
  448.         internal) reference count of the object after incrementing;
  449.         for OREF- and OIREF- events, this is the (external, internal)
  450.         reference count of the object before decrementing; for VMCOPY,
  451.         the destination pointer; and for ZCREATE, it is the granularity
  452.         of the zone. For all other events, this field is "0".
  453.  
  454.     CLASS|CANFREE
  455.         For object allocation events, this is the class name of the object
  456.         the event is about. For the ZCREATE event, it is "YES" or "NO",
  457.         describing whether or not the zone frees memory. For all other zone
  458.         events, and for the AFREE_START and AFREE_END events, it is
  459.         "-".
  460.  
  461. Output version 18 adds a return address backtrace at the end of each line:
  462.  
  463.     @ RETPCS...
  464.         A literal "@" appears in the eigth column followed by the return
  465.         address backtrace, giving the return addresses (as hexidecimal
  466.         numbers) on the procedure call stack, the most recent frame on
  467.         the left. The last value in this list is "0".
  468.  
  469. Not all classes implement an internal reference count, and not all of those
  470. that do emit OIREF+ and OIREF- events.  Note also that NeXT's frameworks do
  471. not exclusively use the zone routines to allocate and free memory, although
  472. the Foundation does (except at the lowest level where the zone routines may
  473. be implemented in terms of the system's malloc package on some platforms).
  474.  
  475. Note: Output format version 0 is undocumented.
  476.  
  477. */
  478.  
  479. /****************    Retain count monitoring        ****************/
  480.  
  481. FOUNDATION_EXPORT BOOL NSNegativeRetainCheckEnabled;
  482.  
  483. FOUNDATION_EXPORT void _NSNegativeRetain(void *object, int virtual_retains);
  484.     // Called when an object being autoreleased or released is
  485.     // about to have less than zero virtual retains. The virtual
  486.     // retain count is the number of real retains on the object
  487.     // minus the number of times the object occurs in all autorelease
  488.     // pools in all threads. This check is enabled by setting the
  489.     // environment variable "NSNegativeRetainCheckEnabled" as
  490.     // explained above, or by setting NSNegativeRetainCheckEnabled
  491.     // flag to YES. This uses the allocation statistics facility
  492.     // described above, and so requires NSKeepAllocationStatistics
  493.     // to be YES. If the output of the allocation statistics
  494.     // facility is not desired, set NSAllocationStatisticsFD to -1,
  495.     // either via the environment or in the debugger or code. Note
  496.     // that this facility does not indicate which autorelease or
  497.     // release of the object is extraneous; it is not necessarily
  498.     // the one which makes the virtual retain count negative, nor
  499.     // one that occurs while the virtual retain count is negative.
  500.     // Note also that an extraneous release may cause an object to
  501.     // be deallocated without its virtual retain count becoming
  502.     // negative.
  503.  
  504. #endif /* !STRICT_OPENSTEP */
  505.