finite_machine 0.13.0 → 0.14.1

data/lib/finite_machine/catchable.rb

@@ -33,7 +33,7 @@ module FiniteMachine
         if block_given?
           options[:with] = block
         else
-          raise ArgumentError, 'Need to provide error handler.'
+          raise ArgumentError, "Need to provide error handler."
         end
       end
       evaluate_exceptions(exceptions, options)
@@ -71,7 +71,7 @@ module FiniteMachine
     #
     # @api private
     def extract_const(class_name)
-      class_name.split('::').reduce(FiniteMachine) do |constant, part|
+      class_name.split("::").reduce(FiniteMachine) do |constant, part|
         constant.const_get(part)
       end
     end
@@ -85,9 +85,9 @@ module FiniteMachine
         target.method(handler)
       when Proc
         if handler.arity.zero?
-          proc { instance_exec(&handler) }
+          -> { instance_exec(&handler) }
         else
-          proc { |_exception| instance_exec(_exception, &handler) }
+          ->(exception) { instance_exec(exception, &handler) }
         end
       end
     end
@@ -101,16 +101,24 @@ module FiniteMachine
     # @api private
     def evaluate_exceptions(exceptions, options)
       exceptions.each do |exception|
-        key = if exception.is_a?(Class) && exception <= Exception
-          exception.name
-        elsif exception.is_a?(String)
-          exception
-        else
-          raise ArgumentError, "#{exception} isn't an Exception"
-        end
-
+        key = extract_exception_name(exception)
         error_handlers << [key, options[:with]]
       end
     end
+
+    # Extract exception name
+    #
+    # @param [Class,Exception,String] exception
+    #
+    # @api private
+    def extract_exception_name(exception)
+      if exception.is_a?(Class) && exception <= Exception
+        exception.name
+      elsif exception.is_a?(String)
+        exception
+      else
+        raise ArgumentError, "#{exception} isn't an Exception"
+      end
+    end
   end # Catchable
 end # FiniteMachine

data/lib/finite_machine/choice_merger.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require_relative 'transition_builder'
+require_relative "transition_builder"
 
 module FiniteMachine
   # A class responsible for merging choice options
@@ -39,6 +39,6 @@ module FiniteMachine
                                                  @transitions.merge(conditions))
       transition_builder.call(@transitions[:from] => to)
     end
-    alias_method :default, :choice
+    alias default choice
   end # ChoiceMerger
 end # FiniteMachine

data/lib/finite_machine/definition.rb

@@ -1,30 +1,38 @@
 # frozen_string_literal: true
 
 module FiniteMachine
-  # A class responsible for defining standalone state machine
+  # Responsible for defining a standalone state machine
+  #
+  # @api public
   class Definition
-    # The machine deferreds
+    # The any event constant
     #
-    # @return [Array[Proc]]
+    # @example
+    #   on_before(any_event) { ... }
     #
-    # @api private
-    def self.deferreds
-      @deferreds ||= []
+    # @return [FiniteMachine::Const]
+    #
+    # @api public
+    def self.any_event
+      ANY_EVENT
     end
 
-    # Add deferred
+    # The any state constant
     #
-    # @param [Proc] deferred
-    #   the deferred execution
+    # @example
+    #   event :go, any_state => :green
     #
-    # @return [Array[Proc]]
+    # @example
+    #   on_enter(any_state) { ... }
     #
-    # @api private
-    def self.add_deferred(deferred)
-      deferreds << deferred
+    # @return [FiniteMachine::Const]
+    #
+    # @api public
+    def self.any_state
+      ANY_STATE
     end
 
-    # Instantiate a new Definition
+    # Initialize a StateMachine
     #
     # @example
     #   class Engine < FiniteMachine::Definition
@@ -43,20 +51,49 @@ module FiniteMachine
       end
     end
 
-    # Set deferrerd methods on the subclass
+    # Add deferred methods to the subclass
+    #
+    # @param [Class] subclass
+    #   the inheriting subclass
+    #
+    # @return [void]
     #
     # @api private
     def self.inherited(subclass)
       super
 
-      self.deferreds.each { |d| subclass.add_deferred(d) }
+      deferreds.each { |d| subclass.add_deferred(d) }
+    end
+
+    # The state machine deferreds
+    #
+    # @return [Array<Proc>]
+    #
+    # @api private
+    def self.deferreds
+      @deferreds ||= []
+    end
+
+    # Add deferred
+    #
+    # @param [Proc] deferred
+    #   the deferred execution
+    #
+    # @return [Array<Proc>]
+    #
+    # @api private
+    def self.add_deferred(deferred)
+      deferreds << deferred
     end
 
     # Delay lookup of DSL method
     #
     # @param [Symbol] method_name
