Invokes the block with a Benchmark::Report object, which may be used to collect and report on the results of individual benchmark tests. Reserves label_width 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 Benchmark::Tms 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

Generates:

             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)

Source Code

# File benchmark.rb, line 170
def benchmark(caption = "", label_width = nil, fmtstr = nil, *labels) # :yield: report
  sync = STDOUT.sync
  STDOUT.sync = true
  label_width ||= 0
  fmtstr ||= FMTSTR
  raise ArgumentError, "no block" unless iterator?
  print caption
  results = yield(Report.new(label_width, fmtstr))
  Array === results and results.grep(Tms).each {|t|
    print((labels.shift || t.label || "").ljust(label_width), 
          t.format(fmtstr))
  }
  STDOUT.sync = sync
end