deferred 0.5.3

data/lib/deferred.rb

@@ -0,0 +1,32 @@
+$LOAD_PATH.unshift(File.expand_path('..', __FILE__)).uniq!
+
+require "deferred/version"
+require 'eventmachine'
+
+module Deferred
+  class DeferredError < StandardError; end
+  class OnRunBlockNotRegisteredError < DeferredError; end
+
+  # convenience to return a new Deferred::Default instance
+  # this would be .new but that might have strange effects on 
+  # classes that mix in this module
+  #
+  def self.new_default
+    Deferred::Default.new
+  end
+end
+
+require "deferred/extensions"
+require "deferred/accessors"
+require "deferred/instance_methods"
+require "deferred/threadpool_job"
+require "deferred/default"
+
+module Deferred
+  include InstanceMethods
+
+  def self.included(base)
+    base.send(:include, Accessors)
+  end
+end
+

data/lib/deferred/accessors.rb

@@ -0,0 +1,170 @@
+module Deferred
+  module Accessors
+    def self.included(base)
+      base.extend(Deferred::Accessors::ClassMethods)
+      base.send(:include, Deferred::Accessors::InstanceMethods)
+    end
+
+    module ClassMethods
+      # creates a DefaultDeferred and attr_reader on the given class
+      # the method created allows for a block to be given, which will be
+      # added to the callback chain.
+      #
+      # Also defines a "reset_#{event_name}" that lets you create a new deferred
+      # for that event. The reset_event method will return the deferred being
+      # replaced.
+      # 
+      # @option opts [bool] :prefix ('on') what prefix should we use for the
+      #   main accessor. if :prefix is false, then no prefix will be used
+      #
+      # @example usage
+      #
+      #   class Foo
+      #     include Deferred::Accessors
+      #     
+      #     deferred_event :stop
+      #   end
+      #
+      #   f = Foo.new
+      #
+      #   # you can use on_stop as Deferred object
+      #   
+      #   f.on_stop.callback do
+      #     puts "called back"
+      #   end
+      #
+      #   f.on_stop.errback do
+      #     puts "erred back"
+      #   end
+      #
+      #   # or you can just hand a block that will be added to the callback
+      #   # chain
+      #
+      #   f.on_stop do
+      #     puts "this is the callback chain"
+      #   end
+      #
+      # @example reset method
+      #
+      #   class Foo
+      #     include Deferred::Accessors
+      #
+      #     deferred_event :stop
+      #
+      #
+      #     # this method fires the stop callbacks and re-arms them
+      #     def restart
+      #       dfr = reset_event_stop
+      #
+      #       # do stuff that requires stop
+      #       dfr.succeed
+      #     end
+      #   end
+      #
+      #
+      def deferred_event(*event_names)
+        opts = event_names.extract_options!
+        opts = {:before => false, :after => false}.merge(opts)
+
+        if opts[:prefix] != false
+          opts[:prefix] ||= 'on'
+        end
+
+        event_names.each do |event_name|
+          event_name = event_name.to_s
+
+          main_accessor_name = (opts[:prefix] == false) ? event_name : "#{opts[:prefix]}_#{event_name}"
+
+          define_method(:"reset_#{event_name}_event") do
+            _reset_deferred_event(event_name, opts.merge(:main_accessor_name => main_accessor_name))
+          end
+
+          create_deferred_event_reader(main_accessor_name)
+        end
+      end
+
+      # @private
+      def create_deferred_event_reader(accessor_name)
+        class_eval(<<-EOS, __FILE__, __LINE__ + 1)
+          def #{accessor_name}(&blk)
+            _deferred_events['#{accessor_name}'].tap do |d|
+              d.callback(&blk) if blk
+            end
+          end
+        EOS
+      end
+
+    end
+
+    module InstanceMethods
+      # Like deferred_event, but called from within a method to ensure that the
+      # state transition happens only once. 
+      #
+      # @example on_stop with deferred_state_transition
+      #
+      #   class Foo
+      #     deferred_event :stop
+      #
+      #     def stop(&event_callback)
+      #       deferred_state_transition(:on_stop, event_callback) do
+      #         # handle stop cases
+      #       end
+      #     end
+      #   end
+      #
+      #   # which is equivalent to
+      #
+      #   class Foo
+      #     deferred_event :stop
+      #
+      #     def stop(&blk)
+      #       on_stop(&blk)
+      #
+      #       return on_stop if @state_transition[:on_stop]
+      #       @state_transition[:on_stop] = true
+      #       
+      #       # handle stop cases
+      #
+      #       on_stop
+      #     end
+      #   end
+      #   
+      #
+      # It's essentially wrapping the logic of a guard and returning a callback. 
+      #
+      # @note This method is *not* threadsafe!
+      #
+      def deferred_state_transition(event_name, blk=nil)
+        event_name = event_name.to_sym
+        dfr = __send__(event_name)
+        
+        dfr.callback(&blk) if blk
+
+        return dfr if _deferred_states[event_name]
+        _deferred_states[event_name] = true
+
+        yield
+
+        return dfr
+      end
+
+      protected
+        def _deferred_events
+          @_deferred_events ||= Hash.new { |h,k| h[k.to_s] = Deferred.new_default }
+        end
+
+        def _deferred_states
+          @_deferred_states ||= {}
+        end
+        
+        # always returns a deferred, even one that has no callbacks
+        def _reset_deferred_event(event_name, opts={})
+          main_accessor_name = opts[:main_accessor_name]
+
+          _deferred_events.delete(main_accessor_name) { Deferred.new_default }
+        end
+    end
+  end
+end
+
+

