ultra_marathon 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 3d4509883d5029d7c4a4a1dae968fce358849c10
-  data.tar.gz: 10319093704148baaa01957b3d0016a1dcb14fd7
+  metadata.gz: 4dc515ceea5248b2ac05129ad6b2f5d074742819
+  data.tar.gz: e68e4458184d953024a5efe23083dfc4a3f9ba8c
 SHA512:
-  metadata.gz: 48e6c87b833a453bc4933847a612678a8e7f239d2f5642ef393a4ebdf05e1d0e330c0d57966ea27f2f6dbe0ac2041196e548d1ade29412e0a586ad81e5863c59
-  data.tar.gz: 4fab0f2cc7c61bc3f615459babc953c6fba3b9878ca6734a28efd791874d21eb7b0fe2ccf54c723476a7a78843a227b5288174175605efb6002f29ed58a67979
+  metadata.gz: 9c32534cc602929cfcc7b0d98d47f868e8838adc1de117ffe31a2f73e64bcd9b6679cf09af40daf8ec5e2b4bd9da86106c4fa05f02e8a350e536d606f4ef9d19
+  data.tar.gz: 932ebf6722c3e7fafe391b0e725eb2d2ef280b9187ccc365bf76ca39bc78d2100e5db415caa183de646ed2d9967f9a8c4b290b87203295af45666c299dd1bea1

data/README.md

@@ -18,7 +18,7 @@ running complex jobs. It is best inheirited to fully customize.
 A simple DSL, currently consisting of only the `run` command, are used to
 specify independent chunks of work. The first argument is the name of the run
 block. Omitted, this defaults to ':main', though names must be unique within a
-given Runner so for a runner with N run blocks, N - 1 must be manually named.
+given Runner. E.g. for a runner with N run blocks, N - 1 must be manually named.
 
 ```ruby
 class MailRunner < UltraMarathon::AbstractRunner
@@ -29,12 +29,19 @@ class MailRunner < UltraMarathon::AbstractRunner
   end
 
   # :eat run block
+  # Must be named because there is already a :main block (one without
+  # a name explicitly defined)
   run :eat do
     add_butter
     add_syrup
     eat!
   end
 
+  # Will throw an error, since the first runner is implicitly named :main
+  run :main do
+    puts 'nope nope nope!'
+  end
+
   # Omitted for brevity
   def add_butter; end
   def add_syrup; end
@@ -137,6 +144,19 @@ class MercurialRunner < UltraMarathon::AbstractRunner
 end
 ```
 
+### Instrumentation
+
+The entire `run!` is instrumented and logged automatically. Additionally,
+individual run blocks are instrumented and logged by default.
+
+You can also choose to not instrument a block:
+
+```ruby
+run :embarrassingly_slowly, instrument: false do
+  sleep(rand(10))
+end
+```
+
 ### Success, Failure, and Reseting
 
 If any part of a runner fails, either by raising an error or explicitly setting
@@ -144,8 +164,10 @@ If any part of a runner fails, either by raising an error or explicitly setting
 which rely on an unsuccessful run block will also be considered failed.
 
 A failed runner can be reset, which essentially changes the failed runners to
