fractor 0.1.0

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/examples/hierarchical_hasher.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+require 'digest'
+require_relative '../lib/fractor'
+
+module HierarchicalHasher
+  class ChunkWork < Fractor::Work
+    work_type :chunk_hash
+    attr_reader :start, :length, :data
+
+    def initialize(start, length, data)
+      super(nil, { start: start, length: length, data: data })
+      @start = start
+      @length = length
+      @data = data
+      @retry_count = 0
+      @max_retries = 3
+    end
+
+    def should_retry?
+      @retry_count < @max_retries
+    end
+
+    def failed
+      @retry_count += 1
+    end
+  end
+
+  class ChunkResult < Fractor::WorkResult
+    attr_reader :start, :length, :hash_result
+
+    def initialize(work, hash_result)
+      super(work, hash_result)
+      @start = work.start
+      @length = work.length
+      @hash_result = hash_result
+    end
+  end
+
+  class HashWorker < Fractor::Worker
+    work_type_accepted :chunk_hash
+
+    def process_work(work)
+      # Simulate some processing time
+      sleep(rand(0.01..0.05))
+
+      # Calculate SHA-3 hash for the chunk
+      hash = Digest::SHA3.hexdigest(work.data)
+
+      # Return the result
+      ChunkResult.new(work, hash)
+    end
+  end
+
+  class HashResultAssembler < Fractor::ResultAssembler
+    def finalize
+      return nil if @results.empty?
+
+      # Sort results by start position
+      sorted_results = @results.sort_by { |result| result.start }
+
+      # Concatenate all hashes with newlines
+      combined_hash_string = sorted_results.map(&:hash_result).join("\n")
+
+      # Calculate final SHA-3 hash
+      Digest::SHA3.hexdigest(combined_hash_string)
+    end
+  end
+
+  class HashSupervisor < Fractor::Supervisor
+    def initialize(file_path, chunk_size = 1024, worker_count = 4)
+      super()
+      @file_path = file_path
+      @chunk_size = chunk_size
+      @worker_count = worker_count
+      @assembler = HashResultAssembler.new
+
+      # Create a queue for chunk work
+      chunk_queue = Fractor::Queue.new(work_types: [:chunk_hash])
+      add_queue(chunk_queue)
+
+      # Create a worker pool
+      worker_pool = Fractor::Pool.new(size: @worker_count)
+      @worker_count.times do
+        worker_pool.add_worker(HashWorker.new)
+      end
+      add_pool(worker_pool)
+
+      # Load the file and create work chunks
+      load_file_chunks
+    end
+
+    def load_file_chunks
+      File.open(@file_path, 'rb') do |file|
+        start_pos = 0
+
+        while chunk = file.read(@chunk_size)
+          work = ChunkWork.new(start_pos, chunk.length, chunk)
+          @queues.first.push(work)
+          start_pos += chunk.length
+        end
+      end
+    end
+
+    def process_results
+      until @result_queue.empty? && @queues.all?(&:empty?) && @idle_workers == @active_workers.size
+        result_data = next_result
+        next if result_data.nil?
+
+        type, *data = result_data
+
+        case type
+        when :result
+          result = data.first
+          @assembler.add_result(result)
+        when :error
+          work, error = data
+          @assembler.add_failed_work(work, error)
+        end
+
+        # Small sleep to prevent CPU spinning
+        sleep 0.001
+      end
+
+      # Return the final hash
+      @assembler.finalize
+    end
+  end
+end
+
+# Example usage
+if __FILE__ == $PROGRAM_NAME
+  if ARGV.empty?
+    puts "Usage: ruby hierarchical_hasher.rb <file_path> [worker_count]"
+    exit 1
+  end
+
+  file_path = ARGV[0]
+  worker_count = (ARGV[1] || 4).to_i
+
+  unless File.exist?(file_path)
+    puts "Error: File '#{file_path}' not found"
+    exit 1
+  end
+
+  puts "Starting hierarchical hasher with #{worker_count} workers..."
+  puts "Processing file: #{file_path}"
+
+  start_time = Time.now
+  supervisor = HierarchicalHasher::HashSupervisor.new(file_path, 1024, worker_count)
+  final_hash = supervisor.start
+  end_time = Time.now
+
+  puts "Final SHA-3 hash: #{final_hash}"
+  puts "Processing completed in #{end_time - start_time} seconds"
+
+  supervisor.shutdown
+end

