state_machines 0.31.0 → 0.50.0

data/lib/state_machines/async_mode/async_transition_collection.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+module StateMachines
+  module AsyncMode
+    # Error class for async-specific transition failures
+    class AsyncTransitionError < StateMachines::Error
+      def initialize(object, machines, failed_events)
+        @object = object
+        @machines = machines
+        @failed_events = failed_events
+        super("Failed to perform async transitions: #{failed_events.join(', ')}")
+      end
+
+      attr_reader :object, :machines, :failed_events
+    end
+
+    # Async-aware transition collection that can execute transitions concurrently
+    class AsyncTransitionCollection < TransitionCollection
+      # Performs transitions asynchronously using Async
+      # Provides better concurrency for I/O-bound operations
+      def perform_async(&block)
+        reset
+
+        unless defined?(::Async::Task) && ::Async::Task.current?
+          return Async do
+            perform_async(&block)
+          end.wait
+        end
+
+        if valid?
+          # Create async tasks for each transition
+          tasks = map do |transition|
+            Async do
+              if use_event_attributes? && !block_given?
+                transition.transient = true
+                transition.machine.write_safely(object, :event_transition, transition)
+                run_actions
+                transition
+              else
+                within_transaction do
+                  catch(:halt) { run_callbacks(&block) }
+                  rollback unless success?
+                end
+                transition
+              end
+            end
+          end
+
+          # Wait for all tasks to complete
+          completed_transitions = []
+          tasks.each do |task|
+            begin
+              result = task.wait
+              completed_transitions << result if result
+            rescue StandardError => e
+              # Handle individual transition failures
+              rollback
+              raise AsyncTransitionError.new(object, map(&:machine), [e.message])
+            end
+          end
+
+          # Check if all transitions succeeded
+          @success = completed_transitions.length == length
+        end
+
+        success?
+      end
+
+      # Performs transitions concurrently using threads
+      # Better for CPU-bound operations but requires more careful synchronization
+      def perform_threaded(&block)
+        reset
+
+        if valid?
+          # Use basic thread approach
+          threads = []
+          results = []
+          results_mutex = Concurrent::ReentrantReadWriteLock.new
+
+          each do |transition|
+            threads << Thread.new do
+              begin
+                result = if use_event_attributes? && !block_given?
+                          transition.transient = true
+                          transition.machine.write_safely(object, :event_transition, transition)
+                          run_actions
+                          transition
+                        else
+                          within_transaction do
+                            catch(:halt) { run_callbacks(&block) }
+                            rollback unless success?
+                          end
+                          transition
+                        end
+
+                results_mutex.with_write_lock { results << result }
+              rescue StandardError => e
+                # Handle individual transition failures
+                rollback
+                raise AsyncTransitionError.new(object, [transition.machine], [e.message])
+              end
+            end
+          end
+
+          # Wait for all threads to complete
+          threads.each(&:join)
+          @success = results.length == length
+        end
+
+        success?
+      end
+
+      private
+
+      # Override run_actions to be thread-safe when needed
+      def run_actions(&block)
+        catch_exceptions do
+          @success = if block_given?
+                      result = yield
+                      actions.each { |action| results[action] = result }
+                      !!result
+                    else
+                      actions.compact.each do |action|
+                        next if skip_actions
+
+                        # Use thread-safe write for results
+                        if object.respond_to?(:state_machine_mutex)
+                          object.state_machine_mutex.with_write_lock do
+                            results[action] = object.send(action)
+                          end
+                        else
+                          results[action] = object.send(action)
+                        end
+                      end
+                      results.values.all?
+                    end
+        end
+      end
+    end
+  end
+end

