home *** CD-ROM | disk | FTP | other *** search
/ The Fred Fish Collection 1.5 / ffcollection-1-5-1992-11.iso / ff_disks / 200-299 / ff280.lzh / Graph / tracker.readme < prev    next >
Text File  |  1989-11-20  |  7KB  |  131 lines
  1. [even though in an alpha state, I think this will be of great use to
  2.  Aztec C programmers who want to be sure they're freeing all of their
  3.  memory -karl]
  4.  
  5.  
  6. C Programmer's Amiga Resource Tracking Routines    Version 0.0a   1/5/89
  7. -------------------------------------------------------------------------
  8.  
  9. This code and documentation is released to the Public Domain without any
  10. restrictions on use, resale or redistribution.
  11.  
  12. No license or warranty of appropriateness, usefulness or bug-freeness is
  13. expressed or implied.   This is free code.  We don't have a contract.
  14.  
  15. Written by:
  16.  
  17. Karl Lehenbauer, Hackercorp, 3918 Panorama, Missouri City, TX, USA  77459
  18. (713) 438-4964 voice,  (713) 438-5018 data
  19. Usenet: uunet!sugar!karl, Internet: karl@sugar.uu.net, BIX: kelehen
  20.  
  21.  
  22. These routines were written to aid C programmers in insuring that their
  23. programs are  properly returning all the memory, signals and locks they
  24. have allocated.
  25.  
  26. To use them, include tracker.h in your C source programs and recompile.
  27. (The use of an "includes.c" along with the Manx +i and +h flags to
  28. precompile the symbol table obviates the necessity of editing
  29. '#include "tracker.h"' into every one of your source files.)
  30. Next, edit your exit routine to call TrackerExitReport() after it has
  31. freed everything.  Then, compile tracker.c using the memory model you're
  32. using for the rest of your code and link your program to include tracker.o.
  33. (This can all be done in your makefile if you've got it set up right.)
  34. Finally, run your program.
  35.  
  36. The program must either be initiated from the CLI or you must edit your
  37. program's startup code to fopen stderr and direct it somewhere  (like
  38. to a  window or a file) or you won't get any of the resource tracker's
  39. messages, or worse.
  40.  
  41. As your program runs, every time it allocs memory via AllocMem(), allocs
  42. a signal via AllocSignal() or gets a Lock via Lock(), special tracking
  43. routines execute instead (thanks to some macros defined by tracker.h)
  44. which, in addition to performing the action you requested, record
  45. information about what you requested and what you got.  For AllocMem(),
  46. the source file and line of the AllocMem call as well as the amount of memory
  47. requested and the pointer to the memory returned are recorded.  For
  48. AllocSignal(), only the signal numbers allocated are recorded at this time.
  49. For Lock(), the file name to be locked, source file and line number and
  50. the lock returned are recorded.
  51.  
  52. When your program frees memory via FreeMem(), a special tracking version
  53. of FreeMem is executed that searches the list of entries recorded by the
  54. tracking version of AllocMem().  The resource tracker reports if you free
  55. something more than once, if you free something that you didn't allocate
  56. or if the length that you are freeing differes from what you allocated.
  57. This includes the source file name and line number of the matching AllocMem
  58. (when it is known) and always includes the source file and line for FreeMem.
  59.  
  60. When your program frees a signal via FreeSignal(), a tracking version
  61. of FreeSignal checks to see if you have allocated the signal you are
  62. now freeing.  If you haven't, it reports it, but it doesn't include the
  63. file name and line number at this time.  I don't think this is a serious
  64. problem, as signals aren't as critical as the other stuff, but I may add
  65. it in a future version.
  66.  
  67. When your program unlocks a lock via UnLock(), a tracking version of UnLock
  68. searches the list of recorded locks to see if you locked the lock you are
  69. unlocking and report accordingly.
  70.  
  71. The tracker exit report provided by TrackerExitReport() is where most of
  72. the bugs are identified.  TrackerExitReport identifies all AllocMems that
  73. didn't have a corresponding FreeMem, including the source file and line
  74. of the call to AllocMem as well as the address and size of the memory
  75. in question.  The resource tracker does not free the memory for you because
  76. you may have not freed the memory on purpose (for example, you may have
  77. spawned a task that uses it will free it later) and it cannot know that.
  78.  
  79. The exit report details all signals that weren't freed.  This isn't very
  80. important, in my opinion.
  81.  
  82. Also, the exit report prints information on all file locks that were made
  83. that didn't have a corresponding UnLock.  This information includes the
  84. name of the file, value of the lock and the source file and line of the
  85. code that locked it.
  86.  
  87. The exit report also prints the number of calls to allocate and free memory,
  88. allocate and free signals and to lock and unlock files as a gross indicator
  89. of whether you're cleaning everything up properly.
  90.  
  91. Note that, in the default configuration, memory that is freed and
  92. reallocated will screw up the tracker because the tracker continues
  93. to track memory objects after they have been  freed. This is a tradeoff
  94. between being to be able to detect multiple frees of the same memory or
  95. not.  If that's a problem, tracker.c can be recompiled with a
  96. -DFORGET_MEMORY_WHEN_FREED option so that it will not try to detect
  97. multiple frees.
  98.  
  99. The same is true for the lock tracking routines, although in that case
  100. the argument is more clear that unlocks should cause the lock tracking
  101. entry to be discarded, because multiple unlocks are common and multiple
  102. locks and unlocks of the same file  during execution are also conceivably
  103. pretty common.  Right now by default, the tracker will track locks after
  104. they have been freed.   To change this behavior, recompile tracker.c with
  105. the -DFORGET_LOCKS_WHEN_UNLOCKED option.
  106.  
  107. Unfortunately, the tracker macros that redefine AllocMem and such will
  108. cause your compiler to barf on any files you have that declare them
  109. as external.  If that happens, either remove the external declarations
  110. (and include <functions.h>) or move them to be before the include of
  111. tracker.h.
  112.  
  113.  
  114. ALPHA RELEASE, SOFTWARE STATUS
  115. ------------------------------
  116.  
  117. The Lock, Unlock and DupLock tracking routines have not been tested
  118. adequately.  The signal stuff works OK, but that's no biggie.  The
  119. main thing of interest is the tracking AllocMem and FreeMem, which
  120. I have used successfully on several programs that I have been working
  121. on.
  122.  
  123. -karl @ The Hacker's Haven, Houston, TX -- 5-Jan-89
  124.  
  125. P.S.  Note that TrackerExitReport() must be called to get the tracking
  126.  routines to free the memory they have allocated, so it's a good idea
  127.  to call it from your abnormal exit (_abort, etc) routines as well as
  128.  normal exit.   Also, that's good because you can make sure you're freeing
  129.  properly from your strange abort conditions, a thing that's hard to get
  130.  right.
  131.