motion-state-machine 0.8.1

data/lib/motion-state-machine/version.rb

@@ -0,0 +1,3 @@
+module StateMachine
+  VERSION = "0.8.1"
+end

data/motion-state-machine.gemspec

@@ -0,0 +1,19 @@
+# -*- encoding: utf-8 -*-
+require File.expand_path('../lib/motion-state-machine/version', __FILE__)
+
+Gem::Specification.new do |gem|
+  gem.authors       = ["Sebastian Burkhart"]
+  gem.email         = ["sebastianburkhart@me.com"]
+  gem.description   = %q{A finite state machine for RubyMotion with a flavor of Grand Central Dispatch.}
+  gem.summary       = %q{Comes with a nice syntax for state and transition definition. Supports triggering via events, timeouts and NSNotifications.}
+  gem.homepage      = "https://github.com/opyh/motion-state-machine"
+
+  gem.files         = `git ls-files`.split($\)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.name          = "motion-state-machine"
+  gem.require_paths = ["lib"]
+  gem.version       = StateMachine::VERSION
+
+  gem.add_development_dependency 'rake'
+end

data/spec/motion-state-machine/base_spec.rb

@@ -0,0 +1,118 @@
+describe StateMachine::Base do
+
+  describe "#initialize" do
+
+    it "should raise if not given a start state" do
+      lambda {state_machine = StateMachine::Base.new}.
+        should.raise(ArgumentError)
+    end
+
+    describe "when given a start state" do
+      before do
+        @fsm = StateMachine::Base.new start_state: :start
+      end
+
+      it "should initialize and use the internal state dictionary" do
+        dictionary = @fsm.instance_variable_get(:@state_symbols_to_states)
+        dictionary.class.should == Hash
+      end
+
+      it "should create an internal waiting_for_start state" do
+        dictionary = @fsm.instance_variable_get(:@state_symbols_to_states)
+        dictionary.count.should == 2
+        state = dictionary[:waiting_for_start]
+        state.class.should == StateMachine::State
+        state.transition_map.count.should == 1
+        transition = state.transition_map[:on][:start].first
+        transition.options[:from].should == :waiting_for_start
+        transition.options[:to].should ==:start
+      end
+
+      it "should set its current state to :waiting_for_start" do
+        state = @fsm.current_state
+        state.class.should == StateMachine::State
+        state.symbol.should == :waiting_for_start
+      end
+    end
+
+  end
+
+  describe "after correct initialization" do
+
+    before do
+      @fsm = StateMachine::Base.new start_state: :awake
+      @fsm.when(:awake) do |state|
+        state.die :on => :terminate
+      end
+    end
+
+    describe "#state(symbol, name = nil)" do
+      it "should create & return a new state for the given symbol if not existing" do
+        states_hash = @fsm.instance_variable_get(:@state_symbols_to_states)
+        state_count_before = states_hash.count
+        states_hash.has_key?(:some_other_state).should == false
+        state = @fsm.state(:some_other_state, "Fake State")
+        state.class.should == StateMachine::State
+        states_hash.count.should == state_count_before + 1
+        states_hash.has_key?(:some_other_state).should == true
+        state.name.should == "Fake State"
+      end
+
+      it "should return the state with the given symbol if existing" do
+        states_hash = @fsm.instance_variable_get(:@state_symbols_to_states)
+        state_count_before = states_hash.count
+        states_hash[:foo] = "bar"
+        states_hash.count.should == state_count_before + 1
+        @fsm.state(:foo).should == "bar"
+        states_hash.count.should == state_count_before + 1
+      end
+    end
+
+    describe "#start!" do
+      it "should remember the initial queue if called from main queue" do
+        Dispatch::Queue.current.to_s.should == Dispatch::Queue.main.to_s
+        @fsm.start!
+        @fsm.initial_queue.to_s.should == Dispatch::Queue.main.to_s
+      end
+
+      it "should remember the initial queue if called from another queue" do
+        other_queue = Dispatch::Queue.concurrent(:default)
+        other_queue.to_s.should != Dispatch::Queue.main.to_s
+        other_queue.sync do
+          @fsm.start!
+        end
+        @fsm.initial_queue.to_s.should == other_queue.to_s
+      end
+
+      it "should change the current state to the start state" do
+        @fsm.current_state.symbol.should == :waiting_for_start
+        @fsm.start!
+        @fsm.current_state.symbol.should == :awake
+      end
+    end
+
+    describe "#terminated?" do
+      it "should return false until the machine is terminated" do
+        @fsm.current_state.symbol.should == :waiting_for_start
+        @fsm.terminated?.should == false
+        @fsm.start!
+        @fsm.current_state.symbol.should == :awake
+        @fsm.terminated?.should == false
+        @fsm.event(:terminate)
+        @fsm.terminated?.should == true
+      end
+    end
+
+    # describe "#stop_and_cleanup" do
+    #   it "should unregister all notifications"
+    #   it "should remove references to self from all registered states"
+    # end
+
+    # it "should not be too slow"
+    #
+    # it "should be thread-safe"
+
+  end
+
+
+end