data/lib/state_machines/async_mode/thread_safe_state.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module StateMachines
+  module AsyncMode
+    # Thread-safe state operations for async-enabled state machines
+    # Uses concurrent-ruby for enterprise-grade thread safety
+    module ThreadSafeState
+      # Gets or creates a reentrant mutex for thread-safe state operations on an object
+      # Each object gets its own mutex to avoid global locking
+      # Uses Concurrent::ReentrantReadWriteLock for better performance
+      def state_machine_mutex
+        @_state_machine_mutex ||= Concurrent::ReentrantReadWriteLock.new
+      end
+
+      # Thread-safe version of state reading
+      # Ensures atomic read operations across concurrent threads
+      def read_state_safely(machine, attribute, ivar = false)
+        state_machine_mutex.with_read_lock do
+          machine.read(self, attribute, ivar)
+        end
+      end
+
+      # Thread-safe version of state writing
+      # Ensures atomic write operations across concurrent threads
+      def write_state_safely(machine, attribute, value, ivar = false)
+        state_machine_mutex.with_write_lock do
+          machine.write(self, attribute, value, ivar)
+        end
+      end
+
+      # Handle marshalling by excluding the mutex (will be recreated when needed)
+      def marshal_dump
+        # Get instance variables excluding the mutex
+        vars = instance_variables.reject { |var| var == :@_state_machine_mutex }
+        vars.map { |var| [var, instance_variable_get(var)] }
+      end
+
+      # Restore marshalled object, mutex will be lazily recreated when needed
+      def marshal_load(data)
+        data.each do |var, value|
+          instance_variable_set(var, value)
+        end
+        # Don't set @_state_machine_mutex - let it be lazily created
+      end
+    end
+  end
+end

data/lib/state_machines/async_mode.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+# Ruby Engine Compatibility Check
+# The async gem requires native extensions and Fiber scheduler support
+# which are not available on JRuby or TruffleRuby
+if RUBY_ENGINE == 'jruby' || RUBY_ENGINE == 'truffleruby'
+  raise LoadError, <<~ERROR
+    StateMachines::AsyncMode is not available on #{RUBY_ENGINE}.
+
+    The async gem requires native extensions (io-event) and Fiber scheduler support
+    which are not implemented in #{RUBY_ENGINE}. AsyncMode is only supported on:
+
+    • MRI Ruby (CRuby) 3.2+
+    • Other Ruby engines with full Fiber scheduler support
+
+    If you need async support on #{RUBY_ENGINE}, consider using:
+    • java.util.concurrent classes (JRuby)
+    • Native threading libraries for your platform
+    • Or stick with synchronous state machines
+  ERROR
+end
+
+# Load required gems with version constraints
+gem 'async', '>= 2.25.0'
+gem 'concurrent-ruby', '>= 1.3.5'  # Security is not negotiable - enterprise-grade thread safety required
+
+require 'async'
+require 'concurrent-ruby'
+
+# Load all async mode components
+require_relative 'async_mode/thread_safe_state'
+require_relative 'async_mode/async_events'
+require_relative 'async_mode/async_event_extensions'
+require_relative 'async_mode/async_machine'
+require_relative 'async_mode/async_transition_collection'
+
+module StateMachines
+  # AsyncMode provides asynchronous state machine capabilities using the async gem
+  # This module enables concurrent, thread-safe state operations for high-performance applications
+  #
+  # @example Basic usage
+  #   class AutonomousDrone < StarfleetShip
+  #     state_machine :teleporter_status, async: true do
+  #       event :power_up do
+  #         transition offline: :charging
+  #       end
+  #     end
+  #   end
+  #
+  #   drone = AutonomousDrone.new
+  #   Async do
+  #     result = drone.fire_event_async(:power_up)  # => true
+  #     task = drone.power_up_async!               # => Async::Task
+  #   end
+  #
+  module AsyncMode
+    # All components are loaded from separate files:
+    # - ThreadSafeState: Mutex-based thread safety
+    # - AsyncEvents: Async event firing methods
+    # - AsyncEventExtensions: Event method generation
+    # - AsyncMachine: Machine-level async capabilities
+    # - AsyncTransitionCollection: Concurrent transition execution
+  end
+end

data/lib/state_machines/branch.rb

@@ -34,6 +34,12 @@ module StateMachines
       # Build conditionals
       @if_condition = options.delete(:if)
       @unless_condition = options.delete(:unless)
+      @if_state_condition = options.delete(:if_state)
+      @unless_state_condition = options.delete(:unless_state)
+      @if_all_states_condition = options.delete(:if_all_states)
+      @unless_all_states_condition = options.delete(:unless_all_states)
+      @if_any_state_condition = options.delete(:if_any_state)
+      @unless_any_state_condition = options.delete(:unless_any_state)
 
       # Build event requirement
       @event_requirement = build_matcher(options, :on, :except_on)
@@ -182,21 +188,56 @@ module StateMachines
     # Verifies that the conditionals for this branch evaluate to true for the
     # given object. Event arguments are passed to guards that accept multiple parameters.
     def matches_conditions?(object, query, event_args = [])
