benchmark-ips 2.10.0 → 2.14.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0516f3e1e35f43a8fe32a6f32357aa124478ba54228ffe57d928cfc1231851bc
-  data.tar.gz: d62da6a6c1d2696b7667bd125ffe6bb2c33b3d61da5c393e729d7ca8a3d70ee7
+  metadata.gz: aaebdee644671b1a757ded5e4868e1035718834832d2cfec8eb4460a3fa33171
+  data.tar.gz: a7349d06bb190b2ea9b7c06caf8da4ba26a48b00e550ca8a71ed1fe22ddff290
 SHA512:
-  metadata.gz: b644d293980f1ac9e3158abbe4f2c9d44d23185878edb9cb3861f3ca4f6837d557f89f8eb19bfcc42a45f53f3d112f2fe3ab22fc85a9633ede7e678b5fb90336
-  data.tar.gz: afe9972cdecdb2f42d4946afbac3d02cb3ead3a3d47a804960026ea77487cf885f6ddd7368edb13c522ee11e251599bf953d3d9a8172411c10e7259f7e9352b2
+  metadata.gz: 5b2cef3b3b852b48eb8cdbaa1b51b728edb0760d77983d5408e81a44d9dfc280f257456a57d8a213155ca0752508c81282e243daf2cbb16d1a95bdaac1b4d211
+  data.tar.gz: 509f946e113907d26745e24a07675684b6870189fcdc36128380b286e774bb03e46a4608b3852aa68e110a2c1e594436e727b9626111bebf1b1a4bdeea7f71f8

data/History.md

@@ -1,3 +1,24 @@
+### 2.14.0 / 2024-09-08
+
+* Feature
+  * Adds Benchmark::IPS.quick_compare.
+  * Adds absolute duration of each iteration to compare output.
+
+### 2.13.0 / 2023-12-12
+
+* Feature
+  * Prints ruby version at top of report.
+
+### 2.12.0 / 2023-03-08
+
+* Feature
+  * Adds MultiReport and ability report to a stream rather than a string.
+
+### 2.11.0 / 2023-02-15
+
+* Feature
+  * Adds .json! method to the ips block argument, allowing you to print the output as JSON to a file or STDOUT.
+
 ### 2.10.0 / 2022-02-17
 
 * Feature
@@ -177,7 +198,7 @@ Add missing files
 * 1 minor fix:
   * Don't send label through printf so that % work directly
 
-* 1 documenation changes:
+* 1 documentation changes:
   * Use HEREDOC and wrap at 80 chars for example result description
 
 * 1 usage fix:

data/README.md

@@ -27,11 +27,7 @@ require 'benchmark/ips'
 Benchmark.ips do |x|
   # Configure the number of seconds used during
   # the warmup phase (default 2) and calculation phase (default 5)
-  x.config(:time => 5, :warmup => 2)
-
-  # These parameters can also be configured this way
-  x.time = 5
-  x.warmup = 2
+  x.config(warmup: 2, time: 5)
 
   # Typical mode, runs the block as many times as it can
   x.report("addition") { 1 + 2 }
@@ -43,8 +39,9 @@ Benchmark.ips do |x|
   x.report("addition2") do |times|
     i = 0
     while i < times
-      1 + 2
       i += 1
+
+      1 + 2
     end
   end
 
