hitimes 1.3.1 → 2.0.0

data/lib/hitimes/mutexed_stats.rb

@@ -11,22 +11,7 @@ module Hitimes
   # 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/stats.rb

@@ -4,11 +4,109 @@
 #++
 
 require 'stringio'
+require 'thread'
 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 ]
 
+    attr_reader :min
+    attr_reader :max
+    attr_reader :count
+    attr_reader :sum
+    attr_reader :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
+
+      return 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?
+      return @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?
+      return @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
@@ -53,6 +151,5 @@ module Hitimes
       s.print "}"
       return s.string
     end
-
   end
 end

data/lib/hitimes/version.rb

@@ -4,5 +4,5 @@
 #++
 
 module Hitimes
-  VERSION = "1.3.1"
+  VERSION = "2.0.0"
 end

data/spec/hitimes_spec.rb

@@ -5,20 +5,20 @@ describe Hitimes do
     d = Hitimes.measure do
       sleep 0.2
     end
-    d.must_be_close_to(0.2, 0.002)
+    _(d).must_be_close_to(0.2, 0.002)
   end
 
   it "raises an error if measure is called with no block" do
-    lambda{ Hitimes.measure }.must_raise( Hitimes::Error )
+    _(lambda{ Hitimes.measure }).must_raise( Hitimes::Error )
   end
 
   it "has the raw instant value" do
     v = Hitimes.raw_instant
-    v.must_be :>, 0
+    _(v).must_be :>, 0
   end
 
   it "has access to the instant conversion factor" do
     f = Hitimes::INSTANT_CONVERSION_FACTOR
-    f.must_be :>, 0
+    _(f).must_be :>, 0
   end
 end

data/spec/interval_spec.rb

@@ -3,54 +3,54 @@ require "spec_helper"
 describe Hitimes::Interval do
   it "raises an error if duration is called on a non-started interval" do
     i = Hitimes::Interval.new
-    lambda{ i.duration }.must_raise( Hitimes::Error, /\AAttempt to report a duration on an interval that has not started\Z/ )
+    _(lambda{ i.duration }).must_raise( Hitimes::Error, /\AAttempt to report a duration on an interval that has not started\Z/ )
   end
 
   it "raises an error if stop is called on a non-started interval" do
     i = Hitimes::Interval.new
-    lambda { i.stop }.must_raise( Hitimes::Error, /\AAttempt to stop an interval that has not started\Z/ )
+    _(lambda { i.stop }).must_raise( Hitimes::Error, /\AAttempt to stop an interval that has not started\Z/ )
   end
 
   it "knows if it has been started" do
     i = Hitimes::Interval.new
-    i.started?.must_equal false
+    _(i.started?).must_equal false
 
     i.start
-    i.started?.must_equal true
+    _(i.started?).must_equal true
   end
 
   it "knows if it has been stopped" do
     i = Hitimes::Interval.new
     i.start
-    i.stopped?.must_equal false
+    _(i.stopped?).must_equal false
     i.stop
-    i.stopped?.must_equal true
+    _(i.stopped?).must_equal true
   end
 
   it "knows if it is currently running" do
     i = Hitimes::Interval.new
-    i.running?.must_equal false
+    _(i.running?).must_equal false
     i.start
-    i.running?.must_equal true
+    _(i.running?).must_equal true
     i.stop
-    i.running?.must_equal false
+    _(i.running?).must_equal false
   end
 
   it "can time a block of code" do
     d = Hitimes::Interval.measure do
       sleep 0.2
     end
-    d.must_be_close_to(0.2, 0.002)
+    _(d).must_be_close_to(0.2, 0.002)
   end
 
   it "raises an error if measure is called with no block" do
-    lambda{ Hitimes::Interval.measure }.must_raise( Hitimes::Error, /\ANo block given to Interval.measure\Z/ )
+    _(lambda{ Hitimes::Interval.measure }).must_raise( Hitimes::Error, /\ANo block given to Interval.measure\Z/ )
   end
 
   it "creates an interval via #now" do
     i = Hitimes::Interval.now
-    i.started?.must_equal true
-    i.stopped?.must_equal false
+    _(i.started?).must_equal true
+    _(i.stopped?).must_equal false
   end
 
   it "calling duration multiple times returns successivly grater durations" do
@@ -58,33 +58,33 @@ describe Hitimes::Interval do
     i.start
     y = i.duration
     z = i.duration
-    z.must_be :>, y
+    _(z).must_be :>, y
   end
 
   it "calling start multiple times on has no effect after the first call" do
     i = Hitimes::Interval.new
-    i.start.must_equal true
+    _(i.start).must_equal true
     x = i.start_instant
-    i.start_instant.must_be :>, 0
-    i.start.must_equal false
-    x.must_equal i.start_instant
+    _(i.start_instant).must_be :>, 0
+    _(i.start).must_equal false
+    _(x).must_equal i.start_instant
   end
 
   it "returns the duration on the first call to stop" do
     i = Hitimes::Interval.now
     d = i.stop