-      case [query[:guard], if_condition, unless_condition]
-      in [false, _, _]
-        true
-      in [_, nil, nil]
-        true
-      in [_, if_conds, nil] if if_conds
-        Array(if_conds).all? { |condition| evaluate_method_with_event_args(object, condition, event_args) }
-      in [_, nil, unless_conds] if unless_conds
-        Array(unless_conds).none? { |condition| evaluate_method_with_event_args(object, condition, event_args) }
-      in [_, if_conds, unless_conds] if if_conds || unless_conds
-        Array(if_conds).all? { |condition| evaluate_method_with_event_args(object, condition, event_args) } &&
-          Array(unless_conds).none? { |condition| evaluate_method_with_event_args(object, condition, event_args) }
-      else
-        true
+      return true if query[:guard] == false
+
+      # Evaluate original if/unless conditions
+      if_passes = !if_condition || Array(if_condition).all? { |condition| evaluate_method_with_event_args(object, condition, event_args) }
+      unless_passes = !unless_condition || Array(unless_condition).none? { |condition| evaluate_method_with_event_args(object, condition, event_args) }
+
+      return false unless if_passes && unless_passes
+
+      # Consolidate all state guards
+      state_guards = {
+        if_state: @if_state_condition,
+        unless_state: @unless_state_condition,
+        if_all_states: @if_all_states_condition,
+        unless_all_states: @unless_all_states_condition,
+        if_any_state: @if_any_state_condition,
+        unless_any_state: @unless_any_state_condition
+      }.compact
+
+      return true if state_guards.empty?
+
+      validate_and_check_state_guards(object, state_guards)
+    end
+
+    private
+
+    def validate_and_check_state_guards(object, guards)
+      guards.all? do |guard_type, conditions|
+        case guard_type
+        when :if_state, :if_all_states
+          conditions.all? { |machine, state| check_state(object, machine, state) }
+        when :unless_state
+          conditions.none? { |machine, state| check_state(object, machine, state) }
+        when :if_any_state
+          conditions.any? { |machine, state| check_state(object, machine, state) }
+        when :unless_all_states
+          !conditions.all? { |machine, state| check_state(object, machine, state) }
+        when :unless_any_state
+          conditions.none? { |machine, state| check_state(object, machine, state) }
+        end
       end
     end
+
+    def check_state(object, machine_name, state_name)
+      machine = object.class.state_machines[machine_name]
+      raise ArgumentError, "State machine '#{machine_name}' is not defined for #{object.class.name}" unless machine
+
+      state = machine.states[state_name]
+      raise ArgumentError, "State '#{state_name}' is not defined in state machine '#{machine_name}'" unless state
+
+      state.matches?(object.send(machine_name))
+    end
   end
 end

data/lib/state_machines/callback.rb

@@ -177,7 +177,8 @@ module StateMachines
     # order.  The callback will only halt if the resulting value from the
     # method passes the terminator.
     def run_methods(object, context = {}, index = 0, *args, &block)
-      if type == :around
+      case type
+      when :around
         current_method = @methods[index]
         if current_method
           yielded = false

data/lib/state_machines/event.rb

@@ -35,15 +35,17 @@ module StateMachines
     # * <tt>:human_name</tt> - The human-readable version of this event's name
     def initialize(machine, name, options = nil, human_name: nil, **extra_options) # :nodoc:
       # Handle both old hash style and new kwargs style for backward compatibility
-      if options.is_a?(Hash)
+      case options
+      in Hash
         # Old style: initialize(machine, name, {human_name: 'Custom Name'})
         StateMachines::OptionsValidator.assert_valid_keys!(options, :human_name)
         human_name = options[:human_name]
-      else
+      in nil
         # New style: initialize(machine, name, human_name: 'Custom Name')
-        raise ArgumentError, "Unexpected positional argument: #{options.inspect}" unless options.nil?
-
         StateMachines::OptionsValidator.assert_valid_keys!(extra_options, :human_name) unless extra_options.empty?
+      else
+        # Handle unexpected options
+        raise ArgumentError, "Unexpected positional argument in Event initialize: #{options.inspect}"
       end
 
       @machine = machine
@@ -102,7 +104,7 @@ module StateMachines
 
       # Only a certain subset of explicit options are allowed for transition
       # requirements