@@ -64,24 +61,24 @@ end
 This will generate the following report:
 
 ```
-Calculating -------------------------------------
-            addition    71.254k i/100ms
-           addition2    68.658k i/100ms
-           addition3    83.079k i/100ms
+Warming up --------------------------------------
+            addition     3.572M i/100ms
+           addition2     3.672M i/100ms
+           addition3     3.677M i/100ms
 addition-test-long-label
-                        70.129k i/100ms
--------------------------------------------------
-            addition     4.955M (± 8.7%) i/s -     24.155M
-           addition2    24.011M (± 9.5%) i/s -    114.246M
-           addition3    23.958M (±10.1%) i/s -    115.064M
+                         3.511M i/100ms
+Calculating -------------------------------------
+            addition     36.209M (± 2.8%) i/s   (27.62 ns/i) -    182.253M in   5.037433s
+           addition2     36.552M (± 7.8%) i/s   (27.36 ns/i) -    183.541M in   5.069987s
+           addition3     36.639M (± 4.8%) i/s   (27.29 ns/i) -    182.994M in   5.009234s
 addition-test-long-label
-                         5.014M (± 9.1%) i/s -     24.545M
+                         36.164M (± 5.8%) i/s   (27.65 ns/i) -    181.312M in   5.038364s
 
 Comparison:
-           addition2: 24011974.8 i/s
-           addition3: 23958619.8 i/s - 1.00x slower
-addition-test-long-label:  5014756.0 i/s - 4.79x slower
-            addition:  4955278.9 i/s - 4.85x slower
+           addition2: 36558904.5 i/s
+           addition3: 36359284.0 i/s - same-ish: difference falls within error
+addition-test-long-label: 36135428.8 i/s - same-ish: difference falls within error
+            addition: 34666931.3 i/s - same-ish: difference falls within error
 ```
 
 Benchmark/ips will report the number of iterations per second for a given block
@@ -94,6 +91,18 @@ One benefit to using this method is benchmark-ips automatically determines the
 data points for testing our code, so we can focus on the results instead of
 guessing iteration counts as we do with the traditional Benchmark library.
 
+You can also use `ips_quick` to save a few lines of code:
+
+```ruby
+Benchmark.ips_quick(:upcase, :downcase, on: "hello") # runs a suite comparing "hello".upcase and "hello".downcase
+
+def first; MyJob.perform(1); end
+def second; MyJobOptimized.perform(1); end
+Benchmark.ips_quick(:first, :second) # compares :first and :second
+```
+
+This adds a very small amount of overhead, which may be significant (i.e. ips_quick will understate the difference) if you're microbenchmarking things that can do over 1 million iterations per second. In that case, you're better off using the full format.
+
 ### Custom Suite
 
 Pass a custom suite to disable garbage collection during benchmark:
