finite_machine 0.9.1 → 0.9.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 5ce0812460235da2deebb8aafc2d542b33392804
-  data.tar.gz: 89bb6ab79f200d7efaf004ffe9704bbbeb86b5c0
+  metadata.gz: 64cf549e74a02a5036aec535a7be9784a10224bf
+  data.tar.gz: e7733f5805b8989033e229109200b7f69feebe3a
 SHA512:
-  metadata.gz: ed665ca255296e317a683106444e9e4ebc8044f927ea9067c92709fe777787de8b26cfa969e5c42bb2089f16c184d69774729fb06cd6c26d93b645dd1d96b133
-  data.tar.gz: 88538af514156c8a5e899b876e747a0716ab4439c271395418364830cc3372bafcbc772383aaeb3cbecf75c07b0e4087961092eec824c42709d1e40656cfd75f
+  metadata.gz: db31c094295a9ed657daca0960b3299d00ee131a3149ce99750d14b44555e0e5375e5f0e3b5c0d70ecf955a895cd4addafc1b9e99576dd03a21df9ca2b271547
+  data.tar.gz: bff4f5c620276cf7cc664662d0c3aa66e555d1e09fd242e9d22ab5577f0425ee94c4db7bf804e4102a2e99d759eb1180fc04988ccff3fca2368879d4cc02ab1d

data/CHANGELOG.md

