hitimes 0.4.1 → 1.0.0

data/HISTORY

@@ -1,4 +1,14 @@
 = Changelog
+== Version 1.0.0 2009-06-12
+
+* Major version bump with complete refactor of the metric collection API
+* 3 types of metrics now instead of just 1 Timer
+  * ValueMetric
+  * TimedMetric
+  * TimedValueMetric
+* The ability to convert all metrics #to_hash
+* Updated documentation with examples using each metric type
+
 == Version 0.4.1 2009-02-19
 
 * change to ISC License

data/README

@@ -15,15 +15,20 @@ Hitimes is a fast, high resolution timer library for recording
 performance metrics.  It uses the appropriate C method calls for each
 system to get the highest granularity time increments possible.  
 
-It currently supports any system with the POSIX call clock_gettime(),
-Mac OS X and Windows.
+It currently supports any of the following systems:
 
-Using Hitimes can be faster than using a series of Time.new calls, and
+* any system with the POSIX call <tt>clock_gettime()</tt>,
+* Mac OS X
+* Windows
+
+Using Hitimes can be faster than using a series of +Time.new+ calls, and
 it will have a much higher granularity.   It is definitely faster than
-using Process.times. 
+using +Process.times+. 
 
 == SYNOPSIS
 
+=== Interval
+
 Use Hitimes::Interval to calculate only the duration of a block of code
 
   duration = Hitimes::Interval.measure do
@@ -32,21 +37,76 @@ Use Hitimes::Interval to calculate only the duration of a block of code
 
   puts duration   
 
-Use a Hitimes::Timer to calculate statistics about an iterative operation
+=== TimedMetric
+
+Use a Hitimes::TimedMetric to calculate statistics about an iterative operation
+
+  timed_metric = Hitimes::TimedMetric.new('operation on items')
+
+Explicitly use +start+ and +stop+:
 
-  timer = Hitimes::Timer.new
   collection.each do |item|
-    timer.start
+    timed_metric.start
     # .. do something with item
-    timer.stop
+    timed_metric.stop
+  end
+
+Or use the block.  In TimedMetric the return value of +measure+ is the return
+value of the block
+
+  collection.each do |item|
+    result_of_do_something = timed_metric.measure { do_something( item ) }
   end
 
-  puts timer.mean
-  puts timer.median
-  puts timer.max
-  puts timer.min
-  puts timer.stddev
-  puts timer.rate
+And then look at the stats
+
+  puts timed_metric.mean
+  puts timed_metric.max
+  puts timed_metric.min
+  puts timed_metric.stddev
+  puts timed_metric.rate
+
+=== ValueMetric 
+
+Use a Hitimes::ValueMetric to calculate statistics about measured samples
+
+  value_metric = Hitimes::ValueMetric.new( 'size of thing' )
+  loop do
+    # ... do stuff changing sizes of 'thing'
+    value_metric.measure( thing.size )
+    # ... do other stuff that may change size of thing
+  end
+
+  puts value_metric.mean
+  puts value_metric.max
+  puts value_metric.min
+  puts value_metric.stddev
+  puts value_metric.rate
+
+
+=== TimedValueMetric
+
+Use a Hitimes::TimedValueMetric to calculate statistics about batches of samples
+
+  timed_value_metric = Hitimes::TimedValueMetric.new( 'batch times' )
+  loop do 
+    batch = ... # get a batch of things
+    timed_value_metric.start
+    # .. do something with batch
+    timed_value_metric.stop( batch.size )
+  end
+
+  puts timed_value_metric.rate
+
+  puts timed_value_metric.timed_stats.mean
+  puts timed_value_metric.timed_stats.max
+  puts timed_value_metric.timed_stats.min
+  puts timed_value_metric.timed_stats.stddev
+
+  puts timed_value_metric.value_stats.mean
+  puts timed_value_metric.value_stats.max
+  puts timed_value_metric.value_stats.min
+  puts timed_value_metric.value_stats.stddev
 
 
 == CHANGES

data/ext/hitimes_interval.c

