benchmark-inputs 1.0.1 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 5f1e62b1ab9bc9870a7d3dcc3f20e6260958ee63
-  data.tar.gz: 0c602dc860cddbd4be045d6ad06821cebb0bbbd0
+SHA256:
+  metadata.gz: a6e909d515239a8262e68c3f13b3cdb6d3840be4999b647aa1267dbd3184f69b
+  data.tar.gz: 37c78630c9af1f254438db2cb427e073a2bc97e2b25f7cedf4a0f73deba34d00
 SHA512:
-  metadata.gz: bf99df51e67a7789e185d9c36ae715697e54e57fa7d81bc1d5bdb003eaf1e5028b2468812bfaac007053396fe4568429691e59d88a2ce9ef9cf971418d404e65
-  data.tar.gz: 49e0985a2d32f963945532bc3d55f6db6eb4c22125ba47afb81903992c062a8d700adbb6fb5f57720d35f01c88a68574fee6c0b2e54638313397f4868af55e2a
+  metadata.gz: 184afc9a7110ad536dce0881db8c092958986e245e0a90af9040ac70372afac583811b29765c0098b5233e7e1c637c3c10188cce44e4e4c0d48930b96e5ccf8d
+  data.tar.gz: 9859889f725c6849d524d6fd08cb1a579c6598f1135b7000adc4cc77cb3910899a8700ee931f3679d36b36cbd11b7c19e08350b4c03b708dc8896b4f7af0c22e

data/CHANGELOG.md

@@ -0,0 +1,13 @@
+## 1.1.0
+
+* Support `Benchmark.inputs` options hash
+
+
+## 1.0.1
+
+* Fix stddev formatting
+
+
+## 1.0.0
+
+* Initial release

data/README.md

@@ -1,47 +1,51 @@
 # benchmark-inputs
 
-Input-focused benchmarking for Ruby.  Given one or more blocks and a
-list of inputs to yield to them, benchmark-inputs will measure the speed
-(in invocations per second) of each block.  Blocks which execute very
-quickly, as in microbenchmarks, are automatically invoked repeatedly to
-provide accurate measurements.
+Input-focused benchmarking for Ruby.  Given one or more blocks and an
+array of inputs to yield to each of them, benchmark-inputs will measure
+the speed (in invocations per second) of each block.  Blocks which
+execute very quickly, as in microbenchmarks, are automatically invoked
+repeatedly to provide accurate measurements.
 
 
 ## Motivation
 
 I <3 [Fast Ruby][fast-ruby].  By extension, I <3 [benchmark-ips].  But,
-for certain usages, benchmark-ips doesn't let me write benchmarks the
-way I'd like. Consider the following example, *using benchmark-ips*:
+for some use cases, benchmark-ips doesn't let me write benchmarks the
+way I'd like.  Consider the following example, *using benchmark-ips*:
 
 ```ruby
-require 'benchmark/ips' ### USING benchmark-ips (NOT benchmark-inputs)
+require "benchmark/ips" ### USING benchmark-ips (NOT benchmark-inputs)
 
-STRINGS = ['abc', 'aaa', 'xyz', '']
+STRINGS = ["abc", "aaa", "xyz", ""]
 Benchmark.ips do |job|
-  job.report('String#tr'){ STRINGS.each{|s| s.tr('a', 'A') } }
-  job.report('String#gsub'){ STRINGS.each{|s| s.gsub(/a/, 'A') } }
+  job.report("String#tr"){ STRINGS.each{|s| s.tr("a", "A") } }
+  job.report("String#gsub"){ STRINGS.each{|s| s.gsub(/a/, "A") } }
   job.compare!
 end
 ```
 
-The calls to `STRINGS.each` introduce performance overhead which skews
+The calls to `STRINGS.each` introduce performance overhead that skews
 the time measurements.  The less time the target function takes, the