+    #   the method name
+    # @param [Array] arguments
+    #   the method arguments
     #
-    # @return [nil]
+    # @return [void]
     #
     # @api private
     def self.method_missing(method_name, *arguments, &block)

data/lib/finite_machine/dsl.rb

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
-require_relative 'choice_merger'
-require_relative 'safety'
-require_relative 'transition_builder'
+require_relative "choice_merger"
+require_relative "safety"
+require_relative "transition_builder"
 
 module FiniteMachine
   # A generic DSL for describing the state machine
@@ -38,6 +38,13 @@ module FiniteMachine
       end
     end
 
+    # Check if message can be handled by this DSL
+    #
+    # @api private
+    def respond_to_missing?(method_name, include_private = false)
+      @machine.respond_to?(method_name) || super
+    end
+
     # Configure state machine properties
     #
     # @api private
@@ -65,6 +72,29 @@ module FiniteMachine
       log_transitions(@attrs.fetch(:log_transitions, false))
     end
 
+    # Add aliases for the target object
+    #
+    # @example
+    #   FiniteMachine.define do
+    #     target_alias :engine
+    #
+    #     on_transition do |event|
+    #       engine.state = event.to
+    #     end
+    #   end
+    #
+    # @param [Array<Symbol>] aliases
+    #   the names for target alias
+    #
+    # @api public
+    def alias_target(*aliases)
+      aliases.each do |alias_name|
+        next if env.aliases.include?(alias_name)
+
+        env.aliases << alias_name
+      end
+    end
+
     # Define initial state
     #
     # @param [Symbol] value
@@ -197,8 +227,8 @@ module FiniteMachine
     #
     # @api private
     def raise_missing_state
-      fail MissingInitialStateError,
-           'Provide state to transition :to for the initial event'
+      raise MissingInitialStateError,
+            "Provide state to transition :to for the initial event"
     end
   end # DSL
 end # FiniteMachine

data/lib/finite_machine/env.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require_relative 'threadable'
+require_relative "threadable"
 
 module FiniteMachine
   # Holds references to targets and aliases

data/lib/finite_machine/events_map.rb

@@ -1,10 +1,10 @@
 # frozen_string_literal: true
 
-require 'concurrent/map'
-require 'forwardable'
+require "concurrent/map"
+require "forwardable"
 
-require_relative 'threadable'
-require_relative 'undefined_transition'
+require_relative "threadable"
+require_relative "undefined_transition"
 
 module FiniteMachine
   # A class responsible for storing mappings between event namess and
@@ -182,8 +182,7 @@ module FiniteMachine
     # @api public
     def match_transition_with(name, from_state, *conditions)
       find(name).find do |trans|
-        trans.matches?(from_state) &&
-        trans.check_conditions(*conditions)
+        trans.matches?(from_state) && trans.check_conditions(*conditions)
       end
     end
 

data/lib/finite_machine/hook_event.rb

@@ -29,7 +29,7 @@ module FiniteMachine
     #
     # @api public
     def self.event_name
-      name.split('::').last.downcase.to_sym
+      name.split("::").last.downcase.to_sym
     end
 
     # String representation

data/lib/finite_machine/hooks.rb

@@ -1,8 +1,9 @@
 # frozen_string_literal: true
 
-require 'concurrent/map'
+require "concurrent/array"
+require "concurrent/map"
 
-require_relative 'hook_event'
+require_relative "hook_event"
 
 module FiniteMachine
   # A class reponsible for registering callbacks
@@ -12,13 +13,17 @@ module FiniteMachine
     # Initialize a hooks_map of hooks
     #
     # @example
-    #   Hoosk.new(machine)
+    #   Hooks.new
     #
     # @api public
     def initialize
       @hooks_map = Concurrent::Map.new do |events_hash, hook_event|
-        events_hash[hook_event] = Concurrent::Map.new do |state_hash, name|
-          state_hash[name] = []
+        events_hash.compute_if_absent(hook_event) do
+          Concurrent::Map.new do |state_hash, name|
+            state_hash.compute_if_absent(name) do
+              Concurrent::Array.new
+            end
+          end
         end
       end
     end

data/lib/finite_machine/message_queue.rb

@@ -1,20 +1,20 @@
 # frozen_string_literal: true
 
