state_machines 0.30.0 → 0.40.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5c732f34387da18f4dc1c3d78cad1fbb111cc88d06d9fe3edcda912adc5e655a
-  data.tar.gz: ef0079a89a1b0e4ddea45dd4a79e11de12740d4eb0c2aa98ad95b5ca7ae3eab8
+  metadata.gz: bc7dae3a88c68f1327da47debac2546fde7c4459346dbfefaabbc4bed5dc5554
+  data.tar.gz: 2fbfc7157580635bd546b9096138677d44b58a92578d6341667a1722c91ccb66
 SHA512:
-  metadata.gz: d71a5bd20b0de0b19e4684b4251954d0cf648e5454b57af96555372bbdee59a9ac855bb27d182e018f87ffa0525b5cd3daff5c3ce53c483f3dec4954d076a331
-  data.tar.gz: 179e0cb6c2a31d14c4078820d254ce35e26d9b5aaa2646e4766b842127411cf49e5ad697d0a764ba79a0036bce5dc288ef113b8bef57c3cac64de8816a23f49b
+  metadata.gz: 4b5ba6ecdeb4dd612c6865657e0a0b590d3fa67fed522359c7b388ab88401283d953d857fc73fab2fbeb97388c5bb71b5f4e125d70366a03547aea91b991ab35
+  data.tar.gz: 07c96c5556ae74d933de3cf1b132cfda9144404361cca87c24c14694e2158e5f0437d65a4ab08b857dca8ad0c453d7fdc674abeb770c528d7ec45e4b060c8ddd

data/README.md

@@ -1,4 +1,5 @@
 ![Build Status](https://github.com/state-machines/state_machines/actions/workflows/ruby.yml/badge.svg)
+
 # State Machines
 
 State Machines adds support for creating state machines for attributes on any Ruby class.
@@ -9,15 +10,21 @@ State Machines adds support for creating state machines for attributes on any Ru
 
 Add this line to your application's Gemfile:
 
-    gem 'state_machines'
+```ruby
+gem 'state_machines'
+```
 
 And then execute:
 
-    $ bundle
+```sh
+bundle
+```
 
 Or install it yourself as:
 
-    $ gem install state_machines
+```sh
+gem install state_machines
+```
 
 ## Usage
 
@@ -38,7 +45,7 @@ Class definition:
 
 ```ruby
 class Vehicle
-  attr_accessor :seatbelt_on, :time_used, :auto_shop_busy
+  attr_accessor :seatbelt_on, :time_used, :auto_shop_busy, :parking_meter_number
 
   state_machine :state, initial: :parked do
     before_transition parked: any - :parked, do: :put_on_seatbelt
@@ -61,6 +68,18 @@ class Vehicle
       transition [:idling, :first_gear] => :parked
     end
 
+    before_transition on: :park do |vehicle, transition|
+      # If using Rails:
+      # options = transition.args.extract_options!
+
+      options = transition.args.last.is_a?(Hash) ? transition.args.pop : {}
+      meter_number = options[:meter_number]
+
+      unless meter_number.nil?
+        vehicle.parking_meter_number = meter_number
+      end
+    end
+
     event :ignite do
       transition stalled: same, parked: :idling
     end
@@ -130,6 +149,7 @@ class Vehicle
     @seatbelt_on = false
     @time_used = 0
     @auto_shop_busy = true
+    @parking_meter_number = nil
     super() # NOTE: This *must* be called, otherwise states won't get initialized
   end
 
@@ -200,6 +220,11 @@ vehicle.park!                   # => StateMachines:InvalidTransition: Cannot tra
 vehicle.state?(:parked)         # => false
 vehicle.state?(:invalid)        # => IndexError: :invalid is an invalid name
 
+# Transition callbacks can receive arguments
+vehicle.park(meter_number: '12345') # => true
+vehicle.parked?                     # => true
+vehicle.parking_meter_number        # => "12345"
+
 # Namespaced machines have uniquely-generated methods
 vehicle.alarm_state             # => 1
 vehicle.alarm_state_name        # => :active
@@ -790,7 +815,7 @@ For RSpec testing, use the custom RSpec matchers:
 
 ## Contributing
 
-1. Fork it ( https://github.com/state-machines/state_machines/fork )
+1. Fork it ( <https://github.com/state-machines/state_machines/fork> )
 2. Create your feature branch (`git checkout -b my-new-feature`)
 3. Commit your changes (`git commit -am 'Add some feature'`)
 4. Push to the branch (`git push origin my-new-feature`)

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

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