ultra_marathon 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: b8225719b7d1b1c43162a163d33bc7c3ebf03be5
+  data.tar.gz: f194c974595a922b4f33d7dc9666e70869e07f98
+SHA512:
+  metadata.gz: c945bed22739aeb22407234ac12da19b5fc9a12912f1a4255c8d48e153fa86e36dca07278cbd52bf0525c637f95ede2d053d2d0ab90ae49a4e6d6069266642dd
+  data.tar.gz: 183b2985c9366a663139a244d0eee485b012448d383ec4b23c9add579dac13ade4395be7cb4bc8ae85dfa65add94b966936c79153febf542d0e1af774f81e093

data/LICENSE.md

@@ -0,0 +1,19 @@
+Copyright (c) 2013 Chris Maddox
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,160 @@
+# UltraMarathon
+
+Fault tolerant platform for long running jobs.
+
+## Usage
+
+The `UltraMarathon::AbstractRunner` class itself provides the functionality for
+running complex jobs. It is best inheirited to fully customize.
+
+### DSL
+
+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.
+
+```ruby
+class MailRunner < UltraMarathon::AbstractRunner
+
+  # :main run block
+  run do
+    raise 'boom'
+  end
+
+  # :eat run block
+  run :eat do
+    add_butter
+    add_syrup
+    eat!
+  end
+
+  # Omitted for brevity
+  def add_butter; end
+  def add_syrup; end
+  def eat!; end
+
+end
+
+# Run the runner:
+MailRunner.run!
+```
+
+Note that, while the run blocks are defined in the context of the class, they
+will be run within an individual instance. Any methods should be defined as
+instance methods.
+
+In this instance, the `eat` run block will still run even if the `main` block is
+executed first. Errors are caught — though they can be evaluated using the
+`on_error` callback, detailed below — and the runner will attempt to complete as
+many run blocks as it is able.
+
+### Dependencies
+
+Independent blocks are not guaranteed to run in any order, unless specifying
+dependents using the `:requires` option.
+
+```ruby
+class WalrusRunner < UltraMarathon::AbstractRunner
+
+  run :bubbles, requires: [:don_scuba_gear] do
+    obtain_bubbles
+  end
+
+  run :don_scuba_gear do
+    aquire_snorkel
+    wear_flippers_on_flippers
+  end
+
+end
+```
+
+In this instance, `bubbles` will not be run until `don_scuba_gear` successfully
+finishes. If `don_scuba_gear` explicitly fails, such as by raising an error,
+`bubbles` will never be run.
+
+### Callbacks
+
+`UltraMarathon::AbstractRunner` includes numerous life-cycle callbacks for
+tangential code execution. Callbacks may be either callable objects
+(procs/lambdas) or symbols of methods defined on the runner.
+
+The basic flow of execution is as follows:
+
+- `before_run`
+- (`run!`)
+- `after_run`
+- `after_all`
+- (`reset`)
+- `on_reset`
+
+If there is an error raised in any run block, any `on_error` callbacks will be
+invoked, passing in the error if the callback takes arguments.
+
+```ruby
+class NewsRunner < UltraMarathon::AbstractRunner
+  before_run :fetch_new_yorker_stories
+  after_run :get_learning_on
+  on_error :contemplate_existence
+
+  run do
+    NewYorker.fetch_rss_feed!
+  end
+
+  private
+
+  def contemplate_existence(error)
+    if error.is_a? HighBrowError
+      puts 'Not cultured enough to understand :('
+    else
+      puts "Error: #{error.message}"
+    end
+  end
+
+end
+```
+
+#### Options
+
+Callbacks can, additionally, take a hash of options. Currently `:if` and
+`:unless` are supported. They too can be callable objects or symbols.
+
+```ruby
+class MercurialRunner < UltraMarathon::AbstractRunner
+  after_all :celebrate, :if => :success?
+  after_all :cry, unless: ->{ success? }
+
+  run do
+    raise 'hell' if rand(2) % 2 == 0
+  end
+
+end
+```
+
+### Success, Failure, and Reseting
+
+If any part of a runner fails, either by raising an error or explicitly setting
+`self.success = false`, the entire run will be considered a failure. Any run blocks
+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.
+
+```ruby
+class WatRunner < UltraMarathon::AbstractRunner
+  after_reset ->{ $global_variable = 42 }
+  after_run ->{ puts 'all is well in the universe'}
+  run do
+    unless $global_variable == 42
+      puts 'wrong!'
+      raise 'boom'
+    end
+  end
+
+end
+
+WatRunner.run!.reset.run!
+#=> boom
+#=> all is well in the universe
+```