-being unrun and returns the success flag to true. It will then execute any
-`on_reset` callbacks before returning itself.
+being unrun and returns the success flag to true. Runners that have been
+successfully run _will not_ be rerun, though any failed dependencies will.
+
+The runner will then execute any `on_reset` callbacks before returning itself.
 
 ```ruby
 class WatRunner < UltraMarathon::AbstractRunner

data/lib/ultra_marathon/abstract_runner.rb

@@ -24,7 +24,7 @@ module UltraMarathon
         begin
           self.success = true
           invoke_before_run_callbacks
-          instrument { run_unrun_sub_runners }
+          instrument(:run_unrun_sub_runners) { run_unrun_sub_runners }
           self.success = failed_sub_runners.empty?
         rescue StandardError => error
           invoke_on_error_callbacks(error)
@@ -180,12 +180,13 @@ module UltraMarathon
     end
 
     def summary
+      run_instrumentation = instrumentations[:run_unrun_sub_runners]
       """
 
       Status: #{status}
-      Start Time: #{formatted_start_time}
-      End Time: #{formatted_end_time}
-      Total Time: #{formatted_total_time}
+      Run Start Time: #{run_instrumentation.formatted_start_time}
+      End Time: #{run_instrumentation.formatted_end_time}
+      Total Time: #{run_instrumentation.formatted_total_time}
 
       Successful SubRunners: #{successful_sub_runners.size}
       Failed SubRunners: #{failed_sub_runners.size}

data/lib/ultra_marathon/instrumentation.rb

@@ -1,49 +1,25 @@
+require 'ultra_marathon/instrumentation/profile'
+
 module UltraMarathon
   module Instrumentation
     TIME_FORMAT = "%02d:%02d:%02d"
-    attr_reader :start_time, :end_time
 
     ## Public Instance Methods
 
-    # returns the total time, in seconds
-    def total_time
-      (end_time - start_time).to_i
-    end
-
-    def formatted_total_time
-      duration = total_time
-      seconds = (duration % 60).floor
-      minutes = (duration / 60).floor
-      hours   = (duration / 3600).floor
-      sprintf(TIME_FORMAT, hours, minutes, seconds)
-    end
-
-    def formatted_start_time
-      format_time(start_time)
-    end
-
-    def formatted_end_time
-      format_time(end_time)
+    def instrumentations
+      @instrumentations ||= Hash.new
     end
 
     private
 
     ## Private Instance Methods
 
-    def format_time(time)
-      sprintf(TIME_FORMAT, time.hour, time.min, time.sec)
-    end
-
     # Instruments given block, setting its start time and end time
     # Returns the result of the block
-    def instrument(&block)
-      @start_time = Time.now
-      begin
-        return_value = yield
-      ensure
-        @end_time = Time.now
-      end
-      return_value
+    def instrument(name, &block)
+      profile = Profile.new(name, &block)
+      instrumentations[name] = profile
+      profile.call
     end
   end
 end

data/lib/ultra_marathon/instrumentation/profile.rb

@@ -0,0 +1,51 @@
+module UltraMarathon
+  module Instrumentation
+    class Profile
+      attr_reader :name, :instrument_block, :start_time, :end_time
+
+      ## Public Instance Methods
+
+      def initialize(name, &block)
+        @name = name
+        @instrument_block = block
+      end
+
+      def call
+        @start_time = Time.now
+        begin
+          return_value = instrument_block.call
+        ensure
+          @end_time = Time.now
+        end
+        return_value
+      end
+
+      # returns the total time, in seconds
+      def total_time
+        (end_time - start_time).to_i
+      end
+
+      def formatted_total_time
+        duration = total_time
+        seconds = (duration % 60).floor
+        minutes = (duration / 60).floor
+        hours   = (duration / 3600).floor
+        sprintf(TIME_FORMAT, hours, minutes, seconds)
+      end
+
+      def formatted_start_time
+        format_time(start_time)
+      end
+
+      def formatted_end_time
+        format_time(end_time)
+      end
+
+      ## Private Instance Methods
+
+      def format_time(time)
+        sprintf(TIME_FORMAT, time.hour, time.min, time.sec)
+      end
+    end
+  end
+end

data/lib/ultra_marathon/sub_runner.rb

@@ -1,11 +1,13 @@
 require 'set'
 require 'active_support/core_ext/proc'
 require 'ultra_marathon/callbacks'
+require 'ultra_marathon/instrumentation'
 require 'ultra_marathon/logging'
 
 module UltraMarathon
   class SubRunner
     include Callbacks
+    include Instrumentation
     include Logging
     attr_accessor :run_block, :success
     attr_reader :sub_context, :options, :name
@@ -22,18 +24,32 @@ module UltraMarathon
     # other class, but do other things (like log) in the context of this one.
     def initialize(options, run_block)
       @name = options[:name]
-      @options = options
+      @options = {
+        instrument: true
+      }.merge(options)
       @sub_context = SubContext.new(options[:context], run_block)
     end
 
     def run!
-      begin
-        self.success = true
-        run_sub_context
-      rescue StandardError => error
-        invoke_on_error_callbacks(error)
-      ensure
-        invoke_after_run_callbacks
+      instrument(:run) do
+        begin
+          self.success = true
+          run_sub_context
+        rescue StandardError => error
+          invoke_on_error_callbacks(error)
+        ensure
+          invoke_after_run_callbacks
+        end
+      end
+      log_instrumentation
+    end
+
+    def log_instrumentation
+      if options[:instrument]
+        run_profile = instrumentations[:run]
+        logger.info """
+        Total Time: #{run_profile.formatted_total_time}
+        """
       end
     end
 
@@ -76,9 +92,14 @@ module UltraMarathon
 
     def initialize(context, run_block)
       @context = context
+      @run_block = run_block
       # Ruby cannot marshal procs or lambdas, so we need to define a method.
       # Binding to self allows us to intercept logging calls.
-      define_singleton_method :call, &run_block.bind(self)
+      define_singleton_method(:call, &bound_block)
+    end
+
+    def bound_block
+      run_block.bind(self)
     end
 
     # If the original context responds, including private methods,

data/lib/ultra_marathon/version.rb

@@ -2,7 +2,7 @@ module UltraMarathon
   class Version
     MAJOR = 0 unless defined? MAJOR
     MINOR = 1 unless defined? MINOR
-    PATCH = 0 unless defined? PATCH
+    PATCH = 1 unless defined? PATCH
     PRE = nil unless defined? PRE
 
     class << self

data/spec/ultra_marathon/instrumentation/profile_spec.rb

@@ -0,0 +1,58 @@
+require 'spec_helper'
+describe UltraMarathon::Instrumentation::Profile do
+  let(:start_time) { Time.local(1991, 1, 31, 15, 15, 00) }
+  let(:end_time) { Time.local(1991, 1, 31, 16, 00, 20) }
+  let(:run_block) do
+    # This is going to be evaluated in context of the instance
+    # so we need to wrap in an IIF to access `end_time`
+    Proc.new do |end_time|
+      Proc.new do
+        Timecop.travel(end_time)
+        'Bubbles'
+      end
+    end.call(end_time)
+  end
+
+  let(:profile) { described_class.new(:speedy, &run_block) }
+
+  subject(:run) { profile.call }
+
+  before(:each) { Timecop.freeze(start_time) }
+  after(:each) { Timecop.return }
+
+  it 'should set its name' do
+    profile.name.should be :speedy
+  end
+
+  describe '#call' do
+    it 'should return the result of the block' do
+      run.should eq 'Bubbles'
+    end
+
+    it 'should set the start_time' do
+      run
+      profile.start_time.should eq start_time
+    end
+
+    it 'should set the end_time' do
+      run
+      profile.end_time.to_i.should eq end_time.to_i
+    end
+  end
+
+  describe 'total_time' do
+    before(:each) { run }
+
+    it 'should return the total seconds elapsed' do
+      profile.total_time.should eq 2720
+    end
+  end
+
+  describe '#formatted_total_time' do
+    before(:each) { run }
+
+    it 'should return the total time, formatted' do
+      profile.formatted_total_time.should eq '00:45:20'
+    end
+  end
+end

data/spec/ultra_marathon/instrumentation_spec.rb

@@ -6,65 +6,26 @@ describe UltraMarathon::Instrumentation do
       include UltraMarathon::Instrumentation
 
       def run(&block)
-        instrument { block.call }
+        instrument(:run) { block.call }
       end
     end
   end
 
   let(:test_instance) { test_class.new }
-  let(:start_time) { Time.local(1991, 1, 31, 15, 15, 00) }
-  let(:end_time) { Time.local(1991, 1, 31, 16, 00, 20) }
-  let(:run_block) do
-    # This is going to be evaluated in context of the instance
-    # so we need to wrap in an IIF to access `end_time`
-    Proc.new do |end_time|
-      Proc.new do
-        Timecop.travel(end_time)
-      end
-    end.call(end_time)
-  end
 
   subject(:run) { test_instance.run &run_block }
 
-  before(:each) { Timecop.freeze(start_time) }
-  after(:each) { Timecop.return }
-
   describe '#instrument' do
+    let(:run_block) { Proc.new { 'Bubbles!' } }
 
-    describe 'method signature' do
-      let(:run_block) { Proc.new { 'Bubbles!' } }
-
-      it 'should return the result of the passed in block' do
-        run.should eq 'Bubbles!'
-      end
+    it 'should return the result of the passed in block' do
+      run.should eq 'Bubbles!'
     end
 
-    describe 'setting instance variables' do
-      before(:each) { run }
-
-      it 'should set the start_time' do
-        test_instance.start_time.should eq start_time
-      end
-
-      it 'should set the end_time' do
-        test_instance.end_time.to_i.should eq end_time.to_i
-      end
-    end
-  end
-
-  describe 'total_time' do
-    before(:each) { run }
-
-    it 'should return the total seconds elapsed' do
-      test_instance.total_time.should eq 2720
-    end
-  end
-
-  describe '#formatted_total_time' do
-    before(:each) { run }
-
-    it 'should return the total time, formatted' do
-      test_instance.formatted_total_time.should eq '00:45:20'
+    it 'should add the instrumentation information to the #instrumentations hash' do
+      run
+      profile = test_instance.instrumentations[:run]
+      profile.should be_an UltraMarathon::Instrumentation::Profile
     end
   end
 end

data/spec/ultra_marathon/sub_runner_spec.rb

@@ -50,5 +50,22 @@ describe UltraMarathon::SubRunner do
         test_instance.logger.contents.should include 'Draws those who are willing, drags those who are not.'
       end
     end
+
+    describe 'instrumentation' do
+      it 'should log the total time' do
+        subject
+        test_instance.logger.contents.should include 'Total Time:'
+      end
+
+      describe 'when instrument: false is set' do
+        let(:options) do
+          { context: context, name: name, instrument: false }
+        end
+
+        it 'should not log total time' do
+          test_instance.logger.contents.should_not include 'Total Time:'
+        end
+      end
+    end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ultra_marathon
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Chris Maddox
@@ -22,6 +22,7 @@ files:
 - lib/ultra_marathon/abstract_runner.rb
 - lib/ultra_marathon/callbacks.rb
 - lib/ultra_marathon/instrumentation.rb
+- lib/ultra_marathon/instrumentation/profile.rb
 - lib/ultra_marathon/logger.rb
 - lib/ultra_marathon/logging.rb
 - lib/ultra_marathon/store.rb
@@ -32,6 +33,7 @@ files:
 - spec/support/test_helpers.rb
 - spec/ultra_marathon/abstract_runner_spec.rb
 - spec/ultra_marathon/callbacks_spec.rb
+- spec/ultra_marathon/instrumentation/profile_spec.rb
 - spec/ultra_marathon/instrumentation_spec.rb
 - spec/ultra_marathon/logging_spec.rb
 - spec/ultra_marathon/store_spec.rb
@@ -67,6 +69,7 @@ test_files:
 - spec/support/test_helpers.rb
 - spec/ultra_marathon/abstract_runner_spec.rb
 - spec/ultra_marathon/callbacks_spec.rb
+- spec/ultra_marathon/instrumentation/profile_spec.rb
 - spec/ultra_marathon/instrumentation_spec.rb
 - spec/ultra_marathon/logging_spec.rb
 - spec/ultra_marathon/store_spec.rb