micro_bench 0.1.3 → 0.2.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 5eeb98130357a3e9320237286d468300c1731a76
-  data.tar.gz: 1a5a9887fc7c0b9600c453565cb3496db58e2de5
+SHA256:
+  metadata.gz: e7b61de43614716fc3e48d6661bc4f77524092a7766cd808a5cfdb09e4a70f3b
+  data.tar.gz: 25deba16810136e20ba13a28dde5b73a63b57a7e639700582b726f9853f8fe9c
 SHA512:
-  metadata.gz: 958052ea9ea084cc0bcba112f41e6de68d9395d5d4e711c0ccc394ad4c82e628463bbd18cd0c1b231c5f906e42c682b7d191aa59a698283d0316d95b549e39fe
-  data.tar.gz: 6dc33d748019010708d9676bc793717a4e54289e11eb74344478384d48b638077164e6a97a41230a1119f5545a492fb3c2e7fd984bab51d08dafac2f44f4c090
+  metadata.gz: 9cdb819b4a60cdc8a7eb958a222217942ff90da5896698af0f2c66b66ed8ccc62f5583241962c0479181aadcf5a098d66505d6a3172dde7246e239d6fffb66f3
+  data.tar.gz: 6612a374748347f8858cacf36acfa0b712c0d8c93a86242896203558261eb748d49c303aff25602ec89a0f34f08e2c34a67b8a92955e20e59027bb4fac70e363

data/README.md