data/lib/deferred/default.rb

@@ -0,0 +1,36 @@
+module Deferred
+  # This acts like the EventMachine::DefaultDeferrable, a blank class
+  # that includes the functionality of a Deferred module. Best used for
+  # cases where you need to follow the deferred result pattern, but don't need
+  # special behavior
+  #
+  class Default
+    include Accessors
+    include InstanceMethods
+  end
+
+  # Like Default but includes the ThreadpoolJob module.
+  class DefaultThreadpoolJob < Default
+    include ThreadpoolJob
+
+    # if you pass a block it will be used as the on_run block
+    #
+    # @example
+    #   
+    #   DefaultThreadpoolJob.new do 
+    #     # do stuff
+    #   end
+    #
+    #   # is the equivalent of
+    #
+    #   dtj = DefaultThreadpoolJob.new
+    #   dtj.on_run do
+    #     # do stuff
+    #   end
+    #
+    def initialize(&blk)
+      on_run(&blk)
+    end
+  end
+end
+

data/lib/deferred/extensions.rb

@@ -0,0 +1,22 @@
+# stolen from active_support, but won't clobber ActiveSupport's definitions
+
+class ::Hash
+  unless method_defined?(:extractable_options?)
+    def extractable_options?
+      instance_of?(Hash)
+    end
+  end
+end
+
+class ::Array
+  unless method_defined?(:extract_options!)
+    def extract_options!
+      if last.is_a?(Hash) && last.extractable_options?
+        pop
+      else
+        {}
+      end
+    end
+  end
+end
+

data/lib/deferred/instance_methods.rb

@@ -0,0 +1,82 @@
+module Deferred
+  module InstanceMethods
+    include EM::Deferrable
+
+    def callback(*a, &b)
+      super(*a, &b)
+      self
+    end
+
+    def errback(*a, &b)
+      super(*a, &b)
+      self
+    end
+
+    # add block to both callback and errback
+    def ensure_that(&b)
+      callback(&b)
+      errback(&b)
+      self
+    end
+
+    # call this deferred with the result (callback or errback) of the +other_dfr+
+    #
+    # @option opts [true,false] :ignore_errors (false) if true, then don't hook
+    #   up the errback.
+    #
+    # @option opts [true,false] :only_errors (false) if true, then don't hook
+    #   up the callback.
+    #
+    # @return self
+    #
+    # @example deferred chaining
+    #
+    #   # this:
+    #
+    #   d.chain_to(other_dfr)
+    #
+    #   # is the equivalent of:
+    #
+    #   other_dfr.callback { |*a| d.succeed(*a) }
+    #   other_dfr.errback  { |*a| d.fail(*a) }
+    #   
+    #
+    def chain_to(other_dfr, opts={})
+      other_dfr.callback { |*a| self.succeed(*a) }  unless opts[:only_errors]
+      other_dfr.errback { |*a| self.fail(*a) }      unless opts[:ignore_errors]
+      self
+    end
+
+    # syntactic sugar equivalent to other_dfr.errback { |*a| self.fail(*a) }
+    def chain_err(other_dfr)
+      chain_to(other_dfr, :only_errors => true)
+    end
+
+    # Like EM::Deferrable's timeout method, but optionally allows you to specify an
+    # exception class. An instance of that exception class will be created and
+    # used as the argument to #fail. If an exception_klass is not given, then #fail
+    # is called without arguments.
+    #
+    def timeout(seconds, exception_klass=nil)
+      cancel_timeout
+      me = self
+      @deferred_timeout = EventMachine::Timer.new(seconds) do
+        if exception_klass
+          e = exception_klass.new("timeout after %0.3f seconds" % [seconds.to_f]).tap { |e| e.set_backtrace([]) }
+          me.fail(*e)
+        else
+          me.fail
+        end
+      end
+    end
+
+    # takes a block, if an exception is raised inside of the block
+    # we do self.fail(exc)
+    def errback_on_exception
+      yield
+    rescue Exception => e
+      self.fail(*e)
+    end
+  end
+end
+