data/lib/ultra_marathon/abstract_runner.rb

@@ -0,0 +1,204 @@
+require 'ultra_marathon/callbacks'
+require 'ultra_marathon/instrumentation'
+require 'ultra_marathon/logging'
+require 'ultra_marathon/sub_runner'
+require 'ultra_marathon/store'
+
+module UltraMarathon
+  class AbstractRunner
+    include Logging
+    include Instrumentation
+    include Callbacks
+    attr_accessor :success
+    callbacks :before_run, :after_run, :after_all, :on_error, :on_reset
+
+    after_all :write_log
+    on_error lambda { self.success = false }
+    on_error lambda { |error| logger.error(error) }
+
+    ## Public Instance Methods
+
+    # Runs the run block safely in the context of the instance
+    def run!
+      if self.class.run_blocks.any?
+        begin
+          self.success = true
+          invoke_before_run_callbacks
+          instrument { run_unrun_sub_runners }
+          self.success = failed_sub_runners.empty?
+          invoke_after_run_callbacks
+        rescue StandardError => error
+          invoke_on_error_callbacks(error)
+        ensure
+          invoke_after_all_callbacks
+        end
+        self
+      end
+    end
+
+    def success?
+      !!success
+    end
+
+    # Resets success to being true, unsets the failed sub_runners to [], and
+    # sets the unrun sub_runners to be the uncompleted/failed ones
+    def reset
+      reset_failed_runners
+      @success = true
+      invoke_on_reset_callbacks
+      self
+    end
+
+    private
+
+    ## Private Class Methods
+
+    class << self
+
+      # This is where the magic happens.
+      # Called in the class context, it will be safely executed in
+      # the context of the instance.
+      #
+      # E.g.
+      #
+      # class BubblesRunner < AbstractRunner
+      #   run do
+      #     fire_the_missiles
+      #     take_a_nap
+      #   end
+      #
+      #   def fire_the_missiles
+      #     puts 'But I am le tired'
+      #   end
+      #
+      #   def take_a_nap
+      #     puts 'zzzzzz'
+      #   end
+      # end
+      #
+      #  BubblesRunner.new.run!
+      #  # => 'But I am le tired'
+      #  # => 'zzzzzz'
+      def run(name=:main, options={}, &block)
+        name = name.to_sym
+        if !run_blocks.key? name
+          options[:name] = name
+          self.run_blocks[name] = [options, block]
+        else
+          raise NameError.new("Run block named #{name} already exists!")
+        end
+      end
+
+      def run_blocks
+        @run_blocks ||= Hash.new
+      end
+    end
+
+    ## Private Instance Methods
+
+    # Memoizes the sub runners based on the run blocks and their included
+    # options.
+    def unrun_sub_runners
+      @unrun_sub_runners ||= begin
+        self.class.run_blocks.reduce(Store.new) do |runner_store, (_name, (options, block))|
+          runner_store << new_sub_runner(options, block)
+          runner_store
+        end
+      end
+    end
+
+    # Creates a new sub runner, defaulting the context to `self`
+    def new_sub_runner(options, block)
+      defaults = {
+        context: self
+      }
+      options = defaults.merge(options)
+      SubRunner.new(options, block)
+    end
+
+    # Stores sub runners which ran and were a success
+    def successful_sub_runners
+      @successful_sub_runners ||= Store.new
+    end
+
+    # Stores sub runners which ran and failed
+    # Also store children of those which failed
+    def failed_sub_runners
+      @failed_sub_runners ||= Store.new
+    end
+
+    # If all of the parents have been successfully run (or there are no
+    # parents), runs the sub_runner.
+    # If any one of the parents has failed, considers the runner a failure
+    # If some parents have not yet completed, carries on
+    def run_unrun_sub_runners
+      unrun_sub_runners.each do |sub_runner|
+        if sub_runner_can_run? sub_runner
+          run_sub_runner(sub_runner)
+        elsif sub_runner.parents.any? { |name| failed_sub_runners.exists? name }
+          failed_sub_runners << sub_runner
+          unrun_sub_runners.delete sub_runner.name
+        end
+      end
+      run_unrun_sub_runners unless complete?
+    end
+
+    # Runs the sub runner, adding it to the appropriate sub runner store based
+    # on its success or failure and removes it from the unrun_sub_runners
+    def run_sub_runner(sub_runner)
+      sub_runner.run!
+      logger.info sub_runner.logger.contents
+      if sub_runner.success
+        successful_sub_runners << sub_runner
+      else
+        failed_sub_runners << sub_runner
+      end
+      unrun_sub_runners.delete sub_runner.name
+    end
+
+    ## TODO: timeout option
+    def complete?
+      unrun_sub_runners.empty?
+    end
+
+    # A sub runner can run if all prerequisites have been satisfied.
+    # This means all parent runners - those specified by name using the
+    # :requires options - have successfully completed.
+    def sub_runner_can_run?(sub_runner)
+      successful_sub_runners.includes_all?(sub_runner.parents)
+    end
+
+    # Resets all failed sub runners, then sets them as
+    # @unrun_sub_runners and @failed_sub_runners to an empty Store
+    def reset_failed_runners
+      failed_sub_runners.each(&:reset)
+      @unrun_sub_runners = failed_sub_runners
+      @failed_sub_runners = Store.new
+    end
+
+    def write_log
+      logger.info summary
+    end
+
+    def summary
+      """
+
+      Status: #{status}
+      Start Time: #{formatted_start_time}
+      End Time: #{formatted_end_time}
+      Total Time: #{formatted_total_time}
+
+      Successful SubRunners: #{successful_sub_runners.size}
+      Failed SubRunners: #{failed_sub_runners.size}
+      """
+    end
+
+    def status
+      if success
+        'Success'
+      else
+        'Failure'
+      end
+    end
+  end
+end

