state_machines 0.31.0 → 0.50.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fcd04394640ccea1429d2e121a46e2c705f8c16b2987b142858ad2f151c9c287
-  data.tar.gz: 58cfb25ff972b1b2802730d9084d3c3b27c59a82e694646ce676e38fc661cbb9
+  metadata.gz: 247ae1ee6fa7beb6ac29a68dfd400ea41a3923b973d842a5adb2ef78960b3266
+  data.tar.gz: 7240a29d3d87740ade0d0197e9c4c0192176023f23e453d1ba659e8be905afef
 SHA512:
-  metadata.gz: c9328eea4f9d8d9e57124571de54bb8f5160a044ef913d3e515bcaac933b7355ccf987c10699c71e94145f44bc1e2387342f350dcbff0100d76a5c1c06645321
-  data.tar.gz: 07c7bfad14f7ce103eec5d6dfa48a9117bc0a73cb5433447c4bf7b6cdea1b87b894a12ad6b85b5a0cb05d63dd68e291f980eeca40e60754c13d5b5c44a7fcf29
+  metadata.gz: 26e8c0a197cdc254c4157a57e3bcfabfef87240280555ae623d993e30ccb68ba6433e911da171f60beb0e756af54aa60ff18395c9d49c6719a06b22bd895bdca
+  data.tar.gz: 9dfbdceba5b428f415dfeeba91995ab52640282b2b6c2fb92dea266c97677263331706e6b37f09a6280dc3f578da27dae1f5ade628a655342e46c565ddbe05db

data/README.md

@@ -36,6 +36,8 @@ Below is an example of many of the features offered by this plugin, including:
 * Namespaced states
 * Transition callbacks
 * Conditional transitions
+* Coordinated state management guards
+* Asynchronous state machines (async: true)
 * State-driven instance behavior
 * Customized state values
 * Parallel events
@@ -245,6 +247,206 @@ vehicle.alarm_state_name                        # => :active
 
 vehicle.fire_events!(:ignite, :enable_alarm)    # => StateMachines:InvalidParallelTransition: Cannot run events in parallel: ignite, enable_alarm
 
+# Coordinated State Management
+
+State machines can coordinate with each other using state guards, allowing transitions to depend on the state of other state machines within the same object. This enables complex system modeling where components are interdependent.
+
+## State Guard Options
+
+### Single State Guards
+
+* `:if_state` - Transition only if another state machine is in a specific state.
+* `:unless_state` - Transition only if another state machine is NOT in a specific state.
+
+```ruby
+class TorpedoSystem
+  state_machine :bay_doors, initial: :closed do
+    event :open do
+      transition closed: :open
+    end
+
+    event :close do
+      transition open: :closed
+    end
+  end
+
+  state_machine :torpedo_status, initial: :loaded do
+    event :fire_torpedo do
+      # Can only fire torpedo if bay doors are open
+      transition loaded: :fired, if_state: { bay_doors: :open }
+    end
+
+    event :reload do
+      # Can only reload if bay doors are closed (for safety)
+      transition fired: :loaded, unless_state: { bay_doors: :open }
+    end
+  end
+end
+
+system = TorpedoSystem.new
+system.fire_torpedo  # => false (bay doors are closed)
+
+system.open_bay_doors!
+system.fire_torpedo  # => true (bay doors are now open)
+```
+
+### Multiple State Guards
+
+* `:if_all_states` - Transition only if ALL specified state machines are in their respective states.
+* `:unless_all_states` - Transition only if NOT ALL specified state machines are in their respective states.
+* `:if_any_state` - Transition only if ANY of the specified state machines are in their respective states.
+* `:unless_any_state` - Transition only if NONE of the specified state machines are in their respective states.
+
+```ruby
+class StarshipBridge
+  state_machine :shields, initial: :down
+  state_machine :weapons, initial: :offline
+  state_machine :warp_core, initial: :stable
+
+  state_machine :alert_status, initial: :green do
+    event :red_alert do
+      # Red alert if ANY critical system needs attention
+      transition green: :red, if_any_state: { warp_core: :critical, shields: :down }
+    end
+
+    event :battle_stations do
+      # Battle stations only if ALL combat systems are ready
+      transition green: :battle, if_all_states: { shields: :up, weapons: :armed }
+    end
+  end
+end
+```
+
+## Error Handling
+
+State guards provide comprehensive error checking:
+
+```ruby
+# Referencing a non-existent state machine
+event :invalid, if_state: { nonexistent_machine: :some_state }
+# => ArgumentError: State machine 'nonexistent_machine' is not defined for StarshipBridge
+
+# Referencing a non-existent state
+event :another_invalid, if_state: { shields: :nonexistent_state }
+# => ArgumentError: State 'nonexistent_state' is not defined in state machine 'shields'
+```
+
+# Asynchronous State Machines
+
+State machines can operate asynchronously for high-performance applications. This is ideal for I/O-bound tasks, such as in web servers or other concurrent environments, where you don't want a long-running state transition (like one involving a network call) to block the entire thread.
+
+This feature is powered by the [async](https://github.com/socketry/async) gem and uses `concurrent-ruby` for enterprise-grade thread safety.
+
+## Platform Compatibility
+
+**Supported Platforms:**
+* MRI Ruby (CRuby) 3.2+
+* Other Ruby engines with full Fiber scheduler support
+
+**Unsupported Platforms:**
+* JRuby - Falls back to synchronous mode with warnings
+* TruffleRuby - Falls back to synchronous mode with warnings
+
+## Basic Async Usage
+
+Enable async mode by adding `async: true` to your state machine declaration:
+
+```ruby
+class AutonomousDrone < StarfleetShip
+  # Async-enabled state machine for autonomous operation
+  state_machine :status, async: true, initial: :docked do
+    event :launch do
+      transition docked: :flying
+    end
+
+    event :land do
+      transition flying: :docked
+    end
+  end
+
+  # Mixed configuration: some machines async, others sync
+  state_machine :teleporter_status, async: true, initial: :offline do
+    event :power_up do
+      transition offline: :charging
+    end
+
+    event :teleport do
+      transition ready: :teleporting
+    end
+  end
+
+  # Weapons remain synchronous for safety
+  state_machine :weapons, initial: :disarmed do
+    event :arm do
+      transition disarmed: :armed
+    end
+  end
+end
+```
+
+## Async Event Methods
+
+Async-enabled machines automatically generate async versions of event methods:
+
+```ruby
+drone = AutonomousDrone.new
+
+# Within an Async context
+Async do
+  # Async event firing - returns Async::Task
+  task = drone.launch_async
+  result = task.wait  # => true
+
+  # Bang methods for strict error handling
+  drone.power_up_async!  # => Async::Task (raises on failure)
+
+  # Generic async event firing
+  drone.fire_event_async(:teleport)  # => Async::Task
+end
+
+# Outside Async context - raises error
+drone.launch_async  # => RuntimeError: launch_async must be called within an Async context
+```
+
+## Thread Safety
+
+Async state machines use enterprise-grade thread safety with `concurrent-ruby`:
+
+```ruby
+# Concurrent operations are automatically thread-safe
+threads = []
+10.times do
+  threads << Thread.new do
+    Async do
+      drone.launch_async.wait
+      drone.land_async.wait
+    end
+  end
+end
+threads.each(&:join)
+```
+
+## Performance Considerations
+
+* **Thread Safety**: Uses `Concurrent::ReentrantReadWriteLock` for optimal read/write performance.
+* **Memory**: Each async-enabled object gets its own mutex (lazy-loaded).
+* **Marshalling**: Objects with async state machines can be serialized (mutex excluded/recreated).
+* **Mixed Mode**: You can mix async and sync state machines in the same class.
+
+## Dependencies
+
+Async functionality requires:
+
+```ruby
+# Gemfile (automatically scoped to MRI Ruby)
+platform :ruby do
+  gem 'async', '>= 2.25.0'
+  gem 'concurrent-ruby', '>= 1.3.5'
+end
+```
+
+*Note: These gems are only installed on supported platforms. JRuby/TruffleRuby won't attempt installation.*
+
 # Human-friendly names can be accessed for states/events
 Vehicle.human_state_name(:first_gear)               # => "first gear"
 Vehicle.human_alarm_state_name(:active)             # => "active"

data/lib/state_machines/async_mode/async_event_extensions.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module StateMachines
+  module AsyncMode
+    # Extensions to Event class for async bang methods
+    module AsyncEventExtensions
+      # Generate async bang methods for events when async mode is enabled
+      def define_helper(scope, method, *args, &block)
+        result = super
+
+        # If this is an async-enabled machine and we're defining an event method
+        if scope == :instance && method !~ /_async[!]?$/ && machine.async_mode_enabled?
+          qualified_name = method.to_s
+
+          # Create async version that returns a task
+          machine.define_helper(scope, "#{qualified_name}_async") do |machine, object, *method_args, **kwargs|
+            # Find the machine that has this event
+            target_machine = object.class.state_machines.values.find { |m| m.events[name] }
+
+            unless defined?(::Async::Task) && ::Async::Task.current?
+              raise RuntimeError, "#{qualified_name}_async must be called within an Async context"
+            end
+
+            Async do
+              target_machine.events[name].fire(object, *method_args, **kwargs)
+            end
+          end
+
+          # Create async bang version that raises exceptions when awaited
+          machine.define_helper(scope, "#{qualified_name}_async!") do |machine, object, *method_args, **kwargs|
+            # Find the machine that has this event
+            target_machine = object.class.state_machines.values.find { |m| m.events[name] }
+
+            unless defined?(::Async::Task) && ::Async::Task.current?
+              raise RuntimeError, "#{qualified_name}_async! must be called within an Async context"
+            end
+
+            Async do
+              # Use fire method which will raise exceptions on invalid transitions
+              target_machine.events[name].fire(object, *method_args, **kwargs) || raise(StateMachines::InvalidTransition.new(object, target_machine, name))
+            end
+          end
+        end
+
+        result
+      end
+    end
+  end
+end

data/lib/state_machines/async_mode/async_events.rb

@@ -0,0 +1,282 @@
+# frozen_string_literal: true
+
+module StateMachines
+  module AsyncMode
+    # Async-aware event firing capabilities using the async gem
+    module AsyncEvents
+      # Fires an event asynchronously using Async
+      # Returns an Async::Task that can be awaited for the result
+      #
+      # Example:
+      #   Async do
+      #     task = vehicle.async_fire_event(:ignite)
+      #     result = task.wait # => true/false
+      #   end
+      def async_fire_event(event_name, *args)
+        # Find the machine that has this event
+        machine = self.class.state_machines.values.find { |m| m.events[event_name] }
+
+        unless machine
+          raise ArgumentError, "Event #{event_name} not found in any state machine"
+        end
+
+        # Must be called within an Async context
+        unless defined?(::Async::Task) && ::Async::Task.current?
+          raise RuntimeError, "async_fire_event must be called within an Async context. Use: Async { vehicle.async_fire_event(:event) }"
+        end
+
+        Async do
+          machine.events[event_name].fire(self, *args)
+        end
+      end
+
+      # Fires multiple events asynchronously across different state machines
+      # Returns an array of Async::Tasks for concurrent execution
+      #
+      # Example:
+      #   Async do
+      #     tasks = vehicle.async_fire_events(:ignite, :buy_insurance)
+      #     results = tasks.map(&:wait) # => [true, true]
+      #   end
+      def async_fire_events(*event_names)
+        event_names.map { |event_name| async_fire_event(event_name) }
+      end
+
+      # Fires an event asynchronously and waits for completion
+      # This is a convenience method that creates and waits for the task
+      #
+      # Example:
+      #   result = vehicle.fire_event_async(:ignite) # => true/false
+      def fire_event_async(event_name, *args)
+        raise NoMethodError, "undefined method `fire_event_async' for #{self}" unless has_async_machines?
+        # Find the machine that has this event
+        machine = self.class.state_machines.values.find { |m| m.events[event_name] }
+
+        unless machine
+          raise ArgumentError, "Event #{event_name} not found in any state machine"
+        end
+
+        if defined?(::Async::Task) && ::Async::Task.current?
+          # Already in async context, just fire directly
+          machine.events[event_name].fire(self, *args)
+        else
+          # Create async context and wait for result
+          Async do
+            machine.events[event_name].fire(self, *args)
+          end.wait
+        end
+      end
+
+      # Fires multiple events asynchronously and waits for all completions
+      # Returns results in the same order as the input events
+      #
+      # Example:
+      #   results = vehicle.fire_events_async(:ignite, :buy_insurance) # => [true, true]
+      def fire_events_async(*event_names)
+        raise NoMethodError, "undefined method `fire_events_async' for #{self}" unless has_async_machines?
+        if defined?(::Async::Task) && ::Async::Task.current?
+          # Already in async context, run concurrently
+          tasks = event_names.map { |event_name| async_fire_event(event_name) }
+          tasks.map(&:wait)
+        else
+          # Create async context and run concurrently
+          Async do
+            tasks = event_names.map { |event_name| async_fire_event(event_name) }
+            tasks.map(&:wait)
+          end.wait
+        end
+      end
+
+      # Fires an event asynchronously using Async and raises exception on failure
+      # Returns an Async::Task that raises StateMachines::InvalidTransition when awaited
+      #
+      # Example:
+      #   Async do
+      #     begin
+      #       task = vehicle.async_fire_event!(:ignite)
+      #       result = task.wait
+      #       puts "Event fired successfully!"
+      #     rescue StateMachines::InvalidTransition => e
+      #       puts "Transition failed: #{e.message}"
+      #     end
+      #   end
+      def async_fire_event!(event_name, *args)
+        # Find the machine that has this event
+        machine = self.class.state_machines.values.find { |m| m.events[event_name] }
+
+        unless machine
+          raise ArgumentError, "Event #{event_name} not found in any state machine"
+        end
+
+        # Must be called within an Async context
+        unless defined?(::Async::Task) && ::Async::Task.current?
+          raise RuntimeError, "async_fire_event! must be called within an Async context. Use: Async { vehicle.async_fire_event!(:event) }"
+        end
+
+        Async do
+          # Use the bang version which raises exceptions on failure
+          machine.events[event_name].fire(self, *args) || raise(StateMachines::InvalidTransition.new(self, machine, event_name))
+        end
+      end
+
+      # Fires an event asynchronously and waits for result, raising exceptions on failure
+      # This is a convenience method that creates and waits for the task
+      #
+      # Example:
+      #   begin
+      #     result = vehicle.fire_event_async!(:ignite)
+      #     puts "Event fired successfully!"
+      #   rescue StateMachines::InvalidTransition => e
+      #     puts "Transition failed: #{e.message}"
+      #   end
+      def fire_event_async!(event_name, *args)
+        raise NoMethodError, "undefined method `fire_event_async!' for #{self}" unless has_async_machines?
+        # Find the machine that has this event
+        machine = self.class.state_machines.values.find { |m| m.events[event_name] }
+
+        unless machine
+          raise ArgumentError, "Event #{event_name} not found in any state machine"
+        end
+
+        if defined?(::Async::Task) && ::Async::Task.current?
+          # Already in async context, just fire directly with bang behavior
+          machine.events[event_name].fire(self, *args) || raise(StateMachines::InvalidTransition.new(self, machine, event_name))
+        else
+          # Create async context and wait for result (may raise exception)
+          Async do
+            machine.events[event_name].fire(self, *args) || raise(StateMachines::InvalidTransition.new(self, machine, event_name))
+          end.wait
+        end
+      end
+
+      # Dynamically handle individual event async methods
+      # This provides launch_async, launch_async!, arm_weapons_async, etc.
+      def method_missing(method_name, *args, **kwargs, &block)
+        method_str = method_name.to_s
+
+        # Check if this is an async event method
+        if method_str.end_with?('_async!')
+          # Remove the _async! suffix to get the base event method
+          base_method = method_str.chomp('_async!').to_sym
+
+          # Check if the base method exists and this machine is async-enabled
+          if respond_to?(base_method) && async_method_for_event?(base_method)
+            return handle_individual_event_async_bang(base_method, *args, **kwargs)
+          end
+        elsif method_str.end_with?('_async')
+          # Remove the _async suffix to get the base event method
+          base_method = method_str.chomp('_async').to_sym
+
+          # Check if the base method exists and this machine is async-enabled
+          if respond_to?(base_method) && async_method_for_event?(base_method)
+            return handle_individual_event_async(base_method, *args, **kwargs)
+          end
+        end
+
+        # If not an async method, call the original method_missing
+        super
+      end
+
+      # Check if we should respond to async methods for this event
+      def respond_to_missing?(method_name, include_private = false)
+        # Only provide async methods if this object has async-enabled machines
+        return super unless has_async_machines?
+
+        method_str = method_name.to_s
+
+        if method_str.end_with?('_async!') || method_str.end_with?('_async')
+          base_method = method_str.chomp('_async!').chomp('_async').to_sym
+          return respond_to?(base_method) && async_method_for_event?(base_method)
+        end
+
+        super
+      end
+
+      # Check if this object has any async-enabled state machines
+      def has_async_machines?
+        self.class.state_machines.any? { |name, machine| machine.async_mode_enabled? }
+      end
+
+      private
+
+      # Check if this event method should have async versions
+      def async_method_for_event?(event_method)
+        # Find which machine contains this event
+        self.class.state_machines.each do |name, machine|
+          if machine.async_mode_enabled?
+            # Check if this event method belongs to this machine
+            machine.events.each do |event|
+              qualified_name = event.qualified_name
+              if qualified_name.to_sym == event_method || "#{qualified_name}!".to_sym == event_method
+                return true
+              end
+            end
+          end
+        end
+        false
+      end
+
+      # Handle individual event async methods (returns task)
+      def handle_individual_event_async(event_method, *args, **kwargs)
+
+        unless defined?(::Async::Task) && ::Async::Task.current?
+          raise RuntimeError, "#{event_method}_async must be called within an Async context"
+        end
+
+        Async do
+          send(event_method, *args, **kwargs)
+        end
+      end
+
+      # Handle individual event async bang methods (returns task, raises on failure)
+      def handle_individual_event_async_bang(event_method, *args, **kwargs)
+        # Extract event name from method and use bang version
+        bang_method = "#{event_method}!".to_sym
+
+        unless defined?(::Async::Task) && ::Async::Task.current?
+          raise RuntimeError, "#{event_method}_async! must be called within an Async context"
+        end
+
+        Async do
+          send(bang_method, *args, **kwargs)
+        end
+      end
+
+      # Extract event name from method name, handling namespaced events
+      def extract_event_name(method_name)
+        method_str = method_name.to_s
+
+        # Find the machine and event for this method
+        self.class.state_machines.each do |name, machine|
+          machine.events.each do |event|
+            qualified_name = event.qualified_name
+            if qualified_name.to_s == method_str || "#{qualified_name}!".to_s == method_str
+              return event.name
+            end
+          end
+        end
+
+        # Fallback: assume the method name is the event name
+        method_str.chomp('!').to_sym
+      end
+
+      public
+
+      # Fires multiple events concurrently within an async context
+      # This method should be called from within an Async block
+      #
+      # Example:
+      #   Async do
+      #     results = vehicle.fire_events_concurrent(:ignite, :buy_insurance)
+      #   end
+      def fire_events_concurrent(*event_names)
+        unless defined?(::Async::Task) && ::Async::Task.current?
+          raise RuntimeError, "fire_events_concurrent must be called within an Async context"
+        end
+
+        tasks = async_fire_events(*event_names)
+        tasks.map(&:wait)
+      end
+    end
+  end
+end

data/lib/state_machines/async_mode/async_machine.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module StateMachines
+  module AsyncMode
+    # Enhanced machine class with async capabilities
+    module AsyncMachine
+      # Thread-safe state reading for machines
+      def read_safely(object, attribute, ivar = false)
+        if object.respond_to?(:read_state_safely)
+          object.read_state_safely(self, attribute, ivar)
+        else
+          read(object, attribute, ivar)
+        end
+      end
+
+      # Thread-safe state writing for machines
+      def write_safely(object, attribute, value, ivar = false)
+        if object.respond_to?(:write_state_safely)
+          object.write_state_safely(self, attribute, value, ivar)
+        else
+          write(object, attribute, value, ivar)
+        end
+      end
+
+      # Fires an event asynchronously on the given object
+      # Returns an Async::Task for concurrent execution
+      def async_fire_event(object, event_name, *args)
+        unless defined?(::Async::Task) && ::Async::Task.current?
+          raise RuntimeError, "async_fire_event must be called within an Async context"
+        end
+
+        Async do
+          events[event_name].fire(object, *args)
+        end
+      end
+
+      # Creates an async-aware transition collection
+      # Supports concurrent transition execution with proper synchronization
+      def create_async_transition_collection(transitions, options = {})
+        if defined?(AsyncTransitionCollection)
+          AsyncTransitionCollection.new(transitions, options)
+        else
+          # Fallback to regular collection if async collection isn't available
+          TransitionCollection.new(transitions, options)
+        end
+      end
+
+      # Thread-safe callback execution for async operations
+      def run_callbacks_safely(type, object, context, transition)
+        if object.respond_to?(:state_machine_mutex)
+          object.state_machine_mutex.with_read_lock do
+            callbacks[type].each { |callback| callback.call(object, context, transition) }
+          end
+        else
+          callbacks[type].each { |callback| callback.call(object, context, transition) }
+        end
+      end
+    end
+  end
+end