fractor 0.1.6 → 0.1.8

data/lib/fractor/performance_report_generator.rb

@@ -0,0 +1,202 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Fractor
+  # Generates formatted reports from performance metrics snapshots.
+  # Supports text, JSON, and Prometheus output formats.
+  class PerformanceReportGenerator
+    # Generate a human-readable text report
+    #
+    # @param stats [Hash] Metrics snapshot from PerformanceMonitor
+    # @return [String] Formatted report
+    def self.generate_report(stats)
+      <<~REPORT
+        Performance Metrics
+        ===================
+        Duration: #{format_duration(stats[:uptime])}
+
+        Jobs:
+          Processed: #{stats[:jobs_processed]}
+          Succeeded: #{stats[:jobs_succeeded]}
+          Failed: #{stats[:jobs_failed]}
+          Success Rate: #{success_rate(stats)}%
+
+        Latency (ms):
+          Average: #{format_ms(stats[:average_latency])}
+          P50: #{format_ms(stats[:p50_latency])}
+          P95: #{format_ms(stats[:p95_latency])}
+          P99: #{format_ms(stats[:p99_latency])}
+
+        Throughput:
+          Jobs/sec: #{format_float(stats[:throughput])}
+
+        Workers:
+          Total: #{stats[:worker_count]}
+          Active: #{stats[:active_workers]}
+          Utilization: #{format_percent(stats[:worker_utilization])}
+
+        Queue:
+          Current Depth: #{stats[:queue_depth]}
+          Average Depth: #{format_float(stats[:queue_depth_avg])}
+          Max Depth: #{stats[:queue_depth_max]}
+          Enqueue Rate: #{format_float(stats[:enqueue_rate])} items/sec
+          Dequeue Rate: #{format_float(stats[:dequeue_rate])} items/sec
+
+        Wait Time (ms):
+          Average: #{format_ms(stats[:average_wait_time])}
+          P50: #{format_ms(stats[:p50_wait_time])}
+          P95: #{format_ms(stats[:p95_wait_time])}
+          P99: #{format_ms(stats[:p99_wait_time])}
+
+        Memory:
+          Current: #{format_float(stats[:memory_mb])} MB
+      REPORT
+    end
+
+    # Export metrics in JSON format
+    #
+    # @param stats [Hash] Metrics snapshot
+    # @return [String] JSON representation
+    def self.to_json(stats)
+      stats.to_json
+    end
+
+    # Export metrics in Prometheus format
+    #
+    # @param stats [Hash] Metrics snapshot
+    # @param total_latency [Float] Total latency for all jobs
+    # @param prefix [String] Metric name prefix
+    # @return [String] Prometheus metrics
+    def self.to_prometheus(stats, total_latency, prefix: "fractor")
+      <<~PROMETHEUS
+        # HELP #{prefix}_jobs_processed_total Total number of jobs processed
+        # TYPE #{prefix}_jobs_processed_total counter
+        #{prefix}_jobs_processed_total #{stats[:jobs_processed]}
+
+        # HELP #{prefix}_jobs_succeeded_total Total number of jobs that succeeded
+        # TYPE #{prefix}_jobs_succeeded_total counter
+        #{prefix}_jobs_succeeded_total #{stats[:jobs_succeeded]}
+
+        # HELP #{prefix}_jobs_failed_total Total number of jobs that failed
+        # TYPE #{prefix}_jobs_failed_total counter
+        #{prefix}_jobs_failed_total #{stats[:jobs_failed]}
+
+        # HELP #{prefix}_latency_seconds Job processing latency
+        # TYPE #{prefix}_latency_seconds summary
+        #{prefix}_latency_seconds{quantile="0.5"} #{stats[:p50_latency] || 0}
+        #{prefix}_latency_seconds{quantile="0.95"} #{stats[:p95_latency] || 0}
+        #{prefix}_latency_seconds{quantile="0.99"} #{stats[:p99_latency] || 0}
+        #{prefix}_latency_seconds_sum #{total_latency}
+        #{prefix}_latency_seconds_count #{stats[:jobs_processed]}
+
+        # HELP #{prefix}_throughput_jobs_per_second Current throughput
+        # TYPE #{prefix}_throughput_jobs_per_second gauge
+        #{prefix}_throughput_jobs_per_second #{stats[:throughput] || 0}
+
+        # HELP #{prefix}_queue_depth Current queue depth
+        # TYPE #{prefix}_queue_depth gauge
+        #{prefix}_queue_depth #{stats[:queue_depth]}
+
+        # HELP #{prefix}_queue_depth_avg Average queue depth
+        # TYPE #{prefix}_queue_depth_avg gauge
+        #{prefix}_queue_depth_avg #{stats[:queue_depth_avg] || 0}
+
+        # HELP #{prefix}_queue_depth_max Maximum queue depth
+        # TYPE #{prefix}_queue_depth_max gauge
+        #{prefix}_queue_depth_max #{stats[:queue_depth_max] || 0}
+
+        # HELP #{prefix}_enqueue_rate_total Items enqueued per second
+        # TYPE #{prefix}_enqueue_rate_total gauge
+        #{prefix}_enqueue_rate_total #{stats[:enqueue_rate] || 0}
+
+        # HELP #{prefix}_dequeue_rate_total Items dequeued per second
+        # TYPE #{prefix}_dequeue_rate_total gauge
+        #{prefix}_dequeue_rate_total #{stats[:dequeue_rate] || 0}
+
+        # HELP #{prefix}_wait_time_seconds Queue wait time
+        # TYPE #{prefix}_wait_time_seconds summary
+        #{prefix}_wait_time_seconds{quantile="0.5"} #{stats[:p50_wait_time] || 0}
+        #{prefix}_wait_time_seconds{quantile="0.95"} #{stats[:p95_wait_time] || 0}
+        #{prefix}_wait_time_seconds{quantile="0.99"} #{stats[:p99_wait_time] || 0}
+        #{prefix}_wait_time_seconds_sum #{stats[:average_wait_time] || 0}
+        #{prefix}_wait_time_seconds_count #{stats[:jobs_processed]}
+
+        # HELP #{prefix}_workers_total Total number of workers
+        # TYPE #{prefix}_workers_total gauge
+        #{prefix}_workers_total #{stats[:worker_count]}
+
+        # HELP #{prefix}_workers_active Number of active workers
+        # TYPE #{prefix}_workers_active gauge
+        #{prefix}_workers_active #{stats[:active_workers]}
+
+        # HELP #{prefix}_worker_utilization Worker utilization ratio
+        # TYPE #{prefix}_worker_utilization gauge
+        #{prefix}_worker_utilization #{stats[:worker_utilization] || 0}
+
+        # HELP #{prefix}_memory_bytes Current memory usage
+        # TYPE #{prefix}_memory_bytes gauge
+        #{prefix}_memory_bytes #{(stats[:memory_mb] || 0) * 1024 * 1024}
+      PROMETHEUS
+    end
+
+    # Calculate success rate from metrics
+    #
+    # @param stats [Hash] Metrics snapshot
+    # @return [Float] Success rate percentage
+    def self.success_rate(stats)
+      total = stats[:jobs_processed]
+      return 0.0 if total.zero?
+
+      (stats[:jobs_succeeded].to_f / total * 100).round(2)
+    end
+
+    # Format duration in human-readable format
+    #
+    # @param seconds [Float] Duration in seconds
+    # @return [String] Formatted duration (e.g., "1h 30m 45s")
+    def self.format_duration(seconds)
+      return "0s" if seconds.nil? || seconds.zero?
+
+      hours = (seconds / 3600).floor
+      minutes = ((seconds % 3600) / 60).floor
+      secs = (seconds % 60).round(2)
+
+      parts = []
+      parts << "#{hours}h" if hours.positive?
+      parts << "#{minutes}m" if minutes.positive?
+      parts << "#{secs}s"
+      parts.join(" ")
+    end
+
+    # Format seconds as milliseconds
+    #
+    # @param seconds [Float] Duration in seconds
+    # @return [String] Milliseconds with 2 decimal places
+    def self.format_ms(seconds)
+      return "0.00" if seconds.nil?
+
+      (seconds * 1000).round(2)
+    end
+
+    # Format float value with 2 decimal places
+    #
+    # @param value [Float] Value to format
+    # @return [String] Formatted float
+    def self.format_float(value)
+      return "0.00" if value.nil?
+
+      value.round(2)
+    end
+
+    # Format ratio as percentage
+    #
+    # @param ratio [Float] Ratio (0.0 to 1.0)
+    # @return [String] Percentage with 2 decimal places
+    def self.format_percent(ratio)
+      return "0.00%" if ratio.nil?
+
+      "#{(ratio * 100).round(2)}%"
+    end
+  end
+end