-      StateMachines::OptionsValidator.assert_valid_keys!(options, :from, :to, :except_from, :except_to, :if, :unless) if (options.keys - %i[from to on except_from except_to except_on if unless]).empty?
+      StateMachines::OptionsValidator.assert_valid_keys!(options, :from, :to, :except_from, :except_to, :if, :unless, :if_state, :unless_state, :if_all_states, :unless_all_states, :if_any_state, :unless_any_state) if (options.keys - %i[from to on except_from except_to except_on if unless if_state unless_state if_all_states unless_all_states if_any_state unless_any_state]).empty?
 
       branches << branch = Branch.new(options.merge(on: name))
       @known_states |= branch.known_states

data/lib/state_machines/event_collection.rb

@@ -117,19 +117,27 @@ module StateMachines
       return unless machine.action
 
       # TODO, simplify
-      machine.read(object, :event_transition) || if event_name = machine.read(object, :event)
-                                                   if event = self[event_name.to_sym, :name]
-                                                     event.transition_for(object) || begin
-                                                       # No valid transition: invalidate
-                                                       machine.invalidate(object, :event, :invalid_event, [[:state, machine.states.match!(object).human_name(object.class)]]) if invalidate
-                                                       false
-                                                     end
-                                                   else
-                                                     # Event is unknown: invalidate
-                                                     machine.invalidate(object, :event, :invalid) if invalidate
-                                                     false
-                                                   end
-                                                 end
+      # First try the regular event_transition
+      transition = machine.read(object, :event_transition)
+      
+      # If not found and we have stored transitions by machine (issue #91)
+      if !transition && (transitions_by_machine = object.instance_variable_get(:@_state_machine_event_transitions))
+        transition = transitions_by_machine[machine.name]
+      end
+      
+      transition || if event_name = machine.read(object, :event)
+                      if event = self[event_name.to_sym, :name]
+                        event.transition_for(object) || begin
+                          # No valid transition: invalidate
+                          machine.invalidate(object, :event, :invalid_event, [[:state, machine.states.match!(object).human_name(object.class)]]) if invalidate
+                          false
+                        end
+                      else
+                        # Event is unknown: invalidate
+                        machine.invalidate(object, :event, :invalid) if invalidate
+                        false
+                      end
+                    end
     end
 
     private

data/lib/state_machines/machine/async_extensions.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+# This file provides optional async extensions for the Machine class.
+# It should only be loaded when async functionality is explicitly requested.
+
+module StateMachines
+  class Machine
+    # AsyncMode extensions for the Machine class
+    # Provides async-aware methods while maintaining backward compatibility
+    module AsyncExtensions
+      # Instance methods added to Machine for async support
+
+      # Configure this specific machine instance for async mode
+      #
+      # Example:
+      #   class Vehicle
+      #     state_machine initial: :parked do
+      #       configure_async_mode! # Enable async for this machine
+      #
+      #       event :ignite do
+      #         transition parked: :idling
+      #       end
+      #     end
+      #   end
+      def configure_async_mode!(enabled = true)
+        if enabled
+          begin
+            require 'state_machines/async_mode'
+            @async_mode_enabled = true
+
+            owner_class.include(StateMachines::AsyncMode::ThreadSafeState)
+            owner_class.include(StateMachines::AsyncMode::AsyncEvents)
+            self.extend(StateMachines::AsyncMode::AsyncMachine)
+
+            # Extend events to generate async versions
+            events.each do |event|
+              event.extend(StateMachines::AsyncMode::AsyncEventExtensions)
+            end
+          rescue LoadError => e
+            # Fallback to sync mode with warning (only once per class)
+            unless owner_class.instance_variable_get(:@async_fallback_warned)
+              warn <<~WARNING
+                ⚠️  #{owner_class.name}: Async mode requested but not available on #{RUBY_ENGINE}.
+
+                #{e.message}
+
+                ⚠️  Falling back to synchronous mode. Results may be unpredictable due to engine limitations.
+                For production async support, use MRI Ruby (CRuby) 3.2+
+              WARNING
+              owner_class.instance_variable_set(:@async_fallback_warned, true)
+            end
+
+            @async_mode_enabled = false
+          end
+        else
+          @async_mode_enabled = false
+        end
+
+        self
+      end
+
+      # Check if this specific machine instance has async mode enabled
+      def async_mode_enabled?
+        @async_mode_enabled || false
+      end
+
+      # Thread-safe version of state reading
+      def read_safely(object, attribute, ivar = false)
+        object.read_state_safely(self, attribute, ivar)
+      end
+
+      # Thread-safe version of state writing
+      def write_safely(object, attribute, value, ivar = false)
+        object.write_state_safely(self, attribute, value, ivar)
+      end
+
+      # Thread-safe callback execution for async operations
+      def run_callbacks_safely(type, object, context, transition)
+        object.state_machine_mutex.with_write_lock do
+          callbacks[type].each { |callback| callback.call(object, context, transition) }
+        end
+      end
+    end
+
+    # Include async extensions by default (but only load AsyncMode when requested)
+    include AsyncExtensions
+  end
+end

