ips 0.0.0 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 170ece43b797beba03ae6e3b9c532a3627d573f1afd41ace6d5fdbf6fc63be1f
-  data.tar.gz: dae5536d6035f67546136f12ffe1fc52d602bdffc8dd5eeba120fec2313c4cd7
+  metadata.gz: 6b0cebe0c91bffd744baf3e8f52b8215799699ba4ca56d0856af1802dfc3df13
+  data.tar.gz: 43f27237a0abb534d951ac7da7c96fe0f8e3f053a1910a0534fcbfafaaf4dabf
 SHA512:
-  metadata.gz: 15b5f0fcb8e89dc9c7e12aa387949a8bf9a68d14ba9a1d122398aeddf63cb5a4dd8e41e479c4949a7e28a3a89759ee05b788a3cdf8fc38644b2cdf5b3ec30571
-  data.tar.gz: 8cf8d948c812075b068479e25737a0d43999831f2dea87a018d6d62fe8c1049d96bb27076f88173ed91d4bd4ae1939669d768402ee9e8ce8e5c215c14014d909
+  metadata.gz: 5bbe4651a8879db139bdd2be7b551d4f5787a42cb22ab145056b92883e02acc7818144b61689f94e70f3218ea9f7566f8e337a97ef0a6ba9b280174a508cafb4
+  data.tar.gz: 3665d4bf59457dcfb246908fcc7f4d0eba583790d9171995f25dc02dad786fb6f5ab44ac4e32ee573b4775a87f4dfbbeb46e4389b1b3ad77ce2d994da5a51d3b

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,10 @@
+# Code of Conduct
+
+"ips" follows [The Ruby Community Conduct Guideline](https://www.ruby-lang.org/en/conduct) in all "collaborative space", which is defined as community communications channels (such as mailing lists, submitted patches, commit comments, etc.):
+
+* Participants will be tolerant of opposing views.
+* Participants must ensure that their language and actions are free of personal attacks and disparaging personal remarks.
+* When interpreting the words and actions of others, participants should always assume good intentions.
+* Behaviour which can be reasonably considered harassment will not be tolerated.
+
+If you have any concerns about behaviour within this project, please contact us at ["john@hawthorn.email"](mailto:"john@hawthorn.email").

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 John Hawthorn
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,56 @@
+# IPS
+
+A Ruby benchmarking tool that measures iterations per second with statistical analysis, automatic warmup, and comparison summaries.
+
+## Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+```bash
+bundle add ips
+```
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+```bash
+gem install ips
+```
+
+## Usage
+
+```ruby
+require "ips"
+
+IPS.run do |x|
+  x.report("addition")       { 1 + 1 }
+  x.report("multiplication") { 2 * 3 }
+  x.report("wtf") { eval("#{1.to_s} + #{1.to_s}") }
+end
+```
+
+Output:
+
+```
+            addition:    45.759M i/s (± 1.2%)
+      multiplication:    45.593M i/s (± 0.2%)
+                 wtf:   463.420k i/s (± 0.9%, GC  6.3%)
+
+Summary
+  addition ran
+    1.00 ± 0.01 times faster than multiplication
+    98.74 ± 1.49 times faster than wtf
+```
+
+When two or more items are reported, a comparison summary is automatically displayed.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/jhawthorn/ips. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/jhawthorn/ips/blob/main/CODE_OF_CONDUCT.md).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Code of Conduct
+
+Everyone interacting in the IPS project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/jhawthorn/ips/blob/main/CODE_OF_CONDUCT.md).

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+
+Minitest::TestTask.create
+
+task default: :test

data/examples/basic.rb

@@ -0,0 +1,12 @@
+# Basic usage example
+#
+# Usage:
+#   ruby -I lib examples/basic.rb
+
+require "bundler/setup"
+require "ips"
+
+IPS.run do |x|
+  x.report("addition")       { 1 + 1 }
+  x.report("multiplication") { 2 * 3 }
+end

data/examples/gc_pressure.rb

@@ -0,0 +1,15 @@
+# Comparing allocation-heavy vs allocation-free approaches
+#
+# Usage:
+#   ruby -I lib examples/gc_pressure.rb
+
+require "bundler/setup"
+require "ips"
+
+array = (1..1000).to_a
+
+IPS.run do |x|
+  x.report("map + sum")  { array.map { |i| i * 2 }.sum }
+  x.report("sum block")  { array.sum { |i| i * 2 } }
+  x.report("inject")     { array.inject(0) { |acc, i| acc + i * 2 } }
+end

data/examples/hash_vs_struct.rb

@@ -0,0 +1,16 @@
+# Hash vs Struct vs Data for simple records
+#
+# Usage:
+#   ruby -I lib examples/hash_vs_struct.rb
+
+require "bundler/setup"
+require "ips"
+
+MyStruct = Struct.new(:name, :age)
+MyData = Data.define(:name, :age)
+
+IPS.run do |x|
+  x.report("Hash.new")   { { name: "Alice", age: 30 } }
+  x.report("Struct.new") { MyStruct.new("Alice", 30) }
+  x.report("Data.new")   { MyData.new(name: "Alice", age: 30) }
+end

data/examples/manual_loop.rb

@@ -0,0 +1,20 @@
+# Using the manual loop style for ultra-fast operations
+# where per-call overhead matters
+#
+# Usage:
+#   ruby -I lib examples/manual_loop.rb
+
+require "bundler/setup"
+require "ips"
+
+IPS.run do |x|
+  x.report("block style") { 1 + 1 }
+
+  x.report("manual loop") { |n|
+    i = 0
+    while i < n
+      1 + 1
+      i += 1
+    end
+  }
+end

data/examples/outlier.rb

@@ -0,0 +1,35 @@
+# Demonstrates how benchmark-ips hides rare stalls.
+#
+# Every 100th iteration sleeps for 1 second.
+# Real throughput: ~100 i/s
+# benchmark-ips reports: ~5.9M i/s (!!!)
+#
+# Usage:
+#   ruby -I lib examples/outlier.rb
+
+require "benchmark/ips"
+require "bundler/setup"
+require "ips"
+
+i = 0
+j = 0
+
+if false
+puts "=== benchmark-ips ==="
+Benchmark.ips do |x|
+  x.report("periodic stall") do
+    sleep 1 if i % 100 == 0
+    i += 1
+  end
+  x.compare!
+end
+end
+
+puts
+puts "=== IPS ==="
+IPS.run do |x|
+  x.report("periodic stall") do
+    sleep 1 if j % 100 == 0
+    j += 1
+  end
+end

data/examples/singleton_class.rb

@@ -0,0 +1,14 @@
+# Singleton class creation benchmark
+# From https://bugs.ruby-lang.org/issues/21856
+#
+# Usage:
+#   ruby -I lib examples/singleton_class.rb
+
+require "bundler/setup"
+require "ips"
+
+IPS.run do |x|
+  x.report("singleton_class") do
+    Object.new.singleton_class
+  end
+end

data/examples/string_matching.rb

@@ -0,0 +1,16 @@
+# Comparing different ways to check string contents
+#
+# Usage:
+#   ruby -I lib examples/string_matching.rb
+
+require "bundler/setup"
+require "ips"
+
+string = "the quick brown fox jumps over the lazy dog"
+
+IPS.run do |x|
+  x.report("include?")  { string.include?("fox") }
+  x.report("match?")    { string.match?(/fox/) }
+  x.report("index")     { string.index("fox") }
+  x.report("=~")        { string =~ /fox/ }
+end

data/lib/ips/display.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module IPS
+  class Display
+    BAR_WIDTH = 30
+
+    def initialize(labels, out: $stdout)
+      @out = out
+      @max_label = labels.map(&:size).max
+      @max_label = 20 if @max_label < 20
+      @tty = @out.tty?
+    end
+
+    def start_item(label, total_ns)
+      @item_label = label
+      @item_start = Timing.now
+      @item_total_ns = total_ns
+      progress
+    end
+
+    def progress(estimate: nil)
+      return unless @tty
+      elapsed_ns = Timing.now - @item_start
+      fraction = (elapsed_ns.to_f / @item_total_ns).clamp(0.0, 1.0)
+      filled = (fraction * BAR_WIDTH).to_i
+      empty = BAR_WIDTH - filled
+      remaining_ns = @item_total_ns - elapsed_ns
+      remaining_s = remaining_ns > 0 ? (remaining_ns.to_f / Timing::NANOSECONDS_PER_SECOND).ceil : 0
+      bar = "█" * filled + "░" * empty
+      est = estimate ? "%10s i/s" % format_ips(estimate) : "              "
+      @out.print "\r%#{@max_label}s: %s %s ETA %ds " % [@item_label, est, bar, remaining_s]
+      @out.flush
+    end
+
+    def finish_item(result)
+      @out.print "\r\e[2K" if @tty
+      gc = result.gc_pct >= 1.0 ? ", GC %4.1f%%" % result.gc_pct : ""
+      error = result.error_pct > 100 ? ">100" : "%4.1f" % result.error_pct
+      @out.printf "%#{@max_label}s: %10s i/s (±%s%%%s)\n",
+        result.label, format_ips(result.ips), error, gc
+    end
+
+    def summary(results)
+      return if results.size < 2
+
+      sorted = results.sort_by { |r| -r.ips }
+      best = sorted.first
+
+      @out.puts "\nSummary"
+      @out.puts "  #{best.label} ran"
+
+      sorted[1..].each do |r|
+        ratio = best.ips / r.ips
+        ratio_error = ratio * Math.sqrt((best.stddev / best.ips)**2 + (r.stddev / r.ips)**2)
+        @out.printf "    %.2f ± %.2f times faster than %s\n",
+          ratio, ratio_error, r.label
+      end
+    end
+
+    def format_ips(ips)
+      if ips >= 1_000_000_000
+        "%.3fB" % (ips / 1_000_000_000.0)
+      elsif ips >= 1_000_000
+        "%.3fM" % (ips / 1_000_000.0)
+      elsif ips >= 1_000
+        "%.3fk" % (ips / 1_000.0)
+      else
+        "%.3f" % ips
+      end
+    end
+  end
+end

data/lib/ips/job/entry.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module IPS
+  class Job
+    class Entry
+      attr_reader :label
+
+      def initialize(label, action)
+        @label = label
+        @action = action
+
+        if action.arity > 0
+          define_call_times_manual_loop
+        else
+          define_call_times_block
+        end
+      end
+
+      private
+
+      def define_call_times_block
+        act = @action
+        define_singleton_method(:call_times) do |times|
+          i = 0
+          while i < times
+            act.call
+            i += 1
+          end
+        end
+      end
+
+      def define_call_times_manual_loop
+        act = @action
+        define_singleton_method(:call_times) do |times|
+          act.call(times)
+        end
+      end
+    end
+  end
+end

data/lib/ips/job.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+require "ips/job/entry"
+require "ips/result"
+require "ips/display"
+
+module IPS
+  class Job
+    MAX_ITERATIONS = 1 << 30
+
+    attr_accessor :warmup, :time
+
+    def initialize(time: 5, warmup: 2, out: $stdout)
+      @list = []
+      @time = time
+      @warmup = warmup
+      @timing = {}
+      @out = out
+    end
+
+    def report(label, &block)
+      @list.push Entry.new(label, block)
+      self
+    end
+
+    def run
+      display = Display.new(@list.map(&:label), out: @out)
+      total_ns = ((@warmup + @time) * Timing::NANOSECONDS_PER_SECOND).to_i
+
+      results = @list.map do |item|
+        display.start_item(item.label, total_ns)
+        warmup_item(item, display)
+        result = measure_item(item, display)
+        display.finish_item(result)
+        result
+      end
+
+      display.summary(results)
+    end
+
+    private
+
+    def cycles_per_100ms(time_ns, iters)
+      cycles = ((Timing::NANOSECONDS_PER_100MS.to_f / time_ns) * iters).to_i
+      cycles <= 0 ? 1 : cycles
+    end
+
+    def warmup_item(item, display)
+      Timing.clean_env
+
+      before = Timing.now
+      target = Timing.add_second(before, @warmup / 2.0)
+
+      cycles = 1
+      begin
+        t0 = Timing.now
+        item.call_times(cycles)
+        t1 = Timing.now
+        warmup_iter = cycles
+        warmup_ns = t1 - t0
+
+        estimate = Timing::NANOSECONDS_PER_SECOND * (warmup_iter.to_f / warmup_ns)
+        display.progress(estimate: estimate)
+
+        break if cycles >= MAX_ITERATIONS
+        cycles *= 2
+      end while Timing.now + warmup_ns * 2 < target
+
+      per_100ms = cycles_per_100ms(warmup_ns, warmup_iter)
+      cycles = per_100ms > MAX_ITERATIONS ? MAX_ITERATIONS : per_100ms
+      @timing[item] = cycles
+
+      target = Timing.add_second(before, @warmup)
+      while Timing.now + Timing::NANOSECONDS_PER_100MS < target
+        t0 = Timing.now
+        item.call_times(cycles)
+        t1 = Timing.now
+        estimate = Timing::NANOSECONDS_PER_SECOND * (cycles.to_f / (t1 - t0))
+        display.progress(estimate: estimate)
+      end
+    end
+
+    def measure_item(item, display)
+      Timing.clean_env
+
+      cycles = @timing[item]
+      times = []  # flat: [start0, end0, start1, end1, ...]
+      gc_times = [] # flat: [gc_before0, gc_after0, ...]
+      iter = 0
+
+      target = Timing.add_second(Timing.now, @time)
+
+      begin
+        gc0 = GC.total_time
+        t0 = Timing.now
+        item.call_times(cycles)
+        t1 = Timing.now
+        gc1 = GC.total_time
+
+        elapsed_ns = t1 - t0
+        next if elapsed_ns <= 0
+
+        iter += cycles
+        times << t0 << t1
+        gc_times << gc0 << gc1
+
+        total_ns = t1 - times[0]
+        display.progress(estimate: Timing::NANOSECONDS_PER_SECOND * (iter.to_f / total_ns))
+      end while Timing.now < target
+
+      Result.new(item.label, cycles, times, gc_times)
+    end
+  end
+end

data/lib/ips/result.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module IPS
+  class Result
+    attr_reader :label, :cycles, :times, :gc_times
+
+    # times: flat array [start0, end0, start1, end1, ...]
+    # gc_times: flat array [gc_before0, gc_after0, gc_before1, gc_after1, ...]
+    def initialize(label, cycles, times, gc_times)
+      @label = label
+      @cycles = cycles
+      @times = times
+      @gc_times = gc_times
+    end
+
+    def sample_count
+      @times.size / 2
+    end
+
+    def iterations
+      sample_count * @cycles
+    end
+
+    # Total wall time from first batch start to last batch end
+    def total_ns
+      @times[-1] - @times[0]
+    end
+
+    # Time spent actually running batches
+    def busy_ns
+      total = 0
+      i = 0
+      while i < @times.size
+        total += @times[i + 1] - @times[i]
+        i += 2
+      end
+      total
+    end
+
+    # Time between batches (measurement overhead, GC, scheduling)
+    def overhead_ns
+      total_ns - busy_ns
+    end
+
+    # Total GC time during measurement
+    def gc_ns
+      total = 0
+      i = 0
+      while i < @gc_times.size
+        total += @gc_times[i + 1] - @gc_times[i]
+        i += 2
+      end
+      total
+    end
+
+    def ips
+      Timing::NANOSECONDS_PER_SECOND * (iterations.to_f / total_ns)
+    end
+
+    # Per-batch IPS samples for error estimation
+    def samples
+      @samples ||= begin
+        s = Array.new(sample_count)
+        i = 0
+        while i < @times.size
+          s[i / 2] = Timing::NANOSECONDS_PER_SECOND * (@cycles.to_f / (@times[i + 1] - @times[i]))
+          i += 2
+        end
+        s
+      end
+    end
+
+    def sample_mean
+      @sample_mean ||= samples.sum / samples.size
+    end
+
+    def stddev
+      variance = samples.sum { |s| (s - sample_mean) ** 2 } / samples.size
+      Math.sqrt(variance)
+    end
+
+    def error_pct
+      (stddev / ips) * 100.0
+    end
+
+    def gc_pct
+      total = total_ns
+      total > 0 ? (gc_ns.to_f / total) * 100.0 : 0.0
+    end
+  end
+end

data/lib/ips/timing.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module IPS
+  module Timing
+    NANOSECONDS_PER_SECOND = 1_000_000_000
+    NANOSECONDS_PER_100MS = 100_000_000
+
+    def self.now
+      Process.clock_gettime(Process::CLOCK_MONOTONIC, :nanosecond)
+    end
+
+    def self.add_second(t, s)
+      t + (s * NANOSECONDS_PER_SECOND).to_i
+    end
+
+    def self.clean_env
+      GC.start
+    end
+  end
+end

data/lib/ips/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module IPS
+  VERSION = "0.1.0"
+end

data/lib/ips.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require "ips/version"
+require "ips/timing"
+require "ips/display"
+require "ips/job"
+
+module IPS
+  def self.run(time: 5, warmup: 2, out: $stdout)
+    job = Job.new(time: time, warmup: warmup, out: out)
+    yield job
+    job.run
+  end
+end
+
+Ips = IPS

metadata

@@ -1,28 +1,46 @@
 --- !ruby/object:Gem::Specification
 name: ips
 version: !ruby/object:Gem::Version
-  version: 0.0.0
+  version: 0.1.0
 platform: ruby
 authors:
 - John Hawthorn
-bindir: bin
+bindir: exe
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
-description: placeholder
+description: A Ruby benchmarking tool that measures iterations per second with automatic
+  warmup, statistical error estimation, GC reporting, and comparison summaries.
 email:
 - john@hawthorn.email
 executables: []
 extensions: []
 extra_rdoc_files: []
-files: []
-homepage: https://jhawthorn.com
+files:
+- CODE_OF_CONDUCT.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- examples/basic.rb
+- examples/gc_pressure.rb
+- examples/hash_vs_struct.rb
+- examples/manual_loop.rb
+- examples/outlier.rb
+- examples/singleton_class.rb
+- examples/string_matching.rb
+- lib/ips.rb
+- lib/ips/display.rb
+- lib/ips/job.rb
+- lib/ips/job/entry.rb
+- lib/ips/result.rb
+- lib/ips/timing.rb
+- lib/ips/version.rb
+homepage: https://github.com/jhawthorn/ips
 licenses:
 - MIT
 metadata:
-  homepage_uri: https://jhawthorn.com
-  source_code_uri: https://jhawthorn.com
-  changelog_uri: https://jhawthorn.com
+  homepage_uri: https://github.com/jhawthorn/ips
+  source_code_uri: https://github.com/jhawthorn/ips
 rdoc_options: []
 require_paths:
 - lib
@@ -30,7 +48,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.0.0
+      version: 3.2.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
@@ -39,5 +57,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 4.0.3
 specification_version: 4
-summary: placeholder
+summary: Iterations per second benchmarking with statistical analysis
 test_files: []