-more relative overhead, and thus the more skew.  For a microbenchmark
-this can be a problem.  A possible workaround is to invoke the function
-on each value individually, but that is more verbose and error-prone:
+more relative overhead, and thus more skew.  For a microbenchmark this
+can be a problem.  A possible workaround is to invoke the function on
+each value individually, but that is more verbose and more error-prone:
 
 ```ruby
-require 'benchmark/ips' ### USING benchmark-ips (NOT benchmark-inputs)
+require "benchmark/ips" ### USING benchmark-ips (NOT benchmark-inputs)
 
-s1 = 'abc'; s2 = 'aaa'; s3 = 'xyz'; s4 = ''
+s1, s2, s3, s4 = ["abc", "aaa", "xyz", ""]
 Benchmark.ips do |job|
-  job.report('String#tr') do
-    s1.tr('a', 'A'); s2.tr('a', 'A')
-    s3.tr('a', 'A'); s4.tr('a', 'A')
+  job.report("String#tr") do
+    s1.tr("a", "A")
+    s2.tr("a", "A")
+    s3.tr("a", "A")
+    s4.tr("a", "A")
   end
-  job.report('String#gsub') do
-    s1.gsub(/a/, 'A'); s2.gsub(/a/, 'A')
-    s3.gsub(/a/, 'A'); s4.gsub(/a/, 'A')
+  job.report("String#gsub") do
+    s1.gsub(/a/, "A")
+    s2.gsub(/a/, "A")
+    s3.gsub(/a/, "A")
+    s4.gsub(/a/, "A")
   end
   job.compare!
 end
@@ -51,11 +55,11 @@ end
 this gem: <a name="example1"></a>
 
 ```ruby
-require 'benchmark/inputs' ### USING benchmark-inputs
+require "benchmark/inputs" ### USING benchmark-inputs
 
-Benchmark.inputs(['abc', 'aaa', 'xyz', '']) do |job|
-  job.report('String#tr'){|s| s.tr('a', 'A') }
-  job.report('String#gsub'){|s| s.gsub(/a/, 'A') }
+Benchmark.inputs(["abc", "aaa", "xyz", ""]) do |job|
+  job.report("String#tr"){|s| s.tr("a", "A") }
+  job.report("String#gsub"){|s| s.gsub(/a/, "A") }
   job.compare!
 end
 ```
@@ -80,18 +84,17 @@ Destructive operations also pose a challenge for microbenchmarks.  Each
 invocation needs to operate on the same data, but `dup`ing the data
 introduces too much overhead and skew.
 
-benchmark-inputs' solution is to estimate the overhead incurred by
-`dup`, and exclude that from time measurements.  Because the benchmark
-job already controls the input data, all of this can be handled with a
-single configuration line:
+benchmark-inputs' solution is to estimate the overhead incurred by each
+`dup`, and exclude that from the time measurements.  Because the
+benchmark job already controls the input data, everything can be handled
+behind the scenes.  To enable this, use the `dup_inputs` option:
 
 ```ruby
-require 'benchmark/inputs'
+require "benchmark/inputs"
 