@@ -2,10 +2,17 @@
 # MicroBench
 
 [![Gem Version](https://badge.fury.io/rb/micro_bench.svg)](https://badge.fury.io/rb/micro_bench)
+[![CircleCI](https://circleci.com/gh/klaxit/micro_bench.svg?style=shield)](https://circleci.com/gh/klaxit/micro_bench)
+
+```
+gem install micro_bench
+```
+
+## Why ?
 
 Ruby `Benchmark` module is nice but it uses blocks. We see 2 problems to it :
 - if we want to instrument a snippet of code, it breaks git history,
-- variables are tied to the benchmark block, so we have to initialize them outside of the benchmark block to use them subsequently.
+- variables declared in the benchmark block cannot be used subsequently.
 
 Let's say you want to output the duration of `method_1` from :
 
@@ -32,7 +39,10 @@ puts "Method 1 duration : #{MicroBench.duration} seconds"
 method_2(foo)
 ```
 
-**WARNING : This is still beta code and may not be suitable for production usage. While still in beta, API may be subject to breaking changes on MINOR versions (but not on PATCH versions).**
+## Project maturity
+
+This has been running in production at [Klaxit](https://www.klaxit.com) for some months now, but it is still a young library. API may be subject to breaking changes on MINOR versions (but not on PATCH versions).
+
 
 ## Install
 
@@ -114,6 +124,31 @@ end
 method_1
 ```
 
+### Configuration
+
+You can configure a bit `MicroBench` to have an even simpler time using it afterwards. Here's how:
+
+```ruby
+MicroBench.configure do |config|
+  config.formatter = ->(duration) { "#{duration.round} seconds" }
+end
+
+MicroBench.start
+sleep 2
+MicroBench.duration == "2 seconds"
+```
+
+There are some default formatters that you can set:
+
+| id        | result                       | description                              |
+| --------- | ---------------------------- | ---------------------------------------- |
+| `default` | `722.327823832`              | the raw original float, for computation  |
+| `simple`  | `722.33`                     | rounds to 2 digits                       |
+| `mmss`    | `"12:02.328"`                | Easy to understand, lossless and compact |
+| `human`   | `"12 minutes and 2 seconds"` | For humans, clutters logs                |
+
+To use one of those, simply write `config.formatter = :simple` instead of a lambda.
+
 ## Versioning
 
 We use [SemVer](http://semver.org/) for versioning. For the versions available, see the [tags on this repository](https://github.com/klaxit/micro_bench/tags).

data/lib/micro_bench.rb

@@ -1,5 +1,18 @@
+# frozen_string_literal: true
+
 module MicroBench
   class << self
+    # Configure MicroBench.
+    #
+    # == Example usage:
+    #   MicroBench.configure do |config|
+    #     config.formatter = proc { |duration| duration.ceil }
+    #   end
+    def configure(&block)
+      block.call(configurations)
+      nil
+    end
+
     # Start a benchmark
     #
     # == Parameters:
@@ -52,11 +65,17 @@ module MicroBench
     #   MicroBench.stop(:my_benchmark)
     #
     def duration(bench_id = nil)
-      benchmarks[benchmark_key(bench_id)]&.duration
+      configurations.formatter.call(
+        benchmarks[benchmark_key(bench_id)]&.duration
+      )
     end
 
     private
 
+    def configurations
+      @configurations ||= Configurations.new
+    end
+
     def benchmarks
       @benchmarks ||= {}
     end
@@ -79,3 +98,4 @@ module MicroBench
 end
 
 require "micro_bench/benchmark"
+require "micro_bench/configurations"

data/lib/micro_bench/benchmark.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 class MicroBench::Benchmark
   def initialize
     @start_time = monotonic_clock_time

data/lib/micro_bench/configurations.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+class MicroBench::Configurations
+  attr_reader :formatter
+
+  # Initialize with a default formatters that changes nothing.
+  def initialize
+    @formatter = method(:default_formatter)
+  end
+
+  # Set formatter to change {MicroBench.duration} results.
+  #
+  # == Parameters:
+  # value::
+  #   It can be a proc that receives a duration float in seconds and returns any
+  #   formatted value. Or it can be one of the default values, +"simple"+,
+  #   +"mmss"+ or +"human"+. If you set it to +nil+ or +"default"+, the
+  #   formatter will be ignored, and the result will be the raw float.
+  def formatter=(value)
+    # This ensures that both Proc and Method can be used there. Or even a user
+    # defined class that responds to call.
+    if value.respond_to?(:call)
+      @formatter = value
+      return
+    end
+
+    formatter_method =
+      case value.to_s
+      when "", "default"
+        :default_formatter
+      when "simple"
+        :simple_formatter
+      when "mmss"
+        :mmss_formatter
+      when "human"
+        :human_formatter
+      else
+        raise ArgumentError, "formatter must be callable or a default string"
+      end
+
+    @formatter = method(formatter_method)
+  end
+
+  private
+
+  def default_formatter(duration)
+    duration
+  end
+
+  def simple_formatter(duration)
+    duration.round(2)
+  end
+
+  def mmss_formatter(duration)
+    ss, ms = duration.divmod(1)
+    mm, ss = ss.divmod(60)
+    hh, mm = mm.divmod(60)
+
+    # Format ms to have only 3 digits.
+    ms = (ms * 1_000).round
+
+    return format("%02d:%02d:%02d.%03d", hh, mm, ss, ms) if hh > 0
+    return format("%02d:%02d.%03d", mm, ss, ms) if mm > 0
+    return format("%d.%03d", ss, ms)
+  end
+
+  def human_formatter(duration)
+    ss = duration.round
+    mm, ss = ss.divmod(60)
+    hh, mm = mm.divmod(60)
+
+    human_unit = ->(value, name) { "#{value} #{name}#{"s" unless value == 1}" }
+
+    hours   = human_unit[hh, "hour"]
+    minutes = human_unit[mm, "minute"]
+    seconds = human_unit[ss, "second"]
+
+    human_join = ->(*array) { array[0..-2].join(", ") + " and #{array.last}" }
+
+    return human_join[hours, minutes, seconds] if hh > 0
+    return human_join[minutes, seconds] if mm > 0
+    return seconds
+  end
+end

data/lib/micro_bench/version.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module MicroBench
-  VERSION = "0.1.3".freeze
+  VERSION = "0.2.3"
 end

data/spec/micro_bench/configurations_spec.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+describe MicroBench::Configurations do
+  let(:duration) { rand(10) + rand }
+
+  describe "#default_formatter" do
+    it "does nothing" do
+      expect(subject.send(:default_formatter, duration)).to eq duration
+    end
+  end
+
+  describe "#simple_formatter" do
+    it "rounds" do
+      expect(subject.send(:simple_formatter, duration)).to eq duration.round(2)
+    end
+  end
+
+  describe "#mmss_formatter" do
+    it "gives hh:mm:ss.s" do
+      expect(subject.send(:mmss_formatter, 457927.127)).to eq "127:12:07.127"
+    end
+  end
+
+  describe "#human_formatter" do
+    it "gives a text" do
+      expect(subject.send(:human_formatter, 457287.4699882))
+        .to eq "127 hours, 1 minute and 27 seconds"
+    end
+  end
+end

data/spec/{micro_bench/micro_bench_spec.rb → micro_bench_spec.rb}

@@ -1,4 +1,4 @@
-require "spec_helper"
+# frozen_string_literal: true
 
 describe MicroBench do
   it "gives seconds duration doing something" do
@@ -91,10 +91,10 @@ describe MicroBench do
   end
 
   it "allows referencing a benchmark from a Proc / Block / Lambda" do
-    MicroBench.start
+    described_class.start
     # from a Proc
     proc = Proc.new do
-      expect(MicroBench.duration).to_not be_nil
+      expect(described_class.duration).to_not be_nil
     end
     proc.call
     # from a Block
@@ -102,12 +102,28 @@ describe MicroBench do
       yield
     end
     my_method do
-      expect(MicroBench.duration).to_not be_nil
+      expect(described_class.duration).to_not be_nil
     end
     # from a Lambda
     l = lambda do
-      expect(MicroBench.duration).to_not be_nil
+      expect(described_class.duration).to_not be_nil
     end
     l.call
   end
+
+  it "formats duration when configured with an id" do
+    described_class.configure do |config|
+      config.formatter = :human
+    end
+    described_class.start
+    expect(described_class.duration).to eq "0 seconds"
+  end
+
+  it "formats duration when using a callable" do
+    described_class.configure do |config|
+      config.formatter = proc { "result" }
+    end
+    described_class.start
+    expect(described_class.duration).to eq "result"
+  end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: micro_bench
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.2.3
 platform: ruby
 authors:
 - Cyrille Courtière
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2018-12-04 00:00:00.000000000 Z
+date: 2020-06-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: byebug
@@ -38,7 +38,7 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.8'
-description: 
+description:
 email:
 - cyrille@klaxit.com
 executables: []
@@ -48,14 +48,16 @@ files:
 - README.md
 - lib/micro_bench.rb
 - lib/micro_bench/benchmark.rb
+- lib/micro_bench/configurations.rb
 - lib/micro_bench/version.rb
-- spec/micro_bench/micro_bench_spec.rb
+- spec/micro_bench/configurations_spec.rb
+- spec/micro_bench_spec.rb
 - spec/spec_helper.rb
 homepage: http://github.com/klaxit/micro_bench
 licenses:
 - MIT
 metadata: {}
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -70,11 +72,11 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.5.2.3
-signing_key: 
+rubygems_version: 3.1.0.pre3
+signing_key:
 specification_version: 4
 summary: Dead simple benchmarks
 test_files:
-- spec/micro_bench/micro_bench_spec.rb
+- spec/micro_bench/configurations_spec.rb
+- spec/micro_bench_spec.rb
 - spec/spec_helper.rb