data/lib/ultra_marathon/callbacks.rb

@@ -0,0 +1,176 @@
+require 'set'
+require 'active_support/concern'
+require 'active_support/core_ext/proc'
+
+module UltraMarathon
+  module Callbacks
+    extend ActiveSupport::Concern
+
+    private
+
+    ## Private Instance Methods
+
+    # Check if the options' hash of conditions are met.
+    # Supports :if, :unless with callable objects/symbols
+    def callback_conditions_met?(options)
+      conditions_met = true
+      if options.key? :if
+        conditions_met &&= call_proc_or_symbol(options[:if])
+      elsif options.key? :unless
+        conditions_met &&= !call_proc_or_symbol(options[:unless])
+      end
+      conditions_met
+    end
+
+    # Exectutes the object in the context of the instance,
+    # whether an explicitly callable object or a string/symbol
+    # representation of one
+    def call_proc_or_symbol(object, args=[], options={})
+      options = options.dup
+      options[:context] ||= self
+      bound_proc = bind_to_context(object, options[:context])
+      evaluate_block_with_arguments(bound_proc, args)
+    end
+
+    # Binds a proc to the given context. If a symbol is passed in,
+    # retrieves the bound method.
+    def bind_to_context(symbol_or_proc, context)
+      if symbol_or_proc.is_a?(Symbol)
+        context.method(symbol_or_proc)
+      elsif symbol_or_proc.respond_to? :call
+        symbol_or_proc.bind(context)
+      else
+        raise ArgumentError.new("Cannot bind #{callback.class} to #{context}. Expected callable object or symbol.")
+      end
+    end
+
+    # Applies a block in context with the correct number of arguments.
+    # If there are more arguments than the arity, takes the first n
+    # arguments where (n) is the arity of the block.
+    # If there are the same number of arguments, splats them into the block.
+    # Otherwise throws an argument error.
+    def evaluate_block_with_arguments(block, args)
+      # If block.arity < 0, when a block takes a variable number of args,
+      # the one's complement (-n-1) is the number of required arguments
+      required_arguments = block.arity < 0 ? ~block.arity : block.arity
+      if args.length >= required_arguments
+        if block.arity < 0
+          instance_exec(*args, &block)
+        else
+          instance_exec(*args.first(block.arity), &block)
+        end
+      else
+        raise ArgumentError.new("wrong number of arguments (#{args.size} for #{required_arguments})")
+      end
+    end
+
+    module ClassMethods
+      ## Public Class Methods
+
+      # Add one or more new callbacks for class
+      # E.g.
+      #
+      # callbacks :after_save
+      #
+      # Defines a class method `after_save` which
+      # takes an object responding to :call (Proc or lambda)
+      # or a symbol to be called in the context of the instance
+      #
+      # Also defines `invoke_after_save_callbacks` instance method
+      # for designating when the callbacks should be invoked
+      def callbacks(*callback_names)
+        new_callbacks = Set.new(callback_names) - _callback_names
+        new_callbacks.each do |callback_name|
+          add_callbacks_accessor callback_name
+          define_callback callback_name
+          add_invoke_callback callback_name
+        end
+        self._callback_names = new_callbacks
+      end
+
+      private
+
+      ## Private Class Methods
+
+      # Only keep unique callback names
+      def _callback_names=(new_callbacks)
+        @_callback_names = _callback_names | new_callbacks
+      end
+
+      def _callback_names
+        @_callback_names ||= Set.new
+      end
+
+      # On inheritance, the child should inheirit all callbacks of the
+      # parent. We don't use class variables because we don't want sibling
+      # classes to share callbacks
+      def inherited(base)
+        base.send(:callbacks, *_callback_names)
+        _callback_names.each do |callback_name|
+          parent_callbacks = send :"#{callback_name}_callbacks"
+          base.instance_variable_set(:"@#{callback_name}_callbacks", parent_callbacks)
+        end
+      end
+
+      # Defines class level accessor that memoizes the set of callbacks
+      # E.g.
+      #
+      # def self.after_save_callbacks
+      #   @after_save_callbacks ||= []
+      # end
+      def add_callbacks_accessor(callback_name)
+        accessor_name = "#{callback_name}_callbacks"
+        instance_variable_name = :"@#{accessor_name}"
+        define_singleton_method("#{callback_name}_callbacks") do
+          instance_variable_get(instance_variable_name) ||
+          instance_variable_set(instance_variable_name, [])
+        end
+      end
+
+      # Validates that the callback is valid and adds it to the callback array
+      def define_callback(callback_name)
+        add_callback_setter(callback_name)
+        add_callback_array_writer(callback_name)
+      end
+
+      def add_callback_setter(callback_name)
+        define_singleton_method(callback_name) do |callback, options={}|
+          if valid_callback? callback
+            send("#{callback_name}_callbacks") << [callback, options]
+          else
+            raise ArgumentError.new("Expected callable object or symbol, got #{callback.class}")
+          end
+        end
+      end
+
+      # Callbacks should either be callable (Procs, lambdas) or a symbol
+      def valid_callback?(callback)
+        callback.respond_to?(:call) || callback.is_a?(Symbol)
+      end
+
+      # Use protected since this is used by parent classes
+      # to inherit callbacks
+      def add_callback_array_writer(callback_name)
+        attr_writer "#{callback_name}_callbacks"
+        protected "#{callback_name}_callbacks="
+      end
+
+      # Clears all callbacks. Useful for testing and inherited classes
+      def clear_callbacks!
+        _callback_names.each do |callback_name|
+          instance_variable_set(:"@#{callback_name}_callbacks", nil)
+        end
+      end
+
+      def add_invoke_callback(callback_name)
+        define_method("invoke_#{callback_name}_callbacks") do |*args|
+          callbacks = self.class.send :"#{callback_name}_callbacks"
+          callbacks.each do |callback, options|
+            next unless callback_conditions_met?(options)
+            call_proc_or_symbol(callback, args, options)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ultra_marathon/instrumentation.rb