@@ -254,6 +254,9 @@ VALUE hitimes_interval_stop_instant( VALUE self )
 /**
  * call-seq:
  *    interval.duration -> Float
+ *    interval.to_f -> Float
+ *    interval.to_seconds -> Float
+ *    interval.length -> Float
  *
  * Returns the Float value of the interval, the value is in seconds.  If the
  * interval has not had stop called yet, it will report the number of seconds
@@ -321,10 +324,10 @@ void Init_hitimes_interval()
     rb_define_module_function( cH_Interval, "now", hitimes_interval_now, 0 ); /* in hitimes_interval.c */
     rb_define_module_function( cH_Interval, "measure", hitimes_interval_measure, 0 ); /* in hitimes_interval.c */
 
-    rb_define_method( cH_Interval, "to_f",         hitimes_interval_duration, 0 ); /* in hitimes_interval.c */
-    rb_define_method( cH_Interval, "to_seconds",   hitimes_interval_duration, 0 ); /* in hitimes_interval.c */
     rb_define_method( cH_Interval, "duration",     hitimes_interval_duration, 0 ); /* in hitimes_interval.c */
-    rb_define_method( cH_Interval, "length",       hitimes_interval_duration, 0 ); /* in hitimes_interval.c */
+    rb_define_method( cH_Interval, "length",       hitimes_interval_duration, 0 ); 
+    rb_define_method( cH_Interval, "to_f",         hitimes_interval_duration, 0 );
+    rb_define_method( cH_Interval, "to_seconds",   hitimes_interval_duration, 0 );
      
     rb_define_method( cH_Interval, "started?",     hitimes_interval_started, 0 ); /* in hitimes_interval.c */
     rb_define_method( cH_Interval, "running?",     hitimes_interval_running, 0 ); /* in hitimes_interval.c */

data/ext/hitimes_stats.c

@@ -39,9 +39,10 @@ VALUE hitimes_stats_alloc(VALUE klass)
 
 /**
  * call-seq:
- *    stat.update( val ) -> nil
+ *    stat.update( val ) -> val
  * 
  * Update the running stats with the new value.
+ * Return the input value.
  */
 VALUE hitimes_stats_update( VALUE self, VALUE v )
 {
@@ -62,7 +63,7 @@ VALUE hitimes_stats_update( VALUE self, VALUE v )
     stats->sum   += new_v;
     stats->sumsq += ( new_v * new_v );
 
-    return Qnil;
+    return v;
 }
 
 /**
@@ -91,10 +92,15 @@ VALUE hitimes_stats_mean( VALUE self )
  * call-seq:
  *    stat.rate -> Float
  * 
- * Return the count per sum.  In many cases when Stats#update( _value_ ) is
- * called, the _value_ is a unit of time, typically seconds.  #rate 
- * is a convenience for those times.  In the most common case, where _value_ 
- * is in seconds, then #rate returns the count / second.
+ * 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.
  *
  */
 VALUE hitimes_stats_rate( VALUE self )
@@ -176,6 +182,22 @@ VALUE hitimes_stats_sum( VALUE self )
     return rb_float_new( stats->sum );
 }
 
+/**
+ * call-seq:
+ *   stat.sumsq -> Float
+ *
+ * Return the sum of the squars of all the values that passed through the Stats
+ * object.
+ */
+VALUE hitimes_stats_sumsq( VALUE self )
+{
+    hitimes_stats_t *stats;
+
+    Data_Get_Struct( self, hitimes_stats_t, stats );
+
+    return rb_float_new( stats->sumsq );
+}
+
 
 /**
  * call-seq:
@@ -205,8 +227,8 @@ VALUE hitimes_stats_stddev ( VALUE self )
  * 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_ and _sum_ and when
- * you want you may also retrieve the _mean_, _stddev_ and _rate_.
+ * 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.
@@ -240,6 +262,7 @@ void Init_hitimes_stats()
     rb_define_method( cH_Stats, "min", hitimes_stats_min, 0 ); /* in hitimes_stats.c */
     rb_define_method( cH_Stats, "rate", hitimes_stats_rate, 0 ); /* in hitimes_stats.c */
     rb_define_method( cH_Stats, "sum", hitimes_stats_sum, 0 ); /* in hitimes_stats.c */