data/examples/producer_subscriber.rb

@@ -0,0 +1,300 @@
+# frozen_string_literal: true
+
+require_relative '../lib/fractor'
+
+module ProducerSubscriber
+  # Define work types
+  class InitialWork < Fractor::Work
+    work_type :initial_processing
+    attr_reader :data, :depth
+
+    def initialize(data, depth = 0)
+      super(data: { data: data, depth: depth })
+      @data = data
+      @depth = depth
+      @retry_count = 0
+      @max_retries = 2
+    end
+
+    def should_retry?
+      @retry_count < @max_retries
+    end
+
+    def failed
+      @retry_count += 1
+    end
+  end
+
+  class SubWork < Fractor::Work
+    work_type :sub_processing
+    attr_reader :data, :parent_id, :depth
+
+    def initialize(data, parent_id, depth)
+      super(data: { data: data, parent_id: parent_id, depth: depth })
+      @data = data
+      @parent_id = parent_id
+      @depth = depth
+      @retry_count = 0
+      @max_retries = 2
+    end
+
+    def should_retry?
+      @retry_count < @max_retries
+    end
+
+    def failed
+      @retry_count += 1
+    end
+  end
+
+  # Define work results
+  class InitialWorkResult < Fractor::WorkResult
+    attr_reader :processed_data, :sub_works
+
+    def initialize(work, processed_data, sub_works = [])
+      super(work, processed_data)
+      @processed_data = processed_data
+      @sub_works = sub_works
+    end
+  end
+
+  class SubWorkResult < Fractor::WorkResult
+    attr_reader :processed_data, :parent_id
+
+    def initialize(work, processed_data)
+      super(work, processed_data)
+      @processed_data = processed_data
+      @parent_id = work.parent_id
+    end
+  end
+
+  # Define worker that can handle both types of work
+  class MultiWorker < Fractor::Worker
+    work_type_accepted [:initial_processing, :sub_processing]
+
+    def process_work(work)
+      case work.work_type
+      when :initial_processing
+        process_initial_work(work)
+      when :sub_processing
+        process_sub_work(work)
+      end
+    end
+
+    private
+
+    def process_initial_work(work)
+      # Simulate processing time
+      sleep(rand(0.01..0.05))
+
+      # Process the data
+      processed_data = "Processed: #{work.data}"
+
+      # Create sub-works if we're not too deep
+      sub_works = []
+      if work.depth < 2  # Limit recursion depth
+        # Split the work into smaller chunks
+        3.times do |i|
+          sub_data = "#{work.data}-#{i}"
+          sub_works << SubWork.new(sub_data, work.object_id, work.depth + 1)
+        end
+      end
+
+      # Return result with sub-works
+      InitialWorkResult.new(work, processed_data, sub_works)
+    end
+
+    def process_sub_work(work)
+      # Simulate processing time
+      sleep(rand(0.01..0.03))
+
+      # Process the data
+      processed_data = "Sub-processed: #{work.data} (depth: #{work.depth})"
+
+      # Create more sub-works if we're not too deep
+      sub_works = []
+      if work.depth < 3  # Limit recursion depth
+        # Create fewer sub-works as we go deeper
+        (4 - work.depth).times do |i|
+          sub_data = "#{work.data}-#{i}"
+          sub_works << SubWork.new(sub_data, work.parent_id, work.depth + 1)
+        end
+      end
+
+      # Return result with any new sub-works
+      result = SubWorkResult.new(work, processed_data)
+      [result, sub_works]
+    end
+  end
+
+  # Define result assembler
+  class TreeResultAssembler < Fractor::ResultAssembler
+    def initialize
+      super()
+      @result_tree = {}
+      @pending_work_count = 0
+    end
+
+    def track_new_work(count = 1)
+      @pending_work_count += count
+    end
+
+    def work_completed
+      @pending_work_count -= 1
+    end
+
+    def add_result(result)
+      super(result)
+      work_completed
+
+      case result
+      when InitialWorkResult
+        @result_tree[result.work.object_id] = {
+          data: result.processed_data,
+          children: []
+        }
+      when SubWorkResult
+        parent = @result_tree[result.parent_id]
+        if parent
+          parent[:children] << result.processed_data
+        end
+      end
+    end
+
+    def all_work_complete?
+      @pending_work_count <= 0
+    end
+
+    def finalize
+      # Build a formatted tree representation
+      format_tree
+    end
+
+    private
+
+    def format_tree
+      result = []
+      @result_tree.each do |id, node|
+        result << "Root: #{node[:data]}"
+        node[:children].each_with_index do |child, index|
+          result << "  ├─ Child #{index + 1}: #{child}"
+        end
+        result << ""
+      end
+      result.join("\n")
+    end
+  end
+
+  # Define supervisor
+  class TreeSupervisor < Fractor::Supervisor
+    def initialize(initial_data, worker_count = 4)
+      super()
+      @initial_data = initial_data
+      @worker_count = worker_count
+      @assembler = TreeResultAssembler.new
+
+      # Create a queue that can handle both work types
+      work_queue = Fractor::Queue.new(work_types: [:initial_processing, :sub_processing])
+      add_queue(work_queue)
+
+      # Create a worker pool
+      worker_pool = Fractor::Pool.new(size: @worker_count)
+      @worker_count.times do
+        worker_pool.add_worker(MultiWorker.new)
+      end
+      add_pool(worker_pool)
+
+      # Create initial work
+      initial_data.each do |data|
+        work = InitialWork.new(data)
+        @queues.first.push(work)
+        @assembler.track_new_work
+      end
+    end
+
+    def process_results
+      until @assembler.all_work_complete? && @queues.all?(&:empty?)
+        result_data = next_result
+        next if result_data.nil?
+
+        type, *data = result_data
+
+        case type
+        when :result
+          result = data.first
+
+          if result.is_a?(Array)
+            # Handle the case where we get a result and sub-works
+            sub_result, sub_works = result
+            @assembler.add_result(sub_result)
+
+            # Add new sub-works to the queue
+            if sub_works && !sub_works.empty?
+              @assembler.track_new_work(sub_works.size)
+              sub_works.each do |work|
+                @queues.first.push(work)
+              end
+            end
+          else
+            # Handle regular result
+            @assembler.add_result(result)
+
+            # If this result generated sub-works, add them to the queue
+            if result.respond_to?(:sub_works) && !result.sub_works.empty?
+              @assembler.track_new_work(result.sub_works.size)
+              result.sub_works.each do |work|
+                @queues.first.push(work)
+              end
+            end
+          end
+
+        when :error
+          work, error = data
+          @assembler.add_failed_work(work, error)
+          @assembler.work_completed
+        end
+
+        # Small sleep to prevent CPU spinning
+        sleep 0.001
+      end
+
+      # Return the final assembled result
+      @assembler.finalize
+    end
+  end
+end
+
+# Example usage: Document processing system
+if __FILE__ == $PROGRAM_NAME
+  puts "Starting producer-subscriber example: Document Processing System"
+  puts "This example simulates a document processing system where:"
+  puts "1. Initial documents are broken down into sections"
+  puts "2. Sections are further broken down into paragraphs"
+  puts "3. Paragraphs are processed individually"
+  puts "4. Results are assembled into a hierarchical structure"
+  puts
+
+  # Sample documents to process
+  documents = [
+    "Annual Report 2025",
+    "Technical Documentation",
+    "Research Paper"
+  ]
+
+  worker_count = 4
+  puts "Using #{worker_count} workers to process #{documents.size} documents"
+  puts
+
+  start_time = Time.now
+  supervisor = ProducerSubscriber::TreeSupervisor.new(documents, worker_count)
+  result = supervisor.start
+  end_time = Time.now
+
+  puts "Processing Results:"
+  puts "==================="
+  puts result
+  puts
+  puts "Processing completed in #{end_time - start_time} seconds"
+
+  supervisor.shutdown
+end

