fractor 0.1.4 → 0.1.7

data/lib/fractor.rb

@@ -2,14 +2,104 @@
 
 # Require all component files
 require_relative "fractor/version"
-require_relative "fractor/worker"
+require_relative "fractor/configuration"
+require_relative "fractor/logger"
 require_relative "fractor/work"
 require_relative "fractor/work_result"
-require_relative "fractor/result_aggregator"
+require_relative "fractor/work_queue"
+require_relative "fractor/priority_work"
+require_relative "fractor/priority_work_queue"
 require_relative "fractor/wrapped_ractor"
+require_relative "fractor/wrapped_ractor3"
+require_relative "fractor/wrapped_ractor4"
+require_relative "fractor/worker"
+require_relative "fractor/work_distribution_manager"
+require_relative "fractor/shutdown_handler"
+require_relative "fractor/main_loop_handler"
+require_relative "fractor/main_loop_handler3"
+require_relative "fractor/main_loop_handler4"
+require_relative "fractor/signal_handler"
+require_relative "fractor/supervisor_logger"
 require_relative "fractor/supervisor"
+require_relative "fractor/result_aggregator"
+require_relative "fractor/continuous_server"
+require_relative "fractor/workflow"
+require_relative "fractor/performance_monitor"
+require_relative "fractor/performance_metrics_collector"
+require_relative "fractor/performance_report_generator"
+require_relative "fractor/error_reporter"
+require_relative "fractor/error_statistics"
+require_relative "fractor/error_report_generator"
+require_relative "fractor/error_formatter"
+require_relative "fractor/execution_tracer"
+
+# Optional: CLI (only load if Thor is available)
+begin
+  require "thor"
+  require_relative "fractor/cli"
+rescue LoadError
+  # Thor not available, CLI commands will not be available
+end
 
 # Fractor: Function-driven Ractors framework
 module Fractor
-  # The module is defined in the individual files
+  # Exception raised when trying to push to a closed queue
+  class ClosedQueueError < StandardError; end
+
+  # Configure Fractor with a block.
+  #
+  # @yield [Configuration] The configuration object
+  #
+  # @example
+  #   Fractor.configure do |config|
+  #     config.debug = true
+  #     config.logger = Logger.new(STDOUT)
+  #     config.default_worker_timeout = 60
+  #   end
+  def self.configure(&)
+    Configuration.configure(&)
+  end
+
+  # Load configuration from a YAML file.
+  #
+  # @param file_path [String] Path to the YAML configuration file
+  def self.configure_from_file(file_path)
+    Configuration.configure_from_file(file_path)
+  end
+
+  # Load configuration from environment variables.
+  # Environment variables should be prefixed with FRACTOR_.
+  #
+  # @example
+  #   # Set environment variables
+  #   # export FRACTOR_DEBUG=true
+  #   # export FRACTOR_DEFAULT_WORKER_TIMEOUT=60
+  #
+  #   Fractor.configure_from_env
+  def self.configure_from_env
+    Configuration.configure_from_env
+  end
+
+  # Access the global configuration instance.
+  #
+  # @return [Configuration] The configuration instance
+  def self.config
+    Configuration.config
+  end
+
+  # Reset all global state to ensure isolation between different uses of Fractor.
+  # This is important for testing and when multiple gems use Fractor together.
+  #
+  # @example Reset state between tests
+  #   Fractor.reset!  # Clears logger, tracer, and other global state
+  def self.reset!
+    Configuration.reset!
+    ExecutionTracer.reset!
+    reset_logger!
+  end
+
+  # Reset logger state (internal method, use reset! instead)
+  def self.reset_logger!
+    @logger = nil if defined?(@logger)
+  end
 end

metadata

@@ -1,55 +1,241 @@
 --- !ruby/object:Gem::Specification
 name: fractor
 version: !ruby/object:Gem::Version
-  version: 0.1.4
+  version: 0.1.7
 platform: ruby
 authors:
 - Ronald Tse
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-10-09 00:00:00.000000000 Z
-dependencies: []
+date: 2026-01-22 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: logger
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: benchmark
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: Fractor is a lightweight Ruby framework designed to simplify the process
   of distributing computational work across multiple Ractors.
 email:
 - ronald.tse@ribose.com