-Benchmark.inputs(['abc', 'aaa', 'xyz', '']) do |job|
-  job.dup_inputs = true  # <--- single configuration line
-  job.report('String#tr!'){|s| s.tr!('a', 'A') }
-  job.report('String#gsub!'){|s| s.gsub!(/a/, 'A') }
+Benchmark.inputs(["abc", "aaa", "xyz", ""], dup_inputs: true) do |job|
+  job.report("String#tr!"){|s| s.tr!("a", "A") }
+  job.report("String#gsub!"){|s| s.gsub!(/a/, "A") }
   job.compare!
 end
 ```
@@ -111,7 +114,7 @@ Comparison:
 
 That shows a slightly larger performance gap than the previous
 benchmark.  This makes sense because the overhead of allocating new
-strings--previously via a non-bang method, but now via `dup`--is now
+strings -- previously via a non-bang method, but now via `dup` -- is now
 excluded from the timings.  Thus, the speed of `tr!` relative to `gsub!`
 is further emphasized.
 
@@ -129,13 +132,15 @@ problem.
 
 ## Installation
 
-    $ gem install benchmark-inputs
+```bash
+$ gem install benchmark-inputs
+```
 
 
 ## Usage
 
-See the [example above](#example1), or check the
-[documentation](http://www.rubydoc.info/gems/benchmark-inputs).
+See the [example above](#example1), or check out the
+[API documentation](http://www.rubydoc.info/gems/benchmark-inputs).
 
 
 ## License
@@ -146,4 +151,4 @@ See the [example above](#example1), or check the
 
 
 [fast-ruby]: https://github.com/JuanitoFatas/fast-ruby
-[benchmark-ips]: https://github.com/evanphx/benchmark-ips
+[benchmark-ips]: https://rubygems.org/gems/benchmark-ips

data/benchmark-inputs.gemspec

@@ -19,7 +19,7 @@ Gem::Specification.new do |spec|
   spec.require_paths = ["lib"]
 
   spec.add_development_dependency "bundler", "~> 1.12"
-  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "rake", ">= 10.0"
   spec.add_development_dependency "minitest", "~> 5.0"
-  spec.add_development_dependency "yard", "~> 0.8"
+  spec.add_development_dependency "yard", "~> 0.9"
 end

data/lib/benchmark/inputs.rb

@@ -1,23 +1,45 @@
-require 'benchmark/inputs/version'
+require "benchmark/inputs/version"
 
 module Benchmark
 
   # Initializes a benchmark job with the given inputs and yields that
   # job to the given block.
   #
-  # Example:
-  #   Benchmark.inputs(['abc', 'aaa', 'xyz', '']) do |job|
-  #     job.report('String#tr'){|s| s.tr('a', 'A') }
-  #     job.report('String#gsub'){|s| s.gsub(/a/, 'A') }
+  # @example Benchmarking non-destructive operations
+  #   Benchmark.inputs(["abc", "aaa", "xyz", ""]) do |job|
+  #     job.report("String#tr"){|s| s.tr("a", "A") }
+  #     job.report("String#gsub"){|s| s.gsub(/a/, "A") }
   #     job.compare!
   #   end
   #
-  # @param [Array] vals input values to yield to each benchmark action
-  # @yield [job] configures job and runs benchmarks
-  # @yieldparam [Benchmark::Inputs::Job] job benchmark runner
-  # @return [Benchmark::Inputs::Job] benchmark runner
-  def self.inputs(vals)
-    job = Inputs::Job.new(vals)
+  # @example Benchmarking destructive operations
+  #   Benchmark.inputs(["abc", "aaa", "xyz", ""], dup_inputs: true) do |job|
+  #     job.report("String#tr!"){|s| s.tr!("a", "A") }
+  #     job.report("String#gsub!"){|s| s.gsub!(/a/, "A") }
+  #     job.compare!
+  #   end
+  #
+  # @param values [Array]
+  #   input values to yield to each benchmark action
+  # @param options [Hash]
+  # @option options :dup_inputs [Boolean]
+  #   whether input values will be +dup+-ed before they are passed to a
+  #   {Inputs::Job#report} block
+  # @option options :sample_n [Integer]
+  #   number of samples to take when benchmarking
+  # @option options :sample_dt [Integer]
+  #   approximate duration of time (in nanoseconds) each sample should
+  #   take when benchmarking
+  # @yield [job]
+  #   configures job and runs benchmarks
+  # @yieldparam job [Benchmark::Inputs::Job]
+  #   benchmark runner
+  # @return [Benchmark::Inputs::Job]
+  #   benchmark runner
+  # @raise [ArgumentError]
+  #   if +values+ is empty
+  def self.inputs(values, **options)
+    job = Inputs::Job.new(values, options)
     yield job
     job
   end
@@ -29,46 +51,78 @@ module Benchmark
     NS_PER_MS = NS_PER_S / 1_000
 
     class Job
-      attr_accessor :sample_n, :sample_dt
-      attr_reader   :dup_inputs, :reports
 
-      def initialize(inputs)
+      # @param inputs [Array]
+      #   input values to yield to each benchmark action
+      # @param dup_inputs [Boolean]
+      #   whether input values will be +dup+-ed before they are passed
+      #   to a {report} block
+      # @param sample_n [Integer]
+      #   number of samples to take when benchmarking
+      # @param sample_dt [Integer]
+      #   approximate duration of time (in nanoseconds) each sample
+      #   should take when benchmarking
+      # @raise [ArgumentError]
+      #   if +inputs+ is empty
+      def initialize(inputs, dup_inputs: false, sample_n: 10, sample_dt: NS_PER_MS * 200)
+        raise ArgumentError, "No inputs specified" if inputs.empty?
+
         @inputs = inputs
-        @dup_inputs = false
-        @sample_n = 10
-        @sample_dt = NS_PER_MS * 200
+        @dup_inputs = dup_inputs
+        @sample_n = sample_n
+        @sample_dt = sample_dt
         @reports = []
         def_bench!
       end
 
-      # Sets the +dup_inputs+ flag.  If set to true, causes input values
-      # to be +dup+'d before they are passed to a +report+ block.  This
-      # is necessary when +report+ blocks destructively modify their
+      # Indicates whether input values will be +dup+-ed before they are
+      # passed to a {report} block.  Defaults to +false+.  This should
+      # be set to +true+ if {report} blocks destructively modify their
       # arguments.
       #
-      # Example:
-      #   Benchmark.inputs(['abc', 'aaa', 'xyz', '']) do |job|
-      #     job.dup_inputs = true  # <---
-      #     job.report('String#tr!'){|s| s.tr!('a', 'A') }
-      #     job.report('String#gsub!'){|s| s.gsub!(/a/, 'A') }
-      #     job.compare!
-      #   end
+      # @return [Boolean]
+      attr_reader :dup_inputs
+
+      # See {dup_inputs}.
       #
-      # @param [Boolean] val value to set
-      def dup_inputs=(val)
-        @dup_inputs = val
+      # @param flag [Boolean]
+      # @return [Boolean]
+      def dup_inputs=(flag)
+        @dup_inputs = flag
         def_bench!
         @dup_inputs
       end
 
-      # Benchmarks the given block using the initially provided input
-      # values.  If +#dup_inputs+ is set to true, each input value is
-      # +dup+'d before being passed to the block.  Afterwards, the
-      # block's invocations per second (i/s) is printed to +$stdout+.
+      # The number of samples to take when benchmarking.  Defaults to 10.
+      #
+      # @return [Integer]
+      attr_accessor :sample_n
+
+      # The approximate duration of time (in nanoseconds) each sample
+      # should take when benchmarking.  Defaults to 200,000 nanoseconds.
+      #
+      # @return [Integer]
+      attr_accessor :sample_dt
+
+      # Array of benchmark reports.  Each call to {report} adds an
+      # element to this array.
       #
-      # @param [String] label label for the benchmark
-      # @yield [input] action to benchmark
-      # @yieldparam input one of the initially provided input values
+      # @return [Array<Benchmark::Inputs::Report>]
+      attr_reader :reports
+
+      # Benchmarks the given block using the previously provided input
+      # values.  If {dup_inputs} is set to true, each input value is
+      # +dup+'d before being passed to the block.  The block's
+      # iterations per second (i/s) is printed to +$stdout+, and a
+      # {Report} is added to {reports}.
+      #
+      # @param label [String]
+      #   label for the benchmark
+      # @yield [input]
+      #   action to benchmark
+      # @yieldparam input [Object]
+      #   one of the initially provided input values
+      # @return [void]
       def report(label)
         # estimate repititions
         reps = 1
@@ -91,13 +145,14 @@ module Benchmark
         $stdout.puts(r.label)
         $stdout.printf("  %.1f i/s (\u00B1%.2f%%)\n", r.ips, r.stddev / r.ips * 100)
         @reports << r
-        r
       end
 
       # Prints the relative speeds (from fastest to slowest) of all
-      # +#report+ed benchmarks to +$stdout+.
+      # {report}-ed benchmarks to +$stdout+.
+      #
+      # @return [void]
       def compare!
-        return $stdout.puts('Nothing to compare!') if @reports.empty?
+        return $stdout.puts("Nothing to compare!") if @reports.empty?
 
         @reports.sort_by!{|r| -r.ips }
         @reports.each{|r| r.slower_than!(@reports.first) }
@@ -109,9 +164,9 @@ module Benchmark
         @reports.each_with_index do |r, i|
           $stdout.printf(format, r.label, r.ips)
           if r.ratio
-            $stdout.printf(' - %.2fx slower', r.ratio)
+            $stdout.printf(" - %.2fx slower", r.ratio)
           elsif i > 0
-            $stdout.printf(' - same-ish: difference falls within error')
+            $stdout.printf(" - same-ish: difference falls within error")
           end
           $stdout.puts
         end
@@ -123,12 +178,11 @@ module Benchmark
       def def_bench!
         assigns = @inputs.each_index.map do |i|
           "x#{i} = @inputs[#{i}]"
-        end.join(';')
+        end.join(";")
 
-        yields = @inputs.each_with_index.map do |x, i|
-          dup = (@dup_inputs && x.respond_to?(:dup)) ? '.dup' : ''
-          "yield(x#{i}#{dup})"
-        end.join(';')
+        yields = @inputs.each_index.map do |i|
+          dup_inputs ? "yield(x#{i}.dup)" : "yield(x#{i})"
+        end.join(";")
 
         code = <<-CODE
           def bench(reps)
@@ -151,8 +205,21 @@ module Benchmark
 
 
     class Report
-      attr_reader :label, :ratio
+      # The label for the report.
+      #
+      # @return [String]
+      attr_reader :label
+
+      # The ratio of iterations per second for this report compared to
+      # the fastest report.  Will be +nil+ if the difference between the
+      # two falls within the combined measurement error.
+      #
+      # This value is set by {Benchmark::Inputs::Job#compare!}.
+      #
+      # @return [Float, nil]
+      attr_reader :ratio
 
+      # @!visibility private
       def initialize(label, invocs_per_sample)
         @label = label.to_s
         @invocs_per_sample = invocs_per_sample.to_f
@@ -163,6 +230,7 @@ module Benchmark
         @m2 = 0.0
       end
 
+      # @!visibility private
       def add_sample(time_ns)
         sample_ips = @invocs_per_sample * NS_PER_S / time_ns
 
@@ -175,18 +243,26 @@ module Benchmark
         @stddev = nil
       end
 
+      # The estimated iterations per second for the report.
+      #
+      # @return [Float]
       def ips
         @mean
       end
 
+      # The {ips} standard deviation.
+      #
+      # @return [Float]
       def stddev
         @stddev ||= @n < 2 ? 0.0 : Math.sqrt(@m2 / (@n - 1))
       end
 
+      # @!visibility private
       def slower_than!(faster)
         @ratio = overlap?(faster) ? nil : (faster.ips / self.ips)
       end
 
+      # @!visibility private
       def overlap?(faster)
         (faster.ips - faster.stddev) <= (self.ips + self.stddev)
       end

data/lib/benchmark/inputs/version.rb

@@ -1,5 +1,5 @@
 module Benchmark
   module Inputs
-    VERSION = "1.0.1"
+    VERSION = "1.1.0"
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: benchmark-inputs
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 1.1.0
 platform: ruby
 authors:
 - Jonathan Hefner
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-07-05 00:00:00.000000000 Z
+date: 2019-03-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -28,14 +28,14 @@ dependencies:
   name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '10.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '10.0'
 - !ruby/object:Gem::Dependency
@@ -58,14 +58,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.8'
+        version: '0.9'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.8'
+        version: '0.9'
 description: 
 email:
 - jonathan.hefner@gmail.com
@@ -75,6 +75,7 @@ extra_rdoc_files: []
 files:
 - ".gitignore"
 - ".travis.yml"
+- CHANGELOG.md
 - Gemfile
 - LICENSE.txt
 - README.md
@@ -101,10 +102,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.4.8
+rubygems_version: 3.0.1
 signing_key: 
 specification_version: 4
 summary: Input-focused benchmarking
 test_files: []
-has_rdoc: