fractor 0.1.9 → 0.1.10

data/lib/fractor/config_schema.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+module Fractor
+  # Configuration schema validation module.
+  #
+  # Provides declarative configuration schemas with validation.
+  # Useful for validating configuration options at initialization time.
+  #
+  # @example Define a schema
+  #   class MyConfig
+  #     extend Fractor::ConfigSchema
+  #
+  #     schema :worker_pools do
+  #       type Array
+  #       default []
+  #       description "Array of worker pool configurations"
+  #     end
+  #
+  #     schema :continuous_mode do
+  #       type :boolean
+  #       default false
+  #       description "Whether to run in continuous mode"
+  #     end
+  #   end
+  #
+  # @example Validate configuration
+  #   MyConfig.validate!(worker_pools: [...], continuous_mode: true)
+  module ConfigSchema
+    # Schema entry definition
+    class SchemaEntry
+      attr_reader :name, :type, :default, :optional, :description
+
+      def initialize(name, **options)
+        @name = name
+        @type = options[:type]
+        @default = options[:default]
+        @optional = options.fetch(:optional, true)
+        @description = options[:description]
+      end
+
+      # Validate a value against this schema entry
+      # @return [Array<String>] Array of error messages (empty if valid)
+      def validate(value)
+        errors = []
+
+        # Check nil for optional fields
+        if value.nil?
+          errors << "#{name} is required" unless @optional
+          return errors
+        end
+
+        # Type validation
+        if @type && !type_matches?(value)
+          errors << "#{name} must be of type #{type_description}, got #{value.class}"
+        end
+
+        errors
+      end
+
+      private
+
+      def type_matches?(value)
+        case @type
+        when :boolean
+          value.is_a?(TrueClass) || value.is_a?(FalseClass)
+        when Class
+          value.is_a?(@type)
+        when Array
+          @type.any? { |t| value.is_a?(t) }
+        else
+          true # No type constraint
+        end
+      end
+
+      def type_description
+        case @type
+        when :boolean
+          "boolean"
+        when Class
+          @type.name
+        when Array
+          @type.map { |t| t.is_a?(Class) ? t.name : t.to_s }.join(" or ")
+        else
+          "any"
+        end
+      end
+    end
+
+    # Module-level methods for defining schemas
+    def self.extended(base)
+      base.instance_variable_set(:@schema_entries, {})
+      base.singleton_class.prepend(SchemaClassMethods)
+    end
+
+    module SchemaClassMethods
+      # Define a configuration schema entry
+      # @param name [Symbol] Configuration key name
+      # @param options [Hash] Schema options (type, default, optional, description)
+      def schema(name, **options)
+        @schema_entries ||= {}
+        @schema_entries[name] = SchemaEntry.new(name, **options)
+      end
+
+      # Get all schema entries
+      # @return [Hash] Schema entries by name
+      def schema_entries
+        @schema_entries || {}
+      end
+
+      # Validate configuration against schema
+      # @param config [Hash] Configuration to validate
+      # @raise [ArgumentError] If configuration is invalid
+      # @return [Hash] Validated and normalized configuration
+      def validate!(config = {})
+        all_errors = []
+
+        schema_entries.each do |name, entry|
+          value = config.fetch(name, entry.default)
+          errors = entry.validate(value)
+          all_errors.concat(errors.map { |e| "- #{e}" })
+        end
+
+        # Check for unknown keys
+        unknown_keys = config.keys - schema_entries.keys.symbolize_keys
+        unknown_keys.each do |key|
+          all_errors << "- Unknown configuration option: #{key}"
+        end
+
+        unless all_errors.empty?
+          raise ArgumentError,
+                "Invalid configuration:\n#{all_errors.join("\n")}\n\n" \
+                "Valid options:\n#{schema_help}"
+        end
+
+        config
+      end
+
+      # Generate schema help text
+      # @return [String] Help text describing all schema entries
+      def schema_help
+        lines = []
+        schema_entries.each_value do |entry|
+          type_desc = case entry.type
+                      when :boolean then "boolean"
+                      when Class then entry.type.name
+                      when Array then entry.type.map(&:name).join(" | ")
+                      else "any"
+                      end
+          default_desc = entry.optional ? " (default: #{entry.default.inspect})" : " (required)"
+          desc = entry.description ? " - #{entry.description}" : ""
+          lines << "  #{entry.name}: #{type_desc}#{default_desc}#{desc}"
+        end
+        lines.join("\n")
+      end
+
+      # Get schema as a hash (for documentation purposes)
+      # @return [Hash] Schema definition
+      def schema_definition
+        schema_entries.transform_values do |entry|
+          {
+            type: entry.type,
+            default: entry.default,
+            optional: entry.optional,
+            description: entry.description,
+          }
+        end
+      end
+    end
+  end
+end

