hitimes 1.3.1 → 3.0.0

data/lib/hitimes/metric.rb

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 
 #--
 # Copyright (c) 2008, 2009 Jeremy Hinegardner
@@ -13,15 +14,14 @@ module Hitimes
   # * The name of the metric
   # * The time of day the first measurement is taken
   # * The time of day the last measurement is taken
-  # * additional data 
+  # * additional data
   #
   # Each derived class is assumed to set the sampling_start_time and
   # sampling_stop_time appropriately.
-  # 
+  #
   # Metric itself should generally not be used.  Only use the derived classes.
   #
   class Metric
-
     # the number of seconds as a float since the sampling_start_time
     attr_reader :sampling_delta
 
@@ -41,7 +41,7 @@ module Hitimes
     # +additional_data+ may be anything that follows the +to_hash+ protocol.
     # +name+ may be anything that follows the +to_s+ protocol.
     #
-    def initialize( name, additional_data = {} )
+    def initialize(name, additional_data = {})
       @sampling_start_time     = nil
       @sampling_start_interval = nil
       @sampling_delta          = 0
@@ -51,7 +51,7 @@ module Hitimes
     end
 
     #
-    # :call-seq: 
+    # :call-seq:
     #   metric.sampling_start_time -> Float or nil
     #
     # The time at which the first sample was taken.
@@ -60,11 +60,9 @@ module Hitimes
     # If the metric has not started measuring then the start time is nil.
     #
     def sampling_start_time
-      if @sampling_start_interval then
-        @sampling_start_time ||= self.utc_microseconds()
-      else
-        nil
-      end
+      return unless @sampling_start_interval
+
+      @sampling_start_time ||= utc_microseconds
     end
 
     #
@@ -73,8 +71,8 @@ module Hitimes
     #
     # The time at which the last sample was taken
     # This is the number of microseconds since UNIX epoch UTC as a Float
-    # 
-    # If the metric has not completely measured at least one thing then 
+    #
+    # If the metric has not completely measured at least one thing then
     # stop time is nil.
     #
     # Because accessing the actual 'time of day' is an expesive operation, we
@@ -84,11 +82,9 @@ module Hitimes
     # When sampling_stop_time is called, the actual time of day is caculated.
     #
     def sampling_stop_time
-      if @sampling_delta > 0 then
-        (self.sampling_start_time + (@sampling_delta * 1_000_000))
-      else 
-        nil
-      end
+      return unless @sampling_delta.positive?
+
+      (sampling_start_time + (@sampling_delta * 1_000_000))
     end
 
     #
@@ -96,13 +92,13 @@ module Hitimes
     #    metric.to_hash -> Hash
     #    metric.to_hash
     #
-    # Convert the metric to a Hash.  
+    # Convert the metric to a Hash.
     #
     def to_hash
-      { 'sampling_start_time' => self.sampling_start_time,
-        'sampling_stop_time'  => self.sampling_stop_time,
-        'additional_data'     => self.additional_data,
-        'name'                => self.name }
+      { "sampling_start_time" => sampling_start_time,
+        "sampling_stop_time" => sampling_stop_time,
+        "additional_data" => additional_data,
+        "name" => name, }
     end
 
     #

data/lib/hitimes/mutexed_stats.rb

@@ -1,32 +1,15 @@
+# frozen_string_literal: true
+
 #--
 # Copyright (c) 2008, 2009 Jeremy Hinegardner
 # All rights reserved.  See LICENSE and/or COPYING for details.
 #++
 
-require 'thread'
-
 module Hitimes
   #
   # MutexedStats is the start of a threadsafe Stats class.  Currently, on MRI
   # Ruby the Stats object is already threadsafe, so there is no need to use
   # MutexedStats.
   #
-  class MutexedStats < Stats
-    def initialize
-      @mutex = Mutex.new
-    end
-
-    # call-seq:
-    #   mutex_stat.update( val ) -> nil
-    # 
-    # Update the running stats with the new value in a threadsafe manner.
-    #
-    def update( value )
-      @mutex.synchronize do
-        super( value )
-      end
-    end
-  end
+  MutexedStats = Stats
 end
-
-

