state_machines 0.30.0 → 0.40.0

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

@@ -108,16 +108,18 @@ module StateMachines
     # * <tt>:guard</tt> - Whether to guard matches with the if/unless
     #   conditionals defined for this branch.  Default is true.
     #
+    # Event arguments are passed to guard conditions if they accept multiple parameters.
+    #
     # == Examples
     #
     #   branch = StateMachines::Branch.new(:parked => :idling, :on => :ignite)
     #
     #   branch.match(object, :on => :ignite)  # => {:to => ..., :from => ..., :on => ...}
     #   branch.match(object, :on => :park)    # => nil
-    def match(object, query = {})
+    def match(object, query = {}, event_args = [])
       StateMachines::OptionsValidator.assert_valid_keys!(query, :from, :to, :on, :guard)
 
-      return unless (match = match_query(query)) && matches_conditions?(object, query)
+      return unless (match = match_query(query)) && matches_conditions?(object, query, event_args)
 
       match
     end
@@ -178,11 +180,23 @@ module StateMachines
     end
 
     # Verifies that the conditionals for this branch evaluate to true for the
-    # given object
-    def matches_conditions?(object, query)
-      query[:guard] == false ||
-        (Array(if_condition).all? { |condition| evaluate_method(object, condition) } &&
-          !Array(unless_condition).any? { |condition| evaluate_method(object, condition) })
+    # 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
+      end
     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
@@ -193,7 +194,7 @@ module StateMachines
       else
         @methods.each do |method|
           result = evaluate_method(object, method, *args)
-          throw :halt if @terminator && @terminator.call(result)
+          throw :halt if @terminator&.call(result)
         end
       end
     end

data/lib/state_machines/eval_helpers.rb

@@ -47,6 +47,11 @@ module StateMachines
     # the method defines additional arguments other than the object context,
     # then all arguments are required.
     #
+    # For guard conditions in state machines, event arguments can be passed
+    # automatically based on the guard's arity:
+    # - Guards with arity 1 receive only the object (backward compatible)
+    # - Guards with arity -1 or > 1 receive object + event arguments
+    #
     # For example,
     #
     #   person = Person.new('John Smith')
@@ -54,18 +59,30 @@ module StateMachines
     #   evaluate_method(person, lambda {|person| person.name}, 21)                              # => "John Smith"
     #   evaluate_method(person, lambda {|person, age| "#{person.name} is #{age}"}, 21)          # => "John Smith is 21"
     #   evaluate_method(person, lambda {|person, age| "#{person.name} is #{age}"}, 21, 'male')  # => ArgumentError: wrong number of arguments (3 for 2)
+    #
+    # With event arguments for guards:
+    #
+    #   # Single parameter guard (backward compatible)
+    #   guard = lambda {|obj| obj.valid? }
+    #   evaluate_method_with_event_args(object, guard, [arg1, arg2])  # => calls guard.call(object)
+    #
+    #   # Multi-parameter guard (receives event args)
+    #   guard = lambda {|obj, *args| obj.valid? && args[0] == :force }
+    #   evaluate_method_with_event_args(object, guard, [:force])      # => calls guard.call(object, :force)
     def evaluate_method(object, method, *args, **, &block)
       case method
-      when Symbol
+      in Symbol => sym
         klass = (class << object; self; end)
-        args = [] if (klass.method_defined?(method) || klass.private_method_defined?(method)) && object.method(method).arity == 0
-        object.send(method, *args, **, &block)
-      when Proc
+        args = [] if (klass.method_defined?(sym) || klass.private_method_defined?(sym)) && object.method(sym).arity.zero?
+        object.send(sym, *args, **, &block)
+      in Proc => proc
         args.unshift(object)
-        arity = method.arity
+        arity = proc.arity
         # Handle blocks for Procs
-        if block_given? && arity != 0
-          if [1, 2].include?(arity)
+        case [block_given?, arity]
+        in [true, arity] if arity != 0
+          case arity
+          in 1 | 2
             # Force the block to be either the only argument or the second one
             # after the object (may mean additional arguments get discarded)
             args = args[0, arity - 1] + [block]
@@ -73,52 +90,126 @@ module StateMachines
             # insert the block to the end of the args
             args << block
           end
-        elsif [0, 1].include?(arity)
+        in [_, 0 | 1]
           # These method types are only called with 0, 1, or n arguments
           args = args[0, arity]
