railsbench 0.9.2 → 0.9.8

data/GCPATCH

@@ -0,0 +1,73 @@
+The garbage collector distributed with ruby tries to adapt memory
+usage to the amount of memory used by the program, dynamically growing
+or shrinking the allocated heap as it sees fit.
+
+For long running server apps this doesn't really work very well. The
+performance very much depends on the ratio heap size/program size. It
+behaves somewhat erratic: adding code can actually make your program
+run faster.
+
+The supplied patch fixes this problem: it allows one to specify the
+initial heap size to start with. Heap size will never drop below the
+initial size. By carefully selecting the initial heap size one can
+decrease startup time and increase throughput of server apps.
+
+There are 4 patches for different versions of Ruby:
+   rubygc184.patch     Ruby 1.8.4 (but will apply to 1.82 as well)
+   rubygc185.patch     Ruby 1.8.5
+   rubygc186.patch     Ruby 1.8.6
+   rubygc19.patch      Ruby 1.9
+
+Heap size and other options are controlled through environment
+variables:
+
+RUBY_HEAP_MIN_SLOTS
+    - the initial heap size in number of slots used
+
+RUBY_HEAP_SLOTS_INCREMENT
+    - how many additional slots to allocate when Ruby allocates
+      new heap slots
+
+RUBY_HEAP_SLOTS_GROWTH_FACTOR
+    - multiplicator used to increase heap block size for the next
+      allocation.
+
+RUBY_GC_MALLOC_LIMIT
+    - the amount of C data structures which can be allocated
+      without triggering a GC (if this is set too low, GC will be
+      started even if there are empty slots available)
+
+RUBY_HEAP_FREE_MIN
+    - number of free slots that should be available after GC
+      if fewer slots are available, additional heap will be allocated
+      (Ruby >= 1.8.5 ensures the freelist has at least heapsize*0.2 entries)
+
+The following values make the patched GC behave like the unpatched GC:
+
+RUBY_HEAP_MIN_SLOTS=10000
+RUBY_HEAP_SLOTS_INCREMENT=10000
+RUBY_HEAP_SLOTS_GROWTH_FACTOR=1.8
+RUBY_GC_MALLOC_LIMIT=8000000
+RUBY_HEAP_FREE_MIN=4096
+
+Try experimenting with these values. You can use perf_run_gc to find
+out how many slots you need.
+
+Memory usage of the ruby interpreter can be observed by setting
+RUBY_GC_STATS=1, before you invoke any of the railsbench commands.
+
+Per default, GC data gets written to stderr. You can change this
+behavior by setting environment variable RUBY_GC_DATA_FILE.
+
+Additionally, the Ruby module GC gets some new methods:
+
+GC.enable_stats   - enable GC statistics collection
+GC.disable_stats  - disable GC statistics collection
+GC.clear_stats    - reset GC statistics
+GC.collections    - number of collections since stats have been enabled
+GC.time           - GC time used since stats have been enabled (miro seconds)
+GC.dump           - dumps current heap topology to the GC log file
+GC.log            - log given string to the GC log file
+
+railsbench detects whether the patch has been applied and provides
+GC statistics only in this case.

data/INSTALL

@@ -36,6 +36,11 @@ base directory, in order for railsbench to work properly.
 If you obtained railsbench as a svn checkout, add the railsbench
 script directory to your search path.
 
+For bash shells you can use railsbench command completion by adding
+this line code to your .bashrc file:
+
+     complete -W "`railsbench commands`" -o default railsbench
+
 
 STEP 2: prepare your application for benchmarking
 -------------------------------------------------

data/Manifest.txt

@@ -1,27 +1,37 @@
 BUGS
 CHANGELOG
+GCPATCH
 INSTALL
-install.rb
-postinstall.rb
 LICENSE
 Manifest.txt
 PROBLEMS
 README
 Rakefile
-setup.rb
-ruby184gc.patch
-ruby185gc.patch
 bin/railsbench