data/lib/hitimes/paths.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 #--
 # Copyright (c) 2008 Jeremy Hinegardner
 # All rights reserved.  See LICENSE and/or COPYING for details.
@@ -8,34 +10,34 @@ module Hitimes
   # Access to various paths inside the project programatically
   #
   module Paths
-    #   
+    #
     # :call-seq:
     #    Hitimes::Paths.root_dir -> String
     #
     # Returns The full expanded path of the parent directory of +lib+
-    # going up the path from the current file.  A trailing File::SEPARATOR 
+    # going up the path from the current file.  A trailing File::SEPARATOR
     # is guaranteed.
-    #   
+    #
     def self.root_dir
-      @root_dir ||=(
+      @root_dir ||= begin
         path_parts = ::File.expand_path(__FILE__).split(::File::SEPARATOR)
         lib_index  = path_parts.rindex("lib")
         @root_dir = path_parts[0...lib_index].join(::File::SEPARATOR) + ::File::SEPARATOR
-      )
-    end 
+      end
+    end
 
-    # 
+    #
     # :call-seq:
     #   Hitimes::Paths.lib_path( *args ) -> String
     #
     # Returns The full expanded path of the +lib+ directory below
-    # _root_dir_.  All parameters passed in are joined onto the 
-    # result. A trailing File::SEPARATOR is guaranteed if 
+    # _root_dir_.  All parameters passed in are joined onto the
+    # result. A trailing File::SEPARATOR is guaranteed if
     # _args_ are *not* present.
-    #   
+    #
     def self.lib_path(*args)
-      self.sub_path("lib", *args)
-    end 
+      sub_path("lib", *args)
+    end
 
     #
     # :call-seq:
@@ -45,9 +47,9 @@ module Hitimes
     # _arg_ parameters passed in are joined onto the result.  A trailing
     # File::SEPARATOR is guaranteed if _args_ are *not* present.
     #
-    def self.sub_path(sub,*args)
+    def self.sub_path(sub, *args)
       sp = ::File.join(root_dir, sub) + File::SEPARATOR
-      sp = ::File.join(sp, *args) if args
+      ::File.join(sp, *args) if args
     end
   end
 end

data/lib/hitimes/stats.rb

@@ -1,34 +1,132 @@
+# frozen_string_literal: true
+
 #--
 # Copyright (c) 2008, 2009 Jeremy Hinegardner
 # All rights reserved.  See LICENSE and/or COPYING for details.
 #++
 
-require 'stringio'
+require "stringio"
 module Hitimes
+  #
+  # The Stats class encapulsates capturing and reporting statistics.  It is
+  # modeled after the RFuzz::Sampler class, but implemented in C.  For general use
+  # you allocate a new Stats object, and then update it with new values.  The
+  # Stats object will keep track of the _min_, _max_, _count_, _sum_ and _sumsq_
+  # and when you want you may also retrieve the _mean_, _stddev_ and _rate_.
+  #
+  # this contrived example shows getting a list of all the files in a directory
+  # and running stats on file sizes.
+  #
+  #     s = Hitimes::Stats.new
+  #     dir = ARGV.shift || Dir.pwd
+  #     Dir.entries( dir ).each do |entry|
+  #       fs = File.stat( entry )
+  #       if fs.file? then
+  #         s.update( fs.size )
+  #        end
+  #     end
+  #
+  #     %w[ count min max mean sum stddev rate ].each do |m|
+  #       puts "#{m.rjust(6)} : #{s.send( m ) }"
+  #     end
+  #
   class Stats
     # A list of the available stats
-    STATS = %w[ count max mean min rate stddev sum sumsq ]
+    STATS = %w[count max mean min rate stddev sum sumsq].freeze
+
+    attr_reader :min, :max, :count, :sum, :sumsq
+
+    def initialize
+      @mutex = Mutex.new
+      @min = Float::INFINITY
+      @max = -Float::INFINITY
+      @count = 0
+      @sum = 0.0
+      @sumsq = 0.0
+    end
 