+        else
+          # No changes needed for other cases
         end
 
         # Call the Proc with the arguments
-        method.call(*args, **)
+        proc.call(*args, **)
 
-      when Method
+      in Method => meth
         args.unshift(object)
-        arity = method.arity
+        arity = meth.arity
 
         # Methods handle blocks via &block, not as arguments
         # Only limit arguments if necessary based on arity
         args = args[0, arity] if [0, 1].include?(arity)
 
         # Call the Method with the arguments and pass the block
-        method.call(*args, **, &block)
-      when String
+        meth.call(*args, **, &block)
+      in String => str
         # Input validation for string evaluation
-        validate_eval_string(method)
+        validate_eval_string(str)
 
-        if block_given?
-          if StateMachines::Transition.pause_supported?
-            eval(method, object.instance_eval { binding }, &block)
-          else
-            # Support for JRuby and Truffle Ruby, which don't support binding blocks
-            # Need to check with @headius, if jruby 10 does now.
-            eigen = class << object; self; end
-            eigen.class_eval <<-RUBY, __FILE__, __LINE__ + 1
-                  def __temp_eval_method__(*args, &b)
-                    #{method}
-                  end
-            RUBY
-            result = object.__temp_eval_method__(*args, &block)
-            eigen.send(:remove_method, :__temp_eval_method__)
-            result
-          end
-        else
-          eval(method, object.instance_eval { binding })
+        case [block_given?, StateMachines::Transition.pause_supported?]
+        in [true, true]
+          eval(str, object.instance_eval { binding }, &block)
+        in [true, false]
+          # Support for JRuby and Truffle Ruby, which don't support binding blocks
+          # Need to check with @headius, if jruby 10 does now.
+          eigen = class << object; self; end
+          eigen.class_eval <<-RUBY, __FILE__, __LINE__ + 1
+                def __temp_eval_method__(*args, &b)
+                  #{str}
+                end
+          RUBY
+          result = object.__temp_eval_method__(*args, &block)
+          eigen.send(:remove_method, :__temp_eval_method__)
+          result
+        in [false, _]
+          eval(str, object.instance_eval { binding })
         end
       else
         raise ArgumentError, 'Methods must be a symbol denoting the method to call, a block to be invoked, or a string to be evaluated'
       end
     end
 
+    # Evaluates a guard method with support for event arguments passed to transitions.
+    # This method uses arity detection to determine whether to pass event arguments
+    # to the guard, ensuring backward compatibility.
+    #
+    # == Parameters
+    # * object - The object context to evaluate within
+    # * method - The guard method/proc to evaluate
+    # * event_args - Array of arguments passed to the event (optional)
+    #
+    # == Arity-based behavior
+    # * Arity 1: Only passes the object (backward compatible)
+    # * Arity -1 or > 1: Passes object + event arguments
+    #
+    # == Examples
+    #
+    #   # Backward compatible single-parameter guard
+    #   guard = lambda {|obj| obj.valid? }
+    #   evaluate_method_with_event_args(object, guard, [:force])  # => calls guard.call(object)
+    #
+    #   # New multi-parameter guard receiving event args
+    #   guard = lambda {|obj, *args| obj.valid? && args[0] != :skip }
+    #   evaluate_method_with_event_args(object, guard, [:skip])   # => calls guard.call(object, :skip)
+    def evaluate_method_with_event_args(object, method, event_args = [])
+      case method
+      in Symbol
+        # Symbol methods currently don't support event arguments
+        # This maintains backward compatibility
+        evaluate_method(object, method)
+      in Proc => proc
+        arity = proc.arity
+
+        # Arity-based decision for backward compatibility using pattern matching
+        case arity
+        in 0
+          proc.call
+        in 1
+          proc.call(object)
+        in -1
+          # Splat parameters: object + all event args
+          proc.call(object, *event_args)
+        in arity if arity > 1
+          # Explicit parameters: object + limited event args
+          args_needed = arity - 1 # Subtract 1 for the object parameter
+          proc.call(object, *event_args[0, args_needed])
+        else
+          # Negative arity other than -1 (unlikely but handle gracefully)
+          proc.call(object, *event_args)
+        end
+      in Method => meth
+        arity = meth.arity
+
+        case arity
+        in 0
+          meth.call
+        in 1
+          meth.call(object)
+        in -1
+          meth.call(object, *event_args)
+        in arity if arity > 1
+          args_needed = arity - 1
+          meth.call(object, *event_args[0, args_needed])
+        else
+          meth.call(object, *event_args)
+        end
+      in String
+        # String evaluation doesn't support event arguments for security
+        evaluate_method(object, method)
+      else
+        # Fall back to standard evaluation
+        evaluate_method(object, method)
+      end
+    end
+
     private
 
     # Validates string input before eval to prevent code injection

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
@@ -131,12 +133,14 @@ module StateMachines
     #   specified, then this will match any to state.
     # * <tt>:guard</tt> - Whether to guard transitions with the if/unless
     #   conditionals defined for each one.  Default is true.