-executables: []
+executables:
+- fractor
 extensions: []
 extra_rdoc_files: []
 files:
 - ".rspec"
+- ".rubocop-https---raw-githubusercontent-com-riboseinc-oss-guides-main-ci-rubocop-yml"
 - ".rubocop.yml"
 - ".rubocop_todo.yml"
 - CODE_OF_CONDUCT.md
 - README.adoc
 - Rakefile
+- docs/.lycheeignore
+- docs/Gemfile
+- docs/README.md
+- docs/_config.yml
+- docs/_features/error-handling.adoc
+- docs/_features/index.adoc
+- docs/_features/monitoring.adoc
+- docs/_features/signal-handling.adoc
+- docs/_features/workflows.adoc
+- docs/_guides/continuous-mode.adoc
+- docs/_guides/cookbook.adoc
+- docs/_guides/index.adoc
+- docs/_guides/pipeline-mode.adoc
+- docs/_guides/troubleshooting.adoc
+- docs/_pages/architecture.adoc
+- docs/_pages/core-concepts.adoc
+- docs/_pages/design-principles.adoc
+- docs/_pages/getting-started.adoc
+- docs/_pages/installation.adoc
+- docs/_reference/api.adoc
+- docs/_reference/error-reporting.adoc
+- docs/_reference/examples.adoc
+- docs/_reference/index.adoc
+- docs/_reference/troubleshooting.adoc
+- docs/_tutorials/complex-workflows.adoc
+- docs/_tutorials/data-processing-pipeline.adoc
+- docs/_tutorials/first-application.adoc
+- docs/_tutorials/index.adoc
+- docs/_tutorials/long-running-services.adoc
+- docs/assets/images/favicon-16.png
+- docs/assets/images/favicon-32.png
+- docs/assets/images/favicon-48.png
+- docs/assets/images/favicon.ico
+- docs/assets/images/favicon.png
+- docs/assets/images/favicon.svg
+- docs/assets/images/fractor-icon.svg
+- docs/assets/images/fractor-logo.svg
+- docs/index.adoc
+- docs/lychee.toml
+- examples/api_aggregator/README.adoc
+- examples/api_aggregator/api_aggregator.rb
 - examples/auto_detection/README.adoc
 - examples/auto_detection/auto_detection.rb
+- examples/continuous_chat_common/message_protocol.rb
+- examples/continuous_chat_fractor/README.adoc
+- examples/continuous_chat_fractor/chat_client.rb
+- examples/continuous_chat_fractor/chat_common.rb
+- examples/continuous_chat_fractor/chat_server.rb
+- examples/continuous_chat_fractor/simulate.rb
+- examples/continuous_chat_server/README.adoc
+- examples/continuous_chat_server/chat_client.rb
+- examples/continuous_chat_server/chat_server.rb
+- examples/continuous_chat_server/simulate.rb
+- examples/error_reporting.rb
+- examples/file_processor/README.adoc
+- examples/file_processor/file_processor.rb
+- examples/file_processor/sample_files/invalid.csv
+- examples/file_processor/sample_files/orders.xml
+- examples/file_processor/sample_files/products.json
+- examples/file_processor/sample_files/users.csv
 - examples/hierarchical_hasher/README.adoc
 - examples/hierarchical_hasher/hierarchical_hasher.rb