data/lib/fractor/main_loop_handler.rb

@@ -20,8 +20,7 @@ module Fractor
     # @param debug [Boolean] Whether debug mode is enabled
     # @return [MainLoopHandler] The appropriate subclass instance
     def self.create(supervisor, debug: false)
-      ruby_4_0 = Gem::Version.new(RUBY_VERSION) >= Gem::Version.new("4.0.0")
-      if ruby_4_0
+      if Fractor::RUBY_4_0_OR_HIGHER
         MainLoopHandler4.new(supervisor, debug: debug)
       else
         MainLoopHandler3.new(supervisor, debug: debug)
@@ -350,11 +349,11 @@ module Fractor
     end
 
     def work_callbacks
-      @supervisor.instance_variable_get(:@work_callbacks)
+      @supervisor.callback_registry.work_callbacks
     end
 
     def error_callbacks
-      @supervisor.instance_variable_get(:@error_callbacks)
+      @supervisor.callback_registry.error_callbacks
     end
 
     # Check if running on Windows with Ruby 3.4
@@ -362,10 +361,7 @@ module Fractor
     #
     # @return [Boolean]
     def windows_ruby_34?
-      return false unless RUBY_PLATFORM.match?(/mswin|mingw|cygwin/)
-
-      ruby_version = Gem::Version.new(RUBY_VERSION)
-      ruby_version >= Gem::Version.new("3.4.0") && ruby_version < Gem::Version.new("3.5.0")
+      Fractor::WINDOWS_RUBY_34
     end
 
     # Handle a stuck ractor by identifying and removing it from the active pool

data/lib/fractor/main_loop_handler3.rb

@@ -19,7 +19,7 @@ module Fractor
         active_ractors = get_active_ractors
 
         # Check for new work from callbacks if in continuous mode
-        process_work_callbacks if continuous_mode? && !work_callbacks.empty?
+        process_work_callbacks if continuous_mode? && @supervisor.callback_registry.has_work_callbacks?
 
         # Handle edge cases - break if edge case handler indicates we should
         next if handle_edge_cases(active_ractors, processed_count)
@@ -46,7 +46,7 @@ module Fractor
     # @return [Array<Ractor>]
     def get_active_ractors
       ractors_map.keys.reject do |ractor|
-        ractor == wakeup_ractor && !(continuous_mode? && !work_callbacks.empty?)
+        ractor == wakeup_ractor && !(continuous_mode? && @supervisor.callback_registry.has_work_callbacks?)
       end
     end
 
@@ -54,16 +54,14 @@ module Fractor
     #
     # @return [void]
     def process_work_callbacks
-      work_callbacks.each do |callback|
-        new_work = callback.call
-        if new_work && !new_work.empty?
-          @supervisor.add_work_items(new_work)
-          puts "Work source provided #{new_work.size} new items" if @debug
-
-          # Distribute work to idle workers
-          distributed = work_distribution_manager.distribute_to_idle_workers
-          puts "Distributed work to #{distributed} idle workers" if @debug && distributed.positive?
-        end
+      new_work = @supervisor.callback_registry.process_work_callbacks
+      if new_work && !new_work.empty?
+        @supervisor.add_work_items(new_work)
+        puts "Work source provided #{new_work.size} new items" if @debug
+
+        # Distribute work to idle workers
+        distributed = work_distribution_manager.distribute_to_idle_workers
+        puts "Distributed work to #{distributed} idle workers" if @debug && distributed.positive?
       end
     end
 

data/lib/fractor/main_loop_handler4.rb

@@ -8,10 +8,11 @@ module Fractor
   class MainLoopHandler4 < MainLoopHandler
     # Run the main event loop for Ruby 4.0+.
     def run_loop
-      # Build mapping of response ports to workers for message routing
-      port_to_worker = build_port_to_worker_map
-
       loop do
+        # Build mapping of response ports to workers for message routing
+        # REBUILD ON EACH ITERATION to handle terminated workers
+        port_to_worker = build_port_to_worker_map
+
         processed_count = get_processed_count
 
         # Check loop termination condition
@@ -22,7 +23,7 @@ module Fractor
         active_items = get_active_items
 
         # Check for new work from callbacks if in continuous mode