data/spec/motion-state-machine/benchmark_spec.rb

@@ -0,0 +1,74 @@
+# Benchmark that checks if the machine is fast enough.
+# If it should ever happen that some implementation change
+# slows it down, this spec will be red.
+
+# Test state machine that loops in 3 states.
+
+class LoopingThreeStateMachine < StateMachine::Base
+	attr_accessor :steps, :loops
+	attr_accessor :is_dead
+
+	def initialize
+    super(start_state: :first_state)
+
+    @steps = 0
+    @loops = 0
+
+		self.when :first_state do |state|
+      state.transition_to :second_state, on: :next,
+        action: proc { @steps += 1 }
+    end
+
+  	self.when :second_state do |state|
+      state.transition_to :third_state, on: :next,
+        action: proc { @steps += 1 }
+    end
+
+  	self.when :third_state do |state|
+      state.transition_to :first_state, on: :next,
+        action: proc { @steps += 1; @loops += 1 }
+    end
+
+    self
+  end
+end
+
+describe LoopingThreeStateMachine do
+  before do
+    @fsm = LoopingThreeStateMachine.new
+  end
+
+  it "should loop correctly" do
+    @fsm.start!
+    100.times { @fsm.event :next }
+    @fsm.steps.should == 100
+    @fsm.loops.should == @fsm.steps / 3
+  end
+
+  it "should prove that the state machine can handle more than 10k events per second" do
+    other_queue = Dispatch::Queue.new('org.screenfashion.motion-state-machine')
+    other_queue.sync { @fsm.start! }
+    started_on = NSDate.date
+    dispatch_group = Dispatch::Group.new
+    event_count = 100000
+
+    event_count.times do |i|
+      other_queue.async(dispatch_group) { @fsm.event :next }
+    end
+
+    send_time = NSDate.date.timeIntervalSinceDate started_on
+
+    dispatch_group.wait # wait for the events to be handled
+
+    handle_time = NSDate.date.timeIntervalSinceDate started_on
+
+    send_time.should < 0.2
+
+    frequency = event_count / handle_time
+    frequency.should > 10000
+
+    puts "\nNeeded #{send_time}s to send #{event_count} events, #{handle_time}s to handle them."
+    puts "That's a frequency of #{frequency} state changes per second.\n"
+  end
+
+end

data/spec/motion-state-machine/notification_transition_spec.rb

@@ -0,0 +1,57 @@
+describe StateMachine::NotificationTransition do
+
+  before do
+    @state_machine = StateMachine::Base.new start_state: :awaiting_notification
+    action = proc {@fired = true}
+    @state_machine.when :awaiting_notification do |state|
+      @transition = state.transition_to(:notified, on_notification: "SomeNotification", action: action).first
+      state.transition_to :canceled, on: :cancel
+    end
+  end
+
+  it "should be created correctly" do
+    @transition.should.is_a(StateMachine::NotificationTransition)
+  end
+
+  describe "when running in main queue" do
+    it "should be executed when receiving the notification and unarm correctly" do
+      @fired = false
+      @state_machine.start! # will arm the transition
+      @state_machine.current_state.symbol.should == :awaiting_notification
+      @fired.should == false
+
+      NSNotificationCenter.defaultCenter.postNotificationName "SomeNotification", object: nil
+      @state_machine.current_state.symbol.should == :notified
+      @fired.should == true
+      @fired = false
+
+      NSNotificationCenter.defaultCenter.postNotificationName "SomeNotification", object: nil
+      @state_machine.current_state.symbol.should == :notified
+      @fired.should == false
+    end
+  end
+
+  describe "when running in other queue" do
+    it "should be executed when receiving the notification and unarm correctly" do
+      @fired = false
+
+      other_queue = Dispatch::Queue.concurrent
+      other_queue.sync do
+        @state_machine.start! # will arm the transition
+      end
+      @state_machine.current_state.symbol.should == :awaiting_notification
+      @fired.should == false
+
+      NSNotificationCenter.defaultCenter.postNotificationName "SomeNotification", object: nil
+      sleep 0.1
+      @state_machine.current_state.symbol.should == :notified
+      @fired.should == true
+      @fired = false
+
+      NSNotificationCenter.defaultCenter.postNotificationName "SomeNotification", object: nil
+      @state_machine.current_state.symbol.should == :notified
+      @fired.should == false
+    end
+  end
+
+end

