home *** CD-ROM | disk | FTP | other *** search
/ Fresh Fish 5 / FreshFish_July-August1994.bin / bbs / dev / codewatcher-1.4.lha / CodeWatcher-1.4 / code.doc next >
Text File  |  1992-10-31  |  13KB  |  322 lines
  1.  
  2.                                                              31 Oct, 1992
  3.  
  4. CodeWatcher - Resource tracking on an individual program basis
  5.  
  6. This document reflects the version 1.4 release of the software.
  7.  
  8. For a list of 1.0 to 1.4 changes, see the end of this document.
  9.  
  10.  
  11. OVERVIEW
  12.  
  13.     CodeWatcher is a program that creates an environment identical to
  14. that of a CLI under which any application can be executed.  While the
  15. application is executing, all resource allocations and releases are
  16. tracked.  The value of this is that it now becomes a simple matter to
  17. reassure yourself that for example, all memory allocated is freed at
  18. the time of process termination.  Another use is to monitor the
  19. resources used by an existing application if you beleive that bugs
  20. exist in someone else's product, or if you simply want to get a better
  21. idea of what system resources a particular application uses.
  22.  
  23.  
  24. THE PARTICULARS - INVOKING CodeWatcher, AND WHAT IT WILL DO FOR YOU
  25.  
  26.     Starting up CodeWatcher is a simple matter.  At the CLI prompt,
  27. simply type:
  28.  
  29.     CodeWatcher <program name> [arg1, arg2...argN]
  30.  
  31.     where:
  32.  
  33.     <program name> is the name of the program you wish to execute.
  34.     [arg1, arg2...argN] are the arguments required by the program to be
  35.         watched.  CodeWatcher itself has no command line arguments or
  36.         switches.
  37.  
  38.     Programs started under CodeWatcher believe that they are running
  39. under their own CLI processes.  At this time, there is no way to
  40. launch a program as though it came from Workbench.
  41.  
  42.     CodeWatcher can run any Amiga program except for those that have
  43. knowledge of the BCPL internals of AmigaDOS (e.g. most of the commands
  44. in the C: directory of a standard pre-2.0 Workbench disk).  Additionally,
  45. it is not recommended that programs which leave behind a piece of code
  46. in the system which has SetFunction()'ed any library vectors be run
  47. under CodeWatcher.  CodeWatcher begins tracking resources just before
  48. the first instruction of the program is executed and stops tracking
  49. immediately after the last instruction has been executed.  Resources
  50. are tracked only for this particular CLI process, and no others in the
  51. system.  The following resources are tracked:
  52.  
  53.  
  54.     Process/task Address - the address of the Exec task structure.
  55.  
  56.     SegList elements.
  57.  
  58.     Files - any files which were opened, but not not closed are listed
  59.         at process termination time.
  60.  
  61.     Locks - any locks which were obtained through Lock(), DupLock() or
  62.         CreateDir() that were not unlocked are listed.
  63.  
  64.     Sprites - the numbers of any sprites allocated by your program
  65.         which were not freed before exit are output.
  66.  
  67.     Open Fonts - at the time of process termination, a list of all
  68.         fonts accessed by the program will be output.  Any non-zero open
  69.         counts mean that a font was either not closed enough times
  70.         (positive open count) or closed too many times (negative open
  71.         count).
  72.  
  73.     Interrupt Servers - all interrupt servers added by the program will be
  74.         listed.  The list can be used to verify that servers were added
  75.         to the system.  The "Rem" field indicates with a "Yes" or "No"
  76.         whether the server was removed from the system by the program.  In
  77.         the output, the "Interrupt" field is the addres of the Exec interrupt
  78.         structure and "Number" is the number of the custom chip interrupt
  79.         (e.g. 5 is a VERTB interrupt).
  80.  
  81.     Tasks - all tasks launched by the program will be listed.  The list can
  82.         be used to verify that tasks/processes were actually added to the
  83.         system.  The "Rem" field indicates wether the Task was removed by
  84.         the program ("No" - not removed, "Self" removed with RemTask(0) or by
  85.         executing a final RTS, "Yes" - removed).  In the output, some labels
  86.         may seem obscure because they have been made short enough to fit in
  87.         most windows (template is as follows: task name, address, priority,
  88.         initialpc, finalpc, stack addr, removed).
  89.  
  90.     Message Ports - all message ports added to the system wide list by the
  91.         program are tracked, and listed in the output.  The "Rem" field in
  92.         the output is the same as for Interrupt Servers.
  93.  
  94.     Open Libraries - at the time of process termination, a list of all
  95.         shared libraries accessed by the program will be output.  Any
  96.         non-zero open counts mean that a library was either not closed
  97.         enough times (positive open count) or closed too many times
  98.         (negative open count).
  99.  
  100.     Open Devices - when the program exits, a list of all exec devices
  101.         accessed by the program will be output.  Any non-zero open
  102.         counts mean that a device was either not closed enough times
  103.         (positive open count) or closed too many times (negative open
  104.         count).
  105.  
  106.     Memory Allocation - all of the memory allocated and released during
  107.         process execution, both indirectly by system calls and directly
  108.         by calls to Exec's memory management routines are tracked.  Any
  109.         allocations that are outstanding at process termination time,
  110.         are listed including the address of the allocated memory, the
  111.         size, and the return address of the calling routine.  With this
  112.         information, it is easy to determine whether your program is
  113.         directly allocating memory which is not freed or whether the
  114.         system is doing it on your behalf.  NOTE: Partial frees of memory
  115.         blocks are not tracked. To help pin down any offending routines,
  116.         the hunk number and offset into the hunk of the instruction after
  117.         the AllocMem() call are output.
  118.  
  119.     Process MemEntry - the contents of the process MemEntry structure
  120.         are output at termination time.  This structure may contain
  121.         elements that were allocated by the process and specifically
  122.         placed there by the program, and elements entered into the
  123.         structure by AmigaDOS before actually adding the process to the
  124.         system.  All allocations listed here are freed by the system
  125.         when the process is removed.  Thus, this is not truly tracking
  126.         anything, but is here simply for educational purposes, and to
  127.         allay any doubts that elements being added to this structure by
  128.         a program are being added correctly.  Any elements listed both
  129.         here, and in the aformentioned list of memory allocations were
  130.         done directly by your process or by system code which your
  131.         process called and is not part of the memory which was allocated
  132.         by AmigaDOS to actually support your process.
  133.  
  134.     Priority - if the program terminates without restoring the process
  135.         priority to its initial state, it will be noted.
  136.  
  137.     Traps - any traps that remain allocated at termination time are
  138.         noted.
  139.  
  140.     Signal Bits - any signal bits that remain allocated at termination
  141.         time are noted.
  142.  
  143.     Interrupt Disable Count - the value of the interrupt disable count
  144.         as modified by the Enable() and Disable() calls, is output at
  145.         program exit time.
  146.  
  147.     Task Disable Count - the value of the task disable count as modified
  148.         by the Forbid() and Permit() calls, is output at process
  149.         termination time.
  150.  
  151.     Current Directory - if the program exits without restoring the
  152.         current directory to where it was when the program was started,
  153.         it will be noted.
  154.  
  155.     Window Pointer - if the program exits without restoring the process
  156.         window pointer to its initial state, it will be noted.
  157.  
  158.     Stack usage - the amount of stack space used by your program.
  159.  
  160.     Return Code of the watched program.
  161.  
  162.  
  163. WHAT CodeWatcher DOES NOT DO
  164.  
  165.     CodeWatcher will not attempt to release any resources which were
  166. allocated by the process but not freed, because these may still be in
  167. use by the system to be released at a later time, or may be used by
  168. another task or process, or interrupt server which the one that was
  169. being watched launched.
  170.  
  171.     Currently, CodeWatcher only tracks those resources that are
  172. "invisible"  - one cannot tell visually without some sort of aid
  173. whether a resource was allocated and freed or not. An example of a
  174. resource that does not fall into this category is an Intuition Window.
  175.  
  176.  
  177. POINTS OF INTEREST
  178.  
  179.     Do not be alarmed if the tracked code runs a bit slower than normal,
  180. especially when doing things like window resizing, because a linked list
  181. of allocated memory is being maintained.  When allocating and freeing many
  182. tiny chunks searching this list can take some time.
  183.  
  184.     Do not be alarmed by dos.library open counts that are greater than
  185. zero.  It appears that AmigaDOS opens itself in the norm