-        process_work_callbacks if continuous_mode? && !work_callbacks.empty?
+        process_work_callbacks if continuous_mode? && @supervisor.callback_registry.has_work_callbacks?
 
         # Handle edge cases - break if edge case handler indicates we should
         next if handle_edge_cases_with_ports(active_items, port_to_worker,
@@ -65,6 +66,7 @@ module Fractor
 
     # Build mapping of response ports to workers.
     # This is needed to route messages from ports back to workers.
+    # Skips workers whose ractors have terminated to avoid blocking on closed ports.
     #
     # @return [Hash] Mapping of Ractor::Port => WrappedRactor
     def build_port_to_worker_map
@@ -72,6 +74,9 @@ module Fractor
       ractors_map.each_value do |wrapped_ractor|
         next unless wrapped_ractor.is_a?(WrappedRactor4)
 
+        # Skip workers whose ractors have terminated
+        next if wrapped_ractor.closed?
+
         port = wrapped_ractor.response_port
         port_map[port] = wrapped_ractor if port
       end
@@ -80,6 +85,7 @@ module Fractor
 
     # Get list of active items for Ractor.select (Ruby 4.0+).
     # Includes both response ports and ractors (excluding wakeup ractor).
+    # Skips workers whose ractors have terminated to avoid blocking on closed ports.
     #
     # @return [Array] List of Ractor::Port and Ractor objects
     def get_active_items
@@ -89,12 +95,17 @@ module Fractor
       ractors_map.each_value do |wrapped_ractor|
         next unless wrapped_ractor.is_a?(WrappedRactor4)
 
+        # Skip workers whose ractors have terminated
+        next if wrapped_ractor.closed?
+
         port = wrapped_ractor.response_port
         items << port if port
       end
 
-      # Add wakeup ractor/port if in continuous mode with callbacks
-      if continuous_mode? && !work_callbacks.empty? && wakeup_ractor && wakeup_port
+      # Add wakeup ractor/port if in continuous mode
+      # CRITICAL: Always include wakeup port in continuous mode to ensure
+      # the main loop can be unblocked for shutdown, even without callbacks.
+      if continuous_mode? && wakeup_ractor && wakeup_port
         items << wakeup_port
       end
 
@@ -106,8 +117,10 @@ module Fractor
     #
     # @return [Array<Ractor>] List of active Ractor objects
     def get_active_ractors
+      # CRITICAL: Always include wakeup ractor in continuous mode to ensure
+      # the main loop can be unblocked for shutdown, even without callbacks.
       ractors_map.keys.reject do |ractor|
-        ractor == wakeup_ractor && !(continuous_mode? && !work_callbacks.empty?)
+        ractor == wakeup_ractor && !continuous_mode?
       end
     end
 
@@ -115,16 +128,14 @@ module Fractor
     #
     # @return [void]
     def process_work_callbacks
-      work_callbacks.each do |callback|
-        new_work = callback.call
-        if new_work && !new_work.empty?
-          @supervisor.add_work_items(new_work)
-          puts "Work source provided #{new_work.size} new items" if @debug
-
-          # Distribute work to idle workers
-          distributed = work_distribution_manager.distribute_to_idle_workers
-          puts "Distributed work to #{distributed} idle workers" if @debug && distributed.positive?
-        end
+      new_work = @supervisor.callback_registry.process_work_callbacks
+      if new_work && !new_work.empty?
+        @supervisor.add_work_items(new_work)
+        puts "Work source provided #{new_work.size} new items" if @debug
+
+        # Distribute work to idle workers
+        distributed = work_distribution_manager.distribute_to_idle_workers
+        puts "Distributed work to #{distributed} idle workers" if @debug && distributed.positive?
       end
     end
 
@@ -211,8 +222,20 @@ processed_count)
 
       ready_item, message = Ractor.select(*active_items)
 
-      # Check if this is the wakeup port
-      if ready_item == wakeup_port
+      # Debug: log what we received
+      if @debug
+        if ready_item.equal?(wakeup_port)
+          puts "DEBUG: Received from wakeup_port: #{message.inspect}"
+        elsif ready_item.is_a?(Ractor::Port)
+          worker = port_to_worker[ready_item]
+          puts "DEBUG: Received from port: #{worker&.name || 'unknown'}, message: #{message.inspect}"
+        else
+          puts "DEBUG: Received from ractor: #{ready_item.inspect}, message: #{message.inspect}"
+        end
+      end
+
+      # Check if this is the wakeup port (use equal? for identity comparison)
+      if wakeup_port && ready_item.equal?(wakeup_port)
         puts "Wakeup signal received: #{message[:message]}" if @debug
         # Remove wakeup ractor from map if shutting down
         if message && message[:message] == :shutdown
@@ -226,7 +249,7 @@ processed_count)
       [ready_item, message]
     rescue Ractor::ClosedError, Ractor::Error => e
       # Handle closed ports/ractors - remove them from ractors_map
-      puts "Ractor::Error in select: #{e.message}. Cleaning up closed ports." if @debug
+      puts "Ractor::Error in select: #{e.class} - #{e.message}. Cleaning up closed ports." if @debug
 
       # Find and remove workers with closed ports
       closed_ports = active_items.select { |item| item.is_a?(Ractor::Port) }
@@ -242,6 +265,11 @@ processed_count)
 
       # Return nil to continue the loop with updated active_items
       [nil, nil]