+- examples/image_processor/README.adoc
+- examples/image_processor/image_processor.rb
+- examples/image_processor/processed_images/sample_10_processed.jpg.json
+- examples/image_processor/processed_images/sample_1_processed.jpg.json
+- examples/image_processor/processed_images/sample_2_processed.jpg.json
+- examples/image_processor/processed_images/sample_3_processed.jpg.json
+- examples/image_processor/processed_images/sample_4_processed.jpg.json
+- examples/image_processor/processed_images/sample_5_processed.jpg.json
+- examples/image_processor/processed_images/sample_6_processed.jpg.json
+- examples/image_processor/processed_images/sample_7_processed.jpg.json
+- examples/image_processor/processed_images/sample_8_processed.jpg.json
+- examples/image_processor/processed_images/sample_9_processed.jpg.json
+- examples/image_processor/test_images/sample_1.png
+- examples/image_processor/test_images/sample_10.png
+- examples/image_processor/test_images/sample_2.png
+- examples/image_processor/test_images/sample_3.png
+- examples/image_processor/test_images/sample_4.png
+- examples/image_processor/test_images/sample_5.png
+- examples/image_processor/test_images/sample_6.png
+- examples/image_processor/test_images/sample_7.png
+- examples/image_processor/test_images/sample_8.png
+- examples/image_processor/test_images/sample_9.png
+- examples/log_analyzer/README.adoc
+- examples/log_analyzer/log_analyzer.rb
+- examples/log_analyzer/sample_logs/apache.log
+- examples/log_analyzer/sample_logs/json.log
+- examples/log_analyzer/sample_logs/nginx.log
+- examples/log_analyzer/sample_logs/rails.log
 - examples/multi_work_type/README.adoc
 - examples/multi_work_type/multi_work_type.rb
+- examples/performance_monitoring.rb
 - examples/pipeline_processing/README.adoc
 - examples/pipeline_processing/pipeline_processing.rb
+- examples/priority_work_example.rb
 - examples/producer_subscriber/README.adoc
 - examples/producer_subscriber/producer_subscriber.rb
 - examples/scatter_gather/README.adoc
 - examples/scatter_gather/scatter_gather.rb
+- examples/simple/README.adoc
 - examples/simple/sample.rb
 - examples/specialized_workers/README.adoc
 - examples/specialized_workers/specialized_workers.rb
+- examples/stream_processor/README.adoc
+- examples/stream_processor/stream_processor.rb
+- examples/web_scraper/README.adoc
+- examples/web_scraper/web_scraper.rb
+- examples/workflow/README.adoc
+- examples/workflow/circuit_breaker/README.adoc
+- examples/workflow/circuit_breaker/circuit_breaker_workflow.rb
+- examples/workflow/conditional/README.adoc
+- examples/workflow/conditional/conditional_workflow.rb
+- examples/workflow/dead_letter_queue/README.adoc
+- examples/workflow/dead_letter_queue/dead_letter_queue_workflow.rb
+- examples/workflow/fan_out/README.adoc
+- examples/workflow/fan_out/fan_out_workflow.rb
+- examples/workflow/retry/README.adoc
+- examples/workflow/retry/retry_workflow.rb
+- examples/workflow/simple_linear/README.adoc
+- examples/workflow/simple_linear/simple_linear_workflow.rb
+- examples/workflow/simplified/README.adoc
+- examples/workflow/simplified/simplified_workflow.rb
+- exe/fractor
 - lib/fractor.rb
+- lib/fractor/cli.rb
+- lib/fractor/configuration.rb
+- lib/fractor/continuous_server.rb
+- lib/fractor/error_formatter.rb
+- lib/fractor/error_report_generator.rb
+- lib/fractor/error_reporter.rb
+- lib/fractor/error_statistics.rb
+- lib/fractor/execution_tracer.rb
+- lib/fractor/logger.rb
+- lib/fractor/main_loop_handler.rb
+- lib/fractor/main_loop_handler3.rb
+- lib/fractor/main_loop_handler4.rb
+- lib/fractor/performance_metrics_collector.rb
+- lib/fractor/performance_monitor.rb
+- lib/fractor/performance_report_generator.rb
+- lib/fractor/priority_work.rb
+- lib/fractor/priority_work_queue.rb
 - lib/fractor/result_aggregator.rb
+- lib/fractor/shutdown_handler.rb
+- lib/fractor/signal_handler.rb
 - lib/fractor/supervisor.rb
+- lib/fractor/supervisor_logger.rb
 - lib/fractor/version.rb
 - lib/fractor/work.rb
