time_up 0.0.2 → 0.0.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3e94465307a2737c930d8dbd195c92fe315850abf8c7be4b1c6f88f1eec2d1bd
-  data.tar.gz: 82cac53d1b5c18acdeb7312da3cc929bed1590e707d8ac8edeb0480fff13af29
+  metadata.gz: 74e2d5917cd228f02d8e8b4ae785affd6f2feeeb689db16003a1ba397653496f
+  data.tar.gz: 2752fe3c544f39ba6c869e0a58ed628ed18f85c7d938ebdf2b0b2a8dcc879e35
 SHA512:
-  metadata.gz: b0a1395d51df9233140f9f7b7dd49d6cdc3bc1c50eea76425da7300a6b165230c17452ecaf7b1721c50a9b87f788775913b93ada281906ab681a19376976a34c
-  data.tar.gz: 12856340affc8a8a298986c8b56c01198256346c5cd0caf8f7fac2726ea742d43fc05e113c7f93960c34cae08318b5c5ac912b5b5adb716e03748bef56818b1a
+  metadata.gz: 74cb8513be353995a49ff1a2a39eaf7247da0c8344d29bd4e6eddc0fdb5a662a22ce0473378dc8f65bf8ae42b5c4284b49f46f587b32995856ea9b12d8da51a2
+  data.tar.gz: 5f9d08ad26099efdcf0410108fe7fc8d156e3fd7920e0c0461b0bee4d3a47b30487f4a7eb7b4441b1d64fde68c9c2e3b908cc231e783bd1332667153575a5d21

data/.standard.yml

@@ -0,0 +1 @@
+ruby_version: 2.4

data/CHANGELOG.md

@@ -1,3 +1,26 @@
+# 0.0.6
+
+- Add `TimeUp.all_timers`. It's weird that it's not a thing.
+
+# 0.0.5
+
+- Add `median` and `percentile` timer statistics, and added them to
+  `print_detailed_summary`
+
+# 0.0.4
+
+- Add `TimeUp.print_detailed_summary`
+
+# 0.0.3
+
+- Change the return value of TimeUp.start when passed a block to be the
+  evaluated value of the block (for easier insertion into existing code without
+  adding a bunch of new assignment and returns)
+- Allow timer instances' `start` method to be called with a block
+- Add `timings`, `count`, `min`, `max`, and `mean` methods for basic stats
+  tracking
+- Add `TimeUp.all_stats` to roll up all these
+
 # 0.0.2
 
 - Switch from a module method to Thread.current variable

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    time_up (0.0.2)
+    time_up (0.0.6)
 
 GEM
   remote: https://rubygems.org/

data/README.md

@@ -11,6 +11,9 @@ process and that you want to measure in aggregate. (For example, to see how
 much time your test suite spends creating factories, truncating the database, or
 invoking a critical code path.)
 
+Here's a [blog post about time_up](https://blog.testdouble.com/posts/2021-07-19-benchmarking-your-ruby-with-time_up/) and 
+a [great example of when it can be useful](https://gist.github.com/searls/feee0b0eac7c329b390fed90c4714afb).
+
 ## Install
 
 Just run `gem install time_up` or add time_up to your Gemfile:
@@ -65,10 +68,10 @@ sleep 5
 puts TimeUp.stop :eggs # => ~5.0
 ```
 
-`TimeUp.start` also returns an instance of the named timer, which has its own
-`start`, `stop`, `elaped`, and `reset` methods. If you want to find that
-instance later, you can also call `TimeUp.timer(:some_name)`. So the above
-example could be rewritten as:
+When passes without a block, `TimeUp.start` returns an instance of the timer,
+which has its own `start`, `stop`, `elaped`, and `reset` methods. If you want to
+find that instance later, you can also call `TimeUp.timer(:some_name)`. So the
+above example could be rewritten as:
 
 ```ruby
 egg_timer = TimeUp.start :eggs
@@ -107,7 +110,7 @@ TimeUp.print_summary
 Which will output something like:
 
 ```
-TimeUp timers summary
+TimeUp summary
 ========================
 :roast   	0.07267s
 :veggies 	0.03760s
@@ -117,39 +120,87 @@ TimeUp timers summary
 * Denotes that the timer is still active
 ```
 
+And if you're calling the timers multiple times and want to see some basic
+statistics in the print-out, you can call `TimeUp.print_detailed_summary`, which
+will produce this:
+
+```
+=============================================================================
+  Name    | Elapsed | Count |   Min   |   Max   |  Mean   | Median  | 95th %
+-----------------------------------------------------------------------------
+:roast    | 0.08454 | 3     | 0.00128 | 0.07280 | 0.02818 | 0.01046 | 0.06657
+:veggies  | 0.03779 | 1     | 0.03779 | 0.03779 | 0.03779 | 0.03779 | 0.03779
+:pasta    | 0.01260 | 11    | 0.00000 | 0.01258 | 0.00115 | 0.00000 | 0.00630
+:souffle* | 0.00024 | 1     | 0.00024 | 0.00025 | 0.00025 | 0.00025 | 0.00026
+
+* Denotes that the timer is still active
+```
+
 ## API
 
 This gem defines a bunch of public methods but they're all pretty short and
-straightforward, so I'd encourage you to [read the code](/lib/time_up.rb).
+straightforward, so when in doubt, I'd encourage you to [read the
+code](/lib/time_up.rb).
 
 ### `TimeUp` module
 