data/lib/fractor/priority_work.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module Fractor
+  # PriorityWork extends Work with priority levels for priority-based scheduling
+  #
+  # Priority levels:
+  # - :critical - Highest priority, processed first
+  # - :high - High priority
+  # - :normal - Default priority (backward compatible)
+  # - :low - Low priority
+  # - :background - Lowest priority
+  #
+  # @example Creating priority work
+  #   work = Fractor::PriorityWork.new(data: "urgent task", priority: :high)
+  #
+  # @example Using default priority
+  #   work = Fractor::PriorityWork.new(data: "normal task")
+  #   work.priority # => :normal
+  class PriorityWork < Work
+    PRIORITY_LEVELS = {
+      critical: 0,
+      high: 1,
+      normal: 2,
+      low: 3,
+      background: 4,
+    }.freeze
+
+    attr_reader :priority, :created_at
+
+    # Initialize a new PriorityWork
+    #
+    # @param input [Object] The input data for the work
+    # @param priority [Symbol] Priority level (:critical, :high, :normal, :low, :background)
+    # @raise [ArgumentError] if priority is not a valid level
+    def initialize(input, priority: :normal)
+      super(input)
+      validate_priority!(priority)
+      @priority = priority
+      @created_at = Time.now
+    end
+
+    # Get numeric priority value (lower is higher priority)
+    #
+    # @return [Integer] Numeric priority (0-4)
+    def priority_value
+      PRIORITY_LEVELS[@priority]
+    end
+
+    # Calculate age in seconds (used for priority aging)
+    #
+    # @return [Float] Age in seconds since creation
+    def age
+      Time.now - @created_at
+    end
+
+    # Compare priorities for sorting
+    # Lower priority value = higher priority
+    # For same priority, older work comes first (FIFO within priority)
+    #
+    # @param other [PriorityWork] Other work to compare with
+    # @return [Integer] -1, 0, or 1 for comparison
+    def <=>(other)
+      return nil unless other.is_a?(PriorityWork)
+
+      # First compare by priority value
+      result = priority_value <=> other.priority_value
+      return result unless result.zero?
+
+      # If same priority, use FIFO (older first)
+      created_at <=> other.created_at
+    end
+
+    # Check if this work has higher priority than another
+    #
+    # @param other [PriorityWork] Other work to compare with
+    # @return [Boolean] true if this work has higher priority
+    def higher_priority_than?(other)
+      return false unless other.is_a?(PriorityWork)
+
+      priority_value < other.priority_value
+    end
+
+    private
+
+    def validate_priority!(priority)
+      return if PRIORITY_LEVELS.key?(priority)
+
+      raise ArgumentError,
+            "Invalid priority: #{priority}. " \
+            "Must be one of: #{PRIORITY_LEVELS.keys.join(', ')}"
+    end
+  end
+end

