state_machine 0.8.1 → 0.9.0

data/lib/state_machine/transition.rb

@@ -1,3 +1,5 @@
+require 'state_machine/transition_collection'
+
 module StateMachine
   # An invalid transition was attempted
   class InvalidTransition < StandardError
@@ -10,83 +12,6 @@ module StateMachine
   # * A starting state
   # * An ending state
   class Transition
-    class << self
-      # Runs one or more transitions in parallel.  All transitions will run
-      # through the following steps:
-      # 1. Before callbacks
-      # 2. Persist state
-      # 3. Invoke action
-      # 4. After callbacks (if configured)
-      # 5. Rollback (if action is unsuccessful)
-      # 
-      # Configuration options:
-      # * <tt>:action</tt> - Whether to run the action configured for each transition
-      # * <tt>:after</tt> - Whether to run after callbacks
-      # 
-      # If a block is passed to this method, that block will be called instead
-      # of invoking each transition's action.
-      def perform(transitions, options = {})
-        # Validate that the transitions are for separate machines / attributes
-        attributes = transitions.map {|transition| transition.attribute}.uniq
-        raise ArgumentError, 'Cannot perform multiple transitions in parallel for the same state machine attribute' if attributes.length != transitions.length
-        
-        success = false
-        
-        # Run before callbacks.  If any callback halts, then the entire chain
-        # is halted for every transition.
-        if transitions.all? {|transition| transition.before}
-          # Persist the new state for each attribute
-          transitions.each {|transition| transition.persist}
-          
-          # Run the actions associated with each machine
-          begin
-            results = {}
-            success =
-              if block_given?
-                # Block was given: use the result for each transition
-                result = yield
-                transitions.each {|transition| results[transition.action] = result}
-                !!result
-              elsif options[:action] == false
-                # Skip the action
-                true
-              else
-                # Run each transition's action (only once)
-                object = transitions.first.object
-                transitions.all? do |transition|
-                  action = transition.action
-                  action && !results.include?(action) ? results[action] = object.send(action) : true
-                end
-              end
-          rescue Exception
-            # Action failed: rollback 
-            transitions.each {|transition| transition.rollback}
-            raise
-          end
-          
-          # Run after callbacks even when the actions failed. The :after option
-          # is ignored if the transitions were unsuccessful.
-          transitions.each {|transition| transition.after(results[transition.action], success)} unless options[:after] == false && success
-          
-          # Rollback the transitions if the transaction was unsuccessful
-          transitions.each {|transition| transition.rollback} unless success
-        end
-        
-        success
-      end
-      
-      # Runs one or more transitions within a transaction.  See StateMachine::Transition.perform
-      # for more information.
-      def perform_within_transaction(transitions, options = {})
-        success = false
-        transitions.first.within_transaction do
-          success = perform(transitions, options)
-        end
-        
-        success
-      end
-    end
-    
     # The object being transitioned
     attr_reader :object
     
@@ -124,11 +49,15 @@ module StateMachine
     # The result of invoking the action associated with the machine
     attr_reader :result
     
+    # Whether the transition is only existing temporarily for the object
+    attr_writer :transient
+    
     # Creates a new, specific transition
     def initialize(object, machine, event, from_name, to_name, read_state = true) #:nodoc:
       @object = object
       @machine = machine
       @args = []
+      @transient = false
       
       # Event information
       event = machine.events.fetch(event)
@@ -146,6 +75,8 @@ module StateMachine
       @to = to_state.value
       @to_name = to_state.name
       @qualified_to_name = to_state.qualified_name
+      
+      reset
     end
     
     # The attribute which this transition's machine is defined for
@@ -170,6 +101,13 @@ module StateMachine
       from_name == to_name
     end
     
+    # Is this transition existing for a short period only?  If this is set, it
+    # indicates that the transition (or the event backing it) should not be
+    # written to the object if it fails.
+    def transient?
+      @transient
+    end
+    
     # A hash of all the core attributes defined for this transition with their
     # names as keys and values of the attributes as values.
     # 
@@ -203,7 +141,7 @@ module StateMachine
       self.args = args
       
       # Run the transition
-      self.class.perform_within_transaction([self], :action => run_action)
+      !!TransitionCollection.new([self], :actions => run_action).perform
     end
     
     # Runs a block within a transaction for the object being transitioned.
@@ -215,37 +153,39 @@ module StateMachine
       end
     end
     
-    # Runs the machine's +before+ callbacks for this transition.  Only
-    # callbacks that are configured to match the event, from state, and to
-    # state will be invoked.
-    # 
-    # Once the callbacks are run, they cannot be run again until this transition
-    # is reset.
+    # Runs the before / after callbacks for this transition.  If a block is
+    # provided, then it will be executed between the before and after callbacks.
     # 
