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 < prev    next >
Encoding:
Text File  |  1992-10-31  |  12.8 KB  |  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 normal way,
  186. but closes itself through some sort of internal call which I am not able
  187. to track.
  188.  
  189.     Chunks of memory which are allocated but not freed and have a
  190. return address in the range of $F80000-$FFFFFF are being allocated by the
  191. system and will be freed at a later time unless they were allocated as
  192. say part of a window which was opened, but not closed.
  193.  
  194.     All programs should be able to have four or less SegList elements
  195. unless they are leaving behind a particular element which is part of
  196. a new process, some sort of code or data which is intentionally being
  197. left behind after the process terminates or code or data that was
  198. loaded as part of an overlay operation.  If your program does not fall
  199. into one of these categories and you have more than four SegList
  200. elements, then you may be linking less efficiently than you otherwise
  201. could.  There is absolutely NO excuse for SegList elements of size
  202. zero being loaded.  These are generally unused BSS data hunks that
  203. can be eliminated through proper linking (this may be because you have
  204. a poor linker e.g. Alink).
  205.  
  206.     CodeWatcher is compatible with both the pre 2.0 and 2.0/3.0 releases of
  207. the dos.library which have data stored in a different format in the
  208. library code vectors.
  209.  
  210.     Programs that SetFuntion certain library vectors and do not undo
  211. the SetFunction before exiting will cause the system to die a horrible
  212. death.
  213.  
  214.     Another useful function of CodeWatcher is to make sure that
  215. programs do not rely on the settings of the condition codes as error
  216. flags.  When CodeWatcher returns after a system call, the value of
  217. the condition codes and the contents of the scratch registers D1, A0
  218. and A1 are almost always different from the "normal" system return
  219. values which should not be relied upon, but which some programs do.
  220. Programs which terminate for some "unknown" reason when run under
  221. CodeWatcher, but function normally when run without CodeWatcher are
  222. usually relying on the scratch registers or condition codes for
  223. return values from the system rather than checking D0.  An example of
  224. this is the pre-2.0 dos.library which returns the same value in D1 as
  225. D0.  In this case, some programs are relying on D1 rather than D0
  226. for return values.  This should NEVER be done, and these programs
  227. may very well break under AmigaDOS 2.0.
  228.  
  229.  
  230. -------- 1.3 to 1.4 changes
  231.  
  232.     Miscellaneous internal.
  233.  
  234. -------- 1.2 to 1.3 changes
  235.  
  236.     The "Rem:" output of Task reports now tells exactly how a task
  237.         terminated: RemTask(0) if the task exited by calling RemTask(0)
  238.         (Processes created by CreateProc() seem to do this), RemTask()ed
  239.         if it was removed by RemTask() but not by itself, and RTS if it
  240.         simply did an RTS from its toplevel routine.
  241.  
  242.     Fixed a couple of bugs with respect to processes that did SegList
  243.         detaching through the cli_Module. Should now work well with
  244.         any method of SegList splitting/detachment.
  245.  
  246.     Fixed a problem where a process would spawn children, exit, my requester
  247.         would appear, all children would exit before you select "Yes" or
  248.         "No" from the requester, and as a result the CLI would be hung.
  249.  
  250. -------- 1.1 to 1.2 changes
  251.  
  252.     Child tasks that were not terminated by RemTask() were always reported
  253.         as not having terminated, when they really had. This has been fixed,
  254.         and in addition, you can opt to have CodeWatcher stop monitoring
  255.         if the main process quits but there are still children active.
  256.  
  257.     The Hunk and offset info has been added to the memory tracking.
  258.  
  259.     Stack usage is now monitored.
  260.  
  261. -------- 1.0 to 1.1 changes
  262.  
  263.     Font resource tracking added.
  264.  
  265.     Task resource tracking added.
  266.  
  267.     Interrupt Server resource tracking added.
  268.  
  269.     Field labels in the output were shortened to prevent line wrapping as
  270.         much as possible.
  271.  
  272.     Unnamed ports which were not removed are given the name "UNNAMED" in
  273.         the output (as are Tasks and Interrupt Servers).
  274.  
  275.     All added ports are listed in the output with the addition of the
  276.         Pri and Rem fields.
  277.  
  278.     CTRL-C/D/E/F now passed to child process.
  279.  
  280.     Internal cleaning and re-coding.
  281.  
  282.     Cleaned up this document.
  283.  
  284. -------- To Be Done
  285.  
  286.     Allow tracking of child processes/tasks.
  287.  
  288.     Allow processes to be launched as though from Workbench.
  289.  
  290.     Allow user selection of memory free checking method.
  291.  
  292. --------
  293.  
  294.     This program is placed in the public domain. If there is sufficient
  295. interest, periodic updates will be posted. Feel free to suggest any new
  296. types of resources to be tracked and, of course, bugs. I have been
  297. using this code to check resource management for several years and have
  298. found it to be reliable in all situations except those specified above
  299. and through all OS revisions from 1.3 to 3.0.
  300.  
  301.  
  302. Please direct all inquiries to:
  303.  
  304. Michael Plitkins
  305.  
  306. Until end of November 1992:
  307.  
  308. 110 Oak Rim Ct. #29
  309. Los Gatos, CA  95032
  310.  
  311. (408) 356-8067
  312.  
  313. After November 1992 ("permanent address no matter where in the world I
  314. might really be :-)"):
  315.  
  316. 1 Woolheater rd.
  317. Fleischmanns, NY  12430
  318.  
  319. (914) 254-5310
  320.  
  321. bix: octree
  322.