-    # 
+    # call-seq:
+    #    stat.update( val ) -> val
+    #
+    # Update the running stats with the new value.
+    # Return the input value.
+    def update(value)
+      @mutex.synchronize do
+        @min = (value < @min) ? value : @min
+        @max = (value > @max) ? value : @max
+
+        @count += 1
+        @sum   += value
+        @sumsq += (value * value)
+      end
+
+      value
+    end
+
+    # call-seq:
+    #    stat.mean -> Float
+    #
+    # Return the arithmetic mean of the values put into the Stats object.  If no
+    # values have passed through the stats object then 0.0 is returned;
+    def mean
+      return 0.0 if @count.zero?
+
+      @sum / @count
+    end
+
+    # call-seq:
+    #    stat.rate -> Float
+    #
+    # Return the +count+ divided by +sum+.
+    #
+    # In many cases when Stats#update( _value_ ) is called, the _value_ is a unit
+    # of time, typically seconds or microseconds.  #rate is a convenience for those
+    # times.  In this case, where _value_ is a unit if time, then count divided by
+    # sum is a useful value, i.e. +something per unit of time+.
+    #
+    # In the case where _value_ is a non-time related value, then the value
+    # returned by _rate_ is not really useful.
+    #
+    def rate
+      return 0.0 if @sum.zero?
+
+      @count / @sum
+    end
+
+    #
+    # call-seq:
+    #    stat.stddev -> Float
+    #
+    # Return the standard deviation of all the values that have passed through the
+    # Stats object.  The standard deviation has no meaning unless the count is > 1,
+    # therefore if the current _stat.count_ is < 1 then 0.0 will be returned;
+    #
+    def stddev
+      return 0.0 unless @count > 1
+
+      Math.sqrt((@sumsq - ((@sum * @sum) / @count)) / (@count - 1))
+    end
+
+    #
     # call-seq:
     #   stat.to_hash   -> Hash
     #   stat.to_hash( %w[ count max mean ]) -> Hash
     #
     # return a hash of the stats.  By default this returns a hash of all stats
     # but passing in an array of items will limit the stats returned to only
-    # those in the Array. 
+    # those in the Array.
     #
     # If passed in an empty array or nil to to_hash then STATS is assumed to be
     # the list of stats to return in the hash.
     #
-    def to_hash( *args )
-      h = {}
-      args = [ args ].flatten
-      args = STATS if args.empty?
-      args.each do |meth|
-        h[meth] = self.send( meth )
+    def to_hash(*args)
+      result = {}
+      fields = [args].flatten
+      fields = STATS if fields.empty?
+      fields.each do |meth|
+        result[meth] = send(meth)
       end
-      return h
+      result
     end
 
     #
@@ -40,19 +138,18 @@ module Hitimes
     # of all the stats.  If an array of items is passed in, those that match the
     # known stats will be all that is included in the json output.
     #
-    def to_json( *args )
-      h = to_hash( *args )
-      a = []
-      s = StringIO.new
+    def to_json(*args)
+      stats = to_hash(*args)
+      slugs = []
+      out = StringIO.new
 
-      s.print "{ "
-      h.each_pair do |k,v|
-        a << "\"#{k}\": #{v}"
+      out.print "{ "
+      stats.each_pair do |key, val|
+        slugs << "\"#{key}\": #{val}"
       end
-      s.print a.join(", ")
-      s.print "}"
-      return s.string
+      out.print slugs.join(", ")
+      out.print "}"
+      out.string
     end
-
   end
 end

data/lib/hitimes/timed_metric.rb

@@ -1,9 +1,11 @@
+# frozen_string_literal: true
+
 #--
 # Copyright (c) 2008, 2009 Jeremy Hinegardner
 # All rights reserved.  See LICENSE and/or COPYING for details.
 #++
 
-require 'forwardable'
+require "forwardable"
 module Hitimes
   #
   # A TimedMetric holds the metrics on how long it takes to do something.  For
@@ -11,11 +13,11 @@ module Hitimes
   #
   #   tm = TimedMetric.new( 'my-method' )
   #
-  #   200.times do 
-  #     my_method_result = tm.measure do 
+  #   200.times do
+  #     my_method_result = tm.measure do
   #       my_method( ... )
   #     end
-  #   end 
+  #   end
   #
   #   puts "#{ tm.name } operated at a rate of #{ tm.rate } calls per second"
   #
@@ -23,9 +25,9 @@ module Hitimes
   # Metric API also.
   #
   # A TimedMetric measures the execution time of an option with the Interval
