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 +format+ to format each line. Returns an array of Benchmark::Tms objects.

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 FORMAT constants

n = 5000000
Benchmark .benchmark(CAPTION , 7, FORMAT , ">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: 0.970000 0.000000 0.970000 ( 0.970493)
 times: 0.990000 0.000000 0.990000 ( 0.989542)
 upto: 0.970000 0.000000 0.970000 ( 0.972854)
 >total: 2.930000 0.000000 2.930000 ( 2.932889)
 >avg: 0.976667 0.000000 0.976667 ( 0.977630)

A simple interface to the #benchmark method, #bm generates sequential reports with labels. The parameters have the same meaning as for

benchmark.

require 'benchmark'
n = 5000000
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

Generates:

 user system total real
 for: 0.960000 0.000000 0.960000 ( 0.957966)
 times: 0.960000 0.000000 0.960000 ( 0.960423)
 upto: 0.950000 0.000000 0.950000 ( 0.954864)

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. GC.start 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

Generates:

 Rehearsal -----------------------------------------
 sort! 1.440000 0.010000 1.450000 ( 1.446833)
 sort 1.440000 0.000000 1.440000 ( 1.448257)
 -------------------------------- total: 2.890000sec
 user system total real
 sort! 1.460000 0.000000 1.460000 ( 1.458065)
 sort 1.450000 0.000000 1.450000 ( 1.455963)

bmbm yields a Benchmark::Job object and returns an array of

Benchmark::Tms objects.

Returns the time used to execute the given block as a Benchmark::Tms object.

Returns the elapsed real time used to execute the given block.