fractor 0.1.0

data/lib/fractor/work_result.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Fractor
+  # Represents the result of processing a Work item.
+  # Can hold either a successful result or an error.
+  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
+
+    def inspect
+      {
+        result: @result,
+        error: @error,
+        work: @work&.to_s # Use safe navigation for work
+      }
+    end
+  end
+end

data/lib/fractor/worker.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Fractor
+  # Base class for defining work processors.
+  # Subclasses must implement the `process` method.
+  class Worker
+    def process(work)
+      raise NotImplementedError, "Subclasses must implement the 'process' method."
+    end
+  end
+end

data/lib/fractor/wrapped_ractor.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+module Fractor
+  # Wraps a Ruby Ractor to manage a worker instance.
+  # Handles communication and error propagation.
+  class WrappedRactor
+    attr_reader :ractor, :name
+
+    # Initializes the WrappedRactor with a name and the Worker class to instantiate.
+    # The worker_class parameter allows flexibility in specifying the worker type.
+    def initialize(name, worker_class)
+      puts "Creating Ractor #{name} with worker #{worker_class}"
+      @name = name
+      @worker_class = worker_class # Store the worker class
+      @ractor = nil # Initialize ractor as nil
+    end
+
+    # Starts the underlying Ractor.
+    def start
+      puts "Starting Ractor #{@name}"
+      # Pass worker_class to the Ractor block
+      @ractor = Ractor.new(@name, @worker_class) do |name, worker_cls|
+        puts "Ractor #{name} started with worker class #{worker_cls}"
+        # Yield an initialization message
+        Ractor.yield({ type: :initialize, processor: name })
+
+        # Instantiate the specific worker inside the Ractor
+        worker = worker_cls.new
+
+        loop do
+          # Ractor.receive will block until a message is received
+          puts "Waiting for work in #{name}"
+          work = Ractor.receive
+          puts "Received work #{work.inspect} in #{name}"
+
+          begin
+            # Process the work using the instantiated worker
+            result = worker.process(work)
+            puts "Sending result #{result.inspect} from Ractor #{name}"
+            # Yield the result back
+            Ractor.yield({ type: :result, result: result, processor: name })
+          rescue StandardError => e
+            # Handle errors during processing
+            puts "Error processing work #{work.inspect} in Ractor #{name}: #{e.message}\n#{e.backtrace.join("\n")}"
+            # Yield an error message back
+            # Ensure the original work object is included in the error result
+            error_result = Fractor::WorkResult.new(error: e.message, work: work)
+            Ractor.yield({ type: :error, result: error_result, processor: name })
+          end
+        end
+      rescue Ractor::ClosedError
+        puts "Ractor #{name} closed."
+      rescue StandardError => e
+        puts "Unexpected error in Ractor #{name}: #{e.message}\n#{e.backtrace.join("\n")}"
+        # Optionally yield a critical error message if needed
+      ensure
+        puts "Ractor #{name} shutting down."
+      end
+      puts "Ractor #{@name} instance created: #{@ractor}"
+    end
+
+    # Sends work to the Ractor if it's active.
+    def send(work)
+      if @ractor
+        begin
+          @ractor.send(work)
+          true
+        rescue Exception => e
+          puts "Warning: Error sending work to Ractor #{@name}: #{e.message}"
+          false
+        end
+      else
+        puts "Warning: Attempted to send work to nil Ractor #{@name}"
+        false
+      end
+    end
+
+    # Closes the Ractor.
+    # Ruby 3.0+ has different ways to terminate Ractors, we try the available methods
+    def close
+      return true if @ractor.nil?
+
+      begin
+        # Send a nil message to signal we're done - this might be processed
+        # if the Ractor is waiting for input
+        begin
+          begin
+            @ractor.send(nil)
+          rescue StandardError
+            nil
+          end
+        rescue StandardError
+          # Ignore errors when sending nil
+        end
+
+        # Mark as closed in our object
+        old_ractor = @ractor
+        @ractor = nil
+
+        # If available in this Ruby version, we'll try kill
+        if old_ractor.respond_to?(:kill)
+          begin
+            old_ractor.kill
+          rescue StandardError
+            nil
+          end
+        end
+
+        true
+      rescue Exception => e
+        puts "Warning: Error closing Ractor #{@name}: #{e.message}"
+        # Consider it closed even if there was an error
+        @ractor = nil
+        true
+      end
+    end
+
+    # Checks if the Ractor is closed or unavailable.
+    def closed?
+      return true if @ractor.nil?
+
+      begin
+        # Check if the Ractor is terminated using Ractor#inspect
+        # This is safer than calling methods on the Ractor
+        r_status = @ractor.inspect
+        if r_status.include?("terminated")
+          # If terminated, clean up our reference
+          @ractor = nil
+          return true
+        end
+        false
+      rescue Exception => e
+        # If we get an exception, the Ractor is likely terminated
+        puts "Ractor #{@name} appears to be terminated: #{e.message}"
+        @ractor = nil
+        true
+      end
+    end
+  end
+end