+    rb_define_method( cH_Stats, "sumsq", hitimes_stats_sumsq, 0 ); /* in hitimes_stats.c */
     rb_define_method( cH_Stats, "stddev", hitimes_stats_stddev, 0 ); /* in hitimes_stats.c */
 }
  

data/gemspec.rb

@@ -20,8 +20,10 @@ Hitimes::GEM_SPEC = Gem::Specification.new do |spec|
   spec.executables  = pkg.files.bin.collect { |b| File.basename(b) }
 
   # add dependencies here
-  spec.add_dependency("rake", ">= 0.8.1")
-  spec.add_dependency("configuration", ">= 0.0.5")
+  spec.add_dependency("rake", "~> 0.8.1")
+  spec.add_dependency("configuration", " ~> 0.0.5")
+
+  spec.add_development_dependency( "json", "~> 1.1.3")
 
   if ext_conf = Configuration.for_if_exist?("extension") then
     spec.extensions <<  ext_conf.configs

data/lib/hitimes.rb

@@ -19,6 +19,10 @@ end
 require 'hitimes/paths'
 require 'hitimes/version'
 require 'hitimes/stats'
+require 'hitimes_ext'
 require 'hitimes/mutexed_stats'
-require 'hitimes/timer'
+require 'hitimes/metric'
+require 'hitimes/value_metric'
+require 'hitimes/timed_metric'
+require 'hitimes/timed_value_metric'
 

data/lib/hitimes/metric.rb

@@ -0,0 +1,74 @@
+module Hitimes
+  #
+  # Metric hold the common meta information for all derived metric classes
+  #
+  # All metrics hold the meta information of:
+  #
+  # * 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 
+  #
+  # 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 time at which the first sample was taken
+    # This is the number of microseconds since UNIX epoch UTC as a Float
+    attr_accessor :sampling_start_time
+
+    # the time at which the last sample was taken.
+    # This is the number of microseconds since UNIX epoch UTC as a Float
+    attr_accessor :sampling_stop_time
+
+    # An additional hash of data to associate with the metric
+    attr_reader :additional_data
+
+    # The 'name' to associate with the metric
+    attr_reader :name
+
+    #
+    # :call-seq:
+    #   Metric.new( 'my_metric' ) -> Metric
+    #   Metric.new( 'my_metric', 'foo' => 'bar', 'this' => 42 ) -> Metric
+    #
+    # Create a new ValueMetric giving it a name and additional data.
+    #
+    # +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 = {} )
+      @sampling_start_time = nil
+      @sampling_stop_time  = nil
+      @name                = name.to_s
+      @additional_data     = additional_data.to_hash
+    end
+
+    #
+    # :call-seq:
+    #    metric.to_hash -> Hash
+    #    metric.to_hash
+    #
+    # Convert the metric to a Hash.  
+    #
+    def to_hash
+      { 'sampling_start_time' => @sampling_start_time,
+        'sampling_stop_time'  => @sampling_stop_time,
+        'additional_data'     => @additional_data,
+        'name'                => @name }
+    end
+
+    #
+    # :call-seq:
+    #   metric.utc_microseconds -> Float
+    #
+    # The current time in microseconds from the UNIX Epoch in the UTC
+    #
+    def utc_microseconds
+      Time.now.gmtime.to_f * 1_000_000
+    end
+  end
+end

data/lib/hitimes/stats.rb

@@ -1,7 +1,9 @@
+require 'hitimes_ext'
+require 'stringio'
 module Hitimes
   class Stats
     # A list of the available stats
-    STATS = %w[ count max mean min rate stddev sum ]
+    STATS = %w[ count max mean min rate stddev sum sumsq ]
 
     # 
     # call-seq:
@@ -25,5 +27,28 @@ module Hitimes
       return h
     end
 
