home *** CD-ROM | disk | FTP | other *** search
/ Power-Programmierung / CD1.mdf / pascal / library / dos / tug__002 / tpstack.doc < prev    next >
Encoding:
Text File  |  1988-08-08  |  4.5 KB  |  129 lines
  1. TUG PDS CERT 1.01 (Documentation)
  2.  
  3. ==========================================================================
  4.  
  5.                   TUG PUBLIC DOMAIN SOFTWARE CERTIFICATION
  6.  
  7. The Turbo User Group (TUG) is recognized by Borland International as the
  8. official support organization for Turbo languages.  This file has been
  9. verified by the TUG library staff.  We are reasonably certain that the
  10. information contained in this file is public domain material, but
  11. it is also subject to any restrictions applied by its author.
  12.  
  13. This diskette contains information determined to be in the PUBLIC
  14. DOMAIN, provided as a service of TUG for the use of its members.  The
  15. Turbo User Group will not be liable for any damages, including any lost
  16. profits, lost savings or other incidental or consequential damages arising
  17. out of the use of or inability to use the contents, even if TUG has been
  18. advised of the possibility of such damages, or for any claim by any
  19. other party.
  20.  
  21. To the best of our knowledge, the information in this file is accurate.
  22.  
  23. If you discover an error in this file, we would appreciate it if you would
  24. report it to us.  To report bugs, or to request information on membership
  25. in TUG, please contact us at:
  26.  
  27.              Turbo User Group
  28.              PO Box 1510
  29.              Poulsbo, Washington USA  98370
  30.  
  31. --------------------------------------------------------------------------
  32.                        F i l e    I n f o r m a t i o n
  33.  
  34. * DESCRIPTION
  35. Documentation file for TPSTACK.PAS.
  36.  
  37. * ASSOCIATED FILES
  38. TPSTACK.PAS
  39. TPSTACK.ASM
  40. TPSTACK.DOC
  41. TPSTACK.OBJ
  42.  
  43. * CHECKED BY
  44. DRM - 08/08/88
  45.  
  46. * KEYWORDS
  47. TURBO PASCAL V4.0 DOCUMENTATION
  48.  
  49. ==========================================================================
  50. }
  51. TPSTACK - Unit for Monitoring Heap and Stack Usage
  52. -------------------------------------------------------
  53. Brian Foley
  54. TurboPower Software
  55. 6/88
  56. Version 1.00
  57. Released to the public domain
  58.  
  59. Overview
  60. ------------------------------------------------------------------------------
  61. TPSTACK allows you to accurately monitor a program's stack and heap usage
  62. simply by adding TPSTACK to the beginning of the program's USES list. The
  63. following program demonstrates how to use it:
  64.  
  65.   program TpStackTest;
  66.     {-Simple program to test TpStack}
  67.   uses
  68.     TpStack,
  69.     CRT;
  70.   var
  71.     P : Pointer;
  72.  
  73.     procedure StackEater;
  74.       {-Use some stack space}
  75.     var
  76.       BigArray : array[1..12331] of Byte; {this is on the stack}
  77.     begin
  78.       {delay a moment to insure that TpStack sees what we've used}
  79.       Delay(10);
  80.     end;
  81.  
  82.   begin
  83.     {use some stack and heap space}
  84.     GetMem(P, 56789);
  85.     StackEater;
  86.   end.
  87.  
  88. If you run this little demo program, you'll see that TpStack automatically
  89. displays the amount of heap and stack space used by the program when it ends.
  90.  
  91. Normally it is just this easy. In some cases, however, you may want or need to
  92. handle the reporting of results yourself. If so, you would set
  93. ReportStackUsage to False and call CalcStackUsage to obtain the necessary
  94. information.
  95.  
  96. If you want to disable stack monitoring temporarily--when executing other
  97. programs, for example--you can call RestoreInt8 to disable it and InstallInt8
  98. to reenable it.
  99.  
  100. TpStack can monitor only a single stack segment, normally the one in use when
  101. the program began. If you need to use it in a program that uses an alternate
  102. stack (a memory resident program, perhaps), you'll have to initialize three
  103. global variables before the first time that you switch to that stack. Here's
  104. an example:
  105.  
  106.    {disable TpStack momentarily}
  107.    RestoreInt8;
  108.    {OurSS has the stack segment to watch}
  109.    OurSS := AlternateStackSegment;
  110.    {InitialSP has the value of "SP" when the program began}
  111.    InitialSP := TopOfAlternateStack;
  112.    {LowestSP has the lowest value of SP so far, same as InitialSP at first}
  113.    LowestSP := InitialSP;
  114.    {reactivate TpStack}
  115.    InstallInt8;
  116.  
  117. Finally, in order to improve the accuracy of its results, TpStack reprograms
  118. the timer chip so that it can get control of the machine over 1000 times a
  119. second. For this reason, TpStack should not be used in programs that
  120. themselves reprogram the chip, or in programs that are using the PEP unit in
  121. Turbo Analyst. If you wish to change the rate at which samples are taken, you
  122. can call the SetSampleRate routine:
  123.  
  124.    {select 100 samples per second}
  125.    SetSampleRate(100);
  126.  
  127. The minimum value allowed is 18 samples per second, which is what the rate
  128. would be TpStack didn't reprogram the timer.
  129.