ultra_marathon 0.1.7 → 0.1.10

data/lib/ultra_marathon/callbacks.rb

@@ -1,10 +1,11 @@
 require 'set'
 require 'active_support/concern'
-require 'core_ext/proc'
+require 'ultra_marathon/contexticution'
 
 module UltraMarathon
   module Callbacks
     extend ActiveSupport::Concern
+    include Contexticution
 
     private
 
@@ -15,56 +16,16 @@ module UltraMarathon
     def callback_conditions_met?(options)
       conditions_met = true
       if options.key? :if
-        conditions_met &&= call_proc_or_symbol(options[:if])
+        conditions_met &&= contexticute(options[:if])
       elsif options.key? :unless
-        conditions_met &&= !call_proc_or_symbol(options[:unless])
+        conditions_met &&= !contexticute(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
+      include Contexticution
+
       ## Public Class Methods
 
       # Add one or more new callbacks for class
@@ -113,11 +74,15 @@ module UltraMarathon
       end
 
       # Defines class level accessor that memoizes the set of callbacks
-      # E.g.
+      # @param callback_name [String, Symbol]
+      # @example
+      #   add_callbacks_accessor(:after_save)
       #
-      # def self.after_save_callbacks
-      #   @after_save_callbacks ||= []
-      # end
+      #   # Equivalent to
+      #   #
+      #   # 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}"
@@ -167,7 +132,7 @@ module UltraMarathon
           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)
+            contexticute(callback, args, options[:context] || self)
           end
         end
       end

data/lib/ultra_marathon/collection_runner.rb

@@ -0,0 +1,111 @@
+require 'set'
+require 'ultra_marathon/base_runner'
+require 'ultra_marathon/store'
+require 'ultra_marathon/sub_context'
+require 'ultra_marathon/sub_runner'
+
+module UltraMarathon
+  class CollectionRunner < BaseRunner
+    attr_reader :collection, :options, :run_block, :name
+    attr_memo_reader :sub_runner_class, -> { options[:sub_runner].try_call }
+
+    after_run :write_logs
+    instrumentation_prefix lambda { |collection| "collection.#{collection.name}." }
+
+    # Takes a collection, each of which will be run in its own subrunner. The collection
+    # Also takes a number of options:
+    #
+    # name:       The name of the collection run block
+    # sub_name:   A callable object (passed the index of the collection) that
+    #             should return a unique (to the collection) name for that subrunner
+    #             Defaults to :"#{options[:name]}__#{index}"
+    # sub_runner: Class inheiriting from UltraMarathon::SubRunner in which each
+    #             run_block will be run
+    #             Defaults to UltraMarathon::SubRunner
+    #
+    # iterator:   Method called to iterate over collection. For example, a Rails
+    #             application may wish to use :find_each with an ActiveRecord::Relation
+    #             to batch queries
+    #             Defaults to :each
+    #
+    # threaded:   Run each iteration in its own thread
+    def initialize(collection, options={}, &run_block)
+      @collection, @run_block = collection, run_block
+      @name = options[:name]
+      @options = {
+        sub_name: proc { |index| :"#{options[:name]}__#{index}" },
+        sub_runner: SubRunner,
+        iterator:   :each,
+        threaded: false
+      }.merge(options)
+    end
+
+    def unrun_sub_runners
+      @unrun_sub_runners ||= begin
+        store = Store.new
+        index = 0
+        collection.send(options[:iterator]) do |item|
+          this_index = index
+          index += 1
+          store << new_item_sub_runner(item, this_index)
+        end
+        store
+      end
+    end
+
+    def threaded?
+      false
+    end
+
+    def complete?
+      unrun_sub_runners.empty? && running_sub_runners.empty?
+    end
+
+    # Set of all sub runners that should be run before this one.
+    # This class cannot do anything with this information, but it is useful
+    # to the enveloping runner.
+    def parents
+      @parents ||= Set.new(options[:requires])
+    end
+
+    private
+
+    def write_logs
+      log_header
+      log_all_sub_runners
+      log_summary
+    end
+
+    def log_header
+      logger.info "Running Collection #{options[:name]}"
+    end
+
+    def new_item_sub_runner(item, index)
+      item_options = sub_runner_item_options(item, index)
+      item_sub_context = build_item_sub_context(item, item_options)
+      sub_runner_class.new(item_options, item_sub_context)
+    end
+
+    # By default, run the sub runner inside this context. Unlikely to be what you
+    # want
+    def sub_runner_base_options
+      {
+        context: options[:context] || self,
+        threaded: options[:threaded]
+      }
+    end
+
+    def sub_runner_item_options(item, index)
+      name = options[:sub_name].try_call(index, item)
+      sub_runner_base_options.merge(name: name)
+    end
+
+    def build_item_sub_context(item, options)
+      Proc.new do |run_block|
+        SubContext.new(options[:context]) do
+          instance_exec(*item, &run_block)
+        end
+      end.call(run_block)
+    end
+  end
+end