data/spec/motion-state-machine/send_event_transition_spec.rb

@@ -0,0 +1,53 @@
+describe StateMachine::SendEventTransition do
+  before do
+    @state_machine = StateMachine::Base.new start_state: :awake
+    @source_state = @state_machine.state :awake
+    @destination_state = @state_machine.state :tired
+    @options = {
+      state_machine: @state_machine,
+      from: :awake,
+      to: :tired,
+      type: :on,
+      on: :work_done
+    }
+    @transition = StateMachine::Transition.make @options
+  end
+
+  it "should correctly register in the factory" do
+    @transition.should.is_a(StateMachine::SendEventTransition)
+  end
+
+  describe "#initialize(options)" do
+    it "should not arm the transition" do
+      @state_machine.event(:work_done)
+      @state_machine.current_state.symbol.should == :waiting_for_start
+    end
+  end
+
+  describe "#arm" do
+    it "should execute the transition when the event is sent to the state machine" do
+      @state_machine.start!
+      @state_machine.current_state.symbol.should == :awake
+      @state_machine.event(:work_done)
+      @state_machine.current_state.symbol.should == :awake
+      @transition.arm
+      # necessary for the event to work
+      @source_state.register(@transition)
+      @state_machine.event(:work_done)
+      @state_machine.current_state.symbol.should == :tired
+    end
+  end
+
+  describe "#unarm" do
+    it "should make sure the transition is not executed when the event is sent to the state machine" do
+      transition = StateMachine::Transition.make @options
+      @state_machine.start!
+      @state_machine.current_state.symbol.should == :awake
+      @transition.unarm
+      @source_state.register(@transition)
+      @state_machine.event(:work_done)
+      @state_machine.current_state.symbol.should == :awake
+    end
+  end
+
+end

data/spec/motion-state-machine/state_spec.rb