-`TimeUp.start(name, [&blk])` - Starts (or restarts) and returns a named `Timer`
+`TimeUp.timer(name)` - Returns the `Timer` instance named `name` (creating it,
+if it doesn't exist)
 
-`TimeUp.timer(name)` - Returns any a `Timer` instance named `name` or `nil`
+`TimeUp.start(name, [&blk])` - Starts (or restarts) a named
+[Timer](#timeuptimer-class). If passed a block, will return whatever the block
+evaluates to. If called without a block, it will return the timer object
 
-`TimeUp.stop(name)` - Stops the named timer or raises if it's not defined
+`TimeUp.stop(name)` - Stops the named timer
+
+`TimeUp.reset(name)` - Resets the named timer's elapsed time to 0, effectively
+restarting it if it's currently running
 
 `TimeUp.elapsed(name)` - Returns a `Float` of the total elapsed seconds that the
-named timer has been running (and raises if no timer is defined with the given
-`name`)
+named timer has been running
 
-`TimeUp.reset(name)` - Resets the named timer's elapsed time to 0, effectively
-restarting it if it's currently running. Raises if the timer isn't defined.
+`TimeUp.timings(name)` - Returns an array of each recorded start-to-stop
+duration (including the current one, if the timer is running) of the named timer
+
+`TimeUp.count(name)` - The number of times the timer has been started (including
+the current timing, if the timer is running)
+
+`TimeUp.min(name)` - The shortest recording by the timer
+
+`TimeUp.max(name)` - The longest recording by the timer
 
-`TimeUp.total_elapsed` - Returns a `Float` of the sum of `elapsed` for all the
-timers you've created
+`TimeUp.mean(name)` - The arithmetic mean of all recordings by the timer
 
-`TimeUp.all_elapsed` - Returns a hash of timer name keys mapped to their
-`elapsed` values. Handy for grabbing a snapshot of the state of things at a
-particular point in time without stopping all your timers
+`TimeUp.median(name)` - The median of all recordings by the timer
 
-`TimeUp.active_timers` - Returns an array of all timers that are currently
-running. Useful for detecting cases where you might be counting the same time in
-multiple places simultaneously
+`TimeUp.percentile(name, percent)` - The timing for the given
+[percentile](https://en.wikipedia.org/wiki/Percentile) of all recordings by the
+timer
 
-`TimeUp.print_summary([IO])` - Pretty-prints a multi-line summary of all your
-timers to STDOUT (or the provided IO)
+`TimeUp.total_elapsed` - Returns a `Float` of the sum of `elapsed` across all
+the timers you've created (note that because you can easily run multiple logical
+timers simultaneously, this figure may exceed the total time spent by the
+computer)
+
+`TimeUp.all_elapsed` - Returns a Hash of timer name keys mapped to their
+`elapsed` values. Handy for grabbing a reference to a snapshot of the state of
+things without requiring you to stop your timers
+
+`TimeUp.all_stats` - Returns a Hash of timer name keys mapped to another
+hash of their basic statistics (`elapsed`, `count`, `min`, `max`,
+and `mean`)
+
+`TimeUp.active_timers` - Returns an Array of all timers that are currently
+running. Useful for detecting cases where you might be keeping time in multiple
+places simultaneously
+
+`TimeUp.print_summary([io])` - Pretty-prints a multi-line summary of all your
+timers' total elapsed times to standard output (or the provided
+[IO](https://ruby-doc.org/core-3.0.1/IO.html))
+
+`TimeUp.print_detailed_summary([io])` - Pretty-prints a multi-line summary of
+all your timers' elapsed times and basic statistics to standard output (or the
+provided [IO](https://ruby-doc.org/core-3.0.1/IO.html))
 
 `TimeUp.stop_all` - Stops all timers
 
@@ -166,6 +217,23 @@ reference to them
 
 `elapsed` - A `Float` of the total elapsed seconds the timer has been running
 
+`timings` - Returns an Array of each recorded start-to-stop duration of the
+timer (including the current one, if the timer is running)
+
+`count` - The number of times the timer has been started and stopped
+
+`min` - The shortest recording of the timer
+
+`max` - The longest recording of the timer
+
+`mean` - The arithmetic mean of all recorded durations of the timer
+
+`median(name)` - The median of all recordings by the timer
+
+`percentile(name, percent)` - The timing for the given
+[percentile](https://en.wikipedia.org/wiki/Percentile) of all recordings by the
+timer
+
 `active?` - Returns `true` if the timer is running
 
 `reset(force: false)` - Resets the timer to 0 elapsed seconds. If `force` is

data/lib/time_up.rb

@@ -5,35 +5,35 @@ module TimeUp
 
   Thread.current[:time_up_timers] = {}
 
-  def self.start(name, &blk)
-    raise Error.new("Timer name must be a String or Symbol") unless name.is_a?(Symbol) || name.is_a?(String)
-    timer = __timers[name] ||= Timer.new(name)
-    timer.start
-    if blk
-      blk.call
-      timer.stop
-    end
-    timer
-  end
-
-  # Delegate methods
   def self.timer(name)
-    __timers[name]
+    __timers[name] ||= Timer.new(name)
   end
 
-  def self.stop(name)
-    __ensure_timer(name)
-    __timers[name].stop
+  # Delegate methods
+  def self.start(name, &blk)
+    timer(name).start(&blk)
   end
 
-  def self.elapsed(name)
-    __ensure_timer(name)
-    __timers[name].elapsed
+  [
+    :stop,
+    :reset,
+    :elapsed,
+    :timings,
+    :count,
+    :min,
+    :max,
+    :mean,
+    :median
+  ].each do |method_name|
+    define_singleton_method method_name do |name|
+      __ensure_timer(name)
+      __timers[name].send(method_name)
+    end
   end
 
-  def self.reset(name)
+  def self.percentile(name, percentage)
     __ensure_timer(name)
-    __timers[name].reset
+    __timers[name].percentile(percentage)
   end
 
   # Interrogative methods
@@ -47,6 +47,24 @@ module TimeUp
     }.to_h
   end
 
+  def self.all_timers
+    __timers.values
+  end
+
+  def self.all_stats
+    __timers.values.map { |timer|
+      [timer.name, {
+        elapsed: timer.elapsed,
+        count: timer.count,
+        min: timer.min,
+        max: timer.max,
+        mean: timer.mean,
+        median: timer.median,
+        "95th": timer.percentile(95)
+      }]
+    }.to_h
+  end
+
   def self.active_timers
     __timers.values.select(&:active?)
   end
@@ -59,7 +77,7 @@ module TimeUp
     }
     io.puts <<~SUMMARY
 
-      TimeUp timers summary
+      TimeUp summary
       ========================
       #{summaries.join("\n")}
 
@@ -67,6 +85,56 @@ module TimeUp
     SUMMARY
   end
 
+  def self.print_detailed_summary(io = $stdout)
+    cols = {
+      names: ["Name"],
+      elapsed: ["Elapsed"],
+      count: ["Count"],
+      min: ["Min"],
+      max: ["Max"],
+      mean: ["Mean"],
+      median: ["Median"],
+      "95th": ["95th %"]
+    }
+    __timers.values.each { |timer|
+      cols[:names] << "#{timer.name.inspect}#{"*" if timer.active?}"
+      cols[:elapsed] << "%.5f" % timer.elapsed
+      cols[:count] << timer.count.to_s
+      cols[:min] << "%.5f" % timer.min
+      cols[:max] << "%.5f" % timer.max
+      cols[:mean] << "%.5f" % timer.mean
+      cols[:median] << "%.5f" % timer.median
+      cols[:"95th"] << "%.5f" % timer.percentile(95)
+    }
+
+    widths = cols.map { |name, vals|
+      [name, vals.map(&:length).max]
+    }.to_h
+
+    rows = cols[:names].size.times.map { |i|
+      if i == 0
+        cols.keys.map { |name|
+          cols[name][i].center(widths[name])
+        }
+      else
+        cols.keys.map { |name|
+          cols[name][i].ljust(widths[name])
+        }
+      end
+    }
+
+    full_width = widths.values.sum + (rows[0].size - 1) * 3
+    io.puts <<~SUMMARY
+
+      #{"=" * full_width}
+      #{rows[0].join(" | ")}
+      #{"-" * full_width}
+      #{rows[1..-1].map { |row| row.join(" | ") }.join("\n")}
+
+      #{"* Denotes that the timer is still active\n" if __timers.values.any?(&:active?)}
+    SUMMARY
+  end
+
   # Iterative methods
   def self.stop_all
     __timers.values.each(&:stop)
@@ -94,46 +162,110 @@ module TimeUp
     attr_reader :name
 
     def initialize(name)
+      validate!(name)
       @name = name
       @start_time = nil
-      @elapsed = 0.0
+      @total_elapsed = 0.0
+      @past_timings = []
     end
 
-    def start
+    def start(&blk)
       @start_time ||= now
+      if blk
+        blk.call.tap do
+          stop
+        end
+      else
+        self
+      end
     end
 
     def stop
       if @start_time
-        @elapsed += now - @start_time
+        duration = now - @start_time
+        @past_timings.push(duration)
+        @total_elapsed += duration
+
         @start_time = nil
       end
-      @elapsed
+      @total_elapsed
     end
 
     def elapsed
       if active?
-        @elapsed + (now - @start_time)
+        @total_elapsed + (now - @start_time)
       else
-        @elapsed
+        @total_elapsed
       end
     end
 
-    def active?
-      !!@start_time
-    end
-
     def reset(force: false)
       if force
         @start_time = nil
       elsif !@start_time.nil?
         @start_time = now
       end
-      @elapsed = 0.0
+      @total_elapsed = 0.0
+      @past_timings = []
+    end
+
+    def count
+      timings.size
+    end
+
+    def min
+      timings.min
+    end
+
+    def max
+      timings.max
+    end
+
+    def mean
+      times = timings
+      return if times.empty?
+      times.sum / times.size
+    end
+
+    def median
+      times = timings.sort
+      return if times.empty?
+      (times[(times.size - 1) / 2] + times[times.size / 2]) / 2.0
+    end
+
+    def percentile(percent)
+      times = timings.sort
+      return if times.empty?
+      return 0 if percent <= 0
+      return max if percent >= 100
+      return times.first if times.size == 1
+      position = (percent / 100.0) * (times.size - 1)
+
+      partial_ratio = position - position.floor
+      whole, partial = times[position.floor, 2]
+      whole + (partial - whole) * partial_ratio
+    end
+
+    def timings
+      if active?
+        @past_timings + [now - @start_time]
+      else
+        @past_timings
+      end
+    end
+
+    def active?
+      !!@start_time
     end
 
     private
 
+    def validate!(name)
+      unless name.is_a?(Symbol) || name.is_a?(String)
+        raise Error.new("Timer name must be a String or Symbol")
+      end
+    end
+
     def now
       Process.clock_gettime(Process::CLOCK_MONOTONIC)
     end

data/lib/time_up/version.rb

@@ -1,3 +1,3 @@
 module TimeUp
-  VERSION = "0.0.2"
+  VERSION = "0.0.6"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: time_up
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.6
 platform: ruby
 authors:
 - Justin Searls
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2021-07-15 00:00:00.000000000 Z
+date: 2021-07-20 00:00:00.000000000 Z
 dependencies: []
 description:
 email:
@@ -19,6 +19,7 @@ extra_rdoc_files: []
 files:
 - ".github/workflows/main.yml"
 - ".gitignore"
+- ".standard.yml"
 - CHANGELOG.md
 - Gemfile
 - Gemfile.lock