-require_relative 'listener'
-require 'thread'
+require_relative "listener"
+require "thread"
 
 module FiniteMachine
-  # Allows for storage of asynchronous messages such as events
+  # Responsible for storage of asynchronous messages such as events
   # and callbacks.
   #
-  # Used internally by {Observer} and {StateMachine}
+  # Used internally by {Observer}
   #
   # @api private
   class MessageQueue
-    # Initialize an event queue in separate thread
+    # Initialize a MessageQueue
     #
     # @example
-    #   MessageQueue.new
+    #   message_queue = FiniteMachine::MessageQueue.new
     #
     # @api public
     def initialize
@@ -28,13 +28,21 @@ module FiniteMachine
 
     # Start a new thread with a queue of callback events to run
     #
+    # @example
+    #   message_queue.start
+    #
+    # @return [Thread, nil]
+    #
     # @api private
     def start
       return if running?
+
       @mutex.synchronize { spawn_thread }
     end
 
-    # Spawn new background thread
+    # Spawn a new background thread
+    #
+    # @return [Thread]
     #
     # @api private
     def spawn_thread
@@ -44,18 +52,27 @@ module FiniteMachine
       end
     end
 
+    # Check whether or not the message queue is running
+    #
+    # @example
+    #   message_queue.running?
+    #
+    # @return [Boolean]
+    #
+    # @api public
     def running?
       !@thread.nil? && alive?
     end
 
-    # Add asynchronous event to the event queue to process
+    # Add an asynchronous event to the message queue to process
     #
     # @example
-    #   event_queue << AsyncCall.build(...)
+    #   message_queue << AsyncCall.build(...)
     #
-    # @param [AsyncCall] event
+    # @param [FiniteMachine::AsyncCall] event
+    #   the event to add
     #
-    # @return [nil]
+    # @return [void]
     #
     # @api public
     def <<(event)
@@ -69,7 +86,12 @@ module FiniteMachine
       end
     end
 
-    # Add listener to the queue to receive messages
+    # Add a listener for the message queue to receive notifications
+    #
+    # @example
+    #   message_queue.subscribe { |event| ... }
+    #
+    # @return [void]
     #
     # @api public
     def subscribe(*args, &block)
@@ -80,20 +102,20 @@ module FiniteMachine
       end
     end
 
-    # Check if there are any events to handle
+    # Check whether or not there are any messages to handle
     #
     # @example
-    #   event_queue.empty?
+    #   message_queue.empty?
     #
     # @api public
     def empty?
       @mutex.synchronize { @queue.empty? }
     end
 
-    # Check if the event queue is alive
+    # Check whether or not the message queue is alive
     #
     # @example
-    #   event_queue.alive?
+    #   message_queue.alive?
     #
     # @return [Boolean]
     #
@@ -102,31 +124,35 @@ module FiniteMachine
       @mutex.synchronize { !@dead }
     end
 
-    # Join the event queue from current thread
+    # Join the message queue from the current thread
     #
     # @param [Fixnum] timeout
+    #   the time limit
     #
     # @example
-    #   event_queue.join
+    #   message_queue.join
     #
-    # @return [nil, Thread]
+    # @return [Thread, nil]
     #
     # @api public
     def join(timeout = nil)
       return unless @thread
+
       timeout.nil? ? @thread.join : @thread.join(timeout)
     end
 
-    # Shut down this event queue and clean it up
+    # Shut down this message queue and clean it up
     #
     # @example
-    #   event_queue.shutdown
+    #   message_queue.shutdown
+    #
+    # @raise [FiniteMachine::MessageQueueDeadError]
     #
     # @return [Boolean]
     #
     # @api public
     def shutdown
-      fail EventQueueDeadError, 'event queue already dead' if @dead
+      raise MessageQueueDeadError, "message queue already dead" if @dead
 
       queue = []
       @mutex.synchronize do
@@ -142,10 +168,10 @@ module FiniteMachine
       true
     end
 
-    # Get number of events waiting for processing
+    # The number of messages waiting for processing
     #
     # @example
-    #   event_queue.size
+    #   message_queue.size
     #
     # @return [Integer]
     #
@@ -154,6 +180,14 @@ module FiniteMachine
       @mutex.synchronize { @queue.size }
     end
 
+    # Inspect this message queue
+    #
+    # @example
+    #   message_queue.inspect
+    #
+    # @return [String]
+    #
+    # @api public
     def inspect
       @mutex.synchronize do
         "#<#{self.class}:#{object_id.to_s(16)} @size=#{size}, @dead=#{@dead}>"