+    rescue StandardError => e
+      # Catch any other unexpected errors and re-raise with context
+      puts "Unexpected error in select_from_mixed: #{e.class} - #{e.message}" if @debug
+      puts e.backtrace.first(5) if @debug
+      raise
     end
 
     # Process a message from a ractor or port (Ruby 4.0+).

data/lib/fractor/result_cache.rb

@@ -156,21 +156,69 @@ module Fractor
 
     # Generate a cache key for a work item.
     #
+    # Optimized to avoid JSON.dump for common simple types.
+    # For complex nested structures, falls back to JSON serialization.
+    #
     # @param work [Fractor::Work] The work item
     # @return [String] The cache key
     def generate_key(work)
-      # Create a deterministic key from the work item
-      data = {
-        class: work.class.name,
-        input: work.input,
-      }
-      if work.respond_to?(:timeout) && !work.timeout.nil?
-        data[:timeout] =
-          work.timeout
-      end
+      # For simple types, use faster string interpolation
+      # For complex nested structures, fall back to JSON
+      input = work.input
+      input_str = if simple_input?(input)
+                    serialize_simple_input(input)
+                  else
+                    JSON.dump(input)
+                  end
+
+      # Build key components
+      parts = [work.class.name, input_str]
+      parts << work.timeout.to_s if work.respond_to?(:timeout) && !work.timeout.nil?
 
       # Use SHA256 hash for consistent, collision-resistant keys
-      Digest::SHA256.hexdigest(JSON.dump(data))
+      Digest::SHA256.hexdigest(parts.join("|"))
+    end
+
+    # Check if input is a simple type that can be serialized without JSON.
+    # @return [Boolean] true if input is a simple, directly serializable type
+    def simple_input?(input)
+      case input
+      when NilClass, TrueClass, FalseClass, String, Numeric, Symbol
+        true
+      when Array
+        input.all? { |item| simple_input?(item) }
+      when Hash
+        input.keys.all? { |k| k.is_a?(String) || k.is_a?(Symbol) } &&
+          input.values.all? { |v| simple_input?(v) }
+      else
+        false
+      end
+    end
+
+    # Serialize simple input types efficiently without JSON.
+    # @return [String] Serialized representation
+    def serialize_simple_input(input)
+      case input
+      when NilClass
+        "nil"
+      when TrueClass
+        "true"
+      when FalseClass
+        "false"
+      when String
+        # Escape special characters for consistent hashing
+        input.inspect
+      when Symbol
+        ":#{input}"
+      when Array
+        "[#{input.map { |item| serialize_simple_input(item) }.join(',')}]"
+      when Hash
+        pairs = input.map { |k, v| "#{k}=>#{serialize_simple_input(v)}" }
+        "{#{pairs.sort.join(',')}}"
+      else
+        # Fallback - shouldn't happen if simple_input? is correct
+        input.to_s
+      end
     end
 
     # Check if a cache entry is expired.

data/lib/fractor/shutdown_handler.rb

@@ -8,29 +8,35 @@ module Fractor
   # the Single Responsibility Principle.
   class ShutdownHandler
     def initialize(workers, wakeup_ractor, timer_thread, performance_monitor,
-                   main_loop_thread: nil, debug: false)
+                   main_loop_thread: nil, debug: false, continuous_mode: false)
       @workers = workers
       @wakeup_ractor = wakeup_ractor
       @timer_thread = timer_thread
       @performance_monitor = performance_monitor
       @main_loop_thread = main_loop_thread
       @debug = debug
+      @continuous_mode = continuous_mode
     end
 
     # Execute a graceful shutdown of all supervisor components.
     # Components are stopped in the correct order to prevent issues:
     # 1. Stop performance monitor (to stop metric collection)
-    # 2. Stop timer thread (to stop periodic wakeups)
-    # 3. Signal wakeup ractor (to unblock Ractor.select)
-    # 4. Signal all workers (to stop processing)
-    # 5. Wait for main loop thread and workers to finish
+    # 2. Skip stopping timer thread in continuous mode (it will exit when workers close)
+    # 3. Stop timer thread in batch mode (to stop periodic wakeups)
+    # 4. Signal wakeup ractor (to unblock Ractor.select)
+    # 5. Signal all workers (to stop processing)
+    # 6. Wait for main loop thread and workers to finish
     #
     # @param wait_for_completion [Boolean] Whether to wait for all workers to close
     # @param timeout [Integer] Maximum seconds to wait for shutdown (default: 10)
     # @return [void]
     def shutdown(wait_for_completion: false, timeout: 10)
       stop_performance_monitor
-      stop_timer_thread
+
+      # Only stop timer thread in batch mode. In continuous mode, the timer thread
+      # will exit on its own when workers are closed (it checks this condition).
+      stop_timer_thread unless @continuous_mode
+
       signal_wakeup_ractor
       signal_all_workers