@@ -1,3 +1,11 @@
+0.9.2 (September 27, 2014)
+
+* Removes use of class variable to share Sync by @reggieb
+* Fix observer to differentiate between any state and any event
+* [#23] Fix transition to correctly set :from and :to parameters for :any state
+* [#25] Fix passing parameters to choice events with same named events
+* Fix choice pseudostate to work with :any state
+
 0.9.1 (August 10, 2014)
 
 * Add TransitionBuilder to internally build transitions from states

data/Gemfile

@@ -3,8 +3,8 @@ source 'https://rubygems.org'
 gemspec
 
 group :development do
-  gem 'rake',  '~> 10.1.0'
-  gem 'rspec', '~> 3.0.0'
+  gem 'rake',  '~> 10.3.2'
+  gem 'rspec', '~> 3.1.0'
   gem 'yard',  '~> 0.8.7'
 end
 

data/README.md

@@ -1217,15 +1217,23 @@ car.reverse_lights_on? # => true
 
 ### 8.2 ActiveRecord
 
-In order to integrate **FiniteMachine** with ActiveRecord use the `target` helper to reference the current class and call ActiveRecord methods inside the callbacks to persist the state.
+In order to integrate **FiniteMachine** with ActiveRecord simply add a method with state machine definition. You can also define the state machine in separate module to aid reusability. Once the state machine is defined use the `target` helper to reference the current class. Having defined `target` you call ActiveRecord methods inside the callbacks to persist the state.
+
+You can use the `restore!` method to specify which state the **FininteMachine** should be put back into as follows:
 
 ```ruby
 class Account < ActiveRecord::Base
   validates :state, presence: true
 
+  before_validation :set_initial_state, on: :create
+
+  def set_initial_state
+    self.state = manage.current
+  end
+
   def initialize(attrs = {})
     super
-    @manage.restore!(state) if state
+    manage.restore!(state.to_sym) if state.present?
   end
 
   def manage
@@ -1241,7 +1249,7 @@ class Account < ActiveRecord::Base
       }
 
       callbacks {
-        on_enter_state do |event|
+        on_enter do |event|
           target.state = event.to
           target.save
         end
@@ -1258,6 +1266,8 @@ account.manage.authorize
 account.state   # => :access
 ```
 
+Please note that you do not need to call `target.save` inside callback, it is enought to just set the state. It is much more prefereable to let the `ActiveRecord` object to persist when it makes sense for the application and thus keep the state machine focused on managing the state transitions.
+
 ### 8.3 Transactions
 
 When using **FiniteMachine** with ActiveRecord it advisable to trigger state changes inside transactions to ensure integrity of the database. Given Account example from section 8.2 one can run event in transaction in the following way:

data/lib/finite_machine.rb

@@ -31,6 +31,7 @@ require "finite_machine/subscribers"
 require "finite_machine/state_parser"
 require "finite_machine/observer"
 require "finite_machine/listener"
+require "finite_machine/two_phase_lock"
 
 module FiniteMachine
   # Default state name
@@ -43,7 +44,7 @@ module FiniteMachine
   ANY_STATE = :any
 
   # Describe any event name
-  ANY_EVENT = :any
+  ANY_EVENT = :any_event
 
   # Returned when transition has successfully performed
   SUCCEEDED = 1

data/lib/finite_machine/events_chain.rb

@@ -16,7 +16,7 @@ module FiniteMachine
 
     # Initialize a EventsChain
     #
-    # @param [FiniteMachine::StateMachine] machine
+    # @param [StateMachine] machine
     #   the state machine
     #
     # @api public
@@ -30,7 +30,7 @@ module FiniteMachine
     # @param [Symbol] name
     #  the event name
     #
-    # @param [FiniteMachine::Transition]
+    # @param [Transition]
     #
     # @return [nil]
     #
@@ -63,7 +63,7 @@ module FiniteMachine
     # @param [Symbol] name
     #   the event name
     #
-    # @return [FiniteMachine::Transition]
+    # @return [Transition]
     #
     # @api public
     def select_transition(name, *args)
@@ -72,12 +72,19 @@ module FiniteMachine
 
     # Examine choice transitions to find one matching condition
     #
-    # @return [FiniteMachine::Transition]
+    # @param [Symbol] name
+    #   the event name
+    #
+    # @param [Symbol] from_state
+    #   the current context from_state
+    #
+    # @return [Transition]
     #   The choice transition that matches
     #
     # @api public
-    def select_choice_transition(name, *args, &block)
+    def select_choice_transition(name, from_state, *args, &block)
       chain[name].state_transitions.find do |trans|
+        [from_state, ANY_STATE].include?(trans.from_state) &&
         trans.check_conditions(*args, &block)
       end
     end

data/lib/finite_machine/observer.rb

@@ -41,7 +41,9 @@ module FiniteMachine
     def on(event_type = HookEvent, *args, &callback)
       sync_exclusive do
         name, async, _ = args
-        name = ANY_EVENT if name.nil?
+        if name.nil?
+          name = event_type < HookEvent::Anyaction ? ANY_EVENT : ANY_STATE
+        end
         async = false if async.nil?
         ensure_valid_callback_name!(event_type, name)
         callback.extend(Async) if async == :async
@@ -52,7 +54,7 @@ module FiniteMachine
     # Unregister callback for a given event
     #
     # @api public
-    def off(event_type = ANY_EVENT, name = ANY_STATE, &callback)
+    def off(event_type, name = ANY_STATE, &callback)
       sync_exclusive do
         hooks.unregister event_type, name, callback
       end
@@ -107,8 +109,8 @@ module FiniteMachine
     # @api public
     def trigger(event, *args, &block)
       sync_exclusive do
-        [event.type, ANY_EVENT].each do |event_type|
-          [event.name, ANY_STATE].each do |event_name|
+        [event.type].each do |event_type|
+          [event.name, ANY_STATE, ANY_EVENT].each do |event_name|
             hooks.call(event_type, event_name) do |hook|
               handle_callback(hook, event)
               off(event_type, event_name, &hook) if hook.is_a?(Once)
@@ -163,7 +165,7 @@ module FiniteMachine
     #
     # @api private
     def callback_names
-      machine.states + machine.event_names + [ANY_EVENT]
+      machine.states + machine.event_names + [ANY_EVENT, ANY_STATE]
     end
 
     # Forward the message to observer

data/lib/finite_machine/state_machine.rb

@@ -38,6 +38,9 @@ module FiniteMachine
     # The state machine environment
     attr_threadsafe :env
 
+    # The previous state before transition
+    attr_threadsafe :previous_state
+
     # The state machine event definitions
     attr_threadsafe :events_chain
 

data/lib/finite_machine/threadable.rb

@@ -4,7 +4,6 @@ module FiniteMachine
   # A mixin to allow instance methods to be synchronized
   module Threadable
     module InstanceMethods
-      @@sync = Sync.new
 
       # Exclusive lock
       #
@@ -12,7 +11,7 @@ module FiniteMachine
       #
       # @api public
       def sync_exclusive(&block)
-        @@sync.synchronize(:EX, &block)
+        TwoPhaseLock.synchronize(:EX, &block)
       end
 
       # Shared lock
@@ -21,7 +20,7 @@ module FiniteMachine
       #
       # @api public
       def sync_shared(&block)
-        @@sync.synchronize(:SH, &block)
+        TwoPhaseLock.synchronize(:SH, &block)
       end
     end
 

data/lib/finite_machine/transition.rb

@@ -63,12 +63,12 @@ module FiniteMachine
     #
     # @api public
     def self.create(machine, attrs = {})
-      _transition = new(machine, attrs)
-      _transition.update_transitions
-      _transition.define_state_methods
+      transition = new(machine, attrs)
+      transition.update_transitions
+      transition.define_state_methods
 
       builder = EventBuilder.new(machine)
-      builder.call(_transition)
+      builder.call(transition)
     end
 
     # Decide :to state from available transitions for this event
@@ -78,10 +78,11 @@ module FiniteMachine
     # @api public
     def to_state(*args)
       if transition_choice?
-        found_trans = machine.select_choice_transition(name, *args)
-        found_trans.map[from_state]
+        found_trans = machine.select_choice_transition(name, from_state, *args)
+        found_trans.map[from_state] || found_trans.map[ANY_STATE]
       else
-        machine.transitions[name][from_state]
+        available_trans = machine.transitions[name]
+        available_trans[from_state] || available_trans[ANY_STATE]
       end
     end
 
@@ -165,7 +166,7 @@ module FiniteMachine
     # @api private
     def update_transitions
       from_states.each do |from|
-        if value = machine.transitions[name][from]
+        if (value = machine.transitions[name][from])
           machine.transitions[name][from] = [value, map[from]].flatten
         else
           machine.transitions[name][from] = map[from] || ANY_STATE
@@ -205,6 +206,20 @@ module FiniteMachine
       end
     end
 
+    # Find latest from state
+    #
+    # Note that for the exit hook the call hasn't happened yet so
+    # we need to find previous to state when the from is :any.
+    #
+    # @return [Object] from_state
+    #
+    # @api private
+    def latest_from_state
+      sync_shared do
+        from_state == ANY_STATE ? machine.previous_state : from_state
+      end
+    end
+
     # Execute current transition
     #
     # @return [nil]
@@ -215,6 +230,7 @@ module FiniteMachine
         return if cancelled
         self.from_state = machine.state
         update_state(*args)
+        machine.previous_state = machine.state
         machine.initial_state = machine.state if from_state == DEFAULT_STATE
       end
     end

data/lib/finite_machine/transition_event.rb

@@ -2,12 +2,28 @@
 
 module FiniteMachine
   # A class representing a callback transition event
+  #
+  # Used internally by {Observer}
+  #
+  # @api private
   class TransitionEvent
-
+    # This event from state name
+    #
+    # @return [Object]
+    #
+    # @api public
     attr_accessor :from
 
+    # This event to state name
+    #
+    # @return [Object]
+    #
+    # @api public
     attr_accessor :to
 
+    # This event name
+    #
+    # @api public
     attr_accessor :name
 
     # Build a transition event
@@ -20,7 +36,7 @@ module FiniteMachine
     def self.build(transition, *data)
       instance = new
       instance.name = transition.name
-      instance.from = transition.from_state
+      instance.from = transition.latest_from_state
       instance.to   = transition.to_state(*data)
       instance
     end

data/lib/finite_machine/two_phase_lock.rb

@@ -0,0 +1,31 @@
+# encoding: utf-8
+
+module FiniteMachine
+  # Mixin to provide lock to a {Threadable}
+  #
+  # @api private
+  module TwoPhaseLock
+    # Create synchronization lock
+    #
+    # @return [Sync]
+    #
+    # @api private
+    def sync
+      @sync ||= Sync.new
+    end
+
+    # Synchronize given block of code
+    #
+    # @param [Symbol] mode
+    #   the synchronization mode out of :SH and :EX
+    #
+    # @return [nil]
+    #
+    # @api private
+    def synchronize(mode, &block)
+      sync.synchronize(mode, &block)
+    end
+
+    module_function :sync, :synchronize
+  end # TwoPhaseLock
+end # FiniteMachine

data/lib/finite_machine/version.rb

@@ -1,5 +1,5 @@
 # encoding: utf-8
 
 module FiniteMachine
-  VERSION = "0.9.1"
+  VERSION = "0.9.2"
 end

data/spec/unit/callbacks_spec.rb

@@ -429,6 +429,92 @@ describe FiniteMachine, 'callbacks' do
     fsm.go(nil, nil)
   end
 
+  it "sets callback parameters correctly for transition from :any state" do
+    expected = {name: :init, from: :none, to: :green, a: nil, b: nil, c: nil }
+
+    callback = Proc.new { |event, a, b, c|
+      target.expect(event.from).to target.eql(expected[:from])
+      target.expect(event.to).to target.eql(expected[:to])
+      target.expect(event.name).to target.eql(expected[:name])
+      target.expect(a).to target.eql(expected[:a])
+      target.expect(b).to target.eql(expected[:b])
+      target.expect(c).to target.eql(expected[:c])
+    }
+
+    context = self
+
+    fsm = FiniteMachine.define do
+      initial :red
+
+      target context
+
+      events {
+        event :power_on,  :off => :red
+        event :power_off, :any => :off
+        event :go,   :red    => :green
+        event :slow, :green  => :yellow
+        event :stop, :yellow => :red
+      }
+
+      callbacks {
+        # generic state callbacks
+        on_enter(&callback)
+        on_transition(&callback)
+        on_exit(&callback)
+
+        # generic event callbacks
+        on_before(&callback)
+        on_after(&callback)
+
+        # state callbacks
+        on_enter :green,  &callback
+        on_enter :yellow, &callback
+        on_enter :red,    &callback
+        on_enter :off,    &callback
+        on_enter :off,    &callback
+
+        on_transition :green,  &callback
+        on_transition :yellow, &callback
+        on_transition :red,    &callback
+        on_transition :off,    &callback
+        on_transition :off,    &callback
+
+        on_exit :green,  &callback
+        on_exit :yellow, &callback
+        on_exit :red,    &callback
+        on_exit :off,    &callback
+        on_exit :off,    &callback
+
+        # event callbacks
+        on_before :power_on, &callback
+        on_before :power_off, &callback
+        on_before :go,       &callback
+        on_before :slow,     &callback
+        on_before :stop,     &callback
+
+        on_after :power_on, &callback
+        on_after :power_off, &callback
+        on_after :go,       &callback
+        on_after :slow,     &callback
+        on_after :stop,     &callback
+      }
+    end
+
+    expect(fsm.current).to eq(:red)
+
+    expected = {name: :go, from: :red, to: :green, a: 1, b: 2, c: 3 }
+    fsm.go(1, 2, 3)
+
+    expected = {name: :slow, from: :green, to: :yellow, a: 4, b: 5, c: 6}
+    fsm.slow(4, 5, 6)
+
+    expected = {name: :stop, from: :yellow, to: :red, a: 7, b: 8, c: 9}
+    fsm.stop(7, 8, 9)
+
+    expected = {name: :power_off, from: :red, to: :off, a: 10, b: 11, c: 12}
+    fsm.power_off(10, 11, 12)
+  end
+
   it "raises an error with invalid callback name" do
     expect {
       FiniteMachine.define do

data/spec/unit/choice_spec.rb

@@ -184,4 +184,80 @@ describe FiniteMachine, '#choice' do
     fsm.next
     expect(fsm.current).to eq(:green)
   end
+
+  it "sets callback properties correctly" do
+    expected = {name: :init, from: :none, to: :red, a: nil, b: nil, c: nil }
+
+    callback = Proc.new { |event, a, b, c|
+      target.expect(event.from).to target.eql(expected[:from])
+      target.expect(event.to).to target.eql(expected[:to])
+      target.expect(event.name).to target.eql(expected[:name])
+      target.expect(a).to target.eql(expected[:a])
+      target.expect(b).to target.eql(expected[:b])
+      target.expect(c).to target.eql(expected[:c])
+    }
+
+    context = self
+
+    fsm = FiniteMachine.define do
+      initial :red
+
+      target context
+
+      events {
+        event :next, from: :red do
+          choice :green, if: -> { false }
+          choice :yellow
+        end
+
+        event :next, from: :yellow do
+          choice :green, if: -> { true }
+          choice :yellow
+        end
+
+        event :finish, from: :any do
+          choice :green, if: -> { false }
+          choice :red
+        end
+      }
+
+      callbacks {
+        # generic state callbacks
+        on_enter(&callback)
+        on_transition(&callback)
+        on_exit(&callback)
+
+        # generic event callbacks
+        on_before(&callback)
+        on_after(&callback)
+
+        # state callbacks
+        on_enter :green,  &callback
+        on_enter :yellow, &callback
+        on_enter :red,    &callback
+
+        on_transition :green,  &callback
+        on_transition :yellow, &callback
+        on_transition :red,    &callback
+
+        on_exit :green,  &callback
+        on_exit :yellow, &callback
+        on_exit :red,    &callback
+
+        # event callbacks
+        on_before :next, &callback
+        on_after  :next, &callback
+      }
+    end
+    expect(fsm.current).to eq(:red)
+
+    expected = {name: :next, from: :red, to: :yellow, a: 1, b: 2, c: 3}
+    fsm.next(1, 2, 3)
+
+    expected = {name: :next, from: :yellow, to: :green, a: 4, b: 5, c: 6}
+    fsm.next(4, 5, 6)
+
+    expected = {name: :finish, from: :green, to: :red, a: 7, b: 8, c: 9}
+    fsm.finish(7, 8, 9)
+  end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: finite_machine
 version: !ruby/object:Gem::Version
-  version: 0.9.1
+  version: 0.9.2
 platform: ruby
 authors:
 - Piotr Murach
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-08-10 00:00:00.000000000 Z
+date: 2014-09-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -72,6 +72,7 @@ files:
 - lib/finite_machine/transition.rb
 - lib/finite_machine/transition_builder.rb
 - lib/finite_machine/transition_event.rb
+- lib/finite_machine/two_phase_lock.rb
 - lib/finite_machine/version.rb
 - spec/spec_helper.rb
 - spec/unit/async_events_spec.rb