+- lib/fractor/work_distribution_manager.rb
+- lib/fractor/work_queue.rb
 - lib/fractor/work_result.rb
 - lib/fractor/worker.rb
+- lib/fractor/workflow.rb
+- lib/fractor/workflow/builder.rb
+- lib/fractor/workflow/chain_builder.rb
+- lib/fractor/workflow/circuit_breaker.rb
+- lib/fractor/workflow/circuit_breaker_orchestrator.rb
+- lib/fractor/workflow/circuit_breaker_registry.rb
+- lib/fractor/workflow/dead_letter_queue.rb
+- lib/fractor/workflow/execution_hooks.rb
+- lib/fractor/workflow/execution_strategy.rb
+- lib/fractor/workflow/execution_trace.rb
+- lib/fractor/workflow/helpers.rb
+- lib/fractor/workflow/job.rb
+- lib/fractor/workflow/job_dependency_validator.rb
+- lib/fractor/workflow/logger.rb
+- lib/fractor/workflow/pre_execution_context.rb
+- lib/fractor/workflow/retry_config.rb
+- lib/fractor/workflow/retry_orchestrator.rb
+- lib/fractor/workflow/retry_strategy.rb
+- lib/fractor/workflow/structured_logger.rb
+- lib/fractor/workflow/type_compatibility_validator.rb
+- lib/fractor/workflow/visualizer.rb
+- lib/fractor/workflow/workflow_context.rb
+- lib/fractor/workflow/workflow_executor.rb
+- lib/fractor/workflow/workflow_result.rb
+- lib/fractor/workflow/workflow_validator.rb
 - lib/fractor/wrapped_ractor.rb
+- lib/fractor/wrapped_ractor3.rb
+- lib/fractor/wrapped_ractor4.rb
 - sig/fractor.rbs
-- tests/sample.rb.bak
-- tests/sample_working.rb.bak
 homepage: https://github.com/ribose/fractor
 licenses: []
 metadata:

data/tests/sample.rb.bak

