home *** CD-ROM | disk | FTP | other *** search
/ RISC DISC 2 / RISC_DISC_2.iso / pd_share / program / code / stubshack / HeapGraph / !Help next >
Encoding:
Text File  |  1995-01-08  |  6.0 KB  |  184 lines
  1. HeapGraph version 1.10 01 24 Nov 1994
  2. -------------------------------------
  3.  
  4.  
  5.  
  6. Introduction
  7. ------------
  8.  
  9. This is a C library which uses my StubsHack library to provide a
  10. very simple way of making your program send information on every block
  11. of memory allocated/freed to a file in pipe:$.C_Debug. This is scanned
  12. by the included application !HeapDisp, which displays your program's
  13. heap graphically in real time.
  14.  
  15. Also provided is a simple way of sending diagnostic text to !HeapDisp.
  16.  
  17.  
  18.  
  19. Installation
  20. ------------
  21.  
  22. You should move the HeapGraph directory into your C path. Don't move any
  23. headers into an existing .h. directory, as they are refered to as
  24. 'HeapGraph.<headername>.h' in the source. 
  25.  
  26. I find this to be a much simpler way of organising C libraries than
  27. changing C$Path etc. It also protects against problems when header files
  28. from different libraries have the same name.
  29.  
  30. The actual library is 'HeapGraph.o.HGLib'.
  31.  
  32. Please note that HeapGraph needs my 'StubsHack' library to work.
  33.  
  34.  
  35.  
  36. To use in your own programs
  37. ---------------------------
  38.  
  39. HeapGraph is dead easy to use. Just include "HeapGraph.HeapGraph.h" in
  40. the source-file which contains your main() function and then, at the
  41. start of main, put a 'HeapGraph_RedirectAllocFns( NULL);'.
  42.  
  43. Then predefine HEAPGRAPH by putting '-DHEAPGRAPH' as one of the
  44. arguments to the C compiler (if you don't do this, the preprocessor will
  45. remove any HeapGraphRedirectAllocFns() statements).
  46.  
  47. Link with HeapGraph.o.HGLib and StubsHack.o.SHLib (in that order, since
  48. HeapGraph refers to things in StubsHack).
  49.  
  50. Compile/link your program, run the program !Displayer, and start your
  51. program. Your program's heap will be dynamically displayed in one of
  52. !Displayer's windows.
  53.  
  54. If you do a '*Filer_OpenDir Pipe:$.C_Debug' from the command line, you
  55. will see the pipe file being created/emptied as the program runs.
  56.  
  57. An example program is provided which uses HeapGraph - it runs a program
  58. in a TaskWindow which continuously allocates/frees memory. !Displayer
  59. will show the blocks of memory moving around. HeapGraph also works
  60. perfectly with Wimp programs - in fact it should work with anything that
  61. can write to the pipe filing system.
  62.  
  63.  
  64.  
  65. Sending diagnostic info
  66. -----------------------
  67.  
  68. To send text to !HeapDisp, #include "HeapGraph.Debug.h" and use
  69. 'Debug_Printf(...)'. Also, you should predefine 'HEAPGRAPH_DEBUG' with
  70. -DHEAPGRAPH_DEBUG as a parameter to your C compiler. 
  71.  
  72. If you don't predefine HEAPGRAPH_DEBUG, all Debuf_Printf()'s will be
  73. removed by the preprocessor.
  74.  
  75. HeapGraph_Sendf is identical to Debug_Printf, except whether or not it
  76. works depends on whether you predefine HEAPGRAPH, rather than
  77. HEAPGRAPH_DEBUG.
  78.  
  79.  
  80.  
  81. HEAPGRAPH and HEAPGRAPH_DEBUG
  82. -----------------------------
  83.  
  84. It may seem a pain to have to predefine HEAPGRAPH and HEAPGRAPH_DEBUG in
  85. order to use the HeapGraph library. However, this enables you to put
  86. 'HeapGraph_RedirectAllocFns()' and lots of 'Debug_Printf's in your code,
  87. and link with C:HeapGraph.o.HGLib, safe in the knowledge that all the
  88. HeapGraph stuff will completely disapear during pre-processing when you
  89. compile (and the linker will not link in the HeapGraph library), unless
  90. you specifically predefine HEAPGRAPH and/or HEAPGRAPH_DEBUG. 
  91.  
  92. Hence you can make different versions of a program without changing the
  93. source, or messing around with '#ifdef HEAPGRAPH_DEBUG's in your code.
  94. All this sort of stuff is in HeapGraph.h - have a look to convince
  95. yourself that not predefining HEAPGRAPH(_DEBUG) will result in a
  96. completely 'clean' compile.
  97.  
  98. There is one slight exception to this if you're making a DDT-version of
  99. your program, as CC will turn off all optimisations. In this case,
  100. Debug_Sendf/Printf(...) will be compiled as 'if (0)
  101. HeapGraph_Dummyf(...)' and this won't be optimsed out. Because of this,
  102. your program will be linked with the tiny HeapGraph.Sources.c.Dummyf
  103. file. 
  104.  
  105. The reason this happens is that there's no way that I know of having
  106. macros which take a variable number of arguments. 
  107.  
  108.  
  109.  
  110. !HeapDisp
  111. ---------
  112.  
  113. This uses my Shell library and DeskLib, and is not particulaly polished.
  114. If you would like to improve it, it's made available under the GNU
  115. licence, so you must release the source with any released improved
  116. version.
  117.  
  118. !HeapDisp will continuously scan Pipe:$.C_Debug.*. When it finds a file,
  119. it will open a separate window for it - !HeapDisp can display the heap
  120. of any number of programs at the same time. 
  121.  
  122. Text sent with HeapGraph_Sendf/Debugf will be displayed along with the
  123. heap display.
  124.  
  125. Pressing <Shift>-Menu will bring up a save box. If the click was over
  126. text, this text will be saved. If the click was over the picture of the
  127. heap, it will be saved as a sprite. This isn't particulaly useful, but
  128. Shell has the code in it aready, so there's no harm done or programming
  129. time wasted!
  130.  
  131. Pressing Menu will bring up a menu with which you can set the vertical
  132. size of the heap display.
  133.  
  134. The colour of malloc blocks displayed by !HeapDisp can be changed with
  135. HeapGraph_SetReference() - see HeapGraph.h for details.
  136.  
  137.  
  138.  
  139. Random thought...
  140. -----------------
  141.  
  142. It should be possible to display the malloc heap of any program which
  143. uses the Shared C Library, *without* re-linking. A module could
  144. intercept the SharedCLibrary_LibInitAPCS_R SWI, which is called whenever
  145. a sharedclib-using application starts up, and find, from the SWI
  146. parameters, the address of the vector table used to implement the
  147. various SCL functions. Then it should be fairly straightforward to patch
  148. the malloc/calloc/free/realloc branchs to go to a routine in the module
  149. which sends appropriate data to pipefs and then returns to the
  150. application.
  151.  
  152.  
  153.  
  154.  
  155. Other
  156. -----
  157.  
  158. All the contents of the HeapGraph directory are © Julian Smith, 1994.
  159. Feel free to distribute it, but only distribute the original version. If
  160. you make any changes, please send them to me and I'll send them out with
  161. the next release.
  162.  
  163. Any suggestions/comments/bug fixes etc are very much welcomed.
  164.  
  165.  
  166.  
  167. - Julian Smith
  168.  
  169.  
  170. ------------------------
  171. julians@cogsci.ed.ac.uk
  172. ------------------------
  173.  
  174. or:
  175.  
  176. ------------------------
  177. Department of Psychology
  178. University of Edinburgh
  179. 7 George Square
  180. Edinburgh
  181. EH8 9JZ
  182. UK
  183. ------------------------
  184.