home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2001 May / SGI IRIX Base Documentation 2001 May.iso / usr / share / catman / p_man / cat3 / perl5 / Benchmark.z / Benchmark
Encoding:
Text File  |  1998-10-30  |  8.3 KB  |  265 lines
  1.  
  2.  
  3.  
  4. BBBBeeeennnncccchhhhmmmmaaaarrrrkkkk((((3333))))                                                      BBBBeeeennnncccchhhhmmmmaaaarrrrkkkk((((3333))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      Benchmark - benchmark running times of code
  10.  
  11.      timethis - run a chunk of code several times
  12.  
  13.      timethese - run several chunks of code several times
  14.  
  15.      timeit - run a chunk of code and see how long it goes
  16.  
  17. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  18.          timethis ($count, "code");
  19.  
  20.          # Use Perl code in strings...
  21.          timethese($count, {
  22.              'Name1' => '...code1...',
  23.              'Name2' => '...code2...',
  24.          });
  25.  
  26.          # ... or use subroutine references.
  27.          timethese($count, {
  28.              'Name1' => sub { ...code1... },
  29.              'Name2' => sub { ...code2... },
  30.          });
  31.  
  32.          $t = timeit($count, '...other code...')
  33.          print "$count loops of other code took:",timestr($t),"\n";
  34.  
  35.  
  36. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  37.      The Benchmark module encapsulates a number of routines to help you figure
  38.      out how long it takes to execute some code.
  39.  
  40.      MMMMeeeetttthhhhooooddddssss
  41.  
  42.      new       Returns the current time.   Example:
  43.  
  44.                    use Benchmark;
  45.                    $t0 = new Benchmark;
  46.                    # ... your code here ...
  47.                    $t1 = new Benchmark;
  48.                    $td = timediff($t1, $t0);
  49.                    print "the code took:",timestr($td),"\n";
  50.  
  51.  
  52.      debug     Enables or disable debugging by setting the $Benchmark::Debug
  53.                flag:
  54.  
  55.                    debug Benchmark 1;
  56.                    $t = timeit(10, ' 5 ** $Global ');
  57.                    debug Benchmark 0;
  58.  
  59.  
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. BBBBeeeennnncccchhhhmmmmaaaarrrrkkkk((((3333))))                                                      BBBBeeeennnncccchhhhmmmmaaaarrrrkkkk((((3333))))
  71.  
  72.  
  73.  
  74.      SSSSttttaaaannnnddddaaaarrrrdddd EEEExxxxppppoooorrrrttttssss
  75.  
  76.      The following routines will be exported into your namespace if you use
  77.      the Benchmark module:
  78.  
  79.      timeit(COUNT, CODE)
  80.                Arguments: COUNT is the number of times to run the loop, and
  81.                CODE is the code to run.  CODE may be either a code reference
  82.                or a string to be eval'd; either way it will be run in the
  83.                caller's package.
  84.  
  85.                Returns: a Benchmark object.
  86.  
  87.      timethis ( COUNT, CODE, [ TITLE, [ STYLE ]] )
  88.                Time COUNT iterations of CODE. CODE may be a string to eval or
  89.                a code reference; either way the CODE will run in the caller's
  90.                package.  Results will be printed to STDOUT as TITLE followed
  91.                by the times.  TITLE defaults to "timethis COUNT" if none is
  92.                provided. STYLE determines the format of the output, as
  93.                described for _t_i_m_e_s_t_r() below.
  94.  
  95.      timethese ( COUNT, CODEHASHREF, [ STYLE ] )
  96.                The CODEHASHREF is a reference to a hash containing names as
  97.                keys and either a string to eval or a code reference for each
  98.                value.  For each (KEY, VALUE) pair in the CODEHASHREF, this
  99.                routine will call
  100.  
  101.                        timethis(COUNT, VALUE, KEY, STYLE)
  102.  
  103.  
  104.      timediff ( T1, T2 )
  105.                Returns the difference between two Benchmark times as a
  106.                Benchmark object suitable for passing to _t_i_m_e_s_t_r().
  107.  
  108.      timestr ( TIMEDIFF, [ STYLE, [ FORMAT ]] )
  109.                Returns a string that formats the times in the TIMEDIFF object
  110.                in the requested STYLE. TIMEDIFF is expected to be a Benchmark
  111.                object similar to that returned by _t_i_m_e_d_i_f_f().
  112.  
  113.                STYLE can be any of 'all', 'noc', 'nop' or 'auto'. 'all' shows
  114.                each of the 5 times available ('wallclock' time, user time,
  115.                system time, user time of children, and system time of
  116.                children). 'noc' shows all except the two children times. 'nop'
  117.                shows only wallclock and the two children times. 'auto' (the
  118.                default) will act as 'all' unless the children times are both
  119.                zero, in which case it acts as 'noc'.
  120.  
  121.                FORMAT is the the _p_r_i_n_t_f(_3) manpage-style format specifier
  122.                (without the leading '%') to use to print the times. It
  123.                defaults to '5.2f'.
  124.  
  125.  
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. BBBBeeeennnncccchhhhmmmmaaaarrrrkkkk((((3333))))                                                      BBBBeeeennnncccchhhhmmmmaaaarrrrkkkk((((3333))))
  137.  
  138.  
  139.  
  140.      OOOOppppttttiiiioooonnnnaaaallll EEEExxxxppppoooorrrrttttssss
  141.  
  142.      The following routines will be exported into your namespace if you
  143.      specifically ask that they be imported:
  144.  
  145.      clearcache ( COUNT )
  146.                Clear the cached time for COUNT rounds of the null loop.
  147.  
  148.      clearallcache ( )
  149.                Clear all cached times.
  150.  
  151.      disablecache ( )
  152.                Disable caching of timings for the null loop. This will force
  153.                Benchmark to recalculate these timings for each new piece of
  154.                code timed.
  155.  
  156.      enablecache ( )
  157.                Enable caching of timings for the null loop. The time taken for
  158.                COUNT rounds of the null loop will be calculated only once for
  159.                each different COUNT used.
  160.  
  161. NNNNOOOOTTTTEEEESSSS
  162.      The data is stored as a list of values from the time and times functions:
  163.  
  164.            ($real, $user, $system, $children_user, $children_system)
  165.  
  166.      in seconds for the whole loop (not divided by the number of rounds).
  167.  
  168.      The timing is done using _t_i_m_e(3) and _t_i_m_e_s(3).
  169.  
  170.      Code is executed in the caller's package.
  171.  
  172.      The time of the null loop (a loop with the same number of rounds but
  173.      empty loop body) is subtracted from the time of the real loop.
  174.  
  175.      The null loop times are cached, the key being the number of rounds. The
  176.      caching can be controlled using calls like these:
  177.  
  178.          clearcache($key);
  179.          clearallcache();
  180.  
  181.          disablecache();
  182.          enablecache();
  183.  
  184.  
  185. IIIINNNNHHHHEEEERRRRIIIITTTTAAAANNNNCCCCEEEE
  186.      Benchmark inherits from no other class, except of course for Exporter.
  187.  
  188. CCCCAAAAVVVVEEEEAAAATTTTSSSS
  189.      Comparing eval'd strings with code references will give you inaccurate
  190.      results: a code reference will show a slower execution time than the
  191.      equivalent eval'd string.
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. BBBBeeeennnncccchhhhmmmmaaaarrrrkkkk((((3333))))                                                      BBBBeeeennnncccchhhhmmmmaaaarrrrkkkk((((3333))))
  203.  
  204.  
  205.  
  206.      The real time timing is done using _t_i_m_e(2) and the granularity is
  207.      therefore only one second.
  208.  
  209.      Short tests may produce negative figures because perl can appear to take
  210.      longer to execute the empty loop than a short test; try:
  211.  
  212.          timethis(100,'1');
  213.  
  214.      The system time of the null loop might be slightly more than the system
  215.      time of the loop with the actual code and therefore the difference might
  216.      end up being < 0.
  217.  
  218. AAAAUUUUTTTTHHHHOOOORRRRSSSS
  219.      Jarkko Hietaniemi <_j_h_i@_i_k_i._f_i>, Tim Bunce <_T_i_m._B_u_n_c_e@_i_g._c_o._u_k>
  220.  
  221. MMMMOOOODDDDIIIIFFFFIIIICCCCAAAATTTTIIIIOOOONNNN HHHHIIIISSSSTTTTOOOORRRRYYYY
  222.      September 8th, 1994; by Tim Bunce.
  223.  
  224.      March 28th, 1997; by Hugo van der Sanden: added support for code
  225.      references and the already documented 'debug' method; revamped
  226.      documentation.
  227.  
  228.  
  229.  
  230.  
  231.  
  232.  
  233.  
  234.  
  235.  
  236.  
  237.  
  238.  
  239.  
  240.  
  241.  
  242.  
  243.  
  244.  
  245.  
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.                                                                         PPPPaaaaggggeeee 4444
  262.  
  263.  
  264.  
  265.