data/lib/fractor/priority_work_queue.rb

@@ -0,0 +1,189 @@
+# frozen_string_literal: true
+
+module Fractor
+  # PriorityWorkQueue manages work items with priority-based scheduling
+  #
+  # Features:
+  # - Priority levels from :critical to :background
+  # - FIFO within same priority level
+  # - Optional priority aging to prevent starvation
+  # - Thread-safe operations
+  #
+  # @example Basic usage
+  #   queue = Fractor::PriorityWorkQueue.new
+  #   queue.push(PriorityWork.new("urgent", priority: :critical))
+  #   queue.push(PriorityWork.new("normal", priority: :normal))
+  #   work = queue.pop # Returns critical priority work first
+  #
+  # @example With priority aging
+  #   queue = Fractor::PriorityWorkQueue.new(aging_enabled: true, aging_threshold: 60)
+  class PriorityWorkQueue
+    attr_reader :aging_enabled, :aging_threshold
+
+    # Initialize a new PriorityWorkQueue
+    #
+    # @param aging_enabled [Boolean] Enable priority aging to prevent starvation
+    # @param aging_threshold [Integer] Seconds before a work item gets priority boost
+    def initialize(aging_enabled: false, aging_threshold: 60)
+      @queue = []
+      @mutex = Mutex.new
+      @condition = ConditionVariable.new
+      @aging_enabled = aging_enabled
+      @aging_threshold = aging_threshold
+      @closed = false
+    end
+
+    # Add work to the queue
+    #
+    # @param work [PriorityWork] Work item to add
+    # @raise [ArgumentError] if work is not a PriorityWork instance
+    # @raise [ClosedQueueError] if queue is closed
+    def push(work)
+      unless work.is_a?(PriorityWork)
+        raise ArgumentError,
+              "Work must be a PriorityWork"
+      end
+      raise ClosedQueueError, "Queue is closed" if @closed
+
+      @mutex.synchronize do
+        @queue << work
+        sort_queue!
+        @condition.signal
+      end
+    end
+    alias << push
+    alias enqueue push
+
+    # Remove and return highest priority work
+    # Blocks if queue is empty
+    #
+    # @return [PriorityWork, nil] Highest priority work or nil if queue closed
+    def pop
+      @mutex.synchronize do
+        loop do
+          return nil if @closed && @queue.empty?
+
+          unless @queue.empty?
+            apply_aging! if @aging_enabled
+            return @queue.shift
+          end
+
+          @condition.wait(@mutex)
+        end
+      end
+    end
+    alias dequeue pop
+    alias shift pop
+
+    # Try to remove and return highest priority work without blocking
+    #
+    # @return [PriorityWork, nil] Highest priority work or nil if empty
+    def pop_non_blocking
+      @mutex.synchronize do
+        return nil if @queue.empty?
+
+        apply_aging! if @aging_enabled
+        @queue.shift
+      end
+    end
+
+    # Get current queue size
+    #
+    # @return [Integer] Number of items in queue
+    def size
+      @mutex.synchronize { @queue.size }
+    end
+    alias length size
+
+    # Check if queue is empty
+    #
+    # @return [Boolean] true if queue is empty
+    def empty?
+      @mutex.synchronize { @queue.empty? }
+    end
+
+    # Close the queue
+    # No new items can be added, but existing items can be popped
+    def close
+      @mutex.synchronize do
+        @closed = true
+        @condition.broadcast
+      end
+    end
+
+    # Check if queue is closed
+    #
+    # @return [Boolean] true if queue is closed
+    def closed?
+      @mutex.synchronize { @closed }
+    end
+
+    # Clear all items from the queue
+    #
+    # @return [Array<PriorityWork>] Removed items
+    def clear
+      @mutex.synchronize do
+        items = @queue.dup
+        @queue.clear
+        items
+      end
+    end
+
+    # Get queue statistics
+    #
+    # @return [Hash] Statistics including count by priority
+    def stats
+      @mutex.synchronize do
+        priority_counts = Hash.new(0)
+        @queue.each { |work| priority_counts[work.priority] += 1 }
+
+        {
+          total: @queue.size,
+          by_priority: priority_counts,
+          oldest_age: @queue.empty? ? 0 : @queue.max_by(&:age).age,
+          closed: @closed,
+        }
+      end
+    end
+
+    private
+
+    # Sort queue by priority (lower priority value = higher priority)
+    # Within same priority, maintains FIFO order (older first)
+    def sort_queue!
+      @queue.sort!
+    end
+
+    # Apply priority aging to prevent starvation
+    # Low-priority items that have waited too long get temporary boost
+    def apply_aging!
+      return unless @aging_enabled
+
+      @queue.each do |work|
+        next unless work.age >= @aging_threshold
+
+        # Boost priority by one level (but not above critical)
+        current_value = work.priority_value
+        next if current_value.zero? # Already critical
+
+        # Temporarily boost priority for sorting
+        # We don't modify the work's actual priority, just resort
+        # This is done by the natural aging factor in comparison
+      end
+
+      # Resort with aging factor considered
+      @queue.sort! do |a, b|
+        # Calculate effective priority with aging
+        a_effective = a.priority_value - (a.age / @aging_threshold).floor
+        b_effective = b.priority_value - (b.age / @aging_threshold).floor
+
+        # Clamp to valid range (0-4)
+        a_effective = [0, [4, a_effective].min].max
+        b_effective = [0, [4, b_effective].min].max
+
+        result = a_effective <=> b_effective
+        result.zero? ? a.created_at <=> b.created_at : result
+      end
+    end
+  end
+end