-    d.must_be_instance_of( Float )
+    _(d).must_be_instance_of( Float )
   end
 
   it "calling stop multiple times on has no effect after the first call" do
     i = Hitimes::Interval.new
-    i.start.must_equal true
+    _(i.start).must_equal true
     i.stop
 
     x = i.stop_instant
-    i.stop_instant.must_be :>, 0
-    i.stop.must_equal false
-    x.must_equal i.stop_instant
+    _(i.stop_instant).must_be :>, 0
+    _(i.stop).must_equal false
+    _(x).must_equal i.stop_instant
 
   end
 
@@ -93,26 +93,26 @@ describe Hitimes::Interval do
     i.start
     x = i.stop
     y = i.duration
-    i.stop.must_equal false
+    _(i.stop).must_equal false
 
     z = i.duration
 
-    x.must_equal y
-    x.must_equal z
+    _(x).must_equal y
+    _(x).must_equal z
 
-    y.must_equal z
+    _(y).must_equal z
   end
 
   it "can return how much time has elapsed from the start without stopping the interval" do
     i = Hitimes::Interval.new
     i.start
     x = i.duration_so_far
-    i.running?.must_equal true
+    _(i.running?).must_equal true
     y = i.duration_so_far
     i.stop
-    x.must_be :<, y
-    x.must_be :<, i.duration
-    y.must_be :<, i.duration
+    _(x).must_be :<, y
+    _(x).must_be :<, i.duration
+    _(y).must_be :<, i.duration
   end
 
   describe "#split" do
@@ -121,14 +121,14 @@ describe Hitimes::Interval do
       i = Hitimes::Interval.new
       i.start
       i2 = i.split
-      i.object_id.wont_equal i2.object_id
+      _(i.object_id).wont_equal i2.object_id
     end
 
     it "with the stop instant equivialent to the previous Interval's start instant" do
       i = Hitimes::Interval.new
       i.start
       i2 = i.split
-      i.stop_instant.must_equal i2.start_instant
+      _(i.stop_instant).must_equal i2.start_instant
     end
   end
 

data/spec/metric_spec.rb

@@ -6,22 +6,22 @@ describe Hitimes::Metric do
   end
 
   it 'has a name' do
-    @metric.name.must_equal "testing"
+    _(@metric.name).must_equal "testing"
   end
 
   it "has associated data from initialization" do
     m = Hitimes::Metric.new( "more-data", 'foo' => 'bar', 'this' => 'that' )
-    m.additional_data['foo'].must_equal 'bar'
-    m.additional_data['this'].must_equal 'that'
+    _(m.additional_data['foo']).must_equal 'bar'
+    _(m.additional_data['this']).must_equal 'that'
     
     m = Hitimes::Metric.new( "more-data", { 'foo' => 'bar', 'this' => 'that' } )
-    m.additional_data['foo'].must_equal 'bar'
-    m.additional_data['this'].must_equal 'that'
+    _(m.additional_data['foo']).must_equal 'bar'
+    _(m.additional_data['this']).must_equal 'that'
   end
 
   it "initially has no sampling times" do
-    @metric.sampling_start_time.must_be_nil
-    @metric.sampling_stop_time.must_be_nil
+    _(@metric.sampling_start_time).must_be_nil
+    _(@metric.sampling_stop_time).must_be_nil
   end
 end
 

data/spec/mutex_stats_spec.rb

@@ -16,21 +16,14 @@ describe Hitimes::MutexedStats do
     return stats
   end
 
-  if (not defined? RUBY_ENGINE) or (RUBY_ENGINE == "ruby") then
-    it "Hitimes::Stats is threadsafe" do
-      stats = run_with_scissors( ::Hitimes::Stats.new, @threads, @iters )
-      stats.count.must_equal @final_value
-    end
-  else
-    it "Hitimes::Stats is not threadsafe" do
-      stats = run_with_scissors( ::Hitimes::Stats.new, @threads, @iters )
-      stats.count.wont_equal @final_value
-    end
+  it "Hitimes::Stats is threadsafe" do
+    stats = run_with_scissors( ::Hitimes::Stats.new, @threads, @iters )
+    _(stats.count).must_equal @final_value
   end
 
   it "has a threadsafe update" do
     stats = run_with_scissors( ::Hitimes::MutexedStats.new, @threads, @iters )
-    stats.count.must_equal @final_value
+    _(stats.count).must_equal @final_value
   end
 
 end

data/spec/paths_spec.rb

@@ -2,10 +2,10 @@ require 'spec_helper'
 
 describe Hitimes::Paths do
   it "can access the root dir of the project" do
-    Hitimes::Paths.root_dir.must_equal File.expand_path( File.join( File.dirname( __FILE__ ), ".." ) ) + ::File::SEPARATOR
+    _(Hitimes::Paths.root_dir).must_equal File.expand_path( File.join( File.dirname( __FILE__ ), ".." ) ) + ::File::SEPARATOR
   end
 
   it "can access the lib path of the project" do
-    Hitimes::Paths.lib_path.must_equal File.expand_path( File.join( File.dirname( __FILE__ ), "..", "lib" ) ) + ::File::SEPARATOR
+    _(Hitimes::Paths.lib_path).must_equal File.expand_path( File.join( File.dirname( __FILE__ ), "..", "lib" ) ) + ::File::SEPARATOR
   end
 end

data/spec/stats_spec.rb

@@ -9,65 +9,65 @@ describe Hitimes::Stats do
     [ 1, 2, 3].each { |i| @full_stats.update( i ) }
   end
 
-  it "is initialized with 0 values" do
-    @stats.count.must_equal 0
-    @stats.min.must_equal 0.0
-    @stats.max.must_equal 0.0
-    @stats.sum.must_equal 0.0
-    @stats.rate.must_equal 0.0
+  it "is initialized with usable values" do
+    _(@stats.count).must_equal 0
+    _(@stats.min).must_equal Float::INFINITY
+    _(@stats.max).must_equal(-Float::INFINITY)
+    _(@stats.sum).must_equal 0.0
+    _(@stats.rate).must_equal 0.0
   end
 
   it "calculates the mean correctly" do
-    @full_stats.mean.must_equal 2.0
+    _(@full_stats.mean).must_equal 2.0
   end
 
   it "calculates the rate correctly" do
-    @full_stats.rate.must_equal 0.5
+    _(@full_stats.rate).must_equal 0.5
   end
 
   it "tracks the maximum value" do
-    @full_stats.max.must_equal 3.0
+    _(@full_stats.max).must_equal 3.0
   end
 
   it "tracks the minimum value" do
-    @full_stats.min.must_equal 1.0
+    _(@full_stats.min).must_equal 1.0
   end
 
   it "tracks the count" do
-    @full_stats.count.must_equal 3
+    _(@full_stats.count).must_equal 3
   end
   
   it "tracks the sum" do
-    @full_stats.sum.must_equal 6.0
+    _(@full_stats.sum).must_equal 6.0
   end
 
   it "calculates the standard deviation" do
-    @full_stats.stddev.must_equal 1.0
+    _(@full_stats.stddev).must_equal 1.0
   end 
 
   it "calculates the sum of squares " do
-    @full_stats.sumsq.must_equal 14.0
+    _(@full_stats.sumsq).must_equal 14.0
   end 
 
   describe "#to_hash " do
     it "converts to a Hash" do
       h = @full_stats.to_hash
-      h.size.must_equal ::Hitimes::Stats::STATS.size
-      h.keys.sort.must_equal ::Hitimes::Stats::STATS
+      _(h.size).must_equal ::Hitimes::Stats::STATS.size
+      _(h.keys.sort).must_equal ::Hitimes::Stats::STATS
     end
 
     it "converts to a limited Hash if given arguments" do
       h = @full_stats.to_hash( "min", "max", "mean" )
-      h.size.must_equal 3
-      h.keys.sort.must_equal %w[ max mean min  ]
+      _(h.size).must_equal 3
+      _(h.keys.sort).must_equal %w[ max mean min  ]
 
       h = @full_stats.to_hash( %w[ count rate ] )
-      h.size.must_equal 2
-      h.keys.sort.must_equal %w[ count rate ]
+      _(h.size).must_equal 2
+      _(h.keys.sort).must_equal %w[ count rate ]
     end
 
     it "raises NoMethodError if an invalid stat is used" do
-      lambda { @full_stats.to_hash( "wibble" ) }.must_raise( NoMethodError )
+      _(lambda { @full_stats.to_hash( "wibble" ) }).must_raise( NoMethodError )
     end
   end
 
@@ -75,24 +75,24 @@ describe Hitimes::Stats do
     it "converts to a json string" do
       j = @full_stats.to_json
       h = JSON.parse( j )
-      h.size.must_equal ::Hitimes::Stats::STATS.size
-      h.keys.sort.must_equal ::Hitimes::Stats::STATS
+      _(h.size).must_equal ::Hitimes::Stats::STATS.size
+      _(h.keys.sort).must_equal ::Hitimes::Stats::STATS
     end
 
     it "converts to a limited Hash if given arguments" do
       j = @full_stats.to_json( "min", "max", "mean" )
       h = JSON.parse( j )
-      h.size.must_equal 3
-      h.keys.sort.must_equal %w[ max mean min  ]
+      _(h.size).must_equal 3
+      _(h.keys.sort).must_equal %w[ max mean min  ]
 
       j = @full_stats.to_json( %w[ count rate ] )
       h = JSON.parse( j )
-      h.size.must_equal 2
-      h.keys.sort.must_equal %w[ count rate ]
+      _(h.size).must_equal 2
+      _(h.keys.sort).must_equal %w[ count rate ]
     end
 
     it "raises NoMethodError if an invalid stat is used" do
-      lambda { @full_stats.to_json( "wibble" ) }.must_raise( NoMethodError )
+      _(lambda { @full_stats.to_json( "wibble" ) }).must_raise( NoMethodError )
     end
   end
 end