-  # class. 
-  # 
-  # A TimedMetric contains a Stats object, therefore TimedMetric has +count+, +max+, 
+  # class.
+  #
+  # A TimedMetric contains a Stats object, therefore TimedMetric has +count+, +max+,
   # +mean+, +min+, +rate+, +stddev+, +sum+, +sumsq+ methods that delegate to that Stats
   # object for convenience.
   #
@@ -41,10 +43,10 @@ module Hitimes
       #
       # Return a TimedMetric that has been started
       #
-      def now( name, additional_data = {} )
-        t = TimedMetric.new( name, additional_data )
-        t.start
-        return t
+      def now(name, additional_data = {})
+        tm = TimedMetric.new(name, additional_data)
+        tm.start
+        tm
       end
     end
 
@@ -56,8 +58,8 @@ module Hitimes
     # Create a new TimedMetric giving it a name and additional data.
     # +additional_data+ may be anything that follows the +to_hash+ protocol
     #
-    def initialize( name, additional_data = {} )
-      super( name, additional_data )
+    def initialize(name, additional_data = {})
+      super(name, additional_data)
       @stats            = Stats.new
       @current_interval = Interval.new
     end
@@ -66,23 +68,23 @@ module Hitimes
     # :call-seq:
     #   timed_metric.running? -> true or false
     #
-    # return whether or not the timer is currently running.  
+    # return whether or not the timer is currently running.
     #
     def running?
       @current_interval.running?
     end
 
-    # 
+    #
     # :call-seq:
     #   timed_metric.start -> nil
     #
     # Start the current metric, if the current metric is already started, then
-    # this is a noop.  
+    # this is a noop.
     #
     def start
-      if not @current_interval.running? then
-        @current_interval.start 
-        @sampling_start_time ||= self.utc_microseconds() 
+      unless @current_interval.running?
+        @current_interval.start
+        @sampling_start_time ||= utc_microseconds
         @sampling_start_interval ||= Interval.now
       end
       nil
@@ -96,19 +98,19 @@ module Hitimes
     # interval. If the timer was stopped then the duration of the last Interval
     # is returned.  If the timer was already stopped then false is returned and
     # no stats are updated.
-    # 
+    #
     def stop
-      if @current_interval.running? then
-        d = @current_interval.stop
-        @stats.update( d )
+      if @current_interval.running?
+        duration = @current_interval.stop
+        @stats.update(duration)
         @current_interval = Interval.new
 
         # update the length of time we have been sampling
         @sampling_delta = @sampling_start_interval.duration_so_far
 
-        return d
+        return duration
       end
-      return false
+      false
     end
 
     #
@@ -118,7 +120,7 @@ module Hitimes
     # Measure the execution of a block and add those stats to the running stats.
     # The return value is the return value of the block
     #
-    def measure( &block )
+    def measure
       return_value = nil
       begin
         start
@@ -126,7 +128,7 @@ module Hitimes
       ensure
         stop
       end
-      return return_value
+      return_value
     end
 
     #
@@ -142,35 +144,34 @@ module Hitimes
     # interval, i.e. the split-time.  If the timer is not running, nothing
     # happens and false is returned.
     #
-    def split  
-      if @current_interval.running? then 
+    def split
+      if @current_interval.running?
         next_interval = @current_interval.split
-        d = @current_interval.duration
-        @stats.update( d )
-        @current_interval = next_interval 
-        return d
-      end 
-      return false
+        duration = @current_interval.duration
+        @stats.update(duration)
+        @current_interval = next_interval
+        return duration
+      end
+      false
     end
 
     #
     # :call-seq:
     #   metric.to_hash -> Hash
-    #   
+    #
     # Convert the metric to a hash
     #
     def to_hash
-      h = super
-      Stats::STATS.each do |s|
-        h[s] = self.send( s ) 
+      result = super
+      Stats::STATS.each do |stat|
+        result[stat] = send(stat)
       end
-      return h
+      result
     end
 
-
     # forward appropriate calls directly to the stats object
     extend Forwardable
     def_delegators :@stats, :count, :max, :mean, :min, :rate, :stddev, :sum, :sumsq
-    alias :duration :sum
+    alias duration sum
   end
 end