Module: StateMachines::Machine::AsyncExtensions

Included in:
StateMachines::Machine
Defined in:
lib/state_machines/machine/async_extensions.rb

Overview

AsyncMode extensions for the Machine class Provides async-aware methods while maintaining backward compatibility

Instance Method Summary collapse

Instance Method Details

#async_mode_enabled? ⇒ Boolean

Check if this specific machine instance has async mode enabled

Returns:

  • (Boolean) 


63
64
65
 
# File 'lib/state_machines/machine/async_extensions.rb', line 63

def async_mode_enabled?
  @async_mode_enabled || false
end

#configure_async_mode!(enabled = true) ⇒ Object

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



25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
 
# File 'lib/state_machines/machine/async_extensions.rb', line 25

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)
      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

#read_safely(object, attribute, ivar = false) ⇒ Object

Thread-safe version of state reading



68
69
70
 
# File 'lib/state_machines/machine/async_extensions.rb', line 68

def read_safely(object, attribute, ivar = false)
  object.read_state_safely(self, attribute, ivar)
end

#run_callbacks_safely(type, object, context, transition) ⇒ Object

Thread-safe callback execution for async operations



78
79
80
81
82
 
# File 'lib/state_machines/machine/async_extensions.rb', line 78

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

#write_safely(object, attribute, value, ivar = false) ⇒ Object

Thread-safe version of state writing



73
74
75
 
# File 'lib/state_machines/machine/async_extensions.rb', line 73

def write_safely(object, attribute, value, ivar = false)
  object.write_state_safely(self, attribute, value, ivar)
end