finite_machine 0.2.0 → 0.3.0

data/lib/finite_machine/state_machine.rb

@@ -6,6 +6,7 @@ module FiniteMachine
   class StateMachine
     include Threadable
     include Catchable
+    include ThreadContext
 
     # Initial state, defaults to :none
     attr_threadsafe :initial_state
@@ -51,8 +52,13 @@ module FiniteMachine
       @dsl = DSL.new self
       @dsl.call(&block) if block_given?
       send(:"#{@dsl.initial_event}") unless @dsl.defer
+      self.event_queue = FiniteMachine::EventQueue.new
     end
 
+    # @example
+    #   machine.subscribe(Observer.new(machine))
+    #
+    # @api public
     def subscribe(*observers)
       @subscribers.subscribe(*observers)
     end
@@ -70,6 +76,30 @@ module FiniteMachine
       end
     end
 
+    # Help to mark the event as synchronous
+    #
+    # @example
+    #   fsm.sync.go
+    #
+    # @return [self]
+    #
+    # @api public
+    alias_method :sync, :method_missing
+
+    # Explicitly invoke event on proxy or delegate to proxy
+    #
+    # @return [AsyncProxy]
+    #
+    # @api public
+    def async(method_name = nil, *args, &block)
+      @async_proxy = AsyncProxy.new(self)
+      if method_name
+        @async_proxy.method_missing method_name, *args, &block
+      else
+        @async_proxy
+      end
+    end
+
     # Get current state
     #
     # @return [String]
@@ -79,7 +109,10 @@ module FiniteMachine
       state
     end
 
-    # Check if current state machtes provided state
+    # Check if current state matches provided state
+    #
+    # @example
+    #   fsm.is?(:green) # => true
     #
     # @param [String, Array[String]] state
     #
@@ -96,6 +129,9 @@ module FiniteMachine
 
     # Retrieve all states
     #
+    # @example
+    #  fsm.states # => [:yellow, :green, :red]
+    #
     # @return [Array[Symbol]]
     #
     # @api public
@@ -114,6 +150,9 @@ module FiniteMachine
 
     # Checks if event can be triggered
     #
+    # @example
+    #   fsm.can?(:go) # => true
+    #
     # @param [String] event
     #
     # @return [Boolean]
@@ -125,6 +164,9 @@ module FiniteMachine
 
     # Checks if event cannot be triggered
     #
+    # @example
+    #   fsm.cannot?(:go) # => false
+    #
     # @param [String] event
     #
     # @return [Boolean]
@@ -160,6 +202,12 @@ module FiniteMachine
 
     # Performs transition
     #
+    # @param [Transition] _transition
+    # @param [Array] args
+    #
+    # @return [Integer]
+    #   the status code for the transition
+    #
     # @api private
     def transition(_transition, *args, &block)
       return CANCELLED if valid_state?(_transition)
@@ -191,14 +239,34 @@ module FiniteMachine
       SUCCEEDED
     end
 
+    # Forward the message to target, observer or self
+    #
+    # @param [String] method_name
+    #
+    # @param [Array] args
+    #
+    # @return [self]
+    #
+    # @api private
     def method_missing(method_name, *args, &block)
       if env.target.respond_to?(method_name.to_sym)
-        env.target.send(method_name.to_sym, *args, &block)
+        env.target.public_send(method_name.to_sym, *args, &block)
+      elsif observer.respond_to?(method_name.to_sym)
+        observer.public_send(method_name.to_sym, *args, &block)
       else
         super
       end
     end
 
+    # Test if a message can be handled by state machine
+    #
+    # @param [String] method_name
+    #
+    # @param [Boolean] include_private
+    #
+    # @return [Boolean]
+    #
+    # @api private
     def respond_to_missing?(method_name, include_private = false)
       env.target.respond_to?(method_name.to_sym)
     end

data/lib/finite_machine/subscribers.rb

@@ -1,15 +1,18 @@
 # encoding: utf-8
 
+require 'monitor'
+
 module FiniteMachine
 
   # A class responsibile for storage of event subscribers
   class Subscribers
     include Enumerable
+    include MonitorMixin
 
     def initialize(machine)
+      super()
       @machine     = machine
       @subscribers = []
-      @mutex       = Mutex.new
     end
 
     def each(&block)