data/lib/fractor/result_aggregator.rb

@@ -39,5 +39,37 @@ module Fractor
         errors: @errors.map(&:inspect),
       }
     end
+
+    # Get a summary of errors
+    # @return [Hash] Error summary with counts, categories, and other stats
+    def errors_summary
+      return {} if @errors.empty?
+
+      # Group errors by category
+      by_category = @errors.group_by do |e|
+        e.error_category || :unknown
+      end.transform_values(&:count)
+
+      # Group errors by severity
+      by_severity = @errors.group_by do |e|
+        e.error_severity || :unknown
+      end.transform_values(&:count)
+
+      # Count error types (class names)
+      error_types = @errors.map do |e|
+        e.error&.class&.name || e.error&.class || "String"
+      end.tally
+
+      # Get unique error messages (first 10)
+      unique_messages = @errors.map { |e| e.error.to_s }.uniq.first(10)
+
+      {
+        total_errors: @errors.size,
+        by_category: by_category,
+        by_severity: by_severity,
+        error_types: error_types,
+        sample_messages: unique_messages,
+      }
+    end
   end
 end

data/lib/fractor/shutdown_handler.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+module Fractor
+  # Manages the shutdown process for a Supervisor.
+  # Responsible for gracefully stopping all components in the correct order.
+  #
+  # This class extracts shutdown logic from Supervisor to follow
+  # the Single Responsibility Principle.
+  class ShutdownHandler
+    def initialize(workers, wakeup_ractor, timer_thread, performance_monitor,
+                   main_loop_thread: nil, debug: false)
+      @workers = workers
+      @wakeup_ractor = wakeup_ractor
+      @timer_thread = timer_thread
+      @performance_monitor = performance_monitor
+      @main_loop_thread = main_loop_thread
+      @debug = debug
+    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
+    #
+    # @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
+      signal_wakeup_ractor
+      signal_all_workers
+
+      wait_for_shutdown_completion(timeout) if wait_for_completion
+    end
+
+    # Wait for all components to finish after shutdown signals have been sent.
+    # This waits for both the main loop thread (if provided) and all workers to close.
+    # This is important for tests and for ensuring clean shutdown.
+    #
+    # @param timeout [Integer] Maximum seconds to wait
+    # @return [Boolean] true if all components finished, false if timeout
+    def wait_for_shutdown_completion(timeout = 10)
+      start_time = Time.now
+      poll_interval = 0.1
+
+      loop do
+        # Check if timeout exceeded
+        break if Time.now - start_time > timeout
+
+        # Check main loop thread status (if provided and alive)
+        main_loop_done = @main_loop_thread.nil? || !@main_loop_thread.alive?
+
+        # Check if all workers are closed
+        workers_done = @workers.empty? || @workers.all?(&:closed?)
+
+        # If both main loop and workers are done, we're finished
+        if main_loop_done && workers_done
+          puts "All components closed successfully" if @debug
+          return true
+        end
+
+        # Show status while waiting
+        if @debug
+          closed_count = @workers.count(&:closed?)
+          main_status = @main_loop_thread&.alive? ? "running" : "stopped"
+          puts "Waiting for shutdown: main_loop=#{main_status}, workers=#{closed_count}/#{@workers.size} closed"
+        end
+
+        sleep(poll_interval)
+      end
+
+      # Timeout exceeded
+      if @debug
+        closed_count = @workers.count(&:closed?)
+        main_status = @main_loop_thread&.alive? ? "running" : "stopped"
+        puts "Shutdown timeout: main_loop=#{main_status}, workers=#{closed_count}/#{@workers.size} closed after #{timeout}s"
+      end
+      false
+    end
+
+    # Stop the performance monitor if it's enabled.
+    #
+    # @return [void]
+    def stop_performance_monitor
+      return unless @performance_monitor
+
+      begin
+        @performance_monitor.stop
+        puts "Performance monitor stopped" if @debug
+      rescue StandardError => e
+        puts "Error stopping performance monitor: #{e.message}" if @debug
+      end
+    end
+
+    # Wait for the timer thread to finish if it exists.
+    #
+    # @return [void]
+    def stop_timer_thread
+      return unless @timer_thread
+
+      # Only wait if thread is alive
+      if @timer_thread.alive?
+        @timer_thread.join(1) # Wait up to 1 second
+        @timer_thread.kill # Ensure thread is stopped
+        puts "Timer thread stopped" if @debug
+      end
+    end
+
+    # Signal the wakeup ractor to unblock Ractor.select.
+    # This is done first to allow the main loop to process the shutdown.
+    #
+    # @return [void]
+    def signal_wakeup_ractor
+      return unless @wakeup_ractor
+
+      begin
+        @wakeup_ractor.send(:shutdown)
+        puts "Sent shutdown signal to wakeup ractor" if @debug
+      rescue StandardError => e
+        puts "Error sending shutdown to wakeup ractor: #{e.message}" if @debug
+      end
+    end
+
+    # Send shutdown signal to all workers.
+    # Workers should gracefully finish their current work and exit.
+    #
+    # @return [void]
+    def signal_all_workers
+      @workers.each do |w|
+        begin
+          w.send(:shutdown)
+        rescue StandardError
+          # Ignore errors when sending shutdown to workers
+          nil
+        end
+        puts "Sent shutdown signal to #{w.name}" if @debug
+      end
+    end
+
+    # Check if the shutdown process has completed.
+    # This is useful for testing and monitoring.
+    #
+    # @return [Boolean] true if all components are stopped
+    def complete?
+      timer_stopped = @timer_thread.nil? || !@timer_thread.alive?
+      workers_stopped = @workers.empty? || @workers.all?(&:closed?)
+
+      timer_stopped && workers_stopped
+    end
+
+    # Get a summary of the shutdown status.
+    #
+    # @return [Hash] Status summary with component states
+    def status_summary
+      {
+        performance_monitor: @performance_monitor&.send(:monitoring?) || false,
+        timer_thread: @timer_thread&.alive? || false,
+        wakeup_ractor: !@wakeup_ractor.nil?,
+        workers_count: @workers.size,
+        workers_closed: @workers.count(&:closed?),
+      }
+    end
+  end
+end