@@ -237,6 +246,29 @@ Benchmark.ips do |x|
 end
 ```
 
+### Output as JSON
+
+You can generate output in JSON. If you want to write JSON to a file, pass filename to `json!` method:
+
+```ruby
+Benchmark.ips do |x|
+  x.report("some report") {  }
+  x.json! 'filename.json'
+end
+```
+
+If you want to write JSON to STDOUT, pass `STDOUT` to `json!` method and set `quiet = true` before `json!`:
+
+```ruby
+Benchmark.ips do |x|
+  x.report("some report") {  }
+  x.quiet = true
+  x.json! STDOUT
+end
+```
+
+This is useful when the output from `benchmark-ips` becomes an input of other tools via stdin.
+
 ## REQUIREMENTS:
 
 * None!

data/examples/quick.rb

@@ -0,0 +1,17 @@
+#!/usr/bin/env ruby
+
+require 'benchmark/ips'
+
+def add
+  1 + 1
+end
+
+def sub
+  2 - 1
+end
+
+Benchmark.ips_quick(:add, :sub, warmup: 1, time: 1)
+
+h = {}
+
+Benchmark.ips_quick(:size, :empty?, on: h)

data/lib/benchmark/compare.rb

@@ -64,7 +64,7 @@ module Benchmark
         sorted = entries.sort_by{ |e| e.stats.central_tendency }.reverse
         baseline = sorted.shift
       else
-        raise ArgumentError, "Unknwon order: #{order.inspect}"
+        raise ArgumentError, "Unknown order: #{order.inspect}"
       end
 
       $stdout.puts "\nComparison:"

data/lib/benchmark/ips/job/multi_report.rb

@@ -0,0 +1,67 @@
+module Benchmark
+  module IPS
+    class Job
+      class MultiReport
+        # @returns out [Array<StreamReport>] list of reports to send output
+        attr_accessor :out
+
+        def empty?
+          @out.empty?
+        end
+
+        def quiet?
+          @out.none? { |rpt| rpt.kind_of?(StreamReport) }
+        end
+
+        def quiet!
+          @out.delete_if { |rpt| rpt.kind_of?(StreamReport) }
+        end
+
+        # @param report [StreamReport] report to accept input?
+        def <<(report)
+          if report.kind_of?(MultiReport)
+            self << report.out
+          elsif report.kind_of?(Enumerable)
+            @out += report
+          elsif report
+            @out << report
+          end
+        end
+
+        # @param out [Array<StreamReport>] list of reports to send output
+        def initialize(out = nil)
+          @out = []
+          self << out
+        end
+
+        def start_warming
+          @out.each { |o| o.start_warming if o.respond_to?(:start_warming) }
+        end
+
+        def warming(label, warmup)
+          @out.each { |o| o.warming(label, warmup) }
+        end
+
+        def warmup_stats(warmup_time_us, timing)
+          @out.each { |o| o.warmup_stats(warmup_time_us, timing) }
+        end
+
+        def start_running
+          @out.each { |o| o.start_running if o.respond_to?(:start_running) }
+        end
+
+        def running(label, warmup)
+          @out.each { |o| o.running(label, warmup) }
+        end
+
+        def add_report(item, caller)
+          @out.each { |o| o.add_report(item, caller) }
+        end
+
+        def footer
+          @out.each { |o| o.footer if o.respond_to?(:footer) }
+        end
+      end
+    end
+  end
+end

data/lib/benchmark/ips/job/{stdout_report.rb → stream_report.rb}

@@ -1,43 +1,45 @@
 module Benchmark
   module IPS
     class Job
-      class StdoutReport
-        def initialize
+      class StreamReport
+        def initialize(stream = $stdout)
           @last_item = nil
+          @out = stream
         end
 
         def start_warming
-          $stdout.puts "Warming up --------------------------------------"
+          @out.puts RUBY_DESCRIPTION
+          @out.puts "Warming up --------------------------------------"
         end
 
         def start_running
-          $stdout.puts "Calculating -------------------------------------"
+          @out.puts "Calculating -------------------------------------"
         end
 
         def warming(label, _warmup)
-          $stdout.print rjust(label)
+          @out.print rjust(label)
         end
 
         def warmup_stats(_warmup_time_us, timing)
           case format
           when :human
-            $stdout.printf "%s i/100ms\n", Helpers.scale(timing)
+            @out.printf "%s i/100ms\n", Helpers.scale(timing)
           else
-            $stdout.printf "%10d i/100ms\n", timing
+            @out.printf "%10d i/100ms\n", timing
           end
         end
 
         alias_method :running, :warming
 
         def add_report(item, caller)
-          $stdout.puts " #{item.body}"
+          @out.puts " #{item.body}"
           @last_item = item
         end
 
         def footer
           return unless @last_item
           footer = @last_item.stats.footer
-          $stdout.puts footer.rjust(40) if footer
+          @out.puts footer.rjust(40) if footer
         end
 
         private

data/lib/benchmark/ips/job.rb

@@ -53,11 +53,15 @@ module Benchmark
 
       # Silence output
       # @return [Boolean]
-      attr_reader :quiet
+      def quiet
+        @out.quiet?
+      end
 
       # Suite
-      # @return [Benchmark::IPS::NoopSuite]
-      attr_reader :suite
+      # @return [Benchmark::IPS::MultiReport]
+      def suite
+        @out
+      end
 
       # Instantiate the Benchmark::IPS::Job.
       def initialize opts={}
@@ -81,7 +85,7 @@ module Benchmark
         @stats = :sd
         @confidence = 95
 
-        self.quiet = false
+        @out = MultiReport.new(StreamReport.new)
       end
 
       # Job configuration options, set +@warmup+ and +@time+.
@@ -91,24 +95,23 @@ module Benchmark
       def config opts
         @warmup = opts[:warmup] if opts[:warmup]
         @time = opts[:time] if opts[:time]
-        @suite = opts[:suite] if opts[:suite]
         @iterations = opts[:iterations] if opts[:iterations]
         @stats = opts[:stats] if opts[:stats]
         @confidence = opts[:confidence] if opts[:confidence]
         self.quiet = opts[:quiet] if opts.key?(:quiet)
-        self.suite = opts[:suite]
+        self.suite = opts[:suite] if opts[:suite]
       end
 
       def quiet=(val)
-        @stdout = reporter(quiet: val)
+        if val # remove instances of StreamReport
+          @out.quiet!
+        else # ensure there is an instance of StreamReport
+          @out << StreamReport.new if @out.quiet?
+        end
       end
 
       def suite=(suite)
-        @suite = suite || Benchmark::IPS::NoopSuite.new
-      end
-
-      def reporter(quiet:)
-        quiet ? NoopReport.new : StdoutReport.new
+        @out << suite
       end
 
       # Return true if job needs to be compared.
@@ -200,7 +203,7 @@ module Benchmark
         (after.to_f - before.to_f) * MICROSECONDS_PER_SECOND
       end
 
-      # Calculate the interations per second given the number
+      # Calculate the iterations per second given the number
       # of cycles run and the time in microseconds that elapsed.
       # @param [Integer] cycles Cycles.
       # @param [Integer] time_us Time in microsecond.
@@ -245,19 +248,19 @@ module Benchmark
 
       def run
         if @warmup && @warmup != 0 then
-          @stdout.start_warming
+          @out.start_warming
           @iterations.times do
             run_warmup
           end
         end
 
-        @stdout.start_running
+        @out.start_running
 
         @iterations.times do |n|
           run_benchmark
         end
 
-        @stdout.footer
+        @out.footer
       end
 
       # Run warmup.
@@ -265,8 +268,7 @@ module Benchmark
         @list.each do |item|
           next if run_single? && @held_results && @held_results.key?(item.label)
 
-          @suite.warming item.label, @warmup
-          @stdout.warming item.label, @warmup
+          @out.warming item.label, @warmup
 
           Timing.clean_env
 
@@ -300,8 +302,7 @@ module Benchmark
             item.call_times cycles
           end
 
-          @stdout.warmup_stats warmup_time_us, @timing[item]
-          @suite.warmup_stats warmup_time_us, @timing[item]
+          @out.warmup_stats warmup_time_us, @timing[item]
 
           break if run_single?
         end
@@ -312,8 +313,7 @@ module Benchmark
         @list.each do |item|
           next if run_single? && @held_results && @held_results.key?(item.label)
 
-          @suite.running item.label, @time
-          @stdout.running item.label, @time
+          @out.running item.label, @time
 
           Timing.clean_env
 
@@ -355,8 +355,7 @@ module Benchmark
             rep.show_total_time!
           end
 
-          @stdout.add_report rep, caller(1).first
-          @suite.add_report rep, caller(1).first
+          @out.add_report rep, caller(1).first
 
           break if run_single?
         end

data/lib/benchmark/ips/report.rb

@@ -62,7 +62,7 @@ module Benchmark
 
         # Control if the total time the job took is reported.
         # Typically this value is not significant because it's very
-        # close to the expected time, so it's supressed by default.
+        # close to the expected time, so it's suppressed by default.
         def show_total_time!
           @show_total_time = true
         end
@@ -86,23 +86,25 @@ module Benchmark
         # percentage of standard deviation, iterations in runtime.
         # @return [String] Left justified body.
         def body
+          per_iter = (" (%s/i)" % Helpers.humanize_duration(1_000_000_000 / @stats.central_tendency)).rjust(15)
+
           case Benchmark::IPS.options[:format]
           when :human
-            left = "%s (±%4.1f%%) i/s" % [Helpers.scale(@stats.central_tendency), @stats.error_percentage]
+            left = ("%s (±%4.1f%%) i/s" % [Helpers.scale(@stats.central_tendency), @stats.error_percentage]).ljust(20)
             iters = Helpers.scale(@iterations)
 
             if @show_total_time
-              left.ljust(20) + (" - %s in %10.6fs" % [iters, runtime])
+              left + per_iter + (" - %s in %10.6fs" % [iters, runtime])
             else
-              left.ljust(20) + (" - %s" % iters)
+              left + per_iter + (" - %s" % iters)
             end
           else
-            left = "%10.1f (±%.1f%%) i/s" % [@stats.central_tendency, @stats.error_percentage]
+            left = ("%10.1f (±%.1f%%) i/s" % [@stats.central_tendency, @stats.error_percentage]).ljust(20)
 
             if @show_total_time
-              left.ljust(20) + (" - %10d in %10.6fs" % [@iterations, runtime])
+              left + per_iter + (" - %10d in %10.6fs" % [@iterations, runtime])
             else
-              left.ljust(20) + (" - %10d" % @iterations)
+              left + per_iter + (" - %10d" % @iterations)
             end
           end
         end
@@ -113,7 +115,7 @@ module Benchmark
           @label.to_s.rjust(20)
         end
 
-        # Return string repesentation of Entry object.
+        # Return string representation of Entry object.
         # @return [String] Header and body.
         def to_s
           "#{header} #{body}"
@@ -183,9 +185,13 @@ module Benchmark
       # Generate json from Report#data to given path.
       # @param path [String] path to generate json.
       def generate_json(path)
-        File.open path, "w" do |f|
-          require "json"
-          f.write JSON.pretty_generate(data)
+        require "json"
+        if path.respond_to?(:write) # STDOUT
+          path.write JSON.pretty_generate(data)
+        else
+          File.open path, "w" do |f|
+            f.write JSON.pretty_generate(data)
+          end
         end
       end
     end

data/lib/benchmark/ips/stats/sd.rb

@@ -24,9 +24,9 @@ module Benchmark
         # @returns [Array<Float, nil>] the slowdown and the error (not calculated for standard deviation)
         def slowdown(baseline)
           if baseline.central_tendency > central_tendency
-            [baseline.central_tendency.to_f / central_tendency, 0]
+            [baseline.central_tendency.to_f / central_tendency, nil]
           else
-            [central_tendency.to_f / baseline.central_tendency, 0]
+            [central_tendency.to_f / baseline.central_tendency, nil]
           end
         end
 

data/lib/benchmark/ips.rb

@@ -5,23 +5,25 @@ require 'benchmark/ips/stats/stats_metric'
 require 'benchmark/ips/stats/sd'
 require 'benchmark/ips/stats/bootstrap'
 require 'benchmark/ips/report'
-require 'benchmark/ips/noop_suite'
 require 'benchmark/ips/job/entry'
-require 'benchmark/ips/job/stdout_report'
-require 'benchmark/ips/job/noop_report'
+require 'benchmark/ips/job/stream_report'
+require 'benchmark/ips/job/multi_report'
 require 'benchmark/ips/job'
 
 # Performance benchmarking library
 module Benchmark
   # Benchmark in iterations per second, no more guessing!
-  # @see https://github.com/evanphx/benchmark-ips
+  #
+  # See Benchmark.ips for documentation on using this gem~
+  #
+  # @see {https://github.com/evanphx/benchmark-ips}
   module IPS
 
     # Benchmark-ips Gem version.
-    VERSION = "2.10.0"
+    VERSION = "2.14.0"
 
     # CODENAME of current version.
-    CODENAME = "Watashi Wa Genki"
+    CODENAME = "Akagi"
 
     # Measure code in block, each code's benchmarked result will display in
     # iteration per second with standard deviation in given time.
@@ -74,6 +76,32 @@ module Benchmark
       report
     end
 
+    # Quickly compare multiple methods on the same object.
+    # @param methods [Symbol...] A list of method names (as symbols) to compare.
+    # @param receiver [Object] The object on which to call the methods. Defaults to Kernel.
+    # @param opts [Hash] Additional options for customizing the benchmark.
+    # @option opts [Integer] :warmup The number of seconds to warm up the benchmark.
+    # @option opts [Integer] :time The number of seconds to run the benchmark.
+    #
+    # @example Compare String#upcase and String#downcase
+    #   ips_quick(:upcase, :downcase, on: "hello")
+    #
+    # @example Compare two methods you just defined, with a custom warmup.
+    #   def add; 1+1; end
+    #   def sub; 2-1; end
+    #   ips_quick(:add, :sub, warmup: 10)
+    def ips_quick(*methods, on: Kernel, **opts)
+      ips(opts) do |x|
+        x.compare!
+
+        methods.each do |name|
+          x.report(name) do |iter|
+            iter.times { on.__send__ name }
+          end
+        end
+      end
+    end
+
     # Set options for running the benchmarks.
     # :format => [:human, :raw]
     #    :human format narrows precision and scales results for readability
@@ -83,26 +111,34 @@ module Benchmark
     end
 
     module Helpers
+      SUFFIXES = ['', 'k', 'M', 'B', 'T', 'Q'].freeze
+
       def scale(value)
         scale = (Math.log10(value) / 3).to_i
-        suffix = case scale
-        when 1; 'k'
-        when 2; 'M'
-        when 3; 'B'
-        when 4; 'T'
-        when 5; 'Q'
+        scale = 0 if scale < 0 || scale >= SUFFIXES.size
+        suffix = SUFFIXES[scale]
+        scaled_value = value.to_f / (1000 ** scale)
+
+        "%10.3f#{suffix}" % scaled_value
+      end
+      module_function :scale
+
+      def humanize_duration(duration_ns)
+        if duration_ns < 1000
+          "%.2f ns" % duration_ns
+        elsif duration_ns < 1_000_000
+          "%.2f μs" % (duration_ns / 1000)
+        elsif duration_ns < 1_000_000_000
+          "%.2f ms" % (duration_ns / 1_000_000)
         else
-          # < 1000 or > 10^15, no scale or suffix
-          scale = 0
-          ' '
+          "%.2f s" % (duration_ns / 1_000_000_000)
         end
-        "%10.3f#{suffix}" % (value.to_f / (1000 ** scale))
       end
-      module_function :scale
+      module_function :humanize_duration
     end
   end
 
-  extend Benchmark::IPS # make ips available as module-level method
+  extend Benchmark::IPS # make ips/ips_quick available as module-level method
 
   ##
   # :singleton-method: ips

data/lib/benchmark/timing.rb

@@ -1,5 +1,5 @@
 module Benchmark
-  # Perform caclulations on Timing results.
+  # Perform calculations on Timing results.
   module Timing
     # Microseconds per second.
     MICROSECONDS_PER_SECOND = 1_000_000

metadata

@@ -1,11 +1,11 @@
 --- !ruby/object:Gem::Specification
 name: benchmark-ips
 version: !ruby/object:Gem::Version
-  version: 2.10.0
+  version: 2.14.0
 platform: ruby
 authors:
 - Evan Phoenix
-autorequire:
+autorequire: 
 bindir: bin
 cert_chain: []
 date: 2015-01-12 00:00:00.000000000 Z
@@ -53,15 +53,15 @@ files:
 - README.md
 - examples/advanced.rb
 - examples/hold.rb
+- examples/quick.rb
 - examples/save.rb
 - examples/simple.rb
 - lib/benchmark/compare.rb
 - lib/benchmark/ips.rb
 - lib/benchmark/ips/job.rb
 - lib/benchmark/ips/job/entry.rb
-- lib/benchmark/ips/job/noop_report.rb
-- lib/benchmark/ips/job/stdout_report.rb
-- lib/benchmark/ips/noop_suite.rb
+- lib/benchmark/ips/job/multi_report.rb
+- lib/benchmark/ips/job/stream_report.rb
 - lib/benchmark/ips/report.rb
 - lib/benchmark/ips/share.rb
 - lib/benchmark/ips/stats/bootstrap.rb
@@ -72,7 +72,7 @@ homepage: https://github.com/evanphx/benchmark-ips
 licenses:
 - MIT
 metadata: {}
-post_install_message:
+post_install_message: 
 rdoc_options:
 - "--main"
 - README.md
@@ -89,8 +89,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.26
-signing_key:
+rubygems_version: 3.0.3.1
+signing_key: 
 specification_version: 4
 summary: A iterations per second enhancement to Benchmark.
 test_files: []

data/lib/benchmark/ips/job/noop_report.rb

@@ -1,27 +0,0 @@
-module Benchmark
-  module IPS
-    class Job
-      class NoopReport
-        def start_warming
-        end
-
-        def start_running
-        end
-
-        def footer
-        end
-
-        def warming(a, b)
-        end
-
-        def warmup_stats(a, b)
-        end
-
-        def add_report(a, b)
-        end
-
-        alias_method :running, :warming
-      end
-    end
-  end
-end

data/lib/benchmark/ips/noop_suite.rb

@@ -1,25 +0,0 @@
-module Benchmark
-  module IPS
-    class NoopSuite
-      def start_warming
-      end
-
-      def start_running
-      end
-
-      def footer
-      end
-
-      def warming(a, b)
-      end
-
-      def warmup_stats(a, b)
-      end
-
-      def add_report(a, b)
-      end
-
-      alias_method :running, :warming
-    end
-  end
-end