summaryrefslogtreecommitdiff
path: root/lib/benchmark.rb
diff options
context:
space:
mode:
Diffstat (limited to 'lib/benchmark.rb')
-rw-r--r--lib/benchmark.rb651
1 files changed, 651 insertions, 0 deletions
diff --git a/lib/benchmark.rb b/lib/benchmark.rb
new file mode 100644
index 0000000..e6c63a7
--- /dev/null
+++ b/lib/benchmark.rb
@@ -0,0 +1,651 @@
+#
+# benchmark.rb
+#
+=begin
+ 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)
+=end
+
+=begin
+= 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)
+ ----------
+
+== Benchmark module
+
+=== CONSTANT
+:CAPTION
+ CAPTION is a caption string which is used in Benchmark::((<benchmark>)) and
+ Benchmark::Report#((<report>)).
+:FMTSTR
+ FMTSTR is a format string which is used in Benchmark::((<benchmark>)) and
+ Benchmark::Report#((<report>)). See also Benchmark::Tms#((<format>)).
+:BENCHMARK_VERSION
+ BENCHMARK_VERSION is version string which statnds for the last modification
+ date (YYYY-MM-DD).
+
+=== INNER CLASS
+* ((<Benchmark::Job>))
+* ((<Benchmark::Report>))
+* ((<Benchmark::Tms>))
+
+=== MODULE FUNCTION
+==== benchmark
+ ----------
+ benchmark([caption [, label_width [, fmtstr]]]) do |x| ... end
+ benchmark([caption [, label_width [, fmtstr]]]) do array_of_Tms end
+ benchmark([caption [, label_width [, fmtstr [, labels...]]]]) do
+ ...
+ array_of_Tms
+ end
+ ----------
+
+(({benchmark})) reports the times. In the first form the block variable x is
+treated as a ((<Benchmark::Report>)) object, which has ((<report>)) method.
+In the second form, each member of array_of_Tms is reported in the
+specified form if the member is a ((<Benchmark::Tms>)) object. The
+last form provides combined above two forms (See ((<EXAMPLE 3>))).
+
+The following lists the meaning of each option.
+
+:caption
+ A string ((|caption|)) is printed once before execution of the given block.
+
+:label_width
+ An integer ((|label_width|)) is used as an offset in each report.
+
+:fmtstr
+ An string ((|fmtstr|)) is used to format each measurement.
+ See ((<format>))
+
+:labels
+ The rest parameters labels is used as prefix of the format to the
+ value of block, that is array_of_Tms.
+
+==== bm
+ ----------
+ bm([label_width [, labels ...]) do ... end
+ ----------
+
+(({bm})) is a simpler interface of ((<benchmark>)).
+(({bm})) acts as same as follows:
+
+ benchmark(" "*label_width + CAPTION, label_width, FMTSTR, *labels) do
+ ...
+ end
+
+==== bmbm
+ ----------
+ bmbm([label_width]) do |x|
+ x.item("label1") { .... }
+ ....
+ end
+ ----------
+
+(({bmbm})) is yet another ((<benchmark>)). This utility function is
+provited to prevent a kind of job order dependency, which is caused
+by memory allocation and object creation. The usage is similar to
+((<bm>)) but has less options and does extra three things:
+
+ (1) ((*Rehearsal*)): runs all items in the job ((<list>)) to allocate
+ enough memory.
+ (2) ((*GC*)): before each ((<measure>))ment, invokes (({GC.start})) to
+ prevent the influence of previous job.
+ (3) If given ((|label_width|)) is less than the maximal width of labels
+ given as ((|item|))'s argument, the latter is used.
+ Because (({bmbm})) is a 2-pass procedure, this is possible.
+
+(({bmbm})) returns an array which consists of Tms correspoding to each
+(({item})).
+==== measure
+ ----------
+ measure([label]) do ... end
+ ----------
+
+measure returns the times used and passed to execute the given block as a
+Benchmark::Tms object.
+
+==== realtime
+ ----------
+ realtime do ... end
+ ----------
+
+realtime returns the times passed to execute the given block.
+
+== Benchmark::Report
+
+=== CLASS METHOD
+
+==== Benchmark::Report::new(width)
+ ----------
+ Benchmark::Report::new([width [, fmtstr]])
+ ----------
+
+Usually, one doesn't have to use this method directly,
+(({Benchmark::Report::new})) is called by ((<benchmark>)) or ((<bm>)).
+((|width|)) and ((|fmtstr|)) are the offset of ((|label|)) and
+format string responsively; Both of them are used in ((<format>)).
+
+=== METHOD
+
+==== report
+
+ ----------
+ report(fmt, *args)
+ ----------
+
+This method reports label and time formated by ((|fmt|)). See
+((<format>)) of Benchmark::Tms for formatting rule.
+
+== Benchmark::Tms
+
+=== CLASS METHOD
+
+== Benchmark::Job
+
+=== CLASS METHOD
+
+==== Benchmark::Job::new
+ ----------
+ Benchmark::Job::new(width)
+ ----------
+
+Usually, one doesn't have to use this method directly,
+(({Benchmark::Job::new})) is called by ((<bmbm>)).
+((|width|)) is a initial value for the offset ((|label|)) for formatting.
+((<bmbm>)) passes its argument ((|width|)) to this constructor.
+
+=== METHOD
+
+==== item
+ ----------
+ item(((|lable|))){ .... }
+ ----------
+
+(({item})) registers a pair of (((|label|))) and given block as job ((<list>)).
+==== width
+
+Maximum length of labels in ((<list>)) plus one.
+
+==== list
+
+array of array which consists of label and jop proc.
+
+==== report
+
+alias to ((<item>)).
+
+==== Benchmark::Tms::new
+ ----------
+ Benchmark::Tms::new([u [, s [, cu [, cs [, re [, l]]]]]])
+ ----------
+
+returns new Benchmark::Tms object which has
+((|u|)) as ((<utime>)),
+((|s|)) as ((<stime>)),
+((|cu|)) as ((<cutime>))
+((|cs|)) as ((<cstime>)),
+((|re|)) as ((<real>)) and
+((|l|)) as ((<label>)).
+
+The default value is assumed as 0.0 for ((|u|)), ((|s|)), ((|cu|)),
+((|cs|)) and ((|re|)). The default of ((|l|)) is null string ((({""}))).
+
+==== operator +
+ ----------
+ tms1 + tms2
+ ----------
+
+returns a new Benchmark::Tms object as memberwise summation.
+This method and ((<(('operator /'))>)) is useful to take statistics.
+
+==== operator /
+ ----------
+ tms / num
+ ----------
+
+returns a new Benchmark::Tms object as memberwise division by ((|num|)).
+This method and ((<operator +>)) is useful to take statistics.
+
+==== add
+ ----------
+ add do ... end
+ ----------
+
+returns a new Benchmark::Tms object which is the result of additional
+execution which is given by block.
+
+==== add!
+ ----------
+ add! do ... end
+ ----------
+
+do additional execution which is given by block.
+
+==== format
+ ----------
+ format([fmtstr [, *args]])
+ ----------
+
+(({format})) returns formatted string of (({self})) according to a
+((|fmtstr|)) like (({Kernel::format})). In addition, (({format})) accepts
+some extentions as follows:
+ :%u
+ ((<utime>)).
+ :%y
+ ((<stime>)). (Mnemonic: y of ``s((*y*))stem'')
+ :%U
+ ((<cutime>)).
+ :%Y
+ ((<cstime>)).
+ :%t
+ ((<total>)).
+ :%r
+ ((<real>)).
+ :%n
+ ((<label>)). (Mnemonic: n of ``((*n*))ame'')
+
+If fmtstr is not given ((<FMTSTR>)) is used as default value.
+
+==== utime
+
+returns user time.
+
+==== stime
+
+returns system time.
+
+==== cutime
+
+returns user time of children.
+
+==== cstime
+
+returns system time of children.
+
+==== total
+
+returns total time, that is
+((<utime>)) + ((<stime>)) + ((<cutime>)) + ((<cstime>)).
+
+==== real
+
+returns really passed time.
+
+==== label
+
+returns label.
+
+==== to_a
+
+returns a new array as follows
+
+ [label, utime, stime, cutime, cstime, real]
+
+==== to_s
+
+same as (({format()})). See also ((<format>)).
+
+== HISTORY
+<<< benchmark.rb
+
+== AUTHOR
+
+Gotoken (gotoken@notwork.org).
+=end
+
+module Benchmark
+ BENCHMARK_VERSION = "2001-11-26"
+
+ def Benchmark::times()
+ Process::times()
+ end
+
+ def benchmark(caption = "", label_width = nil, fmtstr = nil, *labels)
+ 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
+
+ def bm(label_width = 0, *labels, &blk)
+ benchmark(" "*label_width + CAPTION, label_width, FMTSTR, *labels, &blk)
+ end
+
+ def bmbm(width = 0, &blk)
+ job = Job.new(width)
+ yield(job)
+ width = job.width
+ sync = STDOUT.sync
+ STDOUT.sync = true
+
+ # rehearsal
+ print "Rehearsal "
+ puts '-'*(width+CAPTION.length - "Rehearsal ".length)
+ list = []
+ job.list.each{|label,item|
+ print(label.ljust(width))
+ res = Benchmark::measure(&item)
+ print res.format(@fmtstr)
+ list.push res
+ }
+ sum = Tms.new; list.each{|i| sum += i}
+ ets = sum.format("total: %tsec")
+ printf("%s %s\n\n",
+ "-"*(width+CAPTION.length-ets.length-1), ets)
+
+ # take
+ print ' '*width, CAPTION
+ list = []
+ ary = []
+ job.list.each{|label,item|
+ GC::start
+ print label.ljust(width)
+ res = Benchmark::measure(&item)
+ print res.format(@fmtstr)
+ ary.push res
+ list.push [label, res]
+ }
+
+ STDOUT.sync = sync
+ ary
+ end
+
+ def measure(label = "")
+ 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
+
+ def realtime(&blk)
+ Benchmark::measure(&blk).real
+ end
+
+ class Job
+ def initialize(width)
+ @width = width
+ @list = []
+ end
+
+ def item(label = "", &blk)
+ 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
+ attr_reader :list, :width
+ end
+
+ module_function :benchmark, :measure, :realtime, :bm, :bmbm
+
+ class Report
+ def initialize(width = 0, fmtstr = nil)
+ @width, @fmtstr = width, fmtstr
+ end
+
+ def item(label = "", *fmt, &blk)
+ print label.ljust(@width)
+ res = Benchmark::measure(&blk)
+ print res.format(@fmtstr, *fmt)
+ res
+ end
+
+ alias report item
+ end
+
+ class Tms
+ CAPTION = " user system total real\n"
+ FMTSTR = "%10.6u %10.6y %10.6t %10.6r\n"
+
+ attr_reader :utime, :stime, :cutime, :cstime, :real, :total, :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
+
+ def add(&blk)
+ self + Benchmark::measure(&blk)
+ end
+
+ 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
+
+ def +(x); memberwise(:+, x) end
+ def -(x); memberwise(:-, x) end
+ def *(x); memberwise(:*, x) end
+ def /(x); memberwise(:/, x) end
+
+ 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
+
+ def to_s
+ format
+ end
+
+ 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
+
+ CAPTION = Benchmark::Tms::CAPTION
+ 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