-    # == Example
+    # Configuration options:
+    # * +after+ - Whether to run after callbacks.  If false, then any around
+    #   callbacks will be paused until called again with +after+ enabled.
+    #   Default is true.
     # 
-    #   class Vehicle
-    #     state_machine do
-    #       before_transition :on => :ignite, :do => lambda {|vehicle| ...}
-    #     end
-    #   end
-    #   
-    #   vehicle = Vehicle.new
-    #   transition = StateMachine::Transition.new(vehicle, machine, :ignite, :parked, :idling)
-    #   transition.before
-    def before
-      result = false
+    # This will return true if all before callbacks gets executed.  After
+    # callbacks will not have an effect on the result.
+    def run_callbacks(options = {}, &block)
+      options = {:after => true}.merge(options)
+      @success = false
       
-      catch(:halt) do
-        unless @before_run
-          callback(:before)
-          @before_run = true
-        end
-        
-        result = true
+      # Run before callbacks.  :halt is caught here so that it rolls up through
+      # any around callbacks.
+      begin
+        halted = !catch(:halt) { before(options[:after], &block); true }
+      rescue Exception => error
+        raise unless @after_block
+      end
+      
+      # After callbacks are only run if:
+      # * There isn't an after block already running
+      # * An around callback didn't halt after yielding
+      # * They're enabled or the run didn't succeed
+      if @after_block
+        @after_block.call(halted, error)
+      elsif !(@before_run && halted) && (options[:after] || !@success)
+        after
       end
       
-      result
+      @before_run
     end
     
     # Transitions the current value of the state to that specified by the
@@ -274,51 +214,6 @@ module StateMachine
       end
     end
     
-    # Runs the machine's +after+ callbacks for this transition.  Only
-    # callbacks that are configured to match the event, from state, and to
-    # state will be invoked.
-    # 
-    # The result can be used to indicate whether the associated machine action
-    # was executed successfully.
-    # 
-    # Once the callbacks are run, they cannot be run again until this transition
-    # is reset.
-    # 
-    # == Halting
-    # 
-    # If any callback throws a <tt>:halt</tt> exception, it will be caught
-    # and the callback chain will be automatically stopped.  However, this
-    # exception will not bubble up to the caller since +after+ callbacks
-    # should never halt the execution of a +perform+.
-    # 
-    # == Example
-    # 
-    #   class Vehicle
-    #     state_machine do
-    #       after_transition :on => :ignite, :do => lambda {|vehicle| ...}
-    #       
-    #       event :ignite do
-    #         transition :parked => :idling
-    #       end
-    #     end
-    #   end
-    #   
-    #   vehicle = Vehicle.new
-    #   transition = StateMachine::Transition.new(vehicle, Vehicle.state_machine, :ignite, :parked, :idling)
-    #   transition.after(true)
-    def after(result = nil, success = true)
-      @result = result
-      
-      catch(:halt) do
-        unless @after_run
-          callback(:after, :success => success)
-          @after_run = true
-        end
-      end
-      
-      true
-    end
-    
     # Rolls back changes made to the object's state via this transition.  This
     # will revert the state back to the +from+ value.
     # 
@@ -352,6 +247,7 @@ module StateMachine
     # the state has already been persisted
     def reset
       @before_run = @persisted = @after_run = false
+      @around_block = nil
     end
     
     # Generates a nicely formatted description of this transitions's contents.
@@ -364,7 +260,86 @@ module StateMachine
       "#<#{self.class} #{%w(attribute event from from_name to to_name).map {|attr| "#{attr}=#{send(attr).inspect}"} * ' '}>"
     end
     