data/lib/ultra_marathon/contexticution.rb

@@ -0,0 +1,53 @@
+require 'core_ext/proc'
+
+module UltraMarathon
+  module Contexticution
+
+    # @param object [Symbol, String, Proc] a symbol representing a method name,
+    #   a string to be eval'd, or a proc to be called in the given context
+    # @param args [Array] arguments to be passed to +object+
+    # @param context [Object] the context in which to evaluate +object+. Defaults
+    #   to self
+    def contexticute(object, args=[], context=self)
+      bound_proc = bind_to_context(object, context)
+      evaluate_block_with_arguments(bound_proc, args)
+    end
+
+    private
+    # Binds a proc to the given context. If a symbol is passed in,
+    # retrieves the bound method. If it is a string, generates a lambda wrapping
+    # it.
+    def bind_to_context(object, context)
+      if object.is_a?(Symbol)
+        context.method(object)
+      elsif object.respond_to?(:call)
+        object.bind(context)
+      elsif object.is_a?(String)
+        eval("lambda { #{object} }").bind(context)
+      else
+        raise ArgumentError.new("Cannot bind #{callback.class} to #{context}. Expected Symbol, String, or object responding to #call.")
+      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
+
+  end
+end

data/lib/ultra_marathon/instrumentation.rb

@@ -1,25 +1,48 @@
+require 'active_support/concern'
 require 'ultra_marathon/instrumentation/profile'
+require 'ultra_marathon/instrumentation/store'
 
 module UltraMarathon
   module Instrumentation
-    TIME_FORMAT = "%02d:%02d:%02d"
+    extend ActiveSupport::Concern
+    # Creates a default UltraMarathon::Instrumentation::Store and stores
+    # all instrumented profiles there
 
-    ## Public Instance Methods
+    module ClassMethods
+      ## Public Class Methods
 
+      # @param prefix_or_proc [String, Proc] the prefix. If a Proc, it will be
+      #   passed self for each instance
+      # @return [String, Proc, nil]
+      def instrumentation_prefix(prefix_or_proc=nil)
+        if prefix_or_proc
+          @instrumentation_prefix = prefix_or_proc
+        else
+          @instrumentation_prefix
+        end
+      end
+    end
+
+    # The default instrumentation store for the included class
+    # @return [UltraMarathon::Instrumentation::Store]
     def instrumentations
-      @instrumentations ||= Hash.new
+      @instrumentations ||= UltraMarathon::Instrumentation::Store.new([], prefix: instrumentation_prefix)
     end
 
     private
 
     ## Private Instance Methods
 
-    # Instruments given block, setting its start time and end time
-    # Returns the result of the block
-    def instrument(name, &block)
-      profile = Profile.new(name, &block)
-      instrumentations[name] = profile
-      profile.call
+    # @return [String] the prefix for the default instrumentation store passed
+    #   to {.instrumentation_prefix}
+    def instrumentation_prefix
+      self.class.instrumentation_prefix.try_call(self)
+    end
+
+    # @return [Object]
+    # @see UltraMarathon::Instrumentation::Store#instrument
+    def instrument(*args, &block)
+      instrumentations.instrument(*args, &block)
     end
   end
 end

data/lib/ultra_marathon/instrumentation/profile.rb

@@ -1,19 +1,25 @@
+require 'ultra_marathon/instrumentation/profile'
 module UltraMarathon
   module Instrumentation
     class Profile
+      DATETIME_FORMAT = '%H:%M:%S:%L'.freeze
+      RAW_TIME_FORMAT = '%02d:%02d:%02d:%03d'.freeze
       attr_reader :name, :start_time, :end_time
 
       ## Public Instance Methods
 
+      # @param name [String] name of the instrumented block
+      # @param block [Proc] block to be instrumented
       def initialize(name, &block)
         @name = name
         # 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 :instrumented_block do
           block.call
         end
       end
 
+      # Sets {#start_time}, runs the initialized block, then sets {#end_time}
+      # @return [Object] the return value of the initialized block
       def call
         @start_time = Time.now
         begin
@@ -24,31 +30,54 @@ module UltraMarathon
         return_value
       end
 
-      # returns the total time, in seconds
+      # @return [Float] the total time in seconds to the nanosecond
       def total_time