-    def transition_for(object, requirements = {})
+    #
+    # Event arguments are passed to guard conditions if they accept multiple parameters.
+    def transition_for(object, requirements = {}, *event_args)
       StateMachines::OptionsValidator.assert_valid_keys!(requirements, :from, :to, :guard)
       requirements[:from] = machine.states.match!(object).name unless (custom_from_state = requirements.include?(:from))
 
       branches.each do |branch|
-        next unless (match = branch.match(object, requirements))
+        next unless (match = branch.match(object, requirements, event_args))
 
         # Branch allows for the transition to occur
         from = requirements[:from]
@@ -161,13 +165,13 @@ module StateMachines
     #
     # Any additional arguments are passed to the StateMachines::Transition#perform
     # instance method.
-    def fire(object, *)
+    def fire(object, *event_args)
       machine.reset(object)
 
-      if (transition = transition_for(object))
-        transition.perform(*)
+      if (transition = transition_for(object, {}, *event_args))
+        transition.perform(*event_args)
       else
-        on_failure(object, *)
+        on_failure(object, *event_args)
         false
       end
     end
@@ -204,13 +208,13 @@ module StateMachines
     #   event.transition all - :idling => :parked, :idling => same
     #   event   # => #<StateMachines::Event name=:park transitions=[all - :idling => :parked, :idling => same]>
     def inspect
-      transitions = branches.map do |branch|
+      transitions = branches.flat_map do |branch|
         branch.state_requirements.map do |state_requirement|
           "#{state_requirement[:from].description} => #{state_requirement[:to].description}"
-        end * ', '
-      end
+        end
+      end.join(', ')
 
-      "#<#{self.class} name=#{name.inspect} transitions=[#{transitions * ', '}]>"
+      "#<#{self.class} name=#{name.inspect} transitions=[#{transitions}]>"
     end
 
     protected

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
@@ -558,8 +559,8 @@ module StateMachines
         else
           name = self.name
           helper_module.class_eval do
-            define_method(method) do |*block_args, **block_kwargs|
-              block.call((scope == :instance ? self.class : self).state_machine(name), self, *block_args, **block_kwargs)
+            define_method(method) do |*args, **kwargs|
+              block.call((scope == :instance ? self.class : self).state_machine(name), self, *args, **kwargs)
             end
           end
         end

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
@@ -289,9 +290,9 @@ module StateMachines
       predicate_method = "#{qualified_name}?"
 
       if machine.send(:owner_class_ancestor_has_method?, :instance, predicate_method)
-        warn "Instance method #{predicate_method.inspect} is already defined in #{machine.owner_class.ancestors.first.inspect}, use generic helper instead or set StateMachines::Machine.ignore_method_conflicts = true."
+        warn_about_method_conflict(predicate_method, machine.owner_class.ancestors.first)
       elsif machine.send(:owner_class_has_method?, :instance, predicate_method)
-        warn "Instance method #{predicate_method.inspect} is already defined in #{machine.owner_class.inspect}, use generic helper instead or set StateMachines::Machine.ignore_method_conflicts = true."
+        warn_about_method_conflict(predicate_method, machine.owner_class)
       else
         machine.define_helper(:instance, predicate_method) do |machine, object|
           machine.states.matches?(object, name)
@@ -303,5 +304,11 @@ module StateMachines
     def context_name_for(method)
       :"__#{machine.name}_#{name}_#{method}_#{@context.object_id}__"
     end
+
+    def warn_about_method_conflict(method, defined_in)
+      return if StateMachines::Machine.ignore_method_conflicts
+
+      warn "Instance method #{method.inspect} is already defined in #{defined_in.inspect}, use generic helper instead or set StateMachines::Machine.ignore_method_conflicts = true."
+    end
   end
 end