-    protected
+    private
+      # Runs the machine's +before+ callbacks for this transition.  Only
+      # callbacks that are configured to match the event, from state, and to
+      # state will be invoked.
+      # 
+      # Once the callbacks are run, they cannot be run again until this transition
+      # is reset.
+      def before(complete = true, index = 0, &block)
+        unless @before_run
+          while callback = machine.callbacks[:before][index]
+            index += 1
+            
+            if callback.type == :around
+              # Around callback: need to handle recursively.  Execution only gets
+              # paused if:
+              # * The block fails and the callback doesn't run on failures OR
+              # * The block succeeds, but after callbacks are disabled (in which
+              #   case a continuation is stored for later execution)
+              return if catch(:pause) do
+                callback.call(object, context, self) do
+                  before(complete, index, &block)
+                  
+                  if @success && !complete && !@around_block && !@after_block
+                    require 'continuation' unless defined?(callcc)
+                    callcc {|block| @around_block = block}
+                  end
+                  
+                  throw :pause, true if @around_block && !@after_block || !callback.matches_success?(@success)
+                end
+              end
+            else
+              # Normal before callback
+              callback.call(object, context, self)
+            end
+          end
+          
+          @before_run = true
+        end
+        
+        action = {:success => true}.merge(block_given? ? yield : {})
+        @result, @success = action[:result], action[:success]
+      end
+      
+      # Runs the machine's +after+ callbacks for this transition.  Only
+      # callbacks that are configured to match the event, from state, and to
+      # state will be invoked.
+      # 
+      # Once the callbacks are run, they cannot be run again until this transition
+      # is reset.
+      # 
+      # == Halting
+      # 
+      # If any callback throws a <tt>:halt</tt> exception, it will be caught
+      # and the callback chain will be automatically stopped.  However, this
+      # exception will not bubble up to the caller since +after+ callbacks
+      # should never halt the execution of a +perform+.
+      def after
+        unless @after_run
+          catch(:halt) do
+            # First call any yielded around blocks
+            if @around_block
+              halted, error = callcc do |block|
+                @after_block = block
+                @around_block.call
+              end
+              
+              @after_block = @around_block = nil
+              raise error if error
+              throw :halt if halted
+            end
+            
+            # Call normal after callbacks in order
+            after_context = context.merge(:success => @success)
+            machine.callbacks[:after].each {|callback| callback.call(object, after_context, self)}
+          end
+          
+          @after_run = true
+        end
+      end
+      
       # Gets a hash of the context defining this unique transition (including
       # event, from state, and to state).
       # 
@@ -376,19 +351,5 @@ module StateMachine
       def context
         @context ||= {:on => event, :from => from_name, :to => to_name}
       end
-      
-      # Runs the callbacks of the given type for this transition.  This will
-      # only invoke callbacks that exactly match the event, from state, and
-      # to state that describe this transition.
-      # 
-      # Additional callback parameters can be specified.  By default, this
-      # transition is also passed into callbacks.
-      def callback(type, context = {})
-        context = self.context.merge(context)
-        
-        machine.callbacks[type].each do |callback|
-          callback.call(object, context, self)
-        end
-      end
   end
 end

data/lib/state_machine/transition_collection.rb

