fractor 0.1.4 → 0.1.7

data/lib/fractor/main_loop_handler4.rb

@@ -0,0 +1,299 @@
+# frozen_string_literal: true
+
+require_relative "main_loop_handler"
+
+module Fractor
+  # Ruby 4.0+ specific implementation of MainLoopHandler.
+  # Uses Ractor::Port for worker communication.
+  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
+        processed_count = get_processed_count
+
+        # Check loop termination condition
+        break unless should_continue_running?(processed_count)
+
+        log_processing_status(processed_count)
+
+        active_items = get_active_items
+
+        # Check for new work from callbacks if in continuous mode
+        process_work_callbacks if continuous_mode? && !work_callbacks.empty?
+
+        # Handle edge cases - break if edge case handler indicates we should
+        next if handle_edge_cases_with_ports(active_items, port_to_worker,
+                                             processed_count)
+
+        # Wait for next message from any active ractor or port
+        ready_item, message = select_from_mixed(active_items, port_to_worker)
+        next unless ready_item && message
+
+        # Process the received message
+        process_message_40(ready_item, message, port_to_worker)
+      end
+
+      puts "Main loop finished." if @debug
+
+      # Clean up ractors map after batch mode completion
+      cleanup_ractors_map unless continuous_mode?
+    end
+
+    # Clean up the ractors map after batch processing.
+    # In Ruby 4.0, we simply clear the map to allow garbage collection.
+    # The main loop already attempted to shut down workers properly.
+    #
+    # @return [void]
+    def cleanup_ractors_map
+      return if ractors_map.empty?
+
+      puts "Cleaning up ractors map (#{ractors_map.size} entries)..." if @debug
+
+      # Simply clear the map without trying to interact with ractors
+      # The main loop already attempted to shut down workers properly
+      ractors_map.clear
+
+      # Force garbage collection to help clean up orphaned ractors
+      GC.start
+      puts "Ractors map cleared and GC forced." if @debug
+    end
+
+    private
+
+    # Build mapping of response ports to workers.
+    # This is needed to route messages from ports back to workers.
+    #
+    # @return [Hash] Mapping of Ractor::Port => WrappedRactor
+    def build_port_to_worker_map
+      port_map = {}
+      ractors_map.each_value do |wrapped_ractor|
+        next unless wrapped_ractor.is_a?(WrappedRactor4)
+
+        port = wrapped_ractor.response_port
+        port_map[port] = wrapped_ractor if port
+      end
+      port_map
+    end
+
+    # Get list of active items for Ractor.select (Ruby 4.0+).
+    # Includes both response ports and ractors (excluding wakeup ractor).
+    #
+    # @return [Array] List of Ractor::Port and Ractor objects
+    def get_active_items
+      items = []
+
+      # Add response ports from all workers
+      ractors_map.each_value do |wrapped_ractor|
+        next unless wrapped_ractor.is_a?(WrappedRactor4)
+
+        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
+        items << wakeup_port
+      end
+
+      items
+    end
+
+    # Get list of active ractors for compatibility with Ruby 3.x tests.
+    # In Ruby 4.0, returns the actual ractor objects (not ports).
+    #
+    # @return [Array<Ractor>] List of active Ractor objects
+    def get_active_ractors
+      ractors_map.keys.reject do |ractor|
+        ractor == wakeup_ractor && !(continuous_mode? && !work_callbacks.empty?)
+      end
+    end
+
+    # Check for new work from callbacks in continuous mode.
+    #
+    # @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
+      end
+    end
+
+    # Handle edge cases like no active workers or empty queue.
+    # Overload for compatibility with tests (2-argument version).
+    #
+    # @param active_ractors [Array<Ractor>] List of active ractors
+    # @param processed_count [Integer] Current number of processed items
+    # @return [Boolean] true if should break from loop
+    def handle_edge_cases(active_ractors, processed_count)
+      # For Ruby 4.0 compatibility with tests:
+      # Use the active_ractors array directly since tests pass it in
+      # In normal operation, this would be derived from ractors_map
+
+      # In continuous mode, if no active ractors and shutting down, exit loop
+      if active_ractors.empty? && @shutting_down
+        puts "No active ractors during shutdown, exiting main loop" if @debug
+        return true
+      end
+
+      # Break if no active ractors and queue is empty, but work remains
+      if active_ractors.empty? && work_queue.empty? && !continuous_mode? && processed_count < total_work_count
+        puts "Warning: No active ractors and queue is empty, but not all work is processed. Exiting loop." if @debug
+        return true
+      end
+
+      # In continuous mode, just wait if no active ractors but keep running
+      if active_ractors.empty?
+        return true unless continuous_mode?
+
+        sleep(0.1) # Small delay to avoid CPU spinning
+        return false # Continue to next iteration
+      end
+
+      false # There are active ractors, continue the loop
+    end
+
+    # Handle edge cases like no active workers or empty queue (3-argument version).
+    #
+    # @param _active_items [Array] List of active ports/ractors
+    # @param port_to_worker [Hash] Mapping of ports to workers
+    # @param processed_count [Integer] Current number of processed items
+    # @return [Boolean] true if should break from loop
+    def handle_edge_cases_with_ports(_active_items, port_to_worker,
+processed_count)
+      # Count active workers (those with response ports)
+      active_worker_count = port_to_worker.size
+
+      # In continuous mode, if no active workers and shutting down, exit loop
+      if active_worker_count.zero? && @shutting_down
+        puts "No active workers during shutdown, exiting main loop" if @debug
+        return true
+      end
+
+      # Break if no active workers and queue is empty, but work remains
+      if active_worker_count.zero? && work_queue.empty? && !continuous_mode? && processed_count < total_work_count
+        puts "Warning: No active workers and queue is empty, but not all work is processed. Exiting loop." if @debug
+        return true
+      end
+
+      # In continuous mode, just wait if no active workers but keep running
+      if active_worker_count.zero?
+        return true unless continuous_mode?
+
+        sleep(0.1) # Small delay to avoid CPU spinning
+        return false # Continue to next iteration
+      end
+
+      false
+    end
+
+    # Wait for a message from any active ractor or port (Ruby 4.0+).
+    # In Ruby 4.0, we select from a mix of response ports and ractors.
+    #
+    # @param active_items [Array] List of active ports/ractors
+    # @param port_to_worker [Hash] Mapping of ports to workers
+    # @return [Array] ready_item and message, or nil if should continue
+    def select_from_mixed(active_items, port_to_worker)
+      # In Ruby 4.0, we use Ractor.select on ports (and potentially ractors)
+      # The response ports receive :result and :error messages
+      # The wakeup ractor (if present) receives wakeup signals
+
+      return nil, nil if active_items.empty?
+
+      ready_item, message = Ractor.select(*active_items)
+
+      # Check if this is the wakeup port
+      if ready_item == wakeup_port
+        puts "Wakeup signal received: #{message[:message]}" if @debug
+        # Remove wakeup ractor from map if shutting down
+        if message && message[:message] == :shutdown
+          ractors_map.delete(wakeup_ractor)
+          @supervisor.instance_variable_set(:@wakeup_ractor, nil)
+        end
+        # Return nil to indicate we should continue to next iteration
+        return nil, nil
+      end
+
+      [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
+
+      # Find and remove workers with closed ports
+      closed_ports = active_items.select { |item| item.is_a?(Ractor::Port) }
+      closed_ports.each do |port|
+        wrapped_ractor = port_to_worker[port]
+        if wrapped_ractor
+          puts "Removing worker with closed port: #{wrapped_ractor.name}" if @debug
+          ractors_map.delete(wrapped_ractor.ractor)
+          workers.delete(wrapped_ractor)
+          port_to_worker.delete(port)
+        end
+      end
+
+      # Return nil to continue the loop with updated active_items
+      [nil, nil]
+    end
+
+    # Process a message from a ractor or port (Ruby 4.0+).
+    # Most messages come through response ports in Ruby 4.0.
+    #
+    # @param ready_item [Ractor::Port, Ractor] The port or ractor that sent the message
+    # @param message [Hash] The message received
+    # @param port_to_worker [Hash] Mapping of ports to workers
+    # @return [void]
+    def process_message_40(ready_item, message, port_to_worker)
+      # Find the corresponding WrappedRactor instance
+      if ready_item.is_a?(Ractor::Port)
+        # Message from a response port - look up worker
+        wrapped_ractor = port_to_worker[ready_item]
+        unless wrapped_ractor
+          puts "Warning: Received message from unknown port: #{ready_item}. Ignoring." if @debug
+          return
+        end
+      else
+        # Message from a ractor (e.g., initialize, shutdown acknowledgment)
+        wrapped_ractor = ractors_map[ready_item]
+        unless wrapped_ractor
+          puts "Warning: Received message from unknown Ractor: #{ready_item}. Ignoring." if @debug
+          ractors_map.delete(ready_item)
+          return
+        end
+      end
+
+      # Guard against nil messages (indicates closed port/ractor)
+      if message.nil?
+        puts "Warning: Received nil message from #{wrapped_ractor.name}. Port/Ractor likely closed." if @debug
+        ractors_map.delete(wrapped_ractor.ractor)
+        workers.delete(wrapped_ractor)
+        port_to_worker.delete(ready_item) if ready_item.is_a?(Ractor::Port)
+        return
+      end
+
+      puts "Selected from: #{wrapped_ractor.name}, Message Type: #{message[:type]}" if @debug
+
+      # Route to appropriate message handler
+      case message[:type]
+      when :initialize
+        handle_initialize_message(wrapped_ractor)
+      when :shutdown
+        handle_shutdown_message(wrapped_ractor.ractor, wrapped_ractor)
+      when :result
+        handle_result_message(wrapped_ractor, message)
+      when :error
+        handle_error_message(wrapped_ractor, message)
+      else
+        puts "Unknown message type received: #{message[:type]} from #{wrapped_ractor.name}" if @debug
+      end
+    end
+  end
+end

data/lib/fractor/performance_metrics_collector.rb

@@ -0,0 +1,181 @@
+# frozen_string_literal: true
+
+module Fractor
+  # Internal metrics collector for performance monitoring.
+  # Thread-safe collection of performance metrics.
+  class PerformanceMetricsCollector
+    attr_reader :jobs_processed, :jobs_succeeded, :jobs_failed, :total_latency
+
+    def initialize
+      reset
+    end
+
+    # Reset all metrics to initial state
+    def reset
+      @jobs_processed = 0
+      @jobs_succeeded = 0
+      @jobs_failed = 0
+      @latencies = []
+      @total_latency = 0.0
+      @queue_depths = []
+      @memory_samples = []
+      @utilization_samples = []
+      @mutex = Mutex.new
+    end
+
+    # Record a job completion with its latency
+    #
+    # @param latency [Float] Job latency in seconds
+    # @param success [Boolean] Whether job succeeded
+    # @return [void]
+    def record_job(latency, success: true)
+      @mutex.synchronize do
+        @jobs_processed += 1
+        @jobs_succeeded += 1 if success
+        @jobs_failed += 1 unless success
+        @latencies << latency
+        @total_latency += latency
+      end
+    end
+
+    # Sample the current queue depth
+    #
+    # @param depth [Integer] Current queue depth
+    # @return [void]
+    def sample_queue_depth(depth)
+      @mutex.synchronize do
+        @queue_depths << depth
+      end
+    end
+
+    # Sample current memory usage
+    #
+    # @param mb [Float] Memory usage in MB
+    # @return [void]
+    def sample_memory(mb)
+      @mutex.synchronize do
+        @memory_samples << mb
+      end
+    end
+
+    # Sample worker utilization ratio
+    #
+    # @param ratio [Float] Worker utilization (0.0 to 1.0)
+    # @return [void]
+    def sample_worker_utilization(ratio)
+      @mutex.synchronize do
+        @utilization_samples << ratio
+      end
+    end
+
+    # Calculate average latency
+    #
+    # @return [Float] Average latency in seconds
+    def average_latency
+      @mutex.synchronize do
+        average_latency_unsynchronized
+      end
+    end
+
+    # Calculate latency percentile
+    #
+    # @param p [Integer] Percentile (0-100)
+    # @return [Float] Latency at percentile in seconds
+    def percentile(p)
+      @mutex.synchronize do
+        return 0.0 if @latencies.empty?
+
+        sorted = @latencies.sort
+        index = ((p / 100.0) * sorted.size).ceil - 1
+        sorted[[index, 0].max]
+      end
+    end
+
+    # Calculate average queue depth
+    #
+    # @return [Float] Average queue depth
+    def average_queue_depth
+      @mutex.synchronize do
+        return 0.0 if @queue_depths.empty?
+
+        @queue_depths.sum / @queue_depths.size.to_f
+      end
+    end
+
+    # Get maximum queue depth observed
+    #
+    # @return [Integer] Maximum queue depth
+    def max_queue_depth
+      @mutex.synchronize do
+        return 0 if @queue_depths.empty?
+
+        @queue_depths.max
+      end
+    end
+
+    # Calculate enqueue rate (jobs per second)
+    #
+    # @param duration [Float] Time period in seconds
+    # @return [Float] Enqueue rate
+    def enqueue_rate(duration)
+      return 0.0 if duration <= 0
+
+      @jobs_processed / duration.to_f
+    end
+
+    # Calculate dequeue rate (jobs per second)
+    #
+    # @param duration [Float] Time period in seconds
+    # @return [Float] Dequeue rate
+    def dequeue_rate(duration)
+      return 0.0 if duration <= 0
+
+      @jobs_processed / duration.to_f
+    end
+
+    # Calculate average wait time using Little's Law
+    #
+    # @return [Float] Average wait time in seconds
+    def average_wait_time
+      # Wait time approximation based on queue depth and throughput
+      @mutex.synchronize do
+        return 0.0 if @queue_depths.empty? || @latencies.empty?
+
+        avg_depth = @queue_depths.sum / @queue_depths.size.to_f
+        avg_lat = @total_latency / @latencies.size
+        return 0.0 if avg_lat.zero?
+
+        # Little's Law: Wait Time ≈ Queue Length / Throughput
+        avg_depth * avg_lat
+      end
+    end
+
+    # Calculate wait time at a given percentile
+    #
+    # @param p [Integer] Percentile (0-100)
+    # @return [Float] Wait time at percentile in seconds
+    def wait_time_percentile(p)
+      # Simplified wait time percentile based on queue depth percentile
+      @mutex.synchronize do
+        return 0.0 if @queue_depths.empty?
+
+        sorted = @queue_depths.sort
+        index = ((p / 100.0) * sorted.size).ceil - 1
+        depth_percentile = sorted[[index, 0].max]
+
+        avg_lat = @total_latency / @latencies.size
+        return 0.0 if avg_lat.zero?
+
+        depth_percentile * avg_lat
+      end
+    end
+
+    private
+
+    def average_latency_unsynchronized
+      return 0.0 if @latencies.empty?
+
+      @total_latency / @latencies.size
+    end
+  end
+end

data/lib/fractor/performance_monitor.rb

@@ -0,0 +1,215 @@
+# frozen_string_literal: true
+
+require_relative "performance_metrics_collector"
+require_relative "performance_report_generator"
+
+module Fractor
+  # Monitors and tracks performance metrics for Fractor supervisors and workers.
+  #
+  # Collects metrics including:
+  # - Jobs processed count
+  # - Latency statistics (average, p50, p95, p99)
+  # - Throughput (jobs/second)
+  # - Worker utilization
+  # - Queue depth over time
+  # - Memory usage
+  #
+  # @example Basic usage
+  #   supervisor = Fractor::Supervisor.new(...)
+  #   monitor = Fractor::PerformanceMonitor.new(supervisor)
+  #   monitor.start
+  #
+  #   # ... run workload ...
+  #
+  #   monitor.stop
+  #   puts monitor.report
+  #
+  # @example With custom sampling interval
+  #   monitor = Fractor::PerformanceMonitor.new(
+  #     supervisor,
+  #     sample_interval: 0.5  # Sample every 500ms
+  #   )
+  class PerformanceMonitor
+    attr_reader :supervisor, :metrics, :start_time, :end_time
+
+    # Create a new performance monitor
+    #
+    # @param supervisor [Supervisor] The supervisor to monitor
+    # @param sample_interval [Float] How often to sample metrics (seconds)
+    def initialize(supervisor, sample_interval: 1.0)
+      @supervisor = supervisor
+      @sample_interval = sample_interval
+      @metrics = PerformanceMetricsCollector.new
+      @start_time = nil
+      @end_time = nil
+      @monitoring = false
+      @monitor_thread = nil
+    end
+
+    # Start monitoring
+    #
+    # @return [void]
+    def start
+      return if @monitoring
+
+      @monitoring = true
+      @start_time = Time.now
+      @metrics.reset
+
+      # Start background monitoring thread
+      @monitor_thread = Thread.new { monitor_loop }
+    end
+
+    # Stop monitoring
+    #
+    # @return [void]
+    def stop
+      return unless @monitoring
+
+      @monitoring = false
+      @end_time = Time.now
+      @monitor_thread&.join
+      @monitor_thread = nil
+    end
+
+    # Check if currently monitoring
+    #
+    # @return [Boolean]
+    def monitoring?
+      @monitoring
+    end
+
+    # Get current metrics snapshot
+    #
+    # @return [Hash] Current metrics
+    def snapshot
+      {
+        jobs_processed: @metrics.jobs_processed,
+        jobs_succeeded: @metrics.jobs_succeeded,
+        jobs_failed: @metrics.jobs_failed,
+        average_latency: @metrics.average_latency,
+        p50_latency: @metrics.percentile(50),
+        p95_latency: @metrics.percentile(95),
+        p99_latency: @metrics.percentile(99),
+        throughput: calculate_throughput,
+        queue_depth: current_queue_depth,
+        queue_depth_avg: @metrics.average_queue_depth,
+        queue_depth_max: @metrics.max_queue_depth,
+        enqueue_rate: @metrics.enqueue_rate(uptime),
+        dequeue_rate: @metrics.dequeue_rate(uptime),
+        average_wait_time: @metrics.average_wait_time,
+        p50_wait_time: @metrics.wait_time_percentile(50),
+        p95_wait_time: @metrics.wait_time_percentile(95),
+        p99_wait_time: @metrics.wait_time_percentile(99),
+        worker_count: worker_count,
+        active_workers: active_worker_count,
+        worker_utilization: worker_utilization,
+        memory_mb: current_memory_mb,
+        uptime: uptime,
+      }
+    end
+
+    # Generate a human-readable report
+    #
+    # @return [String] Formatted report
+    def report
+      PerformanceReportGenerator.generate_report(snapshot)
+    end
+
+    # Export metrics in JSON format
+    #
+    # @return [String] JSON representation
+    def to_json(*_args)
+      PerformanceReportGenerator.to_json(snapshot)
+    end
+
+    # Export metrics in Prometheus format
+    #
+    # @return [String] Prometheus metrics
+    def to_prometheus
+      stats = snapshot
+      PerformanceReportGenerator.to_prometheus(stats, @metrics.total_latency)
+    end
+
+    # Record a job completion
+    #
+    # @param latency [Float] Job latency in seconds
+    # @param success [Boolean] Whether job succeeded
+    # @return [void]
+    def record_job(latency, success: true)
+      @metrics.record_job(latency, success: success)
+    end
+
+    private
+
+    def monitor_loop
+      while @monitoring
+        sample_metrics
+        sleep(@sample_interval)
+      end
+    rescue StandardError => e
+      warn "Performance monitor error: #{e.message}"
+    end
+
+    def sample_metrics
+      @metrics.sample_queue_depth(current_queue_depth)
+      @metrics.sample_memory(current_memory_mb)
+      @metrics.sample_worker_utilization(worker_utilization)
+    end
+
+    def calculate_throughput
+      duration = uptime
+      return 0.0 if duration <= 0
+
+      @metrics.jobs_processed / duration.to_f
+    end
+
+    def uptime
+      end_time = @end_time || Time.now
+      return 0 unless @start_time
+
+      end_time - @start_time
+    end
+
+    def current_queue_depth
+      @supervisor.work_queue.size
+    rescue StandardError
+      0
+    end
+
+    def worker_count
+      @supervisor.worker_pools.sum { |pool| pool[:num_workers] || 1 }
+    rescue StandardError
+      0
+    end
+
+    def active_worker_count
+      # This would need worker state tracking
+      # For now, estimate based on queue depth
+      depth = current_queue_depth
+      total = worker_count
+      return total if depth.positive?
+
+      0
+    end
+
+    def worker_utilization
+      total = worker_count
+      return 0.0 if total.zero?
+
+      active = active_worker_count
+      active.to_f / total
+    end
+
+    def current_memory_mb
+      # Get current process memory usage in MB
+      if RUBY_PLATFORM.match?(/darwin|linux/)
+        `ps -o rss= -p #{Process.pid}`.to_i / 1024.0
+      else
+        0.0 # Unsupported platform
+      end
+    rescue StandardError
+      0.0
+    end
+  end
+end