-lib/railsbench/version.rb
+config/benchmarking.rb
+config/benchmarks.rb
+config/benchmarks.yml
+images/empty.png
+images/minus.png
+images/plus.png
+install.rb
+latest_changes.txt
+lib/benchmark.rb
+lib/railsbench/benchmark.rb
+lib/railsbench/benchmark_specs.rb
 lib/railsbench/gc_info.rb
 lib/railsbench/perf_info.rb
 lib/railsbench/perf_utils.rb
-lib/railsbench/write_headers_only.rb
 lib/railsbench/railsbenchmark.rb
-lib/railsbench/benchmark_specs.rb
-lib/benchmark.rb
-script/generate_benchmarks
+lib/railsbench/version.rb
+lib/railsbench/write_headers_only.rb
+postinstall.rb
+ruby184gc.patch
+ruby185gc.patch
+ruby186gc.patch
+ruby19gc.patch
 script/convert_raw_data_files
+script/generate_benchmarks
 script/perf_bench
 script/perf_comp
 script/perf_comp_gc
@@ -38,6 +48,6 @@ script/perf_tex
 script/perf_times
 script/perf_times_gc
 script/run_urls
-config/benchmarking.rb
-config/benchmarks.rb
-config/benchmarks.yml
+setup.rb
+test/railsbench_test.rb
+test/test_helper.rb

data/README

@@ -10,7 +10,7 @@ from the various scripts (and some won't run at all without the
 patch).
 
 This software was written and conceived by Stefan Kaes. The author can
-be reached via email: <skaes@gmx.net>. Please send comments, bug
+be reached via email: <skaes@railsexpress.de>. Please send comments, bug
 reports, patches or feature requests to this address.
 
 
@@ -21,7 +21,7 @@ FILES
                   switches:
                   -gcXXX        : perform gc after XXX requests
                   -log[=level]  : turn on rails logging (at given level)
-                  -nochache     : turn off rails caching
+                  -nocache      : turn off rails caching
                   -path         : print $: after loading rails and exit
 
   config/bechmarks.yml
@@ -83,7 +83,7 @@ FILES
   perf_run_gc n [ option-string [ config-name ] ]
                 - run a given benchmark, store performance data in a file
                   in directory $RAILS_PERF_DATA and print results
-                - requires Ruby GC patch
+                - requires Ruby GC patch (or Ruby Enterprise Edition)
 
   perf_times_gc file
                 - analyse and print garbage collection statistics, which you
@@ -103,20 +103,36 @@ FILES
                   store profile data in a HTML file in directory $RAILS_PERF_DATA
                   file name is computed from date and benchmark name as described above
                   but has a .html extension instead of .txt
+                - a number of options to steer ruby-prof are available:
+                    -ruby_prof=number[/number]
+                      sets threshold and min_percent for ruby-prof (defaults to 0.1/1)
+                    -profile_type=stack|grind|flat|graph|multi
+                      selects the profile format (defaults to stack)
+                    -measure_mode=process_time|wall_time|cpu_time|allocations|memory
+                      selects what to measure (default to wall_time)
 
   perf_plot [ options ] file1 file2 ...
-                - plot performance data from raw performance files using gruff
+                - plot performance data from raw performance files using gruff or gnuplot
+                  see source for options
+
+  perf_plot_gc [ options ] file1 file2 ...
+                - plot data points from GC performance data stored in raw GC log files using gruff or gnuplot
+                  this basically shows object type distribution across garbage collections
                   see source for options
 
   perf_table [ options ] file1 file2 ...
                 - produces a tabular overview of perf data from given raw data files
                   see source for options
 
+  analyze_heap_dump file
+                - produces a html representation of a ruby heap dump.
+                  useful for finding memory leaks.
 
 ENVIRONMENT
 
   RAILS_ROOT