data/lib/fractor/result_aggregator.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Fractor
+  # Aggregates results and errors from worker Ractors.
+  class ResultAggregator
+    attr_reader :results, :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.size}, Errors: #{@errors.size}"
+    end
+
+    def inspect
+      {
+        results: @results.map(&:inspect),
+        errors: @errors.map(&:inspect)
+      }
+    end
+  end
+end

data/lib/fractor/supervisor.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+require 'thread' # Required for Queue
+
+module Fractor
+  # Supervises multiple WrappedRactors, distributes work, and aggregates results.
+  class Supervisor
+    attr_reader :work_queue, :workers, :results, :worker_class, :work_class
+
+    # Initializes the Supervisor.
+    # - worker_class: The class inheriting from Fractor::Worker (e.g., MyWorker).
+    # - work_class: The class inheriting from Fractor::Work (e.g., MyWork).
+    # - num_workers: The number of Ractors to spawn.
+    def initialize(worker_class:, work_class:, num_workers: 2)
+      unless worker_class < Fractor::Worker
+        raise ArgumentError, "#{worker_class} must inherit from Fractor::Worker"
+      end
+      unless work_class < Fractor::Work
+        raise ArgumentError, "#{work_class} must inherit from Fractor::Work"
+      end
+
+      @worker_class = worker_class
+      @work_class = work_class
+      @work_queue = Queue.new
+      @results = ResultAggregator.new
+      @num_workers = num_workers
+      @workers = []
+      @total_work_count = 0 # Track total items initially added
+      @ractors_map = {} # Map Ractor object to WrappedRactor instance
+    end
+
+    # Adds work items to the queue.
+    # Items should be the raw input data, not Work objects yet.
+    def add_work(items)
+      items.each { |item| @work_queue << item }
+      @total_work_count += items.size
+      puts "Work added. Initial work count: #{@total_work_count}, Queue size: #{@work_queue.size}"
+    end
+
+    # Starts the worker Ractors.
+    def start_workers
+      @workers = (1..@num_workers).map do |i|
+        # Pass the client's worker class (e.g., MyWorker) to WrappedRactor
+        wrapped_ractor = WrappedRactor.new("worker #{i}", @worker_class)
+        wrapped_ractor.start # Start the underlying Ractor
+        # Map the actual Ractor object to the WrappedRactor instance
+        @ractors_map[wrapped_ractor.ractor] = wrapped_ractor if wrapped_ractor.ractor
+        wrapped_ractor
+      end
+      # Filter out any workers that failed to start properly
+      @workers.compact!
+      @ractors_map.compact! # Ensure map doesn't contain nil keys/values
+      puts "Workers started: #{@workers.size} active."
+    end
+
+    # Sets up a signal handler for graceful shutdown (Ctrl+C).
+    def setup_signal_handler
+      # Need access to @workers within the trap block
+      workers_ref = @workers
+      Signal.trap("INT") do
+        puts "\nCtrl+C received. Initiating immediate shutdown..."
+        puts "Attempting to close worker Ractors..."
+        workers_ref.each do |w|
+          begin
+            w.close # Use the close method of WrappedRactor
+            puts "Closed Ractor: #{w.name}"
+          rescue => e
+            puts "Error closing Ractor #{w.name}: #{e.message}"
+          end
+        end
+        puts "Exiting now."
+        exit(1) # Exit immediately
+      end
+    end
+
+    # Runs the main processing loop.
+    def run
+      setup_signal_handler
+      start_workers
+
+      processed_count = 0
+      # Main loop: Process events until the number of results equals the initial work count.
+      while processed_count < @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}"
+
+        # Get active Ractor objects from the map keys
+        # Use keys from ractors_map for the active ractors
+        active_ractors = @ractors_map.keys
+
+        # Break if no active workers and queue is empty, but work remains (indicates potential issue)
+        if active_ractors.empty? && @work_queue.empty? && processed_count < @total_work_count
+           puts "Warning: No active workers and queue is empty, but not all work is processed. Exiting loop."
+           break
+        end
+
+        # Skip selection if no active ractors are available but loop should continue (e.g., waiting for final results)
+        next if active_ractors.empty?
+
+        # Ractor.select blocks until a message is available from any active Ractor
+        ready_ractor_obj, message = Ractor.select(*active_ractors)
+
+        # Find the corresponding WrappedRactor instance
+        wrapped_ractor = @ractors_map[ready_ractor_obj]
+        unless wrapped_ractor
+          puts "Warning: Received message from unknown Ractor: #{ready_ractor_obj}. Ignoring."
+          next
+        end
+
+        puts "Selected Ractor: #{wrapped_ractor.name}, Message Type: #{message[:type]}"
+
+        # Process the received message
+        case message[:type]
+        when :initialize
+          puts "Ractor initialized: #{message[:processor]}"
+          # Send work immediately upon initialization if available
+          send_next_work_if_available(wrapped_ractor)
+        when :result
+          # The message[:result] should be a WorkResult object
+          work_result = message[:result]
+          puts "Completed work: #{work_result.inspect} in Ractor: #{message[:processor]}"
+          @results.add_result(work_result)
+          puts "Result processed. Total processed: #{@results.results.size + @results.errors.size}/#{@total_work_count}"
+          puts "Aggregated Results: #{@results.inspect}"
+          # Send next piece of work
+          send_next_work_if_available(wrapped_ractor)
+        when :error
+          # The message[:result] should be a WorkResult object containing the error
+          error_result = message[:result]
+          puts "Error processing work #{error_result.work&.inspect} in Ractor: #{message[:processor]}: #{error_result.error}"
+          @results.add_result(error_result) # Add error to aggregator
+          puts "Error handled. Total processed: #{@results.results.size + @results.errors.size}/#{@total_work_count}"
+          puts "Aggregated Results (including errors): #{@results.inspect}"
+          # Send next piece of work even after an error
+          send_next_work_if_available(wrapped_ractor)
+        else
+          puts "Unknown message type received: #{message[:type]} from #{wrapped_ractor.name}"
+        end
+        # Update processed count for the loop condition
+        processed_count = @results.results.size + @results.errors.size
+      end
+
+      puts "Main loop finished."
+      puts "Final Aggregated Results: #{@results.inspect}"
+    end
+
+    private
+
+    # Helper method to send the next available work item to a specific Ractor.
+    def send_next_work_if_available(wrapped_ractor)
+      # Ensure the wrapped_ractor instance is valid and its underlying ractor is not closed
+      if wrapped_ractor && !wrapped_ractor.closed?
+        if !@work_queue.empty?
+          raw_input = @work_queue.pop # Get raw input data
+          # Create an instance of the client's Work class (e.g., MyWork)
+          work_item = @work_class.new(raw_input)
+          puts "Sending next work #{work_item.inspect} to Ractor: #{wrapped_ractor.name}"
+          wrapped_ractor.send(work_item) # Send the Work object
+          puts "Work sent to #{wrapped_ractor.name}."
+        else
+          puts "Work queue empty. Not sending new work to Ractor #{wrapped_ractor.name}."
+          # Consider closing the Ractor if the queue is empty and no more work is expected.
+          # wrapped_ractor.close
+          # @ractors_map.delete(wrapped_ractor.ractor)
+          # puts "Closed idle Ractor: #{wrapped_ractor.name}"
+        end
+      else
+        puts "Attempted to send work to an invalid or closed Ractor: #{wrapped_ractor&.name || 'unknown'}."
+        # Remove from map if found but closed
+        @ractors_map.delete(wrapped_ractor.ractor) if wrapped_ractor && @ractors_map.key?(wrapped_ractor.ractor)
+      end
+    end
+  end
+end

data/lib/fractor/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Fractor
+  # Fractor version
+  VERSION = "0.1.0"
+end

data/lib/fractor/work.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Fractor
+  # Base class for defining work items.
+  # Contains the input data for a worker.
+  class Work
+    attr_reader :input
+
+    def initialize(input)
+      @input = input
+    end
+
+    def to_s
+      "Work: #{@input}"
+    end
+  end
+end