@@ -0,0 +1,244 @@
+module StateMachine
+  # Represents a collection of transitions in a state machine
+  class TransitionCollection < Array
+    include Assertions
+    
+    # Whether to skip running the action for each transition's machine
+    attr_reader :skip_actions
+    
+    # Whether to skip running the after callbacks
+    attr_reader :skip_after
+    
+    # Whether transitions should wrapped around a transaction block
+    attr_reader :use_transaction
+    
+    # Creates a new collection of transitions that can be run in parallel.  Each
+    # transition *must* be for a different attribute.
+    # 
+    # Configuration options:
+    # * <tt>:actions</tt> - Whether to run the action configured for each transition
+    # * <tt>:after</tt> - Whether to run after callbacks
+    # * <tt>:transaction</tt> - Whether to wrap transitions within a transaction
+    def initialize(transitions = [], options = {})
+      super(transitions)
+      
+      # Determine the validity of the transitions as a whole
+      @valid = all?
+      reject! {|transition| !transition}
+      
+      attributes = map {|transition| transition.attribute}.uniq
+      raise ArgumentError, 'Cannot perform multiple transitions in parallel for the same state machine attribute' if attributes.length != length
+      
+      assert_valid_keys(options, :actions, :after, :transaction)
+      options = {:actions => true, :after => true, :transaction => true}.merge(options)
+      @skip_actions = !options[:actions]
+      @skip_after = !options[:after]
+      @use_transaction = options[:transaction]
+    end
+    
+    # Runs each of the collection's transitions in parallel.
+    # 
+    # All transitions will run through the following steps:
+    # 1. Before callbacks
+    # 2. Persist state
+    # 3. Invoke action
+    # 4. After callbacks (if configured)
+    # 5. Rollback (if action is unsuccessful)
+    # 
+    # If a block is passed to this method, that block will be called instead
+    # of invoking each transition's action.
+    def perform(&block)
+      reset
+      
+      if valid?
+        if use_event_attributes? && !block_given?
+          each do |transition|
+            transition.transient = true
+            transition.machine.write(object, :event_transition, transition)
+          end
+          
+          run_actions
+        else
+          within_transaction do
+            catch(:halt) { run_callbacks(&block) }
+            rollback unless success?
+          end
+        end
+      end
+      
+      if actions.length == 1 && results.include?(actions.first)
+        results[actions.first]
+      else
+        success?
+      end
+    end
+    
+    private
+      attr_reader :results #:nodoc:
+      
+      # Is this a valid set of transitions?  If the collection was creating with
+      # any +false+ values for transitions, then the the collection will be
+      # marked as invalid.
+      def valid?
+        @valid
+      end
+      
+      # Did each transition perform successfully?  This will only be true if the
+      # following requirements are met:
+      # * No +before+ callbacks halt
+      # * All actions run successfully (always true if skipping actions)
+      def success?
+        @success
+      end
+      
+      # Gets the object being transitioned
+      def object
+        first.object
+      end
+      
+      # Gets the list of actions to run.  If configured to skip actions, then
+      # this will return an empty collection.
+      def actions
+        empty? ? [nil] : map {|transition| transition.action}.uniq
+      end
+      
+      # Determines whether an event attribute be used to trigger the transitions
+      # in this collection or whether the transitions be run directly *outside*
+      # of the action.
+      def use_event_attributes?
+        !skip_actions && !skip_after && actions.all? && actions.length == 1 && first.machine.action_helper_defined?
+      end
+      
+      # Resets any information tracked from previous attempts to perform the
+      # collection
+      def reset
+        @results = {}
+        @success = false
+      end
+      
+      # Runs each transition's callbacks recursively.  Once all before callbacks
+      # have been executed, the transitions will then be persisted and the
+      # configured actions will be run.
+      # 
+      # If any transition fails to run its callbacks, :halt will be thrown.
+      def run_callbacks(index = 0, &block)
+        if transition = self[index]
+          throw :halt unless transition.run_callbacks(:after => !skip_after) do
+            run_callbacks(index + 1, &block)
+            {:result => results[transition.action], :success => success?}
+          end
+        else
+          persist
+          run_actions(&block)
+        end
+      end
+      
+      # Transitions the current value of the object's states to those specified by
+      # each transition
+      def persist
+        each {|transition| transition.persist}
+      end
+      
+      # Runs the actions for each transition.  If a block is given method, then it
+      # will be called instead of invoking each transition's action.
+      # 
+      # The results of the actions will be used to determine #success?.
+      def run_actions
+        catch_exceptions do
+          @success = if block_given?
+            result = yield
+            actions.each {|action| results[action] = result}
+            !!result
+          else
+            actions.compact.each {|action| !skip_actions && results[action] = object.send(action)}
+            results.values.all?
+          end
+        end
+      end
+      
+      # Rolls back changes made to the object's states via each transition
+      def rollback
+        each {|transition| transition.rollback}
+      end
+      
+      # Wraps the given block with a rescue handler so that any exceptions that
+      # occur will automatically result in the transition rolling back any changes
+      # that were made to the object involved.
+      def catch_exceptions
+        begin
+          yield
+        rescue Exception
+          rollback
+          raise
+        end
+      end
+      
+      # Runs a block within a transaction for the object being transitioned.  If
+      # transactions are disabled, then this is a no-op.
+      def within_transaction
+        if use_transaction && !empty?
+          first.within_transaction do
+            yield
+            success?
+          end
+        else
+          yield
+        end
+      end
+  end
+  
+  # Represents a collection of transitions that were generated from attribute-
+  # based events
+  class AttributeTransitionCollection < TransitionCollection
+    def initialize(transitions = [], options = {}) #:nodoc:
+      super(transitions, {:transaction => false, :actions => false}.merge(options))
+    end
+    
+    private
+      # Hooks into running transition callbacks so that event / event transition
+      # attributes can be properly updated
+      def run_callbacks(index = 0)
+        if index == 0
+          # Clears any traces of the event attribute to prevent it from being
+          # evaluated multiple times if actions are nested
+          each do |transition|
+            transition.machine.write(object, :event, nil)
+            transition.machine.write(object, :event_transition, nil)
+          end
+          
+          # Rollback only if exceptions occur during before callbacks
+          begin
+            super
+          rescue Exception
+            rollback unless @before_run
+            raise
+          end
+          
+          # Persists transitions on the object if partial transition was successful.
+          # This allows us to reference them later to complete the transition with
+          # after callbacks.          
+          each {|transition| transition.machine.write(object, :event_transition, transition)} if skip_after && success?
+        else
+          super
+        end
+      end
+      
+      # Tracks that before callbacks have now completed
+      def persist
+        @before_run = true
+        super
+      end
+      
+      # Resets callback tracking
+      def reset
+        super
+        @before_run = false
+      end
+      
+      # Resets the event attribute so it can be re-evaluated if attempted again
+      def rollback
+        super
+        each {|transition| transition.machine.write(object, :event, transition.event) unless transition.transient?}
+      end
+  end
+end