ztk 2.3.1 → 2.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: b8e1ebec45b236ad05a903e06863a0d6579a60d0
-  data.tar.gz: 44b923bde167cd85317add07f1a2a42f9657563e
+  metadata.gz: fbbba71c8a07c8110549bfcee7445288c8ed3172
+  data.tar.gz: 8c725fa5f1de381ce76f668e52c7735d87a1429f
 SHA512:
-  metadata.gz: 3985319ebe5dab0ade521e48fcd4a1d108f74f11d639aa6c9e2bd77d2ecb8b2599d14002108be5faf602f538887484ef999432eef20235642ad47b9b395623b2
-  data.tar.gz: ecedf4dd5f8777404e151a4753e350c1e6bdd029b86882a4ad498dcb0be478ae762a81858a7dff727107fa21597000229e48783c988fbdbc2f6558408d97c9c7
+  metadata.gz: 4ebd5505c5e8607536a054788d545432011aae08f3243cf9614e9c87c17567009784f014d6dbbc0141e0f117dab5ea3fa0b88dc93f0ed6163a5b280cb81d4de1
+  data.tar.gz: 96e9aa8493a4336e5723df3f3f6aed28856108cef55f16c76208cea07cff583895e92ed122d3125c3bc50276806678a957c3250a03747516b301d3507c71ce6f

data/README.md

@@ -44,6 +44,10 @@ Zachary's Tool Kit contains a collection of reusable classes meant to simplify d
 
   Easily turn linear iterative tasks into parallel tasks and leverage multiple cores to speed up processing of your large sets of data.  Read more at the [ZTK::Parallel](http://zpatten.github.io/ztk/ZTK/Parallel.html) documentation.
 
+- **ZTK::Profiler**
+
+  Build timing profiles easily with this class.  Allows for arbitrary nesting of profiles and provides full reporting.  Read more at the [ZTK::Profiler](http://zpatten.github.io/ztk/ZTK/Profiler.html) documentation.
+
 - **ZTK::Report**
 
   Console based reporting class which allows you to easily output either list or spreadsheet based reports from sets of data.  Read more at the [ZTK::Report](http://zpatten.github.io/ztk/ZTK/Report.html) documentation.

data/lib/ztk.rb

@@ -26,6 +26,7 @@ module ZTK
   require 'ztk/locator'
   require 'ztk/logger'
   require 'ztk/parallel'
+  require 'ztk/profiler'
   require 'ztk/pty'
   require 'ztk/report'
   require 'ztk/rescue_retry'

data/lib/ztk/logger.rb

@@ -18,7 +18,7 @@ module ZTK
   # use this library like so:
   #     LOG_LEVEL=DEBUG bin/cucumber-chef ssh
   #
-  # = Typical usage:
+  # *Typical usage*:
   #
   #     $logger = ZTK::Logger.new("/dev/null")
   #
@@ -28,7 +28,7 @@ module ZTK
   #     $logger.error { "This is a error message!" }
   #     $logger.fatal { "This is a fatal message!" }
   #
-  # = Simple logger chain:
+  # *Simple logger chain*:
   #
   #     logger = ZTK::Logger.new
   #     logger.loggers << ::Logger.new(STDOUT)
@@ -36,7 +36,7 @@ module ZTK
   #
   #     logger.debug { "This will be written to STDOUT as well as test.log!" }
   #
-  # = Alternate logger chaining:
+  # *Alternate logger chaining*:
   #
   #     logger = ZTK::Logger.new(STDOUT)
   #     logger.loggers << ::Logger.new('test.log')

data/lib/ztk/profiler.rb

@@ -0,0 +1,110 @@
+require 'benchmark'
+
+module ZTK
+
+  # Profiler Error Class
+  #
+  # @author Zachary Patten <zachary AT jovelabs DOT com>
+  class ProfilerError < Error; end
+
+  # Profiler Class
+  #
+  # A comprehensive timing profiler, this class functions using method_missing
+  # to allow the consumer to define timing profiles in an ad hoc manner using
+  # a block.
+  #
+  # *Example Code*:
+  #
+  #     ZTK::Profiler.reset
+  #
+  #     ZTK::Profiler.operation_alpha do
+  #       ZTK::Profiler.operation_one do
+  #         ZTK::Profiler.operation_a do
+  #           sleep(0.1)
+  #         end
+  #         ZTK::Profiler.operation_b do
+  #           sleep(0.1)
+  #         end
+  #         ZTK::Profiler.operation_c do
+  #           sleep(0.1)
+  #         end
+  #       end
+  #       ZTK::Profiler.operation_two do
+  #         ZTK::Profiler.operation_d do
+  #           sleep(0.1)
+  #         end
+  #         ZTK::Profiler.operation_e do
+  #           sleep(0.1)
+  #         end
+  #         ZTK::Profiler.operation_f do
+  #           sleep(0.1)
+  #         end
+  #       end
+  #     end
+  #     ZTK::Profiler.operation_beta do
+  #       ZTK::Profiler.operation_three do
+  #         ZTK::Profiler.operation_a do
+  #           sleep(0.1)
+  #         end
+  #         ZTK::Profiler.operation_b do
+  #           sleep(0.1)
+  #         end
+  #         ZTK::Profiler.operation_c do
+  #           sleep(0.1)
+  #         end
+  #       end
+  #     end
+  #
+  #     ZTK::Profiler.report
+  #
+  # *Example Output*:
+  #
+  #     --+ OperationAlpha 0.6070s
+  #       |--+ OperationOne 0.3035s
+  #       |  |--+ OperationA 0.1011s
+  #       |  |--+ OperationB 0.1011s
+  #       |  |--+ OperationC 0.1011s
+  #       |--+ OperationTwo 0.3035s
+  #       |  |--+ OperationD 0.1011s
+  #       |  |--+ OperationE 0.1011s
+  #       |  |--+ OperationF 0.1011s
+  #     --+ OperationBeta 0.3034s
+  #       |--+ OperationThree 0.3034s
+  #       |  |--+ OperationA 0.1011s
+  #       |  |--+ OperationB 0.1011s
+  #       |  |--+ OperationC 0.1011s
+  #
+  #      OperationAlpha: 0.6070s (22.2%)
+  #        OperationOne: 0.3035s (11.1%)
+  #          OperationA: 0.2022s (7.4%)
+  #          OperationB: 0.2022s (7.4%)
+  #          OperationC: 0.2022s (7.4%)
+  #        OperationTwo: 0.3035s (11.1%)
+  #          OperationD: 0.1011s (3.7%)
+  #          OperationE: 0.1011s (3.7%)
+  #          OperationF: 0.1011s (3.7%)
+  #       OperationBeta: 0.3034s (11.1%)
+  #      OperationThree: 0.3034s (11.1%)
+  #
+  #        Nested Time: 2.7306s
+  #        Actual Time: 0.9110s
+  #      Profiled Time: 0.9105s
+  #       Missing Time: 0.0005s
+  #
+  # @author Zachary Patten <zachary AT jovelabs DOT com>
+  class Profiler
+
+    require 'ztk/profiler/core'
+    require 'ztk/profiler/private'
+    require 'ztk/profiler/timer'
+
+    extend ZTK::Profiler::Core
+
+  private
+
+    extend ZTK::Profiler::Private
+
+  end
+
+end
+

data/lib/ztk/profiler/core.rb

@@ -0,0 +1,74 @@
+module ZTK
+  class Profiler
+
+    # Profiler Core Functionality
+    module Core
+      require 'ztk/ui'
+
+      @@start_time  ||= nil
+      @@end_time    ||= nil
+      @@timer_stack ||= Array.new
+
+      def start
+        reset
+
+        true
+      end
+
+      def stop
+        @@end_time ||= Time.now.utc
+
+        true
+      end
+
+      def reset
+        @@start_time  = Time.now.utc
+        @@end_time    = nil
+        @@timer_stack = Array.new
+        Timer.reset
+
+        true
+      end
+
+      def method_missing(method_name, *method_args)
+        raise "You must supply a block to the profiler method #{method_name.inspect}!" unless block_given?
+
+        @@start_time ||= Time.now.utc
+
+        result = nil
+        timer  = Timer.new(method_name, @@timer_stack.last)
+
+        @@timer_stack.push(timer)
+        timer.benchmark = ::Benchmark.realtime do
+          result = yield
+        end
+        @@timer_stack.pop
+
+        result
+      end
+
+      def total_time
+        stop
+        @@end_time - @@start_time
+      end
+
+      def report(options={})
+        options = Base.build_config({}, options)
+
+        stop
+
+        results = Array.new
+
+        report_timers(options)
+        options.ui.stdout.puts
+        results << report_timer_totals(options)
+        options.ui.stdout.puts
+        results << report_totals(options)
+
+        results
+      end
+
+    end
+
+  end
+end

data/lib/ztk/profiler/private.rb

@@ -0,0 +1,52 @@
+module ZTK
+  class Profiler
+
+    # Profiler Private Functionality
+    module Private
+
+      def report_timers(options={}, parent=nil, depth=0)
+        child_timers = Timer.timers_by_parent[parent]
+        child_timers.each do |timer|
+          prefix = ('  |' * (depth))
+
+          options.ui.stdout.print("%s--+ %s %0.4fs\n" % [ prefix, timer.name.to_s.camelize, timer.benchmark ])
+
+          report_timers(options, timer, (depth + 1))
+        end
+
+        true
+      end
+
+      def report_timer_totals(options={})
+        result                = Hash.new
+        timer_names           = Timer.timers_by_name.keys.compact
+        timer_names_camelize  = timer_names.map(&:to_s).map(&:camelize)
+        max_timer_name_length = (timer_names_camelize.map(&:length).max + 1)
+        timer_names.each do |timer_name|
+          benchmark_nested   = Timer.timers_by_name[timer_name].map(&:benchmark_nested).reduce(&:+)
+          result[timer_name] = benchmark_nested
+
+          options.ui.stdout.print("%#{max_timer_name_length}s: %0.4fs (%-3.1f%%)\n" % [timer_name.to_s.camelize, benchmark_nested, (benchmark_nested / Timer.benchmark_nested_total) * 100])
+        end
+        result
+      end
+
+      def report_totals(options={})
+        times = {
+          'Nested Time'   => Timer.benchmark_nested_total,
+          'Actual Time'   => Profiler.total_time,
+          'Profiled Time' => Timer.total_time,
+          'Missing Time'  => (Profiler.total_time - Timer.total_time)
+        }
+        max_key_length = (times.keys.map(&:length).max + 1)
+        time_format    = "%#{max_key_length}s: %0.4fs\n"
+
+        times.each do |name, time|
+          options.ui.stdout.print(time_format % [ name, time ])
+        end
+      end
+
+    end
+
+  end
+end

data/lib/ztk/profiler/timer.rb

@@ -0,0 +1,33 @@
+module ZTK
+  class Profiler
+
+    # Profiler Timer Functionality
+    class Timer
+      require 'ztk/profiler/timer/class_methods'
+
+      extend ZTK::Profiler::Timer::ClassMethods
+
+      attr_accessor :name
+      attr_accessor :parent
+      attr_accessor :benchmark
+
+      def initialize(name, parent=nil)
+        self.name   = name
+        self.parent = parent
+
+        self.class.add(self)
+      end
+
+      def nested_time
+        @nested_time ||= self.class.nested_time(self.name, self)
+        @nested_time
+      end
+
+      def benchmark_nested
+        (self.benchmark - self.nested_time)
+      end
+
+    end
+
+  end
+end

data/lib/ztk/profiler/timer/class_methods.rb

@@ -0,0 +1,76 @@
+module ZTK
+  class Profiler
+    class Timer
+
+      # Profiler Timer Class Functionality
+      module ClassMethods
+
+        @@timers                 ||= Array.new
+        @@timers_by_name         ||= Hash.new { |hash, key| hash[key] = Array.new }
+        @@timers_by_parent       ||= Hash.new { |hash, key| hash[key] = Array.new }
+        @@benchmark_total        ||= nil
+        @@benchmark_nested_total ||= nil
+
+        def timers
+          @@timers
+        end
+
+        def timers_by_parent
+          @@timers_by_parent
+        end
+
+        def timers_by_name
+          @@timers_by_name
+        end
+
+        def add(timer)
+          @@timers << timer
+
+          @@timers_by_parent[timer.parent] << timer
+          @@timers_by_name[timer.name] << timer
+
+          true
+        end
+
+        def reset
+          @@timers           = Array.new
+          @@timers_by_name   = Hash.new { |hash, key| hash[key] = Array.new }
+          @@timers_by_parent = Hash.new { |hash, key| hash[key] = Array.new }
+
+          true
+        end
+
+        def nested_time(name=nil, parent=nil)
+          result = 0.0
+
+          child_timers = @@timers_by_parent[parent]
+          child_timers.each do |child_timer|
+            if (child_timer.name == name)
+              result += child_timer.benchmark_nested
+            end
+            result += nested_time(name, child_timer)
+          end
+
+          result
+        end
+
+        def benchmark_total
+          @@benchmark_total ||= @@timers.map(&:benchmark).reduce(&:+)
+          @@benchmark_total
+        end
+
+        def benchmark_nested_total
+          @@benchmark_nested_total ||= @@timers.map(&:benchmark_nested).reduce(&:+)
+          @@benchmark_nested_total
+        end
+
+        def total_time
+          @@total_time ||= @@timers_by_parent[nil].map(&:benchmark).reduce(&:+)
+          @@total_time
+        end
+
+      end
+
+    end
+  end
+end

data/lib/ztk/version.rb

@@ -1,6 +1,6 @@
 module ZTK
 
   # ZTK Version String
-  VERSION = "2.3.1"
+  VERSION = "2.4.0"
 
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ztk
 version: !ruby/object:Gem::Version
-  version: 2.3.1
+  version: 2.4.0
 platform: ruby
 authors:
 - Zachary Patten
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-07-25 00:00:00.000000000 Z
+date: 2014-10-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -315,6 +315,11 @@ files:
 - lib/ztk/locator.rb
 - lib/ztk/logger.rb
 - lib/ztk/parallel.rb
+- lib/ztk/profiler.rb
+- lib/ztk/profiler/core.rb
+- lib/ztk/profiler/private.rb
+- lib/ztk/profiler/timer.rb
+- lib/ztk/profiler/timer/class_methods.rb
 - lib/ztk/pty.rb
 - lib/ztk/rake/docs.rb
 - lib/ztk/report.rb