@@ -1,309 +0,0 @@
-#!/usr/bin/env ruby
-
-
-class Worker
-  def process(work)
-    raise NotImplementedError, "This #{self.class} cannot respond to:"
-  end
-end
-
-class MyWorker < Worker
-  # This method is called by the Ractor to process the work
-  # It should return a WorkResult object
-  # If there is an error, it should raise an exception
-  # The Ractor will catch the exception and send it back to the main thread
-  def process(work)
-    puts "Working on '#{work.inspect}'"
-
-    if work.input == 5
-      return WorkResult.new(error: "Error processing work #{work.input}", work: work)
-    end
-
-    calculated = work.input * 2
-    WorkResult.new(result: calculated, work: work)
-  end
-end
-
-class Work
-  attr_reader :input
-  def initialize(input)
-    @input = input
-  end
-
-  def to_s
-    "Work: #{@input}"
-  end
-end
-
-class MyWork < Work
-  def initialize(input)
-    super
-  end
-
-  def to_s
-    "MyWork: #{@input}"
-  end
-end
-
-class WorkResult
-  attr_reader :result, :error, :work
-  def initialize(result: nil, error: nil, work: nil)
-    @result = result
-    @error = error
-    @work = work
-  end
-
-  def success?
-    !@error
-  end
-
-  def to_s
-    if success?
-      "Result: #{@result}"
-    else
-      "Error: #{@error}, Work: #{@work}"
-    end
-  end
-end
-
-
-class ResultAggregator
-  attr_reader :results, :errors
-
-  # This class is used to aggregate the results and errors from the Ractors
-  # It will store the results and errors in separate arrays
-  # It will also provide a method to print the results and errors
-  def initialize
-    @results = []
-    @errors = []
-  end
-
-  def add_result(result)
-    if result.success?
-      puts "Work completed successfully: #{result}"
-      @results << result
-    else
-      puts "Error processing work: #{result}"
-      @errors << result
-    end
-  end
-
-  def to_s
-    "Results: #{@results.each(&:to_s).join(", ")}, Errors: #{@errors.each(&:to_s).join(", ")}"
-  end
-
-  def inspect
-    {
-      results: @results.map(&:to_s),
-      errors: @errors.map(&:to_s)
-    }
-  end
-end
-
-class MyRactor
-  def initialize(name)
-    puts "Creating Ractor #{name}"
-    @name = name
-  end
-
-  def start
-    puts "Starting Ractor #{@name}"
-    @ractor = Ractor.new(@name) do |name|
-      puts "Ractor #{name} started"
-      Ractor.yield({ type: :initialize, processor: name })
-      worker = MyWorker.new
-
-      loop do
-        puts "Waiting for work in #{name}"
-        work = Ractor.receive
-        puts "Received work #{work} in #{name}"
-        begin
-          result = worker.process(work)
-          puts "Sending result #{result} from Ractor #{name}"
-          Ractor.yield({ type: :result, result: result })
-        rescue StandardError => e
-          puts "Error processing work #{work} in Ractor #{name}: #{e.message}"
-          Ractor.yield({ type: :error, error: e.message, processor: name, work: work })
-        end
-      end
-    end
-  end
-
-  def ractor
-    @ractor
-  end
-end
-
-class Supervisor
-  # Removed failed_queue from attr_reader
-  attr_reader :work_queue, :workers, :results
-
-  def initialize(num_workers = 2)
-    @work_queue = Queue.new
-    @results = ResultAggregator.new
-    # @failed_queue = Queue.new # Removed failed_queue
-    @num_workers = num_workers
-    @workers = []
-    @total_work_count = 0 # Track total items initially added
-    # @shutdown_requested = false # Removed shutdown flag
-  end
-
-  def add_work(items)
-    items.each { |item| @work_queue << item }
-    @total_work_count += items.size # Increment initial work count
-    puts "Work added. Initial work count: #{@total_work_count}, Queue size: #{@work_queue.size}"
-  end
-
-  def start_workers
-    @workers = (1..@num_workers).map do |i|
-      MyRactor.new("worker #{i}")
-    end
-    @workers.each(&:start)
-    puts "Workers started"
-  end
-
-  def setup_signal_handler
-    # No need for Ractor.current here anymore
-    # Need access to @workers within the trap block
-    workers_ref = @workers
-    Signal.trap("INT") do
-      puts "\nCtrl+C received. Initiating immediate shutdown..."
-      # Attempt to close worker Ractors before exiting
-      puts "Attempting to close worker Ractors..."
-      workers_ref.each do |w|
-        begin
-          # Check if ractor exists and is not closed
-          if w && w.respond_to?(:ractor) && w.ractor && !w.ractor.closed?
-             w.ractor.close
-             puts "Closed Ractor: #{w.ractor}"
-          end
-        rescue => e # Catch potential errors during close
-          puts "Error closing Ractor #{w.ractor rescue 'unknown'}: #{e.message}"
-        end
-      end
-      puts "Exiting now."
-      exit(1) # Exit immediately
-    end
-  end
-
-  def run
-    setup_signal_handler # Sets up the immediate exit trap
-    start_workers
-
-    # Removed the initial work distribution loop.
-    # The main loop will handle sending work upon receiving :initialize message.
-
-    # Main loop: Process events until the number of results equals the initial work count.
-    # The signal trap handles immediate exit.
-    while (@results.results.size + @results.errors.size) < @total_work_count
-      processed_count = @results.results.size + @results.errors.size
-      puts "Waiting for Ractor results. Processed: #{processed_count}/#{@total_work_count}, Queue size: #{@work_queue.size}"
-
-      # Only select from worker ractors now
-      ready_ractors = @workers.map(&:ractor).compact
-      # Safety break if all workers somehow finished/closed unexpectedly AND no work left
-      # This condition might need refinement depending on exact desired behavior if workers die.
-      break if ready_ractors.empty? && @work_queue.empty? && processed_count < @total_work_count
-
-      # Ractor.select will block until a worker sends a message
-      # If ready_ractors is empty but loop continues, select would raise error. Added break above.
-      next if ready_ractors.empty? # Skip iteration if no workers available but loop condition met (e.g., waiting for final results)
-
-      ractor, completed_work = Ractor.select(*ready_ractors)
-
-      puts "Selected Ractor returned: #{ractor}, completed work: #{completed_work}"
-
-      # Process the received message
-      case completed_work[:type]
-      when :initialize
-        puts "Initializing Ractor: #{completed_work[:processor]}"
-        # Send work if available
-        if !@work_queue.empty?
-          queued_work = @work_queue.pop # Pop before sending
-          puts "Sending initial work #{queued_work} to initialized Ractor: #{ractor}"
-          ractor.send(MyWork.new(queued_work))
-          puts "Initial work sent to #{completed_work[:processor]}."
-        else
-          puts "Work queue empty when Ractor #{completed_work[:processor]} initialized."
-        end
-      when :result
-        puts "Completed work: #{completed_work[:result]} in Ractor: #{completed_work[:processor]}"
-        @results.add_result(completed_work[:result])
-        # No need to decrement a counter here, loop condition checks total results
-        puts "Result processed. Total processed: #{@results.results.size + @results.errors.size}/#{@total_work_count}"
-        puts "Results: #{@results.inspect}"
-        # Call helper to send next work
-        send_next_work_if_available(ractor)
-      when :error
-        error_result = WorkResult.new(error: completed_work[:error], work: completed_work[:work])
-        puts "Error processing work #{error_result.work} in Ractor: #{completed_work[:processor]}: #{error_result.error}"
-        # Removed adding to failed_queue
-        @results.add_result(error_result) # This adds it to the errors array in the aggregator
-        # No need to decrement a counter here, loop condition checks total results
-        puts "Error handled. Total processed: #{@results.results.size + @results.errors.size}/#{@total_work_count}"
-        # Removed Failed Queue size log
-        puts "Results (including errors): #{@results.inspect}"
-        # Call helper to send next work
-        send_next_work_if_available(ractor)
-      else
-        # Log unknown message types from workers
-        puts "Unknown message type received: #{completed_work[:type]} from #{ractor}"
-      end
-      # Loop continues based on the while condition at the top
-    end
-
-    # Removed DEBUG LOG for failed_queue
-
-    # This part might not be reached if exit(1) is called in the trap
-    puts "Main loop finished."
-    puts "Final Results: #{@results.inspect}"
-    # Removed Failed Work Queue size log
-    # Optionally print failed items
-    # until @failed_queue.empty?
-    #   puts "Failed: #{@failed_queue.pop.inspect}"
-    # end
-  end
-
-  private
-
-  # Helper method to send next work item if available
-  def send_next_work_if_available(ractor)
-    # Ensure the ractor is valid before attempting to send
-    # Ractor.select should only return active ractors, so closed? check is removed.
-    unless ractor.nil?
-      if !@work_queue.empty?
-        queued_work = @work_queue.pop # Pop before sending
-        puts "Sending next work #{queued_work} to Ractor: #{ractor}"
-        ractor.send(MyWork.new(queued_work))
-        puts "Work sent."
-      else
-        puts "Work queue empty. Not sending new work to Ractor #{ractor}."
-      end
-    else
-      puts "Attempted to send work to an invalid or closed Ractor."
-    end
-  end
-end
-
-# --- Main Execution ---
-if __FILE__ == $0
-  supervisor = Supervisor.new(2) # Create supervisor with 2 workers
-
-  # Add work items
-  work_items = (1..10).to_a
-  supervisor.add_work(work_items)
-
-  # Run the supervisor
-  supervisor.run
-
-  puts "Processing complete."
-  puts "Final Aggregated Results:"
-  puts supervisor.results.inspect
-
-  # Print failed items directly from the ResultAggregator's errors array
-  failed_items = supervisor.results.errors # Access the errors array
-  puts "\nFailed Work Items (#{failed_items.size}):"
-  # Inspect each item individually for better readability if they are objects
-  # The items are already WorkResult objects
-  puts failed_items.map(&:inspect).inspect
-end