finite_machine 0.2.0 → 0.3.0

data/finite_machine.gemspec

@@ -18,7 +18,5 @@ Gem::Specification.new do |spec|
   spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
   spec.require_paths = ["lib"]
 
-  spec.add_development_dependency "bundler", "~> 1.3"
-  spec.add_development_dependency "rake"
-  spec.add_development_dependency "rspec"
+  spec.add_development_dependency "bundler", "~> 1.5"
 end

data/lib/finite_machine.rb

@@ -5,9 +5,13 @@ require "sync"
 
 require "finite_machine/version"
 require "finite_machine/threadable"
+require "finite_machine/thread_context"
 require "finite_machine/callable"
 require "finite_machine/catchable"
+require "finite_machine/async_proxy"
+require "finite_machine/async_call"
 require "finite_machine/event"
+require "finite_machine/event_queue"
 require "finite_machine/hooks"
 require "finite_machine/transition"
 require "finite_machine/dsl"
@@ -59,5 +63,4 @@ module FiniteMachine
   def self.define(*args, &block)
     StateMachine.new(*args, &block)
   end
-
 end # FiniteMachine

data/lib/finite_machine/async_call.rb

@@ -0,0 +1,47 @@
+# encoding: utf-8
+
+module FiniteMachine
+  # An asynchronouse call representation
+  class AsyncCall
+    include Threadable
+
+    attr_threadsafe :context
+
+    attr_threadsafe :callable
+
+    attr_threadsafe :arguments
+
+    attr_threadsafe :block
+
+    # Build asynchronous call instance
+    #
+    # @param [Object] context
+    # @param [Callable] callable
+    # @param [Array] args
+    # @param [#call] block
+    #
+    # @example
+    #   AsyncCall.build(self, Callable.new(:method), :a, :b)
+    #
+    # @return [self]
+    #
+    # @api public
+    def self.build(context, callable, *args, &block)
+      instance = new
+      instance.context = context
+      instance.callable = callable
+      instance.arguments = *args
+      instance.block = block
+      instance
+    end
+
+    # Dispatch the event to the context
+    #
+    # @return [nil]
+    #
+    # @api private
+    def dispatch
+      callable.call(context, *arguments, block)
+    end
+  end # AsyncCall
+end # FiniteMachine

data/lib/finite_machine/async_proxy.rb

@@ -0,0 +1,28 @@
+# encoding: utf-8
+
+module FiniteMachine
+  # An asynchronous messages proxy
+  class AsyncProxy
+    include Threadable
+    include ThreadContext
+
+    attr_threadsafe :context
+
+    # Initialize an AsynxProxy
+    #
+    # @param [Object] context
+    #   the context this proxy is associated with
+    #
+    # @api private
+    def initialize(context)
+      self.context = context
+    end
+
+    # Delegate asynchronous event to event queue
+    #
+    # @api private
+    def method_missing(method_name, *args, &block)
+      event_queue << AsyncCall.build(context, Callable.new(method_name), *args, &block)
+    end
+  end # AsyncProxy
+end # FiniteMachine

data/lib/finite_machine/callable.rb

@@ -1,7 +1,6 @@
 # encoding: utf-8
 
 module FiniteMachine
-
   # A generic interface for executing strings, symbol methods or procs.
   class Callable
 
@@ -21,7 +20,7 @@ module FiniteMachine
     #
     # @api public
     def invert
-      lambda { |*args, &block|  !self.call(*args, &block) }
+      lambda { |*args, &block|  !call(*args, &block) }
     end
 
     # Execute action
@@ -32,14 +31,15 @@ module FiniteMachine
     def call(target, *args, &block)
       case object
       when Symbol
-        target.__send__(@object.to_sym)
+        target.public_send(object.to_sym, *args, &block)
       when String
-        value = eval "lambda { #{@object} }"
+        string = args.empty? ? "-> { #{object} }" : "-> { #{object}(*#{args}) }"
+        value  = eval string
         target.instance_exec(&value)
       when ::Proc
         object.arity.zero? ?  object.call : object.call(target, *args)
       else
-        raise ArgumentError, "Unknown callable #{@object}"
+        raise ArgumentError, "Unknown callable #{object}"
       end
     end
   end # Callable

data/lib/finite_machine/catchable.rb

@@ -6,8 +6,8 @@ module FiniteMachine
   module Catchable
 
     def self.included(base)
-      base.class_eval do
-        attr_threadsafe :error_handlers
+      base.module_eval do
+        attr_threadsafe :error_handlers, default: []
       end
     end
 