data/lib/fractor.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require 'thread' # Required for Queue
+
+# Require all component files
+require_relative 'fractor/version'
+require_relative 'fractor/worker'
+require_relative 'fractor/work'
+require_relative 'fractor/work_result'
+require_relative 'fractor/result_aggregator'
+require_relative 'fractor/wrapped_ractor'
+require_relative 'fractor/supervisor'
+
+# Fractor: Function-driven Ractors framework
+module Fractor
+  # The module is defined in the individual files
+end

data/sample.rb

@@ -0,0 +1,64 @@
+#!/usr/bin/env ruby
+
+require_relative 'fractor'
+
+# Client-specific worker implementation inheriting from Fractor::Worker
+class MyWorker < Fractor::Worker
+  # This method is called by the Ractor to process the work
+  # It should return a Fractor::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 a Fractor::WorkResult for errors
+      return Fractor::WorkResult.new(error: "Error processing work #{work.input}", work: work)
+    end
+
+    calculated = work.input * 2
+    # Return a Fractor::WorkResult for success
+    Fractor::WorkResult.new(result: calculated, work: work)
+  end
+end
+
+# Client-specific work item implementation inheriting from Fractor::Work
+class MyWork < Fractor::Work
+  def initialize(input)
+    super
+  end
+
+  def to_s
+    "MyWork: #{@input}"
+  end
+end
+
+# --- Main Execution ---
+# This section demonstrates how to use the Fractor framework with custom
+# MyWorker and MyWork classes.
+if __FILE__ == $0
+  # Create supervisor, passing the client-specific worker and work classes
+  supervisor = Fractor::Supervisor.new(
+    worker_class: MyWorker,
+    work_class: MyWork,
+    num_workers: 2 # Specify the number of worker Ractors
+  )
+
+  # Add work items (raw data) - the Supervisor will wrap these in MyWork objects
+  work_items = (1..10).to_a
+  supervisor.add_work(work_items)
+
+  # Run the supervisor to start processing work
+  supervisor.run
+
+  puts "Processing complete."
+  puts "Final Aggregated Results:"
+  # Access the results aggregator from the supervisor
+  puts supervisor.results.inspect
+
+  # Print failed items directly from the Fractor::ResultAggregator's errors array
+  failed_items = supervisor.results.errors # Access the errors array
+  puts "\nFailed Work Items (#{failed_items.size}):"
+  # Display each Fractor::WorkResult object in the errors array
+  puts failed_items.map(&:to_s).join("\n") # Use to_s on the WorkResult objects
+end

data/sig/fractor.rbs

@@ -0,0 +1,4 @@
+module Fractor
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

data/tests/sample.rb.bak

@@ -0,0 +1,309 @@
+#!/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