+    #
+    # call-seq:
+    #   stat.to_json  -> String
+    #   stat.to_json( *args ) -> String
+    #
+    # return a json string of the stats.  By default this returns a json string
+    # 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
+
+      s.print "{ "
+      h.each_pair do |k,v|
+        a << "\"#{k}\": #{v}"
+      end
+      s.print a.join(", ")
+      s.print "}"
+      return s.string
+    end
+
   end
 end

data/lib/hitimes/timed_metric.rb

@@ -0,0 +1,181 @@
+#--
+# Copyright (c) 2008, 2009 Jeremy Hinegardner
+# All rights reserved.  See LICENSE and/or COPYING for details.
+#++
+
+require 'hitimes'
+require 'forwardable'
+module Hitimes
+  #
+  # A TimedMetric holds the metrics on how long it takes to do something.  For
+  # example, measuring how long a method takes to operate.
+  #
+  #   tm = TimedMetric.new( 'my-method' )
+  #
+  #   200.times do 
+  #     my_method_result = tm.measure do 
+  #       my_method( ... )
+  #     end
+  #   end 
+  #
+  #   puts "#{ tm.name } operated at a rate of #{ tm.rate } calls per second"
+  #
+  # Since TimedMetric is a child class of Metric make sure to look at the
+  # 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+, 
+  # +mean+, +min+, +rate+, +stddev+, +sum+, +sumsq+ methods that delegate to that Stats
+  # object for convenience.
+  #
+  #
+  class TimedMetric < Metric
+    # holds all the statistics
+    attr_reader :stats
+
+    class << TimedMetric
+      #
+      # :call-seq:
+      #   TimedMetric.now -> TimedMetric
+      #
+      # Return a TimedMetric that has been started
+      #
+      def now( name, additional_data = {} )
+        t = TimedMetric.new( name, additional_data )
+        t.start
+        return t
+      end
+    end
+
+    #
+    # :call-seq:
+    #   TimedMetric.new( 'name') -> TimedMetric
+    #   TimedMetric.new( 'name', 'other' => 'data') -> TimedMetric
+    #
+    # 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 )
+      @stats            = Stats.new
+      @current_interval = nil
+    end
+
+    #
+    # :call-seq:
+    #   timed_metric.current_interval -> Interval
+    #
+    # Return the current interval, if one doesn't exist create one.
+    #
+    def current_interval
+      @current_interval ||= Interval.new
+    end
+
+    #
+    # :call-seq:
+    #   timed_metric.running? -> true or false
+    #
+    # 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.  
+    #
+    def start
+      current_interval.start unless running?
+      @sampling_start_time ||= self.utc_microseconds() 
+      nil
+    end
+
+    #
+    # :call-seq:
+    #   timed_metric.stop -> Float or nil
+    #
+    # Stop the current metric.  This updates the stats and removes the current
+    # 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 running? then
+        d = current_interval.stop
+        @current_interval = nil
+        @sampling_stop_time = self.utc_microseconds()
+        @stats.update( d )
+        return d
+      end
+      return false
+    end
+
+    #
+    # :call-seq:
+    #   timed_metric.measure {  ... } -> Object
+    #
+    # 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 )
+      return_value = nil
+      begin
+        start
+        return_value = yield
+      ensure
+        stop
+      end
+      return return_value
+    end
+
+    #
+    # :call-seq:
+    #   timed_metric.split -> Float
+    #
+    # Split the current TimedMetric.  Essentially, mark a split time. This means
+    # stop the current interval and create a new interval, but make sure
+    # that the new interval lines up exactly, timewise, behind the previous
+    # interval.
+    #
+    # If the timer is running, then split returns the duration of the previous
+    # interval, i.e. the split-time.  If the timer is not running, nothing
+    # happens and false is returned.
+    #
+    def split  
+      if running? then 
+        next_interval = current_interval.split
+        d = current_interval.duration
+        @stats.update( d )
+        @current_interval = next_interval 
+        return d
+      end 
+      return 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 ) 
+      end
+      return h
+    end
+
+
+    # forward appropriate calls directly to the stats object
+    extend Forwardable
+    def_delegators :@stats, :count, :sum, :max, :mean, :min, :rate, :stddev, :sum, :sumsq
+    alias :duration :sum
+  end
+end