home *** CD-ROM | disk | FTP | other *** search
/ The Devil's Doorknob BBS Capture (1996-2003) / devilsdoorknobbbscapture1996-2003.iso / Dloads / PROGRAMM / FGL112B.ZIP / USER14.DOC < prev    next >
Text File  |  1992-10-05  |  8KB  |  199 lines
  1.  
  2.  
  3. Chapter 14
  4.  
  5. Program Timing
  6. 248  Fastgraph User's Guide
  7.  
  8.  
  9. Overview
  10.  
  11.      It is occasionally necessary to delay a program's execution for a brief
  12. period, or to determine how long it takes to execute specific sections of a
  13. program.  Fastgraph includes routines to accomplish these tasks.  Some of
  14. these routines are said to be real-time, which means they are independent of
  15. a system's processor speed, while the speed of others is processor-specific.
  16. This chapter describes both classes of timing routines, all of which are
  17. independent of the other parts of Fastgraph.
  18.  
  19.  
  20. Real-Time Routines
  21.  
  22.      Real-time operations center around the BIOS time-of-day clock, which is
  23. nothing more than a counter that the system automatically increments 18.2
  24. times per second.  This number is often called the clock tick interrupt rate
  25. because an interrupt routine performs the incrementing.  In addition, each
  26. increment is usually called a clock tick.
  27.  
  28.      The Fastgraph routine fg_waitfor delays a program's execution by the
  29. number of clock ticks specified as its argument.  Because fg_waitfor uses
  30. clock ticks, the actual length of the delay is the same, regardless of the
  31. system's processor speed.  Even when Fastgraph's asynchronous sound routines
  32. quadruple the clock tick interrupt rate, Fastgraph compensates for this
  33. internally so fg_waitfor always works as though the actual rate were still
  34. 18.2 times per second.
  35.  
  36.      Example 14-1 displays a message every five seconds that states how long
  37. the program has been running.  The fg_waitfor routine produces the five-
  38. second delay by pausing 91 (18.2 times 5) clock ticks before the program
  39. displays each message.  The program returns to DOS when you press any key.
  40.  
  41.                                 Example 14-1.
  42.  
  43.              #include <fastgraf.h>
  44.              #include <stdio.h>
  45.              void main(void);
  46.  
  47.              void main()
  48.              {
  49.                 unsigned int seconds;
  50.                 unsigned char key, aux;
  51.  
  52.                 seconds = 0;
  53.  
  54.                 do {
  55.                    fg_waitfor(91);
  56.                    seconds += 5;
  57.                    printf("%u seconds have elapsed.\n",seconds);
  58.                    fg_intkey(&key,&aux);
  59.                 }
  60.                 while (key+aux == 0);
  61.              }
  62.  
  63.      Another common application of the fg_waitfor routine is to slow down a
  64. loop that uses the fg_intkey routine to check for keystrokes.  In loops that
  65.                                               Chapter 14:  Program Timing  249
  66.  
  67. do little else, we may call fg_intkey too rapidly without this delay, and it
  68. is then possible that the BIOS may not be able to store characters in its
  69. keyboard buffer fast enough.  A small delay, even one clock tick, often helps
  70. such "tight" loops.
  71.  
  72.      The fg_getclock routine provides an efficient way to measure time,
  73. especially differences in time.  This routine has no arguments and returns a
  74. 32-bit unsigned integer (as its function value) representing the number of
  75. clock ticks since midnight.  Example 14-2 demonstrates the fg_getclock
  76. routine.  In response to any keystroke (except Escape, which returns control
  77. to DOS), the program displays the number of clock ticks since midnight, and
  78. the number of ticks since the program started.
  79.  
  80.                                 Example 14-2.
  81.  
  82.       #include <fastgraf.h>
  83.       #include <stdio.h>
  84.       void main(void);
  85.  
  86.       #define ESC 27
  87.  
  88.       void main()
  89.       {
  90.          unsigned long start, ticks;
  91.          unsigned char key, aux;
  92.  
  93.          start = fg_getclock();
  94.  
  95.          do {
  96.             ticks = fg_getclock();
  97.             printf("%lu ticks since midnight.\n",ticks);
  98.             printf("%lu ticks since start of program.\n\n",ticks-start);
  99.             fg_getkey(&key,&aux);
  100.          }
  101.          while (key != ESC);
  102.       }
  103.  
  104.  
  105.  
  106. Routines Dependent on the System Speed
  107.  
  108.      The fg_waitfor routine described in the previous section is independent
  109. of the system's processor speed.  This means the actual length of its delay
  110. is the same on any system.  Another routine, fg_stall, is similar to
  111. fg_waitfor, but its delay is proportional to the processor speed.  Like
  112. fg_waitfor, fg_stall has a single integer argument that specifies the length
  113. of the delay.  However, instead of being expressed in clock ticks, fg_stall
  114. measures the delay in delay units.  The fg_stall routine treats the length as
  115. an unsigned quantity, so the maximum number of delay units we can specify is
  116. 65,535.  The following table lists the approximate number of delay units per
  117. clock tick on three typical systems.
  118. 250  Fastgraph User's Guide
  119.  
  120.                         system         delay units
  121.                         type           per clock tick
  122.  
  123.                         Tandy 1000 HX        675
  124.                         10 MHz 80286       3,000
  125.                         25 MHz 80386      11,000
  126.  
  127.      Fastgraph includes a routine that determines the number of delay units
  128. per clock tick for the processor being used.  This is the fg_measure routine,
  129. which has no arguments and returns the number of delay units per clock tick
  130. as its function value.  Once we determine this value, we can use fg_stall to
  131. delay a program's execution in real time.  This provides a much more refined
  132. delay than the clock tick unit used by fg_waitfor.
  133.  
  134.      Example 14-3 is functionally identical to example 14-1, but it uses the
  135. fg_stall routine instead of fg_waitfor to delay the program execution.  The
  136. program first calls the fg_measure routine to determine number of delay units
  137. equivalent to one clock tick.  It then passes this value to fg_stall, called
  138. 91 times inside the for loop to create the five-second delay (because 91
  139. clock ticks equals five seconds).  The program returns to DOS when you press
  140. any key.
  141.  
  142.                                 Example 14-3.
  143.  
  144.              #include <fastgraf.h>
  145.              #include <stdio.h>
  146.              void main(void);
  147.  
  148.              void main()
  149.              {
  150.                 int i;
  151.                 int units_per_tick;
  152.                 unsigned int seconds;
  153.                 unsigned char key, aux;
  154.  
  155.                 seconds = 0;
  156.  
  157.                 printf("Benchmarking system speed...\n");
  158.                 units_per_tick = fg_measure();
  159.                 printf("Benchmark completed.\n\n");
  160.  
  161.                 do {
  162.                    for (i = 0; i < 91; i++)
  163.                       fg_stall(units_per_tick);
  164.                    seconds += 5;
  165.                    printf("%u seconds have elapsed.\n",seconds);
  166.                    fg_intkey(&key,&aux);
  167.                 }
  168.                 while (key+aux == 0);
  169.              }
  170.  
  171.  
  172.      One final point:  the fg_measure routine takes a few seconds to
  173. benchmark the system speed accurately.  For this reason, you should only call
  174. fg_measure once (typically at the beginning of the program) and use its
  175. return value instead of calling fg_measure throughout the program.
  176.                                               Chapter 14:  Program Timing  251
  177.  
  178.  
  179. Summary of Timing Routines
  180.  
  181.      This section summarizes the functional descriptions of the Fastgraph
  182. routines presented in this chapter.  More detailed information about these
  183. routines, including their arguments and return values, may be found in the
  184. Fastgraph Reference Manual.
  185.  
  186.      FG_GETCLOCK returns the number of clock ticks since midnight as its
  187. function value.  This quantity is a 32-bit unsigned integer.
  188.  
  189.      FG_MEASURE returns the approximate number of delay units per clock tick
  190. as its function value.  This quantity is proportional to the system's
  191. processor speed.
  192.  
  193.      FG_STALL delays a program's execution for a given number of processor-
  194. specific delay units.
  195.  
  196.      FG_WAITFOR delays a program's execution for a given number of clock
  197. ticks.  There are 18.2 clock ticks per second, regardless of the system's
  198. processor speed.
  199. 252  Fastgraph User's Guide