@@ -0,0 +1,219 @@
+describe StateMachine::State do
+  before do
+    @living = StateMachine::State.new "stub", symbol: :awake, name: "Living"
+  end
+
+  describe "Entering/exiting" do
+    before do
+      # These seem not to be correctly deinitialized after single specs,
+      # so we have to reinitialize them ourselves.
+
+      @entry_action_called = false
+      @other_entry_action_called = false
+      @exit_action_called = false
+      @other_exit_action_called = false
+
+      @state_machine = StateMachine::Base.new start_state: :awake
+      @state_machine.when(:awake) do |state|
+        state.transition_to :tired, on: :work_done
+        state.on_exit do
+          @exit_action_called = true
+        end
+        state.on_exit do
+          @other_exit_action_called = true
+        end
+      end
+      @state_machine.when(:tired) do |state|
+        state.transition_to :very_excited, on: :something_happened
+        state.on_entry do
+          @entry_action_called = true
+        end
+        state.on_entry do
+          @other_entry_action_called = true
+        end
+      end
+
+      @state_machine.start!
+      @state_machine.current_state.symbol.should == :awake
+    end
+
+    describe "#enter!" do
+      it "should set the state machine's current state" do
+        @state_machine.state(:tired).send :enter!
+        @state_machine.current_state.symbol.should == :tired
+      end
+
+      it "should execute the entry actions" do
+        @entry_action_called.should == false
+        @other_entry_action_called.should == false
+        @state_machine.event(:work_done)
+        @entry_action_called.should == true
+        @other_entry_action_called.should == true
+      end
+
+      it "should arm the transitions" do
+        @state_machine.event(:something_happened) # should be ignored
+        @state_machine.current_state.symbol.should == :awake
+        @state_machine.event(:work_done)
+        @state_machine.current_state.symbol.should == :tired
+        @state_machine.event(:something_happened)
+        @state_machine.current_state.symbol.should == :very_excited
+      end
+
+    end
+
+    describe "#exit!" do
+      it "should set the state machine's current state to nil" do
+        @state_machine.state(:awake).send :exit!
+        @state_machine.current_state.should == nil
+      end
+
+      it "should execute the exit actions" do
+        @exit_action_called.should == false
+        @other_exit_action_called.should == false
+        @state_machine.event(:work_done)
+        @exit_action_called.should == true
+        @other_exit_action_called.should == true
+      end
+
+      it "should unarm the transitions" do
+        @state_machine.state(:awake).send :exit!
+        @state_machine.event(:work_done) # should be ignored
+        @state_machine.current_state.should == nil
+      end
+    end
+
+  end
+
+  describe "#guarded_execute(options)" do
+    before do
+      @state_machine = StateMachine::Base.new start_state: :awake
+    end
+    it "should not do anything when on a terminating state" do
+      @state_machine.when :awake do |state|
+        state.die on: :kill
+      end
+      @state_machine.start!
+      @state_machine.current_state.symbol.should == :awake
+      @state_machine.current_state.send :guarded_execute, :on, :kill
+      @state_machine.current_state.should.be.terminating
+    end
+
+    describe ":if and :unless guards" do
+
+      # if/unless logic table is tested in transition specs
+
+      it "should raise if multiple non-guarded transitions would be possible for the same event" do
+        @state_machine.when :awake do |state|
+          state.transition_to :state2, on: :work_done
+          state.transition_to :state3, on: :work_done
+        end
+        @state_machine.start!
+        lambda {@state_machine.current_state.send :guarded_execute, :on, :work_done}.should.raise RuntimeError
+      end
+
+      it "should raise if multiple guarded transitions would be possible for the same event" do
+        @state_machine.when :awake do |state|
+          state.transition_to :state2, on: :work_done, :if => proc { true }
+          state.transition_to :state3, on: :work_done, :if => proc { true }
+        end
+        @state_machine.start!
+        lambda {@state_machine.current_state.send :guarded_execute, :on, :work_done}.should.raise RuntimeError
+      end
+
+      it "should execute right transition of multiple are allowed" do
+        @state_machine.when :awake do |state|
+          state.transition_to :state2, on: :work_done, :if => proc { false }
+          state.transition_to :state3, on: :work_done, :if => proc { true }
+        end
+        @state_machine.start!
+        @state_machine.current_state.send :guarded_execute, :on, :work_done
+        @state_machine.current_state.symbol.should == :state3
+      end
+
+      it "should not execute any transition if all are disallowed" do
+        @state_machine.when :awake do |state|
+          state.transition_to :state2, on: :work_done, :if => proc { false }
+          state.transition_to :state3, on: :work_done, :if => proc { false }
+        end
+        @state_machine.start!
+        @state_machine.current_state.send :guarded_execute, :on, :work_done
+        @state_machine.current_state.symbol.should == :awake
+      end
+
+    end
+
+  end
+
+  describe "Definition DSL" do
+    before do
+      @state_machine = StateMachine::Base.new start_state: :awake
+    end
+
+    describe "#transition_to" do
+      it "should return an array of created transitions" do
+        @state_machine.when(:awake) do |state|
+          transitions = state.transition_to(:tired, after: 42)
+          transitions.class.should == Array
+          transitions.first.class.should == StateMachine::TimedTransition
+        end
+      end
+
+      describe "Argument error handling" do
+        it "should raise if not given a destination state symbol" do
+          proc do
+            @state_machine.when(:awake) do |state|
+              state.transition_to Hash.new, on: :eat
+            end
+          end.should.raise ArgumentError, /No destination state given/
+        end
+
+        it "should raise if not given a trigger event" do
+          proc do
+            @state_machine.when(:awake) do |state|
+              state.transition_to :sleepy
+            end
+          end.should.raise ArgumentError, /No trigger event/
+        end
+
+        it "should create the destination state if not existent" do
+          created = proc {@state_machine.states.collect(&:symbol).include?(:sleepy)}
+          created.call.should == false
+          @state_machine.when(:awake) do |state|
+            state.transition_to :sleepy, on: :hard_work_done
+          end
+          created.call.should == true
+        end
+      end
+    end
+
+    describe "#die" do
+      it "should return an array of created transitions" do
+        @state_machine.when(:awake) do |state|
+          transitions = state.die(on: :eat)
+          transitions.class.should == Array
+          transitions.first.class.should == StateMachine::SendEventTransition
+        end
+      end
+
+      it "should create termination states with different symbols" do
+        @state_machine.when(:awake) do |state|
+          # so many options!
+          transitions1 = state.die on: :suffocation
+          transitions2 = state.die on: :starving
+          transitions1.first.destination_state.symbol.should != transitions2.first.destination_state.symbol
+        end
+      end
+
+      it "should set the termination states' terminating flags" do
+        @state_machine.when(:awake) do |state|
+          non_terminating_transitions = state.transition_to :tired, on: :work_done
+          terminating_transitions = state.die on: :suffocation
+          non_terminating_transitions.first.destination_state.should.not.be.terminating
+          terminating_transitions.first.destination_state.should.be.terminating
+        end
+      end
+    end
+  end
+
+end