@@ -162,9 +196,12 @@ module FiniteMachine
 
     private
 
-    # Notify consumers about process event
+    # Notify listeners about the event
+    #
+    # @param [FiniteMachine::AsyncCall] event
+    #   the event to notify listeners about
     #
-    # @param [AsyncCall] event
+    # @return [void]
     #
     # @api private
     def notify_listeners(event)
@@ -184,6 +221,7 @@ module FiniteMachine
           end
           event = @queue.pop
           break unless event
+
           notify_listeners(event)
           event.dispatch
         end
@@ -192,6 +230,14 @@ module FiniteMachine
       Logger.error "Error while running event: #{Logger.format_error(ex)}"
     end
 
+    # Log discarded message
+    #
+    # @param [FiniteMachine::AsyncCall] message
+    #   the message to discard
+    #
+    # @return [void]
+    #
+    # @api private
     def discard_message(message)
       Logger.debug "Discarded message: #{message}" if $DEBUG
     end

data/lib/finite_machine/observer.rb

@@ -1,32 +1,20 @@
 # frozen_string_literal: true
 
-require_relative 'async_call'
-require_relative 'callable'
-require_relative 'hook_event'
-require_relative 'hooks'
-require_relative 'message_queue'
-require_relative 'safety'
-require_relative 'transition_event'
+require "securerandom"
+
+require_relative "async_call"
+require_relative "callable"
+require_relative "hook_event"
+require_relative "hooks"
+require_relative "message_queue"
+require_relative "safety"
+require_relative "transition_event"
 
 module FiniteMachine
   # A class responsible for observing state changes
   class Observer < GenericDSL
     include Safety
 
-    # Clean up callback queue
-    #
-    # @api private
-    def self.cleanup_callback_queue
-      proc do
-        begin
-          if callback_queue.alive?
-            callback_queue.shutdown
-          end
-        rescue MessageQueueDeadError
-        end
-      end
-    end
-
     # The current state machine
     attr_reader :machine
 
@@ -44,11 +32,6 @@ module FiniteMachine
       @hooks   = Hooks.new
 
       @machine.subscribe(self)
-      ObjectSpace.define_finalizer(self, self.class.cleanup_callback_queue)
-    end
-
-    def callback_queue
-      @callback_queue ||= MessageQueue.new
     end
 
     # Evaluate in current context
@@ -204,6 +187,35 @@ module FiniteMachine
       callback_queue << async_call
     end
 
+    # Get an existing callback queue or create a new one
+    #
+    # @return [FiniteMachine::MessageQueue]
+    #
+    # @api private
+    def callback_queue
+      @callback_queue ||= MessageQueue.new.tap do
+        @queue_id = SecureRandom.uuid
+        ObjectSpace.define_finalizer(@queue_id, proc do
+          cleanup_callback_queue
+        end)
+      end
+    end
+
+    # Clean up the callback queue
+    #
+    # @return [Boolean, nil]
+    #
+    # @api private
+    def cleanup_callback_queue
+      ObjectSpace.undefine_finalizer(@queue_id) if @queue_id
+      return unless @callback_queue && callback_queue.alive?
+
+      begin
+        callback_queue.shutdown
+      rescue MessageQueueDeadError
+      end
+    end
+
     # Create callable instance
     #
     # @api private

data/lib/finite_machine/safety.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require_relative 'hook_event'
+require_relative "hook_event"
 
 module FiniteMachine
   # Module responsible for safety checks against known methods
@@ -39,7 +39,7 @@ module FiniteMachine
           name: event_name,
           type: :instance,
           method: method_name,
-          source: 'FiniteMachine'
+          source: "FiniteMachine"
         }
       end
     end
@@ -89,8 +89,8 @@ module FiniteMachine
     # @api private
     def wrong_event_name?(name, event_type)
       machine.states.include?(name) &&
-      !machine.events.include?(name) &&
-      event_type < HookEvent::Anyaction
+        !machine.events.include?(name) &&
+        event_type < HookEvent::Anyaction
     end
 
     # Check if state name exists
@@ -104,8 +104,8 @@ module FiniteMachine
     # @api private
     def wrong_state_name?(name, event_type)
       machine.events.include?(name) &&
-      !machine.states.include?(name) &&
-      event_type < HookEvent::Anystate
+        !machine.states.include?(name) &&
+        event_type < HookEvent::Anystate
     end
 
     def raise_invalid_callback_error(message)