@@ -29,7 +32,7 @@ module FiniteMachine
     end
 
     def visit(event)
-      each { |subscriber| event.notify subscriber }
+      each { |subscriber| synchronize { event.notify subscriber } }
     end
 
     def reset

data/lib/finite_machine/thread_context.rb

@@ -0,0 +1,16 @@
+# encoding: utf-8
+
+module FiniteMachine
+
+  # A mixin to allow sharing of thread context
+  module ThreadContext
+
+    def event_queue
+      Thread.current[:finite_machine_event_queue]
+    end
+
+    def event_queue=(value)
+      Thread.current[:finite_machine_event_queue] = value
+    end
+  end # ThreadContext
+end # FiniteMachine

data/lib/finite_machine/threadable.rb

@@ -7,15 +7,30 @@ module FiniteMachine
     module InstanceMethods
       @@sync = Sync.new
 
+      # Exclusive lock
+      #
+      # @return [nil]
+      #
+      # @api public
       def sync_exclusive(&block)
         @@sync.synchronize(:EX, &block)
       end
 
+      # Shared lock
+      #
+      # @return [nil]
+      #
+      # @api public
       def sync_shared(&block)
         @@sync.synchronize(:SH, &block)
       end
     end
 
+    # Module hook
+    #
+    # @return [nil]
+    #
+    # @api private
     def self.included(base)
       base.extend ClassMethods
       base.module_eval do
@@ -23,17 +38,35 @@ module FiniteMachine
       end
     end
 
+    private_class_method :included
+
     module ClassMethods
       include InstanceMethods
 
+      # Defines threadsafe attributes for a class
+      #
+      # @example
+      #   attr_threadable :errors, :events
+      #
+      # @example
+      #   attr_threadable :errors, default: []
+      #
+      # @return [nil]
+      #
+      # @api public
       def attr_threadsafe(*attrs)
+        opts    = attrs.last.is_a?(::Hash) ? attrs.pop : {}
+        default = opts.fetch(:default, nil)
         attrs.flatten.each do |attr|
           class_eval <<-RUBY_EVAL, __FILE__, __LINE__ + 1
             def #{attr}(*args)
