
                                 benchmark.rb

NAME

   benchmark.rb - a benchmark utility

SYNOPSIS

----------
     require "benchmark"
     include Benchmark
----------

DESCRIPTION

   benchmark.rb provides some utilities to measure and report the times
   used and passed to execute.

SIMPLE EXAMPLE

  EXAMPLE 0

   To measure the times to make "a"*1_000_000:
----------
     puts measure{ "a"*1_000_000 }
----------

   On my machine (FreeBSD 3.2 on P5100MHz) this reported as follows:
----------
       1.166667   0.050000   1.216667 (  0.571355)
----------

   The above shows user time, system time, user+system, and really passed
   time. The unit of time is second.

  EXAMPLE 1

   To do some experiments sequentially, bm is useful:
----------
     n = 50000
     bm do |x|
       x.report{for i in 1..n; a = "1"; end}
       x.report{n.times do   ; a = "1"; end}
       x.report{1.upto(n) do ; a = "1"; end}
     end
----------

   The result:
----------
           user     system      total        real
       1.033333   0.016667   1.016667 (  0.492106)
       1.483333   0.000000   1.483333 (  0.694605)
       1.516667   0.000000   1.516667 (  0.711077)
----------

  EXAMPLE 2

   To put a label in each report:
----------
     n = 50000
     bm(7) do |x|
       x.report("for:")   {for i in 1..n; a = "1"; end}
       x.report("times:") {n.times do   ; a = "1"; end}
       x.report("upto:")  {1.upto(n) do ; a = "1"; end}
     end
----------

   The option 7 specifies the offset of each report accoding to the
   longest label.

   This reports as follows:
----------
                  user     system      total        real
     for:     1.050000   0.000000   1.050000 (  0.503462)
     times:   1.533333   0.016667   1.550000 (  0.735473)
     upto:    1.500000   0.016667   1.516667 (  0.711239)
----------

  EXAMPLE 3

   By the way, benchmarks might seem to depend on the order of items. It
   is caused by the cost of memory allocation and the garbage collection.
   To prevent this boresome, Benchmark::bmbm is provided, e.g., to
   compare ways for sort array of strings:
----------
     require "rbconfig"
     include Config
     def file
       open("%s/lib/ruby/%s.%s/tk.rb" %
            [CONFIG['prefix'],CONFIG['MAJOR'],CONFIG['MINOR']]).read
     end

     n = 10
     bmbm do |x|
       x.report("destructive!"){
         t = (file*n).to_a; t.each{|line| line.upcase!}; t.sort!
       }
       x.report("method chain"){
         t = (file*n).to_a.collect{|line| line.upcase}.sort
       }
     end
----------

   This reports:
----------
     Rehearsal ------------------------------------------------
     destructive!   2.664062   0.070312   2.734375 (  2.783401)
     method chain   5.257812   0.156250   5.414062 (  5.736088)
     --------------------------------------- total: 8.148438sec

                        user     system      total        real
     destructive!   2.359375   0.007812   2.367188 (  2.381015)
     method chain   3.046875   0.023438   3.070312 (  3.085816)
----------

  EXAMPLE 4

   To report statistics of sequential experiments with unique label,
   benchmark is available:
----------
     n = 50000
     benchmark(" "*7 + CAPTION, 7, FMTSTR, ">total:", ">avg:") do |x|
       tf = x.report("for:")  {for i in 1..n; a = "1"; end}
       tt = x.report("times:"){n.times do   ; a = "1"; end}
       tu = x.report("upto:") {1.upto(n) do ; a = "1"; end}
       [tf+tt+tu, (tf+tt+tu)/3]
     end
----------

   The result:
----------
                  user     system      total        real
     for:     1.016667   0.016667   1.033333 (  0.485749)
     times:   1.450000   0.016667   1.466667 (  0.681367)
     upto:    1.533333   0.000000   1.533333 (  0.722166)
     >total:  4.000000   0.033333   4.033333 (  1.889282)
     >avg:    1.333333   0.011111   1.344444 (  0.629761)
----------

HISTORY

2002-04-25: bmbm(): killed unused parameter @fmtstr (gotoken)
2001-11-26: Time.times renamed Process.times for ruby17 (gotoken#notwork.org)
2001-01-12: made bmbm module func.  bmbm return Tms array.
2001-01-10: added bmbm, Job and INSTALL.rb (gotoken#notwork.org)
2000-04-00: report() prints tag before eval block (gotoken#notwork.org)
2000-02-22: report(): measure -> Benchmark::measure (nakahiro#sarion.co.jp)
2000-01-02: bug fix, documentation (gotoken#notwork.org)
2000-01-01: measure can take a tag as opt. (nobu.nakada#nifty.ne.jp)
2000-01-01: first release (gotoken#notwork.org)

AUTHOR

   Gotoken (gotoken@notwork.org).
