state_machines 0.40.0 → 0.50.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bc7dae3a88c68f1327da47debac2546fde7c4459346dbfefaabbc4bed5dc5554
-  data.tar.gz: 2fbfc7157580635bd546b9096138677d44b58a92578d6341667a1722c91ccb66
+  metadata.gz: 247ae1ee6fa7beb6ac29a68dfd400ea41a3923b973d842a5adb2ef78960b3266
+  data.tar.gz: 7240a29d3d87740ade0d0197e9c4c0192176023f23e453d1ba659e8be905afef
 SHA512:
-  metadata.gz: 4b5ba6ecdeb4dd612c6865657e0a0b590d3fa67fed522359c7b388ab88401283d953d857fc73fab2fbeb97388c5bb71b5f4e125d70366a03547aea91b991ab35
-  data.tar.gz: 07c96c5556ae74d933de3cf1b132cfda9144404361cca87c24c14694e2158e5f0437d65a4ab08b857dca8ad0c453d7fdc674abeb770c528d7ec45e4b060c8ddd
+  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/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/event.rb

@@ -104,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/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module StateMachines
-  VERSION = '0.40.0'
+  VERSION = '0.50.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: state_machines
 version: !ruby/object:Gem::Version
-  version: 0.40.0
+  version: 0.50.0
 platform: ruby
 authors:
 - Abdelkader Boudih