@@ -0,0 +1,48 @@
+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)
+    end
+
+    private
+    def format_time(time)
+      sprintf(TIME_FORMAT, time.hour, time.min, time.sec)
+    end
+
+    ## Private Instance Methods
+
+    # 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
+    end
+  end
+end

data/lib/ultra_marathon/logger.rb

@@ -0,0 +1,61 @@
+require 'forwardable'
+
+module UltraMarathon
+  class Logger
+    extend Forwardable
+    NEW_LINE = "\n".freeze
+
+    ## Public Instance Methods
+
+    # Adds the line plus a newline
+    def info(line)
+      return if line.empty?
+      log_string << padded_line(line)
+    end
+
+    def error(error)
+      if error.is_a? Exception
+        log_formatted_error(error)
+      else
+        info error
+      end
+    end
+
+    # Returns a copy of the log data so it cannot be externally altered
+    def contents
+      log_string.dup
+    end
+
+    alias_method :emerg, :info
+    alias_method :warning, :info
+    alias_method :notice, :info
+    alias_method :debug, :info
+    alias_method :err, :error
+    alias_method :panic, :emerg
+    alias_method :warn, :warning
+
+    private
+
+    ## Private Instance Methods
+
+    def log_string
+      @log_string ||= ''
+    end
+
+    def padded_line(line)
+      if line.end_with? NEW_LINE
+        line
+      else
+        line << NEW_LINE
+      end
+    end
+
+    def log_formatted_error(error)
+      info error.message
+      formatted_backtrace = error.backtrace.map.with_index do |backtrace_line, line_number|
+        sprintf('%03i) %s', line_number, backtrace_line)
+      end
+      info formatted_backtrace.join("\n")
+    end
+  end
+end