home *** CD-ROM | disk | FTP | other *** search
/ Graphics Plus / Graphics Plus.iso / general / raytrace / rayshade / ryshd40n.lha / Doc / StackWatch.doc < prev    next >
Encoding:
Text File  |  1991-06-05  |  6.8 KB  |  154 lines
  1.  
  2. This is StackWatch.  I wrote it because no one else did.
  3.  
  4. Legal Stuff
  5.  
  6. StackWatch ⌐ 1990 by James R. Locker.  All rights reserved.  Feel free to
  7. redistribute this program  so  long  as  you  don't  modify it, you don't
  8. profit by it (except  a  reasonable  disk  copying  charge),  and  you do
  9. include all the documentation.   No  shareware  fee  is  requested, but I
  10. never turn down a contribution.
  11.  
  12. FIRST A WORD FROM OUR SPONSOR
  13.  
  14. VIDEO PROFESSIONALS...Control any Amiga application (such as an animation 
  15. or titling program)  through  the  Amiga's  second  gameport,  from a GPI
  16. controller, or from any other  external  device that can provide a switch
  17. closure.  Automatically synchronize your  animations with another source.
  18. Reduce your workload.  Let the Amiga do the work for you.
  19.  
  20. Contact:
  21.  
  22.  Jim Locker
  23.  Integral Systems Co.
  24.  P.O. Box 31626
  25.  Dayton, Oh 45424
  26.  (513) 237 8290
  27.  
  28.  for information about VidControl and MasterControl.
  29.  
  30. HANDICAPPED USERS...operate the  Amiga  WITHOUT A KEYBOARD.  KeyWhiz (tm)
  31. enables keyboard input to any application  using only a joystick or other
  32. custom input device connected to  the  second gameport.  The entire Amiga
  33. keyboard is supported, and  operation  is transparent to the application.
  34. Contact Integral Systems Co. for information.
  35.  
  36. AND NOW ON WITH THE SHOW
  37.  
  38. What StackWatch does is quite simple.   It monitors the stack of the task
  39. or process that you  select.   It  will  try  to  run  about 30 times per
  40. second, so it will look at your  stack  frequently.   This enables you to
  41. keep a pretty good ongoing record  of  how you are doing, stack-wise.  It
  42. is much faster about updating then, for instance, Xoper.  This is because
  43. its purpose is different than Xoper's  and it is dedicated to one job and
  44. only one job.  It seems to do that one thing fairly well.
  45.  
  46. The Amiga is a  very  stack  intensive  machine.   If  you do not provide
  47. enough stack for your routine, you  will  encounter  intermittent crashes
  48. and peculiar behavior.  Unfortunately,  the operating system doesn't tell
  49. you when you run out of stack, and  most  applications  don't check their
  50. own stack (although some  do...StackWatch,  for  instance, does not watch
  51. its own stack.)
  52.  
  53. If you set your stack up to a huge number, you will probably be safe, but
  54. you are also  wasting  memory.   What  is  needed  is a good way to tell,
  55. dynamically, how any program is  doing.   You  may then tailor your stack
  56. allocations to be more efficient.
  57.  
  58. StackWatch helps you with this.
  59.  
  60. Using StackWatch
  61.  
  62. StackWatch starts from CLI only.  It requires  one command line argument,
  63. which is the name of the task or process to be monitored.  This name must
  64. be entered EXACTLY  as  it  is  maintained  in  the  system  task  lists.
  65. StackWatch is case sensitive, so if  you  use  an upper case letter while
  66. the system knows the task by a lower case letter, it won't work.
  67.  
  68. The syntax is as follows:
  69.  
  70. StackWatch MyTaskName  <RETURN>
  71.  
  72. For instance, 
  73.  
  74. StackWatch Scribble!
  75.  
  76.  will monitor Scribble!.
  77.  
  78. StackWatch will find  Workbench  or  CLI  applications.   An  application
  79. started from Workbench will have  the  exact  name shown on the icon.  An
  80. application started from CLI may be known by a number of different names,
  81. depending upon how it hooks itself into the system.  For instance, if you
  82. start the Calculator utility that is found in the Utilities drawer of the
  83. Workbench  disk  by  clicking   on  its  icon,  it  will  have  the  name
  84. "Calculator" and typing:
  85.  
  86. StackWatch Calculator
  87.  
  88. will get you there.  However, if you start Calculator from the CLI, while
  89. your current directory is the utilities  drawer, then the routine will be
  90. known to the system according to the exact name (including case) that you
  91. invoked it by.   If  you  invoked  it  by  its  full  path name - such as
  92. "sys:utilities/calculator", then  you  must  locate it with StackWatch by
  93. typing:
  94.  
  95. StackWatch sys:utilities/calculator
  96.  
  97. Some utilities - such as PopCLI and  StackWatch  - detach themselves from
  98. the CLI that started them.  These  utilities  tell  the system what their
  99. name is.  StackWatch is known as -  you  guessed it - StackWatch.  PopCLI
  100. has a name that depends on the  revision  number.   If you were to rename
  101. StackWatch - maybe to SW - in order  to  save typing, it would still tell
  102. the system that its name is  StackWatch,  and  you would have to track it
  103. down by that name.
  104.  
  105. The point is that you might have to figure out what name the system knows
  106. your intended target by.  This effort is facilitated by using the utility
  107. Who - which I have provided in this archive.   I did not write it, but it
  108. is useful and it will help you with StackWatch.
  109.  
  110.  
  111. The StackWatch Window
  112.  
  113. Has four lines and a "gas gauge".  The  first line tells you what process
  114. (or task)  StackWatch is  monitoring.   This is useful if you are running
  115. multiple copies of StackWatch.  The second  line tells you what the stack
  116. allocation for that  process  is.   The  third  line  tells  you what the
  117. largest amount of  stack  used  was  at  any  time  since  StackWatch was
  118. invoked.  The fourth line tells you what the stack usage is right now.
  119.  
  120. Below the text is a graphic display.  This "Gas Gauge" tells you - with a
  121. picture - how much of your stack allocation  you are currently using.  It
  122. also has a peak indicator that  tells  you what your peak stack usage has
  123. been .  The peak indicator may move toward  the right of the display, but
  124. it never comes back to the left.   It  is a "high water mark".   The "Gas
  125. Gauge" will indicate stack overflows -  if the color bar slops out of the
  126. box on the right, you  have  overflowed  your  stack.  You may or may not
  127. crash, but it might be a good time to save any critical work in progress.
  128.  
  129. StackWatch limitations
  130.  
  131. Stackwatch  takes  "snapshots"  of  your  process  -  it  is  not looking
  132. continuously.  Therefore, it won't necessarily spot a quick peak in stack
  133. usage.  Caveat Emptor.
  134.  
  135. StackWatch hooks itself into the system  at priority 10, and wants to run
  136. at frequent intervals.  One of the  first  things it does when running is
  137. disable multitasking so it  can  safely  wander  through  the system Task
  138. lists.  As a consequence,  under  certain  circumstances,  or if multiple
  139. copies of StackWatch are running, it can noticeably slow system response.
  140. I thought about providing  a  command  line  option to change the default
  141. priority, but decided not to.  Maybe in the next release.
  142.  
  143. Future upgrades
  144.  
  145. May or may not occur.   If  they  do,  we  might  go shareware...how many
  146. people are interested?
  147.  
  148. I would add Workbench  startup,  with  an  Intuition Requester that would
  149. display all the current tasks in the system and allow you to pick the one
  150. you wanted - this in lieu of a  command  line argument.  Might also add a
  151. pull-down menu to let you change  tasks  on the fly.  Currently, you must
  152. close StackWatch  and  restart  it  to  change  tasks.   Of  course,  the
  153. capability to change priorities would be nice.
  154.