data/lib/finite_machine/dsl.rb

@@ -48,7 +48,7 @@ module FiniteMachine
 
     # Define initial state
     #
-    # @params [String, Hash] value
+    # @param [String, Hash] value
     #
     # @api public
     def initial(value)
@@ -58,8 +58,14 @@ module FiniteMachine
       machine.events.call(&event)
     end
 
-    def target(value)
-      machine.env.target = value
+    # Attach state machine to an object. This allows state machine
+    # to initiate events in the context of a particular object.
+    #
+    # @param [Object] object
+    #
+    # @api public
+    def target(object)
+      machine.env.target = object
     end
 
     # Define terminal state
@@ -94,7 +100,7 @@ module FiniteMachine
 
     # Parse initial options
     #
-    # @params [String, Hash] value
+    # @param [String, Hash] value
     #
     # @return [Array[Symbol,String]]
     #
@@ -124,6 +130,7 @@ module FiniteMachine
       sync_exclusive do
         _transition = Transition.new(machine, attrs.merge!(name: name))
         _transition.define
+        _transition.define_state_methods
         _transition.define_event
       end
     end
@@ -131,15 +138,15 @@ module FiniteMachine
 
   class ErrorsDSL < GenericDSL
 
-    def initialize(machine)
-      super(machine)
-      machine.error_handlers = []
-    end
-
     # Add error handler
     #
     # @param [Array] exceptions
     #
+    # @example
+    #   handle InvalidStateError, with: :log_errors
+    #
+    # @return [Array[Exception]]
+    #
     # @api public
     def handle(*exceptions, &block)
       machine.handle(*exceptions, &block)

data/lib/finite_machine/event.rb

@@ -29,7 +29,7 @@ module FiniteMachine
 
     def notify(subscriber, *args, &block)
       if subscriber.respond_to? MESSAGE
-        subscriber.__send__(MESSAGE, self, *args, &block)
+        subscriber.public_send(MESSAGE, self, *args, &block)
       end
     end
 

data/lib/finite_machine/event_queue.rb

@@ -0,0 +1,123 @@
+# encoding: utf-8
+
+module FiniteMachine
+
+  # A class responsible for running asynchronous events
+  class EventQueue
+    include Enumerable
+
+    # Initialize an event queue
+    #
+    # @example
+    #  EventQueue.new
+    #
+    # @api public
+    def initialize
+      @queue = Queue.new
+      @mutex = Mutex.new
+      @dead  = false
+      run
+    end
+
+    # Retrieve the next event
+    #
+    # @return [AsyncCall]
+    #
+    # @api private
+    def next_event
+      @queue.pop
+    end
+
+    # Add asynchronous event to the event queue
+    #
+    # @example
+    #   event_queue << AsyncCall.build(...)
+    #
+    # @param [AsyncCall] event
+    #
+    # @return [nil]
+    #
+    # @api public
+    def <<(event)
+      @mutex.lock
+      begin
+        @queue << event
+      ensure
+        @mutex.unlock rescue nil
+      end
+    end
+
+    # Check if there are any events to handle
+    #
+    # @example
+    #   event_queue.empty?
+    #
+    # @api public
+    def empty?
+      @queue.empty?
+    end
+
+    # Check if the event queue is alive
+    #
+    # @example
+    #   event_queue.alive?
+    #
+    # @return [Boolean]
+    #
+    # @api public
+    def alive?
+      !@dead
+    end
+
+    # Join the event queue from current thread
+    #
+    # @param [Fixnum] timeout
+    #
+    # @example
+    #   event_queue.join
+    #
+    # @return [nil, Thread]
+    #
+    # @api public
+    def join(timeout)
+      @thread.join timeout
+    end
+
+    # Shut down this event queue and clean it up
+    #
+    # @example
+    #   event_queue.shutdown
+    #
+    # @return [Boolean]
+    #
+    # @api public
+    def shutdown
+      @mutex.lock
+      begin
+        @queue.clear
+        @dead = true
+      ensure
+        @mutex.unlock rescue nil
+      end
+      true
+    end
+
+    private
+
+    # Run all the events
+    #
+    # @return [Thread]
+    #
+    # @api private
+    def run
+      @thread = Thread.new do
+        Thread.current.abort_on_exception = true
+        until(@dead) do
+          event = next_event
+          Thread.exit unless event
+          event.dispatch
+        end
+      end
+    end
+  end # EventQueue
+end # FiniteMachine

data/lib/finite_machine/hooks.rb