-                - must be set to point to your rails app
+                - can be set to point to your rails app. if not set, railsbench can only
+                  be called from the top level directory of your rails app
 
   RAILS_PERF_DATA
                 - performance data sets will be stored into this directory
@@ -167,7 +183,7 @@ USAGE
 
   will store benchmark data in file
 
-     $RAILS_PERF_DATA/`current-date�.index.mail.txt.
+     $RAILS_PERF_DATA/<current-date>.index.mail.txt.
 
   You can get nicely formatted output of benchmark data by running
 
@@ -306,7 +322,7 @@ CONFIGURATION
   for the following benchmarks:
 
     a) an entry for each named route
-    b) an entry for each route generated from by the unnamed route definitions
+    b) an entry for each route generated by unnamed route definitions
     c) an entry for each controller, combining all actions (named xyz_controller)
     d) an entry combining all controllers (all_controllers), combining all
        benchmarks generated by step c.

data/Rakefile

@@ -12,14 +12,13 @@ include FileUtils
 require File.join(File.dirname(__FILE__), 'lib', 'railsbench', 'version')
 
 AUTHOR = "Stefan Kaes"  # can also be an array of Authors
-EMAIL = "skaes@gmx.net"
+EMAIL = "skaes@railsexpress.de"
 DESCRIPTION = "rails benchmarking tools"
 GEM_NAME = "railsbench" # what ppl will type to install your gem
 RUBYFORGE_PROJECT = "railsbench" # The unix name for your project
 HOMEPATH = "http://#{RUBYFORGE_PROJECT}.rubyforge.org"
 RELEASE_TYPES = %w(gem tar zip) # can use: gem, tar, zip
 
-
 NAME = "railsbench"
 REV = nil # UNCOMMENT IF REQUIRED: File.read(".svn/entries")[/committed-rev="(d+)"/, 1] rescue nil
 VERS = (ENV['VERSION'] ||= (Railsbench::VERSION::STRING + (REV ? ".#{REV}" : "")))

data/bin/railsbench

@@ -1,8 +1,10 @@
 #!/usr/bin/env ruby
 
 RAILSBENCH_CMDS = %w(
+analyze_heap_dump
 base
 generate_benchmarks
+commands
 convert_raw_data_files
 help
 install
@@ -38,6 +40,8 @@ end
 RAILSBENCH_BASE = File.expand_path(File.dirname(__FILE__) + '/..')
 
 case real_cmd
+when 'commands'
+  puts RAILSBENCH_CMDS.keys.uniq.sort
 when 'base'
   puts "railsbench is installed in: #{RAILSBENCH_BASE}"
   exit
@@ -49,12 +53,14 @@ when 'path'
   exit
 when 'install', 'postinstall'
   load "#{RAILSBENCH_BASE}/#{real_cmd}.rb"
+when 'analyze_heap_dump', /plot/
+  load "#{RAILSBENCH_BASE}/script/#{real_cmd}"
 else
   unless ENV['RAILS_ROOT']
     if File.exists? 'config/environment.rb'
       ENV['RAILS_ROOT'] = File.expand_path '.'
     else
-      $stderr.puts "railsbench: RAILS_ROOT not set"
+      $stderr.puts "railsbench: RAILS_ROOT not set and could not be configured automatically"
       exit 1
     end
   end

data/config/benchmarks.rb

@@ -13,8 +13,9 @@ RAILS_BENCHMARKER = RailsBenchmark.new
 # especially if you use page caching.
 # RAILS_BENCHMARKER.relative_url_root = '/blog'
 
-# Create session data required to run the benchmark.
-# Customize the code below if your benchmark needs session data.
+# Customize the code below if your benchmark needs session data
+# and/or your application specifies a custom session key.
 
 # require 'user'
 # RAILS_BENCHMARKER.session_data = {'account' => User.find_first("name='stefan'")}
+# RAILS_BENCHMARKER.session_key = "my_secret_cookie_name"

data/install.rb

@@ -53,7 +53,7 @@ __END__
 ### mode:ruby ***
 ### End: ***
 
-#  Copyright (C) 2005, 2006, 2007  Stefan Kaes
+#  Copyright (C) 2005-2008  Stefan Kaes
 #
 #  This program is free software; you can redistribute it and/or modify
 #  it under the terms of the GNU General Public License as published by

data/latest_changes.txt

@@ -0,0 +1,18 @@
+* added support for generating call trees using ruby-prof
+* show length of freelist in gc plots
+* make it possible to plot very large gc logs by artificially reducing the data set size
+* changed logger handling to no longer set logger to nil as most apps don't test for logger being nil
+* rails 2.2 compatibility
+* support gnuplot as a plotting engine
+* allow post and query data to be stored in raw form in benchmarks file
+* railsbench command completion: complete -W "`railsbench commands`" -o default railsbench
+* individual scripts now try to autoconfigure RAILS_ROOT too
+* make it possible to add cookie data in benchmarks
+* support for memory leak checking under OS X
+* print detailed comparison of total garbage allocated per object type
+* provide an interface to summed garbage per object type via :garbage_totals
+* railsbench now requires ruby-prof version >= 0.6
+* support for XMLHttpRequest. patch by Vít Ondruch
+* enable specification of session key. patch by Vít Ondruch
+* exit benchmarking when an action raises an exception
+* new GC patches for 1.8.6 and 1.9

data/lib/railsbench/benchmark.rb

@@ -0,0 +1,576 @@
+=begin
+#
+# benchmark.rb - a performance benchmarking library 
+# 
+# $Id$
+# 
+# Created by Gotoken (gotoken@notwork.org). 
+#
+# Documentation by Gotoken (original RD), Lyle Johnson (RDoc conversion), and
+# Gavin Sinclair (editing). 
+#
+=end
+
+# == Overview
+#
+# The Benchmark module provides methods for benchmarking Ruby code, giving
+# detailed reports on the time taken for each task.
+#
+
+# The Benchmark module provides methods to measure and report the time
+# used to execute Ruby code.
+#
+# * Measure the time to construct the string given by the expression
+#   <tt>"a"*1_000_000</tt>:
+#
+#       require 'benchmark'
+#
+#       puts Benchmark.measure { "a"*1_000_000 }
+# 
+#   On my machine (FreeBSD 3.2 on P5, 100MHz) this generates:
+# 
+#       1.166667   0.050000   1.216667 (  0.571355)
+# 
+#   This report shows the user CPU time, system CPU time, the sum of
+#   the user and system CPU times, and the elapsed real time. The unit
+#   of time is seconds.
+# 
+# * Do some experiments sequentially using the #bm method:
+#
+#       require 'benchmark'
+#
+#       n = 50000
+#       Benchmark.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)
+#
+# * Continuing the previous example, put a label in each report:
+#
+#       require 'benchmark'
+#
+#       n = 50000
+#       Benchmark.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 result:
+# 
+#                     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)
+# 
+#
+# * The times for some benchmarks depend on the order in which items
+#   are run.  These differences are due to the cost of memory
+#   allocation and garbage collection. To avoid these discrepancies,
+#   the #bmbm method is provided.  For example, to compare ways to
+#   sort an array of floats:
+#
+#       require 'benchmark'
+#       
+#       array = (1..1000000).map { rand }
+#       
+#       Benchmark.bmbm do |x|
+#         x.report("sort!") { array.dup.sort! }
+#         x.report("sort")  { array.dup.sort  }
+#       end
+# 
+#   The result:
+# 
+#        Rehearsal -----------------------------------------
+#        sort!  11.928000   0.010000  11.938000 ( 12.756000)
+#        sort   13.048000   0.020000  13.068000 ( 13.857000)
+#        ------------------------------- total: 25.006000sec
+#        
+#                    user     system      total        real
+#        sort!  12.959000   0.010000  12.969000 ( 13.793000)
+#        sort   12.007000   0.000000  12.007000 ( 12.791000)
+#
+#
+# * Report statistics of sequential experiments with unique labels,
+#   using the #benchmark method:
+#
+#       require 'benchmark'
+#
+#       n = 50000
+#       Benchmark.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)
+
+module Benchmark
+
+  BENCHMARK_VERSION = "2002-04-25" #:nodoc"
+
+  OUTPUT = STDOUT unless defined?(OUTPUT)
+  SYNC = true unless defined?(SYNC)
+
+  def Benchmark::times() # :nodoc:
+      Process::times()
+  end
+
+
+  # Invokes the block with a <tt>Benchmark::Report</tt> object, which
+  # may be used to collect and report on the results of individual
+  # benchmark tests. Reserves <i>label_width</i> leading spaces for
+  # labels on each line. Prints _caption_ at the top of the
+  # report, and uses _fmt_ to format each line.
+  # If the block returns an array of
+  # <tt>Benchmark::Tms</tt> objects, these will be used to format
+  # additional lines of output. If _label_ parameters are
+  # given, these are used to label these extra lines.
+  #
+  # _Note_: Other methods provide a simpler interface to this one, and are
+  # suitable for nearly all benchmarking requirements.  See the examples in
+  # Benchmark, and the #bm and #bmbm methods.
+  #
+  # Example: 
+  #
+  #     require 'benchmark'
+  #     include Benchmark          # we need the CAPTION and FMTSTR constants 
+  #
+  #     n = 50000
+  #     Benchmark.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
+  # 
+  # <i>Generates:</i>
+  # 
+  #                     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)
+  # 
+
+  def benchmark(caption = "", label_width = nil, fmtstr = nil, *labels) # :yield: report
+    if SYNC
+      sync = OUTPUT.sync
+      OUTPUT.sync = true
+    end
+    label_width ||= 0
+    fmtstr ||= FMTSTR
+    raise ArgumentError, "no block" unless iterator?
+    OUTPUT.print caption
+    results = yield(Report.new(label_width, fmtstr))
+    Array === results and results.grep(Tms).each {|t|
+      OUTPUT.print((labels.shift || t.label || "").ljust(label_width), 
+                   t.format(fmtstr))
+    }
+    OUTPUT.sync = sync if SYNC
+  end
+
+
+  # A simple interface to the #benchmark method, #bm is generates sequential reports
+  # with labels.  The parameters have the same meaning as for #benchmark.
+  # 
+  #     require 'benchmark'
+  #
+  #     n = 50000
+  #     Benchmark.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
+  # 
+  # <i>Generates:</i>
+  # 
+  #                     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)
+  #
+
+  def bm(label_width = 0, *labels, &blk) # :yield: report
+    benchmark(" "*label_width + CAPTION, label_width, FMTSTR, *labels, &blk)
+  end
+
+
+  # Sometimes benchmark results are skewed because code executed
+  # earlier encounters different garbage collection overheads than
+  # that run later. #bmbm attempts to minimize this effect by running
+  # the tests twice, the first time as a rehearsal in order to get the
+  # runtime environment stable, the second time for
+  # real. <tt>GC.start</tt> is executed before the start of each of
+  # the real timings; the cost of this is not included in the
+  # timings. In reality, though, there's only so much that #bmbm can
+  # do, and the results are not guaranteed to be isolated from garbage
+  # collection and other effects.
+  #
+  # Because #bmbm takes two passes through the tests, it can
+  # calculate the required label width.
+  #
+  #       require 'benchmark'
+  #       
+  #       array = (1..1000000).map { rand }
+  #       
+  #       Benchmark.bmbm do |x|
+  #         x.report("sort!") { array.dup.sort! }
+  #         x.report("sort")  { array.dup.sort  }
+  #       end
+  # 
+  # <i>Generates:</i>
+  # 
+  #        Rehearsal -----------------------------------------
+  #        sort!  11.928000   0.010000  11.938000 ( 12.756000)
+  #        sort   13.048000   0.020000  13.068000 ( 13.857000)
+  #        ------------------------------- total: 25.006000sec
+  #        
+  #                    user     system      total        real
+  #        sort!  12.959000   0.010000  12.969000 ( 13.793000)
+  #        sort   12.007000   0.000000  12.007000 ( 12.791000)
+  #
+  # #bmbm yields a Benchmark::Job object and returns an array of
+  # Benchmark::Tms objects.
+  #
+  def bmbm(width = 0, &blk) # :yield: job
+    job = Job.new(width)
+    yield(job)
+    width = job.width
+    if SYNC
+      sync = OUTPUT.sync
+      OUTPUT.sync = true
+    end
+
+    # rehearsal
+    OUTPUT.print "Rehearsal "
+    puts '-'*(width+CAPTION.length - "Rehearsal ".length)
+    list = []
+    job.list.each{|label,item|
+      OUTPUT.print(label.ljust(width))
+      res = Benchmark::measure(&item)
+      OUTPUT.print res.format()
+      list.push res
+    }
+    sum = Tms.new; list.each{|i| sum += i}
+    ets = sum.format("total: %tsec")
+    OUTPUT.printf("%s %s\n\n",
+                  "-"*(width+CAPTION.length-ets.length-1), ets)
+    
+    # take
+    OUTPUT.print ' '*width, CAPTION
+    list = []
+    ary = []
+    job.list.each{|label,item|
+      GC::start
+      OUTPUT.print label.ljust(width)
+      res = Benchmark::measure(&item)
+      OUTPUT.print res.format()
+      ary.push res
+      list.push [label, res]
+    }
+
+    OUTPUT.sync = sync if SYNC
+    ary
+  end
+
+  # 
+  # Returns the time used to execute the given block as a
+  # Benchmark::Tms object.
+  #
+  def measure(label = "") # :yield:
+    t0, r0 = Benchmark.times, Time.now
+    yield
+    t1, r1 = Benchmark.times, Time.now
+    Benchmark::Tms.new(t1.utime  - t0.utime, 
+                       t1.stime  - t0.stime, 
+                       t1.cutime - t0.cutime, 
+                       t1.cstime - t0.cstime, 
+                       r1.to_f - r0.to_f,
+                       label)
+  end
+
+  #
+  # Returns the elapsed real time used to execute the given block.
+  #
+  def realtime(&blk) # :yield:
+    Benchmark::measure(&blk).real
+  end
+
+
+
+  #
+  # A Job is a sequence of labelled blocks to be processed by the
+  # Benchmark.bmbm method.  It is of little direct interest to the user.
+  #
+  class Job # :nodoc:
+    #
+    # Returns an initialized Job instance.
+    # Usually, one doesn't call this method directly, as new
+    # Job objects are created by the #bmbm method.
+    # _width_ is a initial value for the label offset used in formatting;
+    # the #bmbm method passes its _width_ argument to this constructor. 
+    # 
+    def initialize(width)
+      @width = width
+      @list = []
+    end
+
+    #
+    # Registers the given label and block pair in the job list.
+    #
+    def item(label = "", &blk) # :yield:
+      raise ArgmentError, "no block" unless block_given?
+      label.concat ' '
+      w = label.length
+      @width = w if @width < w
+      @list.push [label, blk]
+      self
+    end
+
+    alias report item
+    
+    # An array of 2-element arrays, consisting of label and block pairs.
+    attr_reader :list
+    
+    # Length of the widest label in the #list, plus one.  
+    attr_reader :width
+  end
+
+  module_function :benchmark, :measure, :realtime, :bm, :bmbm
+
+
+
+  #
+  # This class is used by the Benchmark.benchmark and Benchmark.bm methods.
+  # It is of little direct interest to the user.
+  #
+  class Report # :nodoc:
+    #
+    # Returns an initialized Report instance.
+    # Usually, one doesn't call this method directly, as new
+    # Report objects are created by the #benchmark and #bm methods. 
+    # _width_ and _fmtstr_ are the label offset and 
+    # format string used by Tms#format. 
+    # 
+    def initialize(width = 0, fmtstr = nil)
+      @width, @fmtstr = width, fmtstr
+    end
+
+    #
+    # Prints the _label_ and measured time for the block,
+    # formatted by _fmt_. See Tms#format for the
+    # formatting rules.
+    #
+    def item(label = "", *fmt, &blk) # :yield:
+      OUTPUT.print label.ljust(@width)
+      res = Benchmark::measure(&blk)
+      OUTPUT.print res.format(@fmtstr, *fmt)
+      res
+    end
+
+    alias report item
+  end
+
+
+
+  #
+  # A data object, representing the times associated with a benchmark
+  # measurement.
+  #
+  class Tms
+    CAPTION = "      user     system      total        real\n"
+    FMTSTR = "%10.6u %10.6y %10.6t %10.6r\n"
+
+    # User CPU time
+    attr_reader :utime
+    
+    # System CPU time
+    attr_reader :stime
+   
+    # User CPU time of children
+    attr_reader :cutime
+    
+    # System CPU time of children
+    attr_reader :cstime
+    
+    # Elapsed real time
+    attr_reader :real
+    
+    # Total time, that is _utime_ + _stime_ + _cutime_ + _cstime_ 
+    attr_reader :total
+    
+    # Label
+    attr_reader :label
+
+    #
+    # Returns an initialized Tms object which has
+    # _u_ as the user CPU time, _s_ as the system CPU time, 
+    # _cu_ as the children's user CPU time, _cs_ as the children's
+    # system CPU time, _real_ as the elapsed real time and _l_
+    # as the label. 
+    # 
+    def initialize(u = 0.0, s = 0.0, cu = 0.0, cs = 0.0, real = 0.0, l = nil)
+      @utime, @stime, @cutime, @cstime, @real, @label = u, s, cu, cs, real, l
+      @total = @utime + @stime + @cutime + @cstime
+    end
+
+    # 
+    # Returns a new Tms object whose times are the sum of the times for this
+    # Tms object, plus the time required to execute the code block (_blk_).
+    # 
+    def add(&blk) # :yield:
+      self + Benchmark::measure(&blk) 
+    end
+
+    # 
+    # An in-place version of #add.
+    # 
+    def add!
+      t = Benchmark::measure(&blk) 
+      @utime  = utime + t.utime
+      @stime  = stime + t.stime
+      @cutime = cutime + t.cutime
+      @cstime = cstime + t.cstime
+      @real   = real + t.real
+      self
+    end
+
+    # 
+    # Returns a new Tms object obtained by memberwise summation
+    # of the individual times for this Tms object with those of the other
+    # Tms object.
+    # This method and #/() are useful for taking statistics. 
+    # 
+    def +(other); memberwise(:+, other) end
+    
+    #
+    # Returns a new Tms object obtained by memberwise subtraction
+    # of the individual times for the other Tms object from those of this
+    # Tms object.
+    #
+    def -(other); memberwise(:-, other) end
+    
+    #
+    # Returns a new Tms object obtained by memberwise multiplication
+    # of the individual times for this Tms object by _x_.
+    #
+    def *(x); memberwise(:*, x) end
+
+    # 
+    # Returns a new Tms object obtained by memberwise division
+    # of the individual times for this Tms object by _x_.
+    # This method and #+() are useful for taking statistics. 
+    # 
+    def /(x); memberwise(:/, x) end
+
+    #
+    # Returns the contents of this Tms object as
+    # a formatted string, according to a format string
+    # like that passed to Kernel.format. In addition, #format
+    # accepts the following extensions:
+    #
+    # <tt>%u</tt>::     Replaced by the user CPU time, as reported by Tms#utime.
+    # <tt>%y</tt>::     Replaced by the system CPU time, as reported by #stime (Mnemonic: y of "s*y*stem")
+    # <tt>%U</tt>::     Replaced by the children's user CPU time, as reported by Tms#cutime 
+    # <tt>%Y</tt>::     Replaced by the children's system CPU time, as reported by Tms#cstime
+    # <tt>%t</tt>::     Replaced by the total CPU time, as reported by Tms#total
+    # <tt>%r</tt>::     Replaced by the elapsed real time, as reported by Tms#real
+    # <tt>%n</tt>::     Replaced by the label string, as reported by Tms#label (Mnemonic: n of "*n*ame")
+    # 
+    # If _fmtstr_ is not given, FMTSTR is used as default value, detailing the
+    # user, system and real elapsed time.
+    # 
+    def format(arg0 = nil, *args)
+      fmtstr = (arg0 || FMTSTR).dup
+      fmtstr.gsub!(/(%[-+\.\d]*)n/){"#{$1}s" % label}
+      fmtstr.gsub!(/(%[-+\.\d]*)u/){"#{$1}f" % utime}
+      fmtstr.gsub!(/(%[-+\.\d]*)y/){"#{$1}f" % stime}
+      fmtstr.gsub!(/(%[-+\.\d]*)U/){"#{$1}f" % cutime}
+      fmtstr.gsub!(/(%[-+\.\d]*)Y/){"#{$1}f" % cstime}
+      fmtstr.gsub!(/(%[-+\.\d]*)t/){"#{$1}f" % total}
+      fmtstr.gsub!(/(%[-+\.\d]*)r/){"(#{$1}f)" % real}
+      arg0 ? Kernel::format(fmtstr, *args) : fmtstr
+    end
+
+    # 
+    # Same as #format.
+    # 
+    def to_s
+      format
+    end
+
+    # 
+    # Returns a new 6-element array, consisting of the
+    # label, user CPU time, system CPU time, children's
+    # user CPU time, children's system CPU time and elapsed
+    # real time.
+    # 
+    def to_a
+      [@label, @utime, @stime, @cutime, @cstime, @real]
+    end
+
+    protected
+    def memberwise(op, x)
+      case x
+      when Benchmark::Tms
+        Benchmark::Tms.new(utime.__send__(op, x.utime),
+                           stime.__send__(op, x.stime),
+                           cutime.__send__(op, x.cutime),
+                           cstime.__send__(op, x.cstime),
+                           real.__send__(op, x.real)
+                           )
+      else
+        Benchmark::Tms.new(utime.__send__(op, x),
+                           stime.__send__(op, x),
+                           cutime.__send__(op, x),
+                           cstime.__send__(op, x),
+                           real.__send__(op, x)
+                           )
+      end
+    end
+  end
+
+  # The default caption string (heading above the output times).
+  CAPTION = Benchmark::Tms::CAPTION
+
+  # The default format string used to display times.  See also Benchmark::Tms#format. 
+  FMTSTR = Benchmark::Tms::FMTSTR
+end
+
+if __FILE__ == $0
+  include Benchmark
+
+  n = ARGV[0].to_i.nonzero? || 50000
+  puts %Q([#{n} times iterations of `a = "1"'])
+  benchmark("       " + CAPTION, 7, FMTSTR) do |x|
+    x.report("for:")   {for i in 1..n; a = "1"; end} # Benchmark::measure
+    x.report("times:") {n.times do   ; a = "1"; end}
+    x.report("upto:")  {1.upto(n) do ; a = "1"; end}
+  end
+
+  benchmark do
+    [
+      measure{for i in 1..n; a = "1"; end},  # Benchmark::measure
+      measure{n.times do   ; a = "1"; end},
+      measure{1.upto(n) do ; a = "1"; end}
+    ]
+  end
+end