-        (end_time - start_time).to_i
+        @total_time ||= end_time - start_time
       end
 
+      # @return [String] {#total_time} formatted per {RAW_TIME_FORMAT}
       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)
+        format_seconds(total_time)
       end
 
+      # @return [String] {#start_time} formatted per {DATETIME_FORMAT}
       def formatted_start_time
         format_time(start_time)
       end
 
+      # @return [String] {#end_time} formatted per {DATETIME_FORMAT}
       def formatted_end_time
         format_time(end_time)
       end
 
+      # Comparison delegated to {#total_time}
+      # @param other_profile [Profile]
+      # @return [Integer] {#total_time} <=> other_profile.total_time
+      def <=>(other_profile)
+        total_time <=> other_profile.total_time
+      end
+
+      # Profiles are considered equal if their names are `eql?`
+      # @param other_profile [Profile]
+      # @return [Boolean] delegates to {#name}
+      def eql?(other_profile)
+        name.eql? other_profile.name
+      end
+
+      private
+
       ## Private Instance Methods
 
+      def format_seconds(total_seconds)
+        seconds = (total_seconds % 60).floor
+        minutes = (total_seconds / 60).floor
+        hours   = (total_seconds / 3600).floor
+        milliseconds = (total_seconds - total_seconds.to_i) * 1000.0
+        sprintf(RAW_TIME_FORMAT, hours, minutes, seconds, milliseconds)
+      end
+
       def format_time(time)
-        sprintf(TIME_FORMAT, time.hour, time.min, time.sec)
+        time.strftime(DATETIME_FORMAT)
       end
     end
   end

data/lib/ultra_marathon/instrumentation/store.rb

@@ -0,0 +1,103 @@
+require 'set'
+module UltraMarathon
+  module Instrumentation
+    class Store < SortedSet
+      attr_reader :options
+
+      # @param new_members [Array, Set]
+      # @param options [Hash]
+      # @option options [String] :prefix ('') will prefix the name of every
+      #   name passed into {#instrument}
+      def initialize(new_members=[], options={})
+        super(new_members)
+        @options = {
+          prefix: ''
+        }.merge(options)
+      end
+
+      # Instruments given block, setting its start time and end time
+      # Stores the resulting profile in in itself
+      # @param name [String] name of the instrumented block
+      # @param block [Proc] block to instrument
+      # @return [Object] return value of the instrumented block
+      def instrument(name, &block)
+        profile = Profile.new(full_name(name), &block)
+        return_value = profile.call
+        self.add(profile)
+        return_value
+      end
+
+      # The passed in prefix
+      # @return [String]
+      def prefix
+        options[:prefix]
+      end
+
+      # Access a profile by name. Instrumentations shouldn't have to know about
+      # their fully qualified name, so the unprefixed version should be passed
+      # @param name [String] name of the profile that was passed to
+      #   {#instrument}
+      # @return [UltraMarathon::Instrumentation::Profile, nil]
+      def [](name)
+        full_name = full_name(name)
+        detect do |profile|
+          profile.name == full_name
+        end
+      end
+
+      # Accumulated total time for all stored profiles
+      # @return [Float]
+      def total_time
+        total_times.reduce(0.0, :+)
+      end
+
+      # @return [Float] the mean time for all profiles
+      def mean_runtime
+        total_time / size
+      end
+
+      # @return [UltraMarthon::Instrumentation::Profile] the profile in the
+      #   middle of the pack per
+      #   {UltraMarthon::Instrumentation::Profile#total_time}
+      def median
+        to_a[size / 2]
+      end
+
+
+      # Please forgive me Mr. Brooks, I had to Google it
+      # @return [Float] the standard deviation from the mean
+      def standard_deviation
+        sum_of_squares = total_times.reduce(0) do |sum, total_time|
+          sum + (mean_runtime - total_time) ** 2
+        end
+        Math.sqrt(sum_of_squares / size)
+      end
+
+      # Adds all profiles from the other_store
+      # @param other_store [UltraMarathon::Instrumentation::Profile]
+      # @return [self] the other_store
+      def merge!(other_store)
+        other_store.each do |member|
+          add(member)
+        end
+        self
+      end
+
+      private
+
+      ## Private Instance Methods
+
+      # Adds the prefix to the name
+      # @param name [String] the raw name
+      # @return [String] the prefixed name
+      def full_name(name)
+        "#{prefix}#{name}"
+      end
+
+      # @return [Array<Float>] the total times for all stored profiles
+      def total_times
+        map(&:total_time)
+      end
+    end
+  end
+end