-              if args.empty?
+              value = args.shift
+              if value
+                self.#{attr} = value
+              elsif instance_variables.include?(:@#{attr})
                 sync_shared { @#{attr} }
-              else
-                self.#{attr} = args.shift
+              elsif #{!default.nil?}
+                sync_shared { instance_variable_set(:@#{attr}, #{default}) }
               end
             end
             alias_method '#{attr}?', '#{attr}'

data/lib/finite_machine/transition.rb

@@ -1,7 +1,6 @@
 # encoding: utf-8
 
 module FiniteMachine
-
   # Class describing a transition associated with a given event
   class Transition
     include Threadable
@@ -25,6 +24,9 @@ module FiniteMachine
 
     # Initialize a Transition
     #
+    # @param [StateMachine] machine
+    # @param [Hash] attrs
+    #
     # @api public
     def initialize(machine, attrs = {})
       @machine    = machine
@@ -36,6 +38,9 @@ module FiniteMachine
       @conditions = make_conditions
     end
 
+    # Reduce conditions
+    #
+    # @api private
     def make_conditions
       @if.map { |c| Callable.new(c) } +
         @unless.map { |c| Callable.new(c).invert }
@@ -43,6 +48,8 @@ module FiniteMachine
 
     # Extract states from attributes
     #
+    # @param [Hash] attrs
+    #
     # @api private
     def parse_states(attrs)
       _attrs = attrs.dup
@@ -67,19 +74,44 @@ module FiniteMachine
       end
     end
 
+    # Define helper state mehods for the transition states
+    #
+    # @api private
+    def define_state_methods
+      from.concat([to]).each { |state| define_state_method(state) }
+    end
+
+    # Define state helper method
+    #
+    # @param [Symbol] state
+    #
+    # @api private
+    def define_state_method(state)
+      return if machine.respond_to?("#{state}?")
+      machine.send(:define_singleton_method, "#{state}?") do
+        machine.is?(state.to_sym)
+      end
+    end
+
     # Define event on the machine
     #
     # @api private
     def define_event
       _transition = self
-      # TODO check if event is already defined and raise error
-      machine.class.__send__(:define_method, name) do |*args, &block|
+      _name       = name
+
+      machine.singleton_class.class_eval do
+        undef_method(_name) if method_defined?(_name)
+      end
+      machine.send(:define_singleton_method, name) do |*args, &block|
         transition(_transition, *args, &block)
       end
     end
 
     # Execute current transition
     #
+    # @return [nil]
+    #
     # @api private
     def call
       sync_exclusive do
@@ -96,6 +128,11 @@ module FiniteMachine
       @name
     end
 
+    # Return string representation
+    #
+    # @return [String]
+    #
+    # @api public
     def inspect
       "<#{self.class} name: #{@name}, transitions: #{@from} => #{@to}, when: #{@conditions}>"
     end
@@ -104,10 +141,16 @@ module FiniteMachine
 
     # Raise error when not enough transitions are provided
     #
+    # @param [Hash] attrs
+    #
+    # @raise [NotEnoughTransitionsError]
+    #   if the event has not enough transition arguments
+    #
+    # @return [nil]
+    #
     # @api private
     def raise_not_enough_transitions(attrs)
       raise NotEnoughTransitionsError, "please provide state transitions for '#{attrs.inspect}'"
     end
-
   end # Transition
 end # FiniteMachine

data/lib/finite_machine/version.rb

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

data/spec/spec_helper.rb

@@ -1,5 +1,20 @@
 # encoding: utf-8
 
+if RUBY_VERSION > '1.9' and (ENV['COVERAGE'] || ENV['TRAVIS'])
+  require 'simplecov'
+  require 'coveralls'
+
+  SimpleCov.formatter = SimpleCov::Formatter::MultiFormatter[
+    SimpleCov::Formatter::HTMLFormatter,
+    Coveralls::SimpleCov::Formatter
+  ]
+
+  SimpleCov.start do
+    command_name 'spec'
+    add_filter 'spec'
+  end
+end
+
 require 'finite_machine'
 
 RSpec.configure do |config|

data/spec/unit/async_events_spec.rb

@@ -0,0 +1,68 @@
+# encoding: utf-8
+
+require 'spec_helper'
+
+describe FiniteMachine, 'async_events' do
+
+  it 'runs events asynchronously' do
+    called = []
+    fsm = FiniteMachine.define do
+      initial :green
+
+      events {
+        event :slow, :green => :yellow
+        event :stop, :yellow => :red
+        event :ready, :red    => :yellow
+        event :go,    :yellow => :green
+      }
+
+      callbacks {
+        on_enter :yellow do |event, a| called << "on_enter_yellow_#{a}" end
+        on_enter :red    do |event, a| called << "on_enter_red_#{a}" end
+      }
+    end
+
+    expect(fsm.current).to eql(:green)
+    fsm.async.slow(:foo)
+    fsm.event_queue.join 0.01
+    expect(fsm.current).to eql(:yellow)
+    expect(called).to eql([
+      'on_enter_yellow_foo'
+    ])
+    fsm.async.stop(:bar)
+    fsm.event_queue.join 0.01
+    expect(fsm.current).to eql(:red)
+    expect(called).to eql([
+      'on_enter_yellow_foo',
+      'on_enter_red_bar'
+    ])
+  end
+
+  it "ensure queue per thread" do
+    called = []
+    fsmFoo = FiniteMachine.define do
+      initial :green
+      events { event :slow, :green => :yellow }
+
+      callbacks {
+        on_enter :yellow do |event, a| called << "(foo)on_enter_yellow_#{a}" end
+      }
+    end
+    fsmBar = FiniteMachine.define do
+      initial :green
+      events { event :slow, :green => :yellow }
+
+      callbacks {
+        on_enter :yellow do |event, a| called << "(bar)on_enter_yellow_#{a}" end
+      }
+    end
+    fsmFoo.slow(:foo)
+    fsmBar.slow(:bar)
+    fsmFoo.event_queue.join 0.01
+    fsmBar.event_queue.join 0.01
+    expect(called).to include('(foo)on_enter_yellow_foo')
+    expect(called).to include('(bar)on_enter_yellow_bar')
+    expect(fsmFoo.current).to eql(:yellow)
+    expect(fsmBar.current).to eql(:yellow)
+  end
+end