data/lib/state_machines/machine/class_methods.rb

@@ -30,6 +30,10 @@ module StateMachines
             machine = machine.clone
             machine.initial_state = options[:initial] if options.include?(:initial)
             machine.owner_class = owner_class
+            # Configure async mode if requested in options
+            if options.include?(:async)
+              machine.configure_async_mode!(options[:async])
+            end
           end
 
           # Evaluate DSL

data/lib/state_machines/machine/configuration.rb

@@ -6,7 +6,7 @@ module StateMachines
       # Initializes a new state machine with the given configuration.
       def initialize(owner_class, *args, &)
         options = args.last.is_a?(Hash) ? args.pop : {}
-        StateMachines::OptionsValidator.assert_valid_keys!(options, :attribute, :initial, :initialize, :action, :plural, :namespace, :integration, :messages, :use_transactions)
+        StateMachines::OptionsValidator.assert_valid_keys!(options, :attribute, :initial, :initialize, :action, :plural, :namespace, :integration, :messages, :use_transactions, :async)
 
         # Find an integration that matches this machine's owner class
         @integration = if options.include?(:integration)
@@ -35,6 +35,8 @@ module StateMachines
         @use_transactions = options[:use_transactions]
         @initialize_state = options[:initialize]
         @action_hook_defined = false
+        @async_requested = options[:async]
+
         self.owner_class = owner_class
 
         # Merge with sibling machine configurations
@@ -47,6 +49,12 @@ module StateMachines
 
         # Evaluate DSL
         instance_eval(&) if block_given?
+
+        # Configure async mode if requested, after owner_class is set and DSL is evaluated
+        if @async_requested
+          configure_async_mode!(true)
+        end
+
         self.initial_state = options[:initial] unless sibling_machines.any?
       end
 
@@ -61,6 +69,8 @@ module StateMachines
         @states = @states.dup
         @states.machine = self
         @callbacks = { before: @callbacks[:before].dup, after: @callbacks[:after].dup, failure: @callbacks[:failure].dup }
+        @async_requested = orig.instance_variable_get(:@async_requested)
+        @async_mode_enabled = orig.instance_variable_get(:@async_mode_enabled)
       end
 
       # Sets the class which is the owner of this state machine.  Any methods

data/lib/state_machines/machine.rb

@@ -14,6 +14,7 @@ require_relative 'machine/event_methods'
 require_relative 'machine/callbacks'
 require_relative 'machine/rendering'
 require_relative 'machine/integration'
+require_relative 'machine/async_extensions'
 require_relative 'syntax_validator'
 
 module StateMachines

data/lib/state_machines/state.rb

@@ -55,7 +55,8 @@ module StateMachines
     # * <tt>:human_name</tt> - The human-readable version of this state's name
     def initialize(machine, name, options = nil, initial: false, value: :__not_provided__, cache: nil, if: nil, human_name: nil, **extra_options) # :nodoc:
       # Handle both old hash style and new kwargs style for backward compatibility
-      if options.is_a?(Hash)
+      case options
+      in Hash
         # Old style: initialize(machine, name, {initial: true, value: 'foo'})
         StateMachines::OptionsValidator.assert_valid_keys!(options, :initial, :value, :cache, :if, :human_name)
         initial = options.fetch(:initial, false)
@@ -63,13 +64,13 @@ module StateMachines
         cache = options[:cache]
         if_condition = options[:if]
         human_name = options[:human_name]
-      else
+      in nil
         # New style: initialize(machine, name, initial: true, value: 'foo')
-        # options parameter should be nil in this case
-        raise ArgumentError, "Unexpected positional argument: #{options.inspect}" unless options.nil?
-
         StateMachines::OptionsValidator.assert_valid_keys!(extra_options, :initial, :value, :cache, :if, :human_name) unless extra_options.empty?
         if_condition = binding.local_variable_get(:if) # 'if' is a keyword, need special handling
+      else
+        # Handle unexpected options
+        raise ArgumentError, "Unexpected positional argument in State initialize: #{options.inspect}"
       end
 
       @machine = machine