1 # frozen_string_literal: true
3 # benchmark.rb - a performance benchmarking library
7 # Created by Gotoken (gotoken@notwork.org).
9 # Documentation by Gotoken (original RD), Lyle Johnson (RDoc conversion), and
10 # Gavin Sinclair (editing).
15 # The Benchmark module provides methods for benchmarking Ruby code, giving
16 # detailed reports on the time taken for each task.
19 # The Benchmark module provides methods to measure and report the time
20 # used to execute Ruby code.
22 # * Measure the time to construct the string given by the expression
23 # <code>"a"*1_000_000_000</code>:
27 # puts Benchmark.measure { "a"*1_000_000_000 }
29 # On my machine (OSX 10.8.3 on i5 1.7 GHz) this generates:
31 # 0.350000 0.400000 0.750000 ( 0.835234)
33 # This report shows the user CPU time, system CPU time, the sum of
34 # the user and system CPU times, and the elapsed real time. The unit
37 # * Do some experiments sequentially using the #bm method:
43 # x.report { for i in 1..n; a = "1"; end }
44 # x.report { n.times do ; a = "1"; end }
45 # x.report { 1.upto(n) do ; a = "1"; end }
50 # user system total real
51 # 1.010000 0.000000 1.010000 ( 1.014479)
52 # 1.000000 0.000000 1.000000 ( 0.998261)
53 # 0.980000 0.000000 0.980000 ( 0.981335)
55 # * Continuing the previous example, put a label in each report:
60 # Benchmark.bm(7) do |x|
61 # x.report("for:") { for i in 1..n; a = "1"; end }
62 # x.report("times:") { n.times do ; a = "1"; end }
63 # x.report("upto:") { 1.upto(n) do ; a = "1"; end }
68 # user system total real
69 # for: 1.010000 0.000000 1.010000 ( 1.015688)
70 # times: 1.000000 0.000000 1.000000 ( 1.003611)
71 # upto: 1.030000 0.000000 1.030000 ( 1.028098)
73 # * The times for some benchmarks depend on the order in which items
74 # are run. These differences are due to the cost of memory
75 # allocation and garbage collection. To avoid these discrepancies,
76 # the #bmbm method is provided. For example, to compare ways to
77 # sort an array of floats:
81 # array = (1..1000000).map { rand }
83 # Benchmark.bmbm do |x|
84 # x.report("sort!") { array.dup.sort! }
85 # x.report("sort") { array.dup.sort }
90 # Rehearsal -----------------------------------------
91 # sort! 1.490000 0.010000 1.500000 ( 1.490520)
92 # sort 1.460000 0.000000 1.460000 ( 1.463025)
93 # -------------------------------- total: 2.960000sec
95 # user system total real
96 # sort! 1.460000 0.000000 1.460000 ( 1.460465)
97 # sort 1.450000 0.010000 1.460000 ( 1.448327)
99 # * Report statistics of sequential experiments with unique labels,
100 # using the #benchmark method:
102 # require 'benchmark'
103 # include Benchmark # we need the CAPTION and FORMAT constants
106 # Benchmark.benchmark(CAPTION, 7, FORMAT, ">total:", ">avg:") do |x|
107 # tf = x.report("for:") { for i in 1..n; a = "1"; end }
108 # tt = x.report("times:") { n.times do ; a = "1"; end }
109 # tu = x.report("upto:") { 1.upto(n) do ; a = "1"; end }
110 # [tf+tt+tu, (tf+tt+tu)/3]
115 # user system total real
116 # for: 0.950000 0.000000 0.950000 ( 0.952039)
117 # times: 0.980000 0.000000 0.980000 ( 0.984938)
118 # upto: 0.950000 0.000000 0.950000 ( 0.946787)
119 # >total: 2.880000 0.000000 2.880000 ( 2.883764)
120 # >avg: 0.960000 0.000000 0.960000 ( 0.961255)
126 BENCHMARK_VERSION = "2002-04-25" # :nodoc:
128 # Invokes the block with a Benchmark::Report object, which
129 # may be used to collect and report on the results of individual
130 # benchmark tests. Reserves +label_width+ leading spaces for
131 # labels on each line. Prints +caption+ at the top of the
132 # report, and uses +format+ to format each line.
133 # (Note: +caption+ must contain a terminating newline character,
134 # see the default Benchmark::Tms::CAPTION for an example.)
136 # Returns an array of Benchmark::Tms objects.
138 # If the block returns an array of
139 # Benchmark::Tms objects, these will be used to format
140 # additional lines of output. If +labels+ parameter are
141 # given, these are used to label these extra lines.
143 # _Note_: Other methods provide a simpler interface to this one, and are
144 # suitable for nearly all benchmarking requirements. See the examples in
145 # Benchmark, and the #bm and #bmbm methods.
149 # require 'benchmark'
150 # include Benchmark # we need the CAPTION and FORMAT constants
153 # Benchmark.benchmark(CAPTION, 7, FORMAT, ">total:", ">avg:") do |x|
154 # tf = x.report("for:") { for i in 1..n; a = "1"; end }
155 # tt = x.report("times:") { n.times do ; a = "1"; end }
156 # tu = x.report("upto:") { 1.upto(n) do ; a = "1"; end }
157 # [tf+tt+tu, (tf+tt+tu)/3]
162 # user system total real
163 # for: 0.970000 0.000000 0.970000 ( 0.970493)
164 # times: 0.990000 0.000000 0.990000 ( 0.989542)
165 # upto: 0.970000 0.000000 0.970000 ( 0.972854)
166 # >total: 2.930000 0.000000 2.930000 ( 2.932889)
167 # >avg: 0.976667 0.000000 0.976667 ( 0.977630)
170 def benchmark(caption = "", label_width = nil, format = nil, *labels) # :yield: report
176 print ' '*label_width + caption unless caption.empty?
177 report = Report.new(label_width, format)
178 results = yield(report)
179 Array === results and results.grep(Tms).each {|t|
180 print((labels.shift || t.label || "").ljust(label_width), t.format(format))
184 $stdout.sync = sync unless sync.nil?
188 # A simple interface to the #benchmark method, #bm generates sequential
189 # reports with labels. +label_width+ and +labels+ parameters have the same
190 # meaning as for #benchmark.
192 # require 'benchmark'
195 # Benchmark.bm(7) do |x|
196 # x.report("for:") { for i in 1..n; a = "1"; end }
197 # x.report("times:") { n.times do ; a = "1"; end }
198 # x.report("upto:") { 1.upto(n) do ; a = "1"; end }
203 # user system total real
204 # for: 0.960000 0.000000 0.960000 ( 0.957966)
205 # times: 0.960000 0.000000 0.960000 ( 0.960423)
206 # upto: 0.950000 0.000000 0.950000 ( 0.954864)
209 def bm(label_width = 0, *labels, &blk) # :yield: report
210 benchmark(CAPTION, label_width, FORMAT, *labels, &blk)
214 # Sometimes benchmark results are skewed because code executed
215 # earlier encounters different garbage collection overheads than
216 # that run later. #bmbm attempts to minimize this effect by running
217 # the tests twice, the first time as a rehearsal in order to get the
218 # runtime environment stable, the second time for
219 # real. GC.start is executed before the start of each of
220 # the real timings; the cost of this is not included in the
221 # timings. In reality, though, there's only so much that #bmbm can
222 # do, and the results are not guaranteed to be isolated from garbage
223 # collection and other effects.
225 # Because #bmbm takes two passes through the tests, it can
226 # calculate the required label width.
228 # require 'benchmark'
230 # array = (1..1000000).map { rand }
232 # Benchmark.bmbm do |x|
233 # x.report("sort!") { array.dup.sort! }
234 # x.report("sort") { array.dup.sort }
239 # Rehearsal -----------------------------------------
240 # sort! 1.440000 0.010000 1.450000 ( 1.446833)
241 # sort 1.440000 0.000000 1.440000 ( 1.448257)
242 # -------------------------------- total: 2.890000sec
244 # user system total real
245 # sort! 1.460000 0.000000 1.460000 ( 1.458065)
246 # sort 1.450000 0.000000 1.450000 ( 1.455963)
248 # #bmbm yields a Benchmark::Job object and returns an array of
249 # Benchmark::Tms objects.
251 def bmbm(width = 0) # :yield: job
254 width = job.width + 1
259 puts 'Rehearsal '.ljust(width+CAPTION.length,'-')
260 ets = job.list.inject(Tms.new) { |sum,(label,item)|
261 print label.ljust(width)
262 res = Benchmark.measure(&item)
265 }.format("total: %tsec")
266 print " #{ets}\n\n".rjust(width+CAPTION.length+2,'-')
269 print ' '*width + CAPTION
270 job.list.map { |label,item|
272 print label.ljust(width)
273 Benchmark.measure(label, &item).tap { |res| print res }
276 $stdout.sync = sync unless sync.nil?
280 # Returns the time used to execute the given block as a
281 # Benchmark::Tms object. Takes +label+ option.
283 # require 'benchmark'
287 # time = Benchmark.measure do
288 # n.times { a = "1" }
294 # 0.220000 0.000000 0.220000 ( 0.227313)
296 def measure(label = "") # :yield:
297 t0, r0 = Process.times, Process.clock_gettime(Process::CLOCK_MONOTONIC)
299 t1, r1 = Process.times, Process.clock_gettime(Process::CLOCK_MONOTONIC)
300 Benchmark::Tms.new(t1.utime - t0.utime,
302 t1.cutime - t0.cutime,
303 t1.cstime - t0.cstime,
309 # Returns the elapsed real time used to execute the given block.
311 def realtime # :yield:
312 r0 = Process.clock_gettime(Process::CLOCK_MONOTONIC)
314 Process.clock_gettime(Process::CLOCK_MONOTONIC) - r0
317 module_function :benchmark, :measure, :realtime, :bm, :bmbm
320 # A Job is a sequence of labelled blocks to be processed by the
321 # Benchmark.bmbm method. It is of little direct interest to the user.
325 # Returns an initialized Job instance.
326 # Usually, one doesn't call this method directly, as new
327 # Job objects are created by the #bmbm method.
328 # +width+ is a initial value for the label offset used in formatting;
329 # the #bmbm method passes its +width+ argument to this constructor.
331 def initialize(width)
337 # Registers the given label and block pair in the job list.
339 def item(label = "", &blk) # :yield:
340 raise ArgumentError, "no block" unless block_given?
343 @width = w if @width < w
344 @list << [label, blk]
350 # An array of 2-element arrays, consisting of label and block pairs.
353 # Length of the widest label in the #list.
358 # This class is used by the Benchmark.benchmark and Benchmark.bm methods.
359 # It is of little direct interest to the user.
361 class Report # :nodoc:
363 # Returns an initialized Report instance.
364 # Usually, one doesn't call this method directly, as new
365 # Report objects are created by the #benchmark and #bm methods.
366 # +width+ and +format+ are the label offset and
367 # format string used by Tms#format.
369 def initialize(width = 0, format = nil)
370 @width, @format, @list = width, format, []
374 # Prints the +label+ and measured time for the block,
375 # formatted by +format+. See Tms#format for the
378 def item(label = "", *format, &blk) # :yield:
379 print label.to_s.ljust(@width)
380 @list << res = Benchmark.measure(label, &blk)
381 print res.format(@format, *format)
387 # An array of Benchmark::Tms objects representing each item.
394 # A data object, representing the times associated with a benchmark
399 # Default caption, see also Benchmark::CAPTION
400 CAPTION = " user system total real\n"
402 # Default format string, see also Benchmark::FORMAT
403 FORMAT = "%10.6u %10.6y %10.6t %10.6r\n"
411 # User CPU time of children
414 # System CPU time of children
420 # Total time, that is +utime+ + +stime+ + +cutime+ + +cstime+
427 # Returns an initialized Tms object which has
428 # +utime+ as the user CPU time, +stime+ as the system CPU time,
429 # +cutime+ as the children's user CPU time, +cstime+ as the children's
430 # system CPU time, +real+ as the elapsed real time and +label+ as the label.
432 def initialize(utime = 0.0, stime = 0.0, cutime = 0.0, cstime = 0.0, real = 0.0, label = nil)
433 @utime, @stime, @cutime, @cstime, @real, @label = utime, stime, cutime, cstime, real, label.to_s
434 @total = @utime + @stime + @cutime + @cstime
438 # Returns a new Tms object whose times are the sum of the times for this
439 # Tms object, plus the time required to execute the code block (+blk+).
441 def add(&blk) # :yield:
442 self + Benchmark.measure(&blk)
446 # An in-place version of #add.
447 # Changes the times of this Tms object by making it the sum of the times
448 # for this Tms object, plus the time required to execute
449 # the code block (+blk+).
452 t = Benchmark.measure(&blk)
453 @utime = utime + t.utime
454 @stime = stime + t.stime
455 @cutime = cutime + t.cutime
456 @cstime = cstime + t.cstime
457 @real = real + t.real
462 # Returns a new Tms object obtained by memberwise summation
463 # of the individual times for this Tms object with those of the +other+
465 # This method and #/() are useful for taking statistics.
467 def +(other); memberwise(:+, other) end
470 # Returns a new Tms object obtained by memberwise subtraction
471 # of the individual times for the +other+ Tms object from those of this
474 def -(other); memberwise(:-, other) end
477 # Returns a new Tms object obtained by memberwise multiplication
478 # of the individual times for this Tms object by +x+.
480 def *(x); memberwise(:*, x) end
483 # Returns a new Tms object obtained by memberwise division
484 # of the individual times for this Tms object by +x+.
485 # This method and #+() are useful for taking statistics.
487 def /(x); memberwise(:/, x) end
490 # Returns the contents of this Tms object as
491 # a formatted string, according to a +format+ string
492 # like that passed to Kernel.format. In addition, #format
493 # accepts the following extensions:
495 # <tt>%u</tt>:: Replaced by the user CPU time, as reported by Tms#utime.
496 # <tt>%y</tt>:: Replaced by the system CPU time, as reported by #stime (Mnemonic: y of "s*y*stem")
497 # <tt>%U</tt>:: Replaced by the children's user CPU time, as reported by Tms#cutime
498 # <tt>%Y</tt>:: Replaced by the children's system CPU time, as reported by Tms#cstime
499 # <tt>%t</tt>:: Replaced by the total CPU time, as reported by Tms#total
500 # <tt>%r</tt>:: Replaced by the elapsed real time, as reported by Tms#real
501 # <tt>%n</tt>:: Replaced by the label string, as reported by Tms#label (Mnemonic: n of "*n*ame")
503 # If +format+ is not given, FORMAT is used as default value, detailing the
504 # user, system and real elapsed time.
506 def format(format = nil, *args)
507 str = (format || FORMAT).dup
508 str.gsub!(/(%[-+.\d]*)n/) { "#{$1}s" % label }
509 str.gsub!(/(%[-+.\d]*)u/) { "#{$1}f" % utime }
510 str.gsub!(/(%[-+.\d]*)y/) { "#{$1}f" % stime }
511 str.gsub!(/(%[-+.\d]*)U/) { "#{$1}f" % cutime }
512 str.gsub!(/(%[-+.\d]*)Y/) { "#{$1}f" % cstime }
513 str.gsub!(/(%[-+.\d]*)t/) { "#{$1}f" % total }
514 str.gsub!(/(%[-+.\d]*)r/) { "(#{$1}f)" % real }
515 format ? str % args : str
526 # Returns a new 6-element array, consisting of the
527 # label, user CPU time, system CPU time, children's
528 # user CPU time, children's system CPU time and elapsed
532 [@label, @utime, @stime, @cutime, @cstime, @real]
536 # Returns a hash containing the same data as `to_a`.
552 # Returns a new Tms object obtained by memberwise operation +op+
553 # of the individual times for this Tms object with those of the other
556 # +op+ can be a mathematical operation such as <tt>+</tt>, <tt>-</tt>,
557 # <tt>*</tt>, <tt>/</tt>
559 def memberwise(op, x)
562 Benchmark::Tms.new(utime.__send__(op, x.utime),
563 stime.__send__(op, x.stime),
564 cutime.__send__(op, x.cutime),
565 cstime.__send__(op, x.cstime),
566 real.__send__(op, x.real)
569 Benchmark::Tms.new(utime.__send__(op, x),
570 stime.__send__(op, x),
571 cutime.__send__(op, x),
572 cstime.__send__(op, x),
579 # The default caption string (heading above the output times).
580 CAPTION = Benchmark::Tms::CAPTION
582 # The default format string used to display times. See also Benchmark::Tms#format.
583 FORMAT = Benchmark::Tms::FORMAT