@@ -10,6 +10,9 @@ module FiniteMachine
 
     # Initialize a collection of hoooks
     #
+    # @example
+    #   Hoosk.new(machine)
+    #
     # @api public
     def initialize(machine)
       @collection = Hash.new do |events_hash, event_type|
@@ -25,13 +28,43 @@ module FiniteMachine
     # @param [String] name
     # @param [Proc]   callback
     #
+    # @example
+    #   hooks.register :enterstate, :green do ... end
+    #
+    # @return [Hash]
+    #
     # @api public
     def register(event_type, name, callback)
       @collection[event_type][name] << callback
     end
 
+    # Unregister callback
+    #
+    # @param [String] event_type
+    # @param [String] name
+    # @param [Proc]   callback
+    #
+    # @example
+    #   hooks.unregister :enterstate, :green do ... end
+    #
+    # @return [Hash]
+    #
+    # @api public
+    def unregister(event_type, name, callback)
+      @collection[event_type][name].shift
+    end
+
     # Return all hooks matching event and state
     #
+    # @param [String] event_type
+    # @param [String] event_state
+    # @param [Event] event
+    #
+    # @example
+    #   hooks.call(:entersate, :green, Event.new)
+    #
+    # @return [Hash]
+    #
     # @api public
     def call(event_type, event_state, event)
       @collection[event_type][event_state].each do |hook|

data/lib/finite_machine/observer.rb

@@ -28,7 +28,7 @@ module FiniteMachine
       instance_eval(&block)
     end
 
-    # Register callback for a given event.
+    # Register callback for a given event
     #
     # @param [Symbol] event_type
     # @param [Symbol] name
@@ -42,6 +42,17 @@ module FiniteMachine
       end
     end
 
+    # Unregister callback for a given event
+    #
+    # @api public
+    def off(event_type = ANY_EVENT, name = ANY_STATE, &callback)
+      sync_exclusive do
+        hooks.unregister event_type, name, callback
+      end
+    end
+
+    module Once; end
+
     def listen_on(type, *args, &callback)
       name   = args.first
       events = []
@@ -67,18 +78,16 @@ module FiniteMachine
       listen_on :exit, *args, &callback
     end
 
-    def method_missing(method_name, *args, &block)
-      _, event_name, callback_name = *method_name.to_s.match(/^(on_\w+?)_(\w+)$/)
-      if callback_names.include?(callback_name.to_sym)
-        send(event_name, callback_name.to_sym, *args, &block)
-      else
-        super
-      end
+    def once_on_enter(*args, &callback)
+      listen_on :enter, *args, &callback.extend(Once)
     end
 
-    def respond_to_missing?(method_name, include_private = false)
-      _, callback_name = *method_name.to_s.match(/^(on_\w+?)_(\w+)$/)
-      callback_names.include?(callback_name.to_sym)
+    def once_on_transition(*args, &callback)
+      listen_on :transition, *args, &callback.extend(Once)
+    end
+
+    def once_on_exit(*args, &callback)
+      listen_on :exit, *args, &callback.extend(Once)
     end
 
     TransitionEvent = Struct.new(:from, :to, :name) do
@@ -106,6 +115,7 @@ module FiniteMachine
            ANY_STATE_HOOK, ANY_EVENT_HOOK].each do |event_state|
             hooks.call(event_type, event_state, event) do |hook|
               run_callback(hook, event)
+              off(event_type, event_state, &hook) if hook.is_a?(Once)
             end
           end
         end
@@ -131,5 +141,37 @@ module FiniteMachine
       end
     end
 
+    # Forward the message to observer
+    #
+    # @param [String] method_name
+    #
+    # @param [Array] args
+    #
+    # @return [self]
+    #
+    # @api private
+    def method_missing(method_name, *args, &block)
+      _, event_name, callback_name = *method_name.to_s.match(/^(\w*?on_\w+?)_(\w+)$/)
+      if callback_names.include?(callback_name.to_sym)
+        public_send(event_name, :"#{callback_name}", *args, &block)
+      else
+        super
+      end
+    end
+
+    # Test if a message can be handled by observer
+    #
+    # @param [String] method_name
+    #
+    # @param [Boolean] include_private
+    #
+    # @return [Boolean]
+    #
+    # @api private
+    def respond_to_missing?(method_name, include_private = false)
+      *_, callback_name = *method_name.to_s.match(/^(\w*?on_\w+?)_(\w+)$/)
+      callback_names.include?(:"#{callback_name}")
+    end
+
   end # Observer
 end # FiniteMachine