data/lib/deferred/threadpool_job.rb

@@ -0,0 +1,63 @@
+module Deferred
+  # Adds several methods that simplify using a Deferred as a mechanism for
+  # handling the results of an EM.defer call. see #defer!
+  module ThreadpoolJob
+    include Deferred::InstanceMethods
+    include Deferred::Accessors
+
+    deferred_event :before_run, :prefix => false
+
+    attr_accessor :on_run_block
+
+    # Used with the defer! method. the block given will be the block run
+    # in the EM.threadpool (via EM.defer). see #defer!
+    def on_run(&block)
+      @on_run_block = block
+    end
+
+    # Calls the @on_run_block as the first argument to EM.defer, and uses the 
+    # result (the value returned from calling the block) as the deferred result
+    # that will be used to call the registered callbacks. If the block raises an
+    # exception, that exception instance will be the argument used to call the 
+    # registered errbacks. 
+    #
+    # @raise [OnRunBlockNotRegisteredError] when defer! has been called without an
+    #   on_run block assigned (i.e. with no work to defer to a threadpool)
+    #
+    def defer!
+      raise OnRunBlockNotRegisteredError unless @on_run_block
+
+      EM.next_tick do 
+        before_run.succeed
+        EM.defer(method(:call_on_run_block).to_proc, method(:handle_completion).to_proc)
+      end
+
+      self
+    end
+
+    protected
+      def call_on_run_block
+        @on_run_block.call
+      rescue Exception => exc
+        exc
+      end
+
+      # after cb above runs, this method is called in the reactor
+      def handle_completion(*tp_result)
+        first = tp_result.first
+
+        if first.kind_of?(Exception)
+          self.fail(first)
+        elsif first.respond_to?(:callback) and first.respond_to?(:errback)
+          first.callback { |*a| handle_completion(*a) }
+          first.errback  { |*a| handle_completion(*a) }
+          if first.respond_to?(:defer!)
+            EM.schedule { first.defer! }
+          end
+        else
+          self.succeed(*tp_result)
+        end
+      end
+  end
+end
+

data/lib/deferred/version.rb

@@ -0,0 +1,3 @@
+module Deferred
+  VERSION = "0.5.3"
+end

data/spec/deferred/accessors_spec.rb

@@ -0,0 +1,95 @@
+require 'spec_helper'
+
+describe 'Deferred::Accessors' do
+  describe 'an Accessorized class' do
+    it %[should respond_to deferred_event] do
+      Accessorized.should be_respond_to(:deferred_event)
+    end
+
+    describe 'instance' do
+      before do
+        @acc = Accessorized.new
+      end
+
+      it %[should define an on_plain reader] do
+        @acc.should be_respond_to(:on_plain)
+      end
+
+      it %[should return a Deferred::Default instance] do
+        @acc.on_plain.should be_instance_of(Deferred::Default)
+      end
+
+      it %[should use a block passed to the reader as a callback] do
+        @callback_called = nil
+
+        @acc.on_plain do
+          @callback_called = true
+        end
+
+        @acc.on_plain.succeed
+
+        @callback_called.should be_true
+      end
+
+      describe 'generated methods' do
+        it %[should have a 'no_prefix' deferred defined] do
+          @acc.no_prefix.should be_instance_of(Deferred::Default)
+        end
+      end
+
+      describe 'reset_event' do
+        before do
+          @orig_deferred = @acc.on_plain
+          @rval = @acc.reset_plain_event
+        end
+
+        it %[should return the original deferred] do
+          @rval.should be_kind_of(Deferred::Default)
+          @rval.should == @orig_deferred
+        end
+
+        it %[should return new deferreds after reset] do
+          @rval.should_not == @acc.on_plain
+        end
+      end
+    end
+  end
+
+  describe 'deferred_state_transition' do
+    before do
+      @dsx = DeferredStateXtn.new
+    end
+
+    it %[should return the deferred when called] do
+      @dsx.start.should == @dsx.on_start
+    end
+
+    it %[should add the given block as a callback to the deferred] do
+      callback_called = false
+
+      @dsx.start { callback_called = true }
+
+      @dsx.on_start.succeed
+
+      callback_called.should be_true
+    end
+
+    it %[should add the given block as a callback to the deferred after the callback has fired] do
+      callback_called = false
+
+      @dsx.on_start.succeed
+
+      @dsx.start { callback_called = true }
+
+      callback_called.should be_true
+    end
+
+    it %[should only allow the contained block to be called once] do
+      @dsx.start
+      @dsx.start
+
+      @dsx.start_run_times.should == 1
+    end
+  end
+end
+