hitimes 1.0.4-x86-mswin32

data/ext/hitimes/hitimes_stats.c

@@ -0,0 +1,269 @@
+/**
+ * Copyright (c) 2008 Jeremy Hinegardner
+ * All rights reserved.  See LICENSE and/or COPYING for details.
+ *
+ * vim: shiftwidth=4 
+ */ 
+
+#include "hitimes_stats.h"
+
+/* classes defined here */
+VALUE cH_Stats;         /* Hitimes::Stats */
+
+/**
+ * Allocator and Deallocator for Stats classes
+ */
+
+VALUE hitimes_stats_free(hitimes_stats_t* s) 
+{
+    xfree( s );
+    return Qnil;
+}
+
+VALUE hitimes_stats_alloc(VALUE klass)
+{
+    VALUE obj;
+    hitimes_stats_t* s = xmalloc( sizeof( hitimes_stats_t ) );
+
+    s->min = 0.0;
+    s->max = 0.0;
+    s->count = 0;
+    s->sum = 0.0;
+    s->sumsq = 0.0;
+
+    obj = Data_Wrap_Struct(klass, NULL, hitimes_stats_free, s);
+
+    return obj;
+}
+
+
+/**
+ * call-seq:
+ *    stat.update( val ) -> val
+ * 
+ * Update the running stats with the new value.
+ * Return the input value.
+ */
+VALUE hitimes_stats_update( VALUE self, VALUE v )
+{
+    long double      new_v;
+    hitimes_stats_t *stats;
+
+    Data_Get_Struct( self, hitimes_stats_t, stats );
+    new_v = NUM2DBL( v );
+
+    if ( 0 == stats->count ) {
+      stats->min = new_v;
+      stats->max = new_v;
+    } else {
+      stats->min = ( new_v < stats->min) ? ( new_v ) : ( stats->min );
+      stats->max = ( new_v > stats->max) ? ( new_v ) : ( stats->max );
+    }
+
+    stats->count += 1;
+    stats->sum   += new_v;
+    stats->sumsq += ( new_v * new_v );
+
+    return v;
+}
+
+/**
+ * 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;
+ */
+VALUE hitimes_stats_mean( VALUE self )
+{
+    hitimes_stats_t *stats;
+    long double      mean = 0.0;
+
+    Data_Get_Struct( self, hitimes_stats_t, stats );
+
+    if ( stats->count > 0 ) {
+      mean = stats->sum / stats->count ;
+    }
+
+    return rb_float_new( mean );
+}
+
+
+/**
+ * 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.
+ *
+ */
+VALUE hitimes_stats_rate( VALUE self )
+{
+    hitimes_stats_t *stats;
+    long double      rate = 0.0;
+
+    Data_Get_Struct( self, hitimes_stats_t, stats );
+
+    if ( stats->sum > 0.0 ) {
+      rate = stats->count / stats->sum;
+    }
+
+    return rb_float_new( rate );
+}
+
+
+/**
+ * call-seq:
+ *    stat.max -> Float
+ * 
+ * Return the maximum value that has passed through the Stats object
+ */
+VALUE hitimes_stats_max( VALUE self )
+{
+    hitimes_stats_t *stats;
+
+    Data_Get_Struct( self, hitimes_stats_t, stats );
+
+    return rb_float_new( stats->max );
+}
+
+
+
+/**
+ * call-seq:
+ *    stat.min  -> Float
+ * 
+ * Return the minimum value that has passed through the Stats object
+ */
+VALUE hitimes_stats_min( VALUE self )
+{
+    hitimes_stats_t *stats;
+
+    Data_Get_Struct( self, hitimes_stats_t, stats );
+
+    return rb_float_new( stats->min );
+}
+
+
+/**
+ * call-seq:
+ *    stat.count -> Integer
+ * 
+ * Return the number of values that have passed through the Stats object.
+ */
+VALUE hitimes_stats_count( VALUE self )
+{
+    hitimes_stats_t *stats;
+
+    Data_Get_Struct( self, hitimes_stats_t, stats );
+
+    return LONG2NUM( stats->count );
+}
+
+
+/**
+ * call-seq:
+ *    stat.sum -> Float
+ * 
+ * Return the sum of all the values that have passed through the Stats object.
+ */
+VALUE hitimes_stats_sum( VALUE self )
+{
+    hitimes_stats_t *stats;
+
+    Data_Get_Struct( self, hitimes_stats_t, stats );
+
+    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:
+ *    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;
+ */
+VALUE hitimes_stats_stddev ( VALUE self )
+{
+    hitimes_stats_t *stats;
+    long double     stddev = 0.0;
+
+    Data_Get_Struct( self, hitimes_stats_t, stats );
+    if ( stats->count > 1 ) {
+      stddev = sqrt( ( stats->sumsq - ( stats->sum * stats->sum  / stats->count ) ) / ( stats->count - 1 ) );
+    }
+
+    return rb_float_new( stddev );
+}
+
+
+/**
+ * Document-class: Hitimes::Stats
+ *
+ * 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
+ */
+void Init_hitimes_stats()
+{
+
+    mH = rb_define_module("Hitimes"); 
+
+    cH_Stats = rb_define_class_under( mH, "Stats", rb_cObject ); /* in hitimes_stats.c */
+    rb_define_alloc_func( cH_Stats, hitimes_stats_alloc );
+
+    rb_define_method( cH_Stats, "update", hitimes_stats_update, 1 ); /* in hitimes_stats.c */
+    
+    rb_define_method( cH_Stats, "count", hitimes_stats_count, 0 ); /* in hitimes_stats.c */
+    rb_define_method( cH_Stats, "max", hitimes_stats_max, 0 ); /* in hitimes_stats.c */
+    rb_define_method( cH_Stats, "mean", hitimes_stats_mean, 0 ); /* in hitimes_stats.c */
+    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/ext/hitimes/hitimes_stats.h

@@ -0,0 +1,30 @@
+/**
+ * Copyright (c) 2008 Jeremy Hinegardner
+ * All rights reserved.  See LICENSE and/or COPYING for details.
+ *
+ * vim: shiftwidth=4 
+ */ 
+
+#ifndef __HITIMES_STATS_H__
+#define __HITIMES_STATS_H__
+
+#include <ruby.h>
+#include <math.h>
+
+/* classes and modules defined elswhere */
+extern VALUE mH;        /* Hitimes */
+extern VALUE eH_Error;  /* Hitimes::Error */
+extern VALUE cH_Stats;  /* Hitimes::Stats */
+
+
+typedef struct hitimes_stats {
+    long double min;
+    long double max;
+    long double sum;
+    long double sumsq;
+    long long   count;
+} hitimes_stats_t;
+
+#endif
+
+

data/gemspec.rb

@@ -0,0 +1,60 @@
+require 'rubygems'
+require 'hitimes/version'
+require 'tasks/config'
+
+Hitimes::GEM_SPEC = Gem::Specification.new do |spec|
+  proj = Configuration.for('project')
+  spec.name         = proj.name
+  spec.version      = Hitimes::VERSION
+  
+  spec.author       = proj.author
+  spec.email        = proj.email
+  spec.homepage     = proj.homepage
+  spec.summary      = proj.summary
+  spec.description  = proj.description
+  spec.platform     = Gem::Platform::RUBY
+
+  
+  pkg = Configuration.for('packaging')
+  spec.files        = pkg.files.all
+  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_development_dependency( "json", "~> 1.1.3")
+  spec.add_development_dependency( "rake-compiler", "~> 0.5.0")
+
+  if ext_conf = Configuration.for_if_exist?("extension") then
+    spec.extensions <<  ext_conf.configs
+    spec.require_paths << 'ext'
+    spec.extensions.flatten!
+  end   
+
+  if rdoc = Configuration.for_if_exist?('rdoc') then
+    spec.has_rdoc         = true
+    spec.extra_rdoc_files = pkg.files.rdoc
+    spec.rdoc_options     = rdoc.options + [ "--main" , rdoc.main_page ]
+  else
+    spec.has_rdoc         = false
+  end 
+
+  if test = Configuration.for_if_exist?('testing') then
+    spec.test_files       = test.files
+  end 
+
+  if rf = Configuration.for_if_exist?('rubyforge') then
+    spec.rubyforge_project  = rf.project
+  end 
+end
+
+Hitimes::GEM_SPEC_MSWIN32 = Hitimes::GEM_SPEC.clone
+Hitimes::GEM_SPEC_MSWIN32.platform = ::Gem::Platform.new( "i386-mswin32" )
+Hitimes::GEM_SPEC_MSWIN32.extensions = []
+
+Hitimes::GEM_SPEC_MINGW32= Hitimes::GEM_SPEC.clone
+Hitimes::GEM_SPEC_MINGW32.platform = ::Gem::Platform.new( "i386-mingw32" )
+Hitimes::GEM_SPEC_MINGW32.extensions = []
+
+Hitimes::SPECS = [ Hitimes::GEM_SPEC, Hitimes::GEM_SPEC_MSWIN32, Hitimes::GEM_SPEC_MINGW32 ] 

data/lib/hitimes.rb

@@ -0,0 +1,31 @@
+#--
+# Copyright (c) 2008 Jeremy Hinegardner
+# All rights reserved.  See LICENSE and/or COPYING for details.
+#++
+
+#
+# The top level module containing the contents of the hitimes library
+#
+# use the library with:
+#
+#   require 'hitimes'
+#
+module Hitimes
+  #
+  # Base class of all errors in Hitimes
+  #
+  class Error < ::StandardError; end
+end
+require 'hitimes/paths'
+require 'hitimes/version'
+
+# use a version subdirectory for extensions, initially to support windows, but
+# why make a special case.  It doesn't hurt anyone to have an extra subdir.
+require "hitimes/#{RUBY_VERSION.sub(/\.\d$/,'')}/hitimes_ext"
+require 'hitimes/stats'
+require 'hitimes/mutexed_stats'
+require 'hitimes/metric'
+require 'hitimes/value_metric'
+require 'hitimes/timed_metric'
+require 'hitimes/timed_value_metric'
+

data/lib/hitimes/metric.rb

@@ -0,0 +1,112 @@
+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 number of seconds as a float since the sampling_start_time
+    attr_reader :sampling_delta
+
+    # 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_start_interval = nil
+      @sampling_delta          = 0
+
+      @name                = name.to_s
+      @additional_data     = additional_data.to_hash
+    end
+
+    #
+    # :call-seq: 
+    #   metric.sampling_start_time -> Float or nil
+    #
+    # The time at which the first sample was taken.
+    # This is the number of microseconds since UNIX epoch UTC as a Float
+    #
+    # 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
+    end
+
+    #
+    # :call-seq:
+    #   metric.sampling_stop_time -> Float or nil
+    #
+    # 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 
+    # stop time is nil.
+    #
+    # Because accessing the actual 'time of day' is an expesive operation, we
+    # only get the time of day at the beginning of the first measurement and we
+    # keep track of the offset from that point in @sampling_delta.
+    #
+    # 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
+    end
+
+    #
+    # :call-seq:
+    #    metric.to_hash -> Hash
+    #    metric.to_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 }
+    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