fractor 0.1.3 → 0.1.6

data/lib/fractor/supervisor.rb

@@ -1,6 +1,12 @@
 # frozen_string_literal: true
 
+require "etc"
+require "timeout"
+
 module Fractor
+  # Custom exception for shutdown signal handling
+  class ShutdownSignal < StandardError; end
+
   # Supervises multiple WrappedRactors, distributes work, and aggregates results.
   class Supervisor
     attr_reader :work_queue, :workers, :results, :worker_pools
@@ -13,14 +19,17 @@ module Fractor
     def initialize(worker_pools: [], continuous_mode: false)
       @worker_pools = worker_pools.map do |pool_config|
         worker_class = pool_config[:worker_class]
-        num_workers = pool_config[:num_workers] || 2
+        num_workers = pool_config[:num_workers] || detect_num_workers
 
-        raise ArgumentError, "#{worker_class} must inherit from Fractor::Worker" unless worker_class < Fractor::Worker
+        unless worker_class < Fractor::Worker
+          raise ArgumentError,
+                "#{worker_class} must inherit from Fractor::Worker"
+        end
 
         {
           worker_class: worker_class,
           num_workers: num_workers,
-          workers: [] # Will hold the WrappedRactor instances
+          workers: [], # Will hold the WrappedRactor instances
         }
       end
 
@@ -32,12 +41,18 @@ module Fractor
       @continuous_mode = continuous_mode
       @running = false
       @work_callbacks = []
+      @wakeup_ractor = nil # Control ractor for unblocking select
+      @timer_thread = nil # Timer thread for periodic wakeup
+      @idle_workers = [] # Track workers waiting for work
     end
 
     # Adds a single work item to the queue.
     # The item must be an instance of Fractor::Work or a subclass.
     def add_work_item(work)
-      raise ArgumentError, "#{work.class} must be an instance of Fractor::Work" unless work.is_a?(Fractor::Work)
+      unless work.is_a?(Fractor::Work)
+        raise ArgumentError,
+              "#{work.class} must be an instance of Fractor::Work"
+      end
 
       @work_queue << work
       @total_work_count += 1
@@ -46,9 +61,6 @@ module Fractor
       puts "Work item added. Initial work count: #{@total_work_count}, Queue size: #{@work_queue.size}"
     end
 
-    # Alias for better naming
-    alias add_work_item add_work_item
-
     # Adds multiple work items to the queue.
     # Each item must be an instance of Fractor::Work or a subclass.
     def add_work_items(works)
@@ -65,6 +77,23 @@ module Fractor
 
     # Starts the worker Ractors for all worker pools.
     def start_workers
+      # Create a wakeup Ractor for unblocking Ractor.select
+      @wakeup_ractor = Ractor.new do
+        puts "Wakeup Ractor started" if ENV["FRACTOR_DEBUG"]
+        loop do
+          msg = Ractor.receive
+          puts "Wakeup Ractor received: #{msg.inspect}" if ENV["FRACTOR_DEBUG"]
+          if %i[wakeup shutdown].include?(msg)
+            Ractor.yield({ type: :wakeup, message: msg })
+            break if msg == :shutdown
+          end
+        end
+        puts "Wakeup Ractor shutting down" if ENV["FRACTOR_DEBUG"]
+      end
+
+      # Add wakeup ractor to the map with a special marker
+      @ractors_map[@wakeup_ractor] = :wakeup
+
       @worker_pools.each do |pool|
         worker_class = pool[:worker_class]
         num_workers = pool[:num_workers]
@@ -86,37 +115,65 @@ module Fractor
       puts "Workers started: #{@workers.size} active across #{@worker_pools.size} pools."
     end
 
-    # Sets up a signal handler for graceful shutdown (Ctrl+C).
+    # Sets up signal handlers for graceful shutdown.
+    # Handles SIGINT (Ctrl+C), SIGTERM (systemd/docker), and platform-specific status signals.
     def setup_signal_handler
-      # Store instance variables in local variables for the signal handler
-      workers_ref = @workers
+      # Universal signals (work on all platforms)
+      Signal.trap("INT") { handle_shutdown("SIGINT") }
+      Signal.trap("TERM") { handle_shutdown("SIGTERM") }
 
-      # Trap INT signal (Ctrl+C)
-      Signal.trap("INT") do
-        puts "\nCtrl+C received. Initiating immediate shutdown..." if ENV["FRACTOR_DEBUG"]
-
-        # Set running to false to break the main loop
-        @running = false
+      # Platform-specific status monitoring
+      setup_status_signal
+    end
 
-        puts "Sending shutdown message to all Ractors..." if ENV["FRACTOR_DEBUG"]
+    # Handles shutdown signal by mode (continuous vs batch)
+    def handle_shutdown(signal_name)
+      if @continuous_mode
+        puts "\n#{signal_name} received. Initiating graceful shutdown..." if ENV["FRACTOR_DEBUG"]
+        stop
+      else
+        puts "\n#{signal_name} received. Initiating immediate shutdown..." if ENV["FRACTOR_DEBUG"]
+        Thread.current.raise(ShutdownSignal, "Interrupted by #{signal_name}")
+      end
+    rescue Exception => e
+      puts "Error in signal handler: #{e.class}: #{e.message}" if ENV["FRACTOR_DEBUG"]
+      puts e.backtrace.join("\n") if ENV["FRACTOR_DEBUG"]
+      exit!(1)
+    end
 
-        # Send shutdown message to each worker Ractor
-        workers_ref.each do |w|
-          w.send(:shutdown)
-          puts "Sent shutdown to Ractor: #{w.name}" if ENV["FRACTOR_DEBUG"]
-        rescue StandardError => e
-          puts "Error sending shutdown to Ractor #{w.name}: #{e.message}" if ENV["FRACTOR_DEBUG"]
+    # Sets up platform-specific status monitoring signal
+    def setup_status_signal
+      if Gem.win_platform?
+        # Windows: Try SIGBREAK (Ctrl+Break) if available
+        begin
+          Signal.trap("BREAK") { print_status }
+        rescue ArgumentError
+          # SIGBREAK not supported on this Ruby version/platform
+          # Status monitoring unavailable on Windows
+        end
+      else
+        # Unix/Linux/macOS: Use SIGUSR1
+        begin
+          Signal.trap("USR1") { print_status }
+        rescue ArgumentError
+          # SIGUSR1 not supported on this platform
         end
-
-        puts "Exiting now." if ENV["FRACTOR_DEBUG"]
-        exit!(1) # Use exit! to exit immediately without running at_exit handlers
-      rescue Exception => e
-        puts "Error in signal handler: #{e.class}: #{e.message}" if ENV["FRACTOR_DEBUG"]
-        puts e.backtrace.join("\n") if ENV["FRACTOR_DEBUG"]
-        exit!(1)
       end
     end
 
+    # Prints current supervisor status
+    def print_status
+      puts "\n=== Fractor Supervisor Status ==="
+      puts "Mode: #{@continuous_mode ? 'Continuous' : 'Batch'}"
+      puts "Running: #{@running}"
+      puts "Workers: #{@workers.size}"
+      puts "Idle workers: #{@idle_workers.size}"
+      puts "Queue size: #{@work_queue.size}"
+      puts "Results: #{@results.results.size}"
+      puts "Errors: #{@results.errors.size}"
+      puts "================================\n"
+    end
+
     # Runs the main processing loop.
     def run
       setup_signal_handler
@@ -125,92 +182,174 @@ module Fractor
       @running = true
       processed_count = 0
 
-      # Main loop: Process events until conditions are met for termination
-      while @running && (@continuous_mode || processed_count < @total_work_count)
-        processed_count = @results.results.size + @results.errors.size
-
-        if ENV["FRACTOR_DEBUG"]
-          if @continuous_mode
-            puts "Continuous mode: Waiting for Ractor results. Processed: #{processed_count}, Queue size: #{@work_queue.size}"
-          else
-            puts "Waiting for Ractor results. Processed: #{processed_count}/#{@total_work_count}, Queue size: #{@work_queue.size}"
+      # Start timer thread for continuous mode to periodically check work sources
+      if @continuous_mode && !@work_callbacks.empty?
+        @timer_thread = Thread.new do
+          while @running
+            sleep(0.1) # Check work sources every 100ms
+            if @wakeup_ractor && @running
+              begin
+                @wakeup_ractor.send(:wakeup)
+              rescue StandardError => e
+                puts "Timer thread error sending wakeup: #{e.message}" if ENV["FRACTOR_DEBUG"]
+                break
+              end
+            end
           end
+          puts "Timer thread shutting down" if ENV["FRACTOR_DEBUG"]
         end
+      end
 
-        # Get active Ractor objects from the map keys
-        active_ractors = @ractors_map.keys
+      begin
+        # Main loop: Process events until conditions are met for termination
+        while @running && (@continuous_mode || processed_count < @total_work_count)
+          processed_count = @results.results.size + @results.errors.size
 
-        # Check for new work from callbacks if in continuous mode and queue is empty
-        if @continuous_mode && @work_queue.empty? && !@work_callbacks.empty?
-          @work_callbacks.each do |callback|
-            new_work = callback.call
-            add_work_items(new_work) if new_work && !new_work.empty?
+          if ENV["FRACTOR_DEBUG"]
+            if @continuous_mode
+              puts "Continuous mode: Waiting for Ractor results. Processed: #{processed_count}, Queue size: #{@work_queue.size}"
+            else
+              puts "Waiting for Ractor results. Processed: #{processed_count}/#{@total_work_count}, Queue size: #{@work_queue.size}"
+            end
           end
-        end
 
-        # Break if no active workers and queue is empty, but work remains (indicates potential issue)
-        if active_ractors.empty? && @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 ENV["FRACTOR_DEBUG"]
-          break
-        end
+          # Get active Ractor objects from the map keys
+          active_ractors = @ractors_map.keys
+
+          # Check for new work from callbacks if in continuous mode
+          if @continuous_mode && !@work_callbacks.empty?
+            @work_callbacks.each do |callback|
+              new_work = callback.call
+              if new_work && !new_work.empty?
+                add_work_items(new_work)
+                puts "Work source provided #{new_work.size} new items" if ENV["FRACTOR_DEBUG"]
+
+                # Try to send work to idle workers first
+                while !@work_queue.empty? && !@idle_workers.empty?
+                  worker = @idle_workers.shift
+                  if send_next_work_if_available(worker)
+                    puts "Sent work to idle worker #{worker.name}" if ENV["FRACTOR_DEBUG"]
+                  else
+                    # Worker couldn't accept work, don't re-add to idle list
+                  end
+                end
+              end
+            end
+          end
 
-        # In continuous mode, just wait if no active ractors but keep running
-        if active_ractors.empty?
-          break unless @continuous_mode
+          # Break if no active workers and queue is empty, but work remains (indicates potential issue)
+          if active_ractors.empty? && @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 ENV["FRACTOR_DEBUG"]
+            break
+          end
 
-          sleep(0.1) # Small delay to avoid CPU spinning
-          next
+          # In continuous mode, just wait if no active ractors but keep running
+          if active_ractors.empty?
+            break unless @continuous_mode
 
-        end
-
-        # Ractor.select blocks until a message is available from any active Ractor
-        ready_ractor_obj, message = Ractor.select(*active_ractors)
+            sleep(0.1) # Small delay to avoid CPU spinning
+            next
+          end
 
-        # 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." if ENV["FRACTOR_DEBUG"]
-          next
-        end
+          # Ractor.select blocks until a message is available from any active Ractor
+          # The wakeup ractor ensures we can unblock this call when needed
+          ready_ractor_obj, message = Ractor.select(*active_ractors)
+
+          # Check if this is the wakeup ractor
+          if ready_ractor_obj == @wakeup_ractor
+            puts "Wakeup signal received: #{message[:message]}" if ENV["FRACTOR_DEBUG"]
+            # Remove wakeup ractor from map if shutting down
+            if message[:message] == :shutdown
+              @ractors_map.delete(@wakeup_ractor)
+              @wakeup_ractor = nil
+            end
+            # Continue loop to check @running flag
+            next
+          end
 
-        puts "Selected Ractor: #{wrapped_ractor.name}, Message Type: #{message[:type]}" if ENV["FRACTOR_DEBUG"]
-
-        # Process the received message
-        case message[:type]
-        when :initialize
-          puts "Ractor initialized: #{message[:processor]}" if ENV["FRACTOR_DEBUG"]
-          # 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]}" if ENV["FRACTOR_DEBUG"]
-          @results.add_result(work_result)
-          if ENV["FRACTOR_DEBUG"]
-            puts "Result processed. Total processed: #{@results.results.size + @results.errors.size}"
-            puts "Aggregated Results: #{@results.inspect}" unless @continuous_mode
+          # 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." if ENV["FRACTOR_DEBUG"]
+            next
           end
-          # 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}" if ENV["FRACTOR_DEBUG"]
-          @results.add_result(error_result) # Add error to aggregator
-          if ENV["FRACTOR_DEBUG"]
-            puts "Error handled. Total processed: #{@results.results.size + @results.errors.size}"
-            puts "Aggregated Results (including errors): #{@results.inspect}" unless @continuous_mode
+
+          puts "Selected Ractor: #{wrapped_ractor.name}, Message Type: #{message[:type]}" if ENV["FRACTOR_DEBUG"]
+
+          # Process the received message
+          case message[:type]
+          when :initialize
+            puts "Ractor initialized: #{message[:processor]}" if ENV["FRACTOR_DEBUG"]
+            # Send work immediately upon initialization if available
+            if send_next_work_if_available(wrapped_ractor)
+              # Work was sent
+            else
+              # No work available, mark worker as idle
+              @idle_workers << wrapped_ractor unless @idle_workers.include?(wrapped_ractor)
+              puts "Worker #{wrapped_ractor.name} marked as idle" if ENV["FRACTOR_DEBUG"]
+            end
+          when :shutdown
+            puts "Ractor #{wrapped_ractor.name} acknowledged shutdown" if ENV["FRACTOR_DEBUG"]
+            # Remove from active ractors
+            @ractors_map.delete(ready_ractor_obj)
+          when :result
+            # The message[:result] should be a WorkResult object
+            work_result = message[:result]
+            puts "Completed work: #{work_result.inspect} in Ractor: #{message[:processor]}" if ENV["FRACTOR_DEBUG"]
+            @results.add_result(work_result)
+            if ENV["FRACTOR_DEBUG"]
+              puts "Result processed. Total processed: #{@results.results.size + @results.errors.size}"
+              puts "Aggregated Results: #{@results.inspect}" unless @continuous_mode
+            end
+            # Send next piece of work
+            if send_next_work_if_available(wrapped_ractor)
+              # Work was sent
+            else
+              # No work available, mark worker as idle
+              @idle_workers << wrapped_ractor unless @idle_workers.include?(wrapped_ractor)
+              puts "Worker #{wrapped_ractor.name} marked as idle after completing work" if ENV["FRACTOR_DEBUG"]
+            end
+          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}" if ENV["FRACTOR_DEBUG"]
+            @results.add_result(error_result) # Add error to aggregator
+            if ENV["FRACTOR_DEBUG"]
+              puts "Error handled. Total processed: #{@results.results.size + @results.errors.size}"
+              puts "Aggregated Results (including errors): #{@results.inspect}" unless @continuous_mode
+            end
+            # Send next piece of work even after an error
+            if send_next_work_if_available(wrapped_ractor)
+              # Work was sent
+            else
+              # No work available, mark worker as idle
+              @idle_workers << wrapped_ractor unless @idle_workers.include?(wrapped_ractor)
+              puts "Worker #{wrapped_ractor.name} marked as idle after error" if ENV["FRACTOR_DEBUG"]
+            end
+          else
+            puts "Unknown message type received: #{message[:type]} from #{wrapped_ractor.name}" if ENV["FRACTOR_DEBUG"]
           end
-          # 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}" if ENV["FRACTOR_DEBUG"]
+          # Update processed count for the loop condition
+          processed_count = @results.results.size + @results.errors.size
         end
-        # Update processed count for the loop condition
-        processed_count = @results.results.size + @results.errors.size
+
+        puts "Main loop finished." if ENV["FRACTOR_DEBUG"]
+      rescue ShutdownSignal => e
+        puts "Shutdown signal caught: #{e.message}" if ENV["FRACTOR_DEBUG"]
+        puts "Sending shutdown message to all Ractors..." if ENV["FRACTOR_DEBUG"]
+
+        # Send shutdown message to each worker Ractor
+        @workers.each do |w|
+          w.send(:shutdown)
+          puts "Sent shutdown to Ractor: #{w.name}" if ENV["FRACTOR_DEBUG"]
+        rescue StandardError => send_error
+          puts "Error sending shutdown to Ractor #{w.name}: #{send_error.message}" if ENV["FRACTOR_DEBUG"]
+        end
+
+        puts "Exiting due to shutdown signal." if ENV["FRACTOR_DEBUG"]
+        exit!(1) # Force exit immediately
       end
 
-      puts "Main loop finished." if ENV["FRACTOR_DEBUG"]
       return if @continuous_mode
 
       return unless ENV["FRACTOR_DEBUG"]
@@ -222,21 +361,53 @@ module Fractor
     def stop
       @running = false
       puts "Stopping supervisor..." if ENV["FRACTOR_DEBUG"]
+
+      # Wait for timer thread to finish if it exists
+      if @timer_thread&.alive?
+        @timer_thread.join(1) # Wait up to 1 second
+        puts "Timer thread stopped" if ENV["FRACTOR_DEBUG"]
+      end
+
+      # Signal the wakeup ractor first to unblock Ractor.select
+      if @wakeup_ractor
+        begin
+          @wakeup_ractor.send(:shutdown)
+          puts "Sent shutdown signal to wakeup ractor" if ENV["FRACTOR_DEBUG"]
+        rescue StandardError => e
+          puts "Error sending shutdown to wakeup ractor: #{e.message}" if ENV["FRACTOR_DEBUG"]
+        end
+      end
+
+      # Send shutdown signal to all workers
+      @workers.each do |w|
+        begin
+          w.send(:shutdown)
+        rescue StandardError
+          nil
+        end
+        puts "Sent shutdown signal to #{w.name}" if ENV["FRACTOR_DEBUG"]
+      end
     end
 
     private
 
+    # Detects the number of available processors on the system.
+    # Returns the number of processors, or 2 as a fallback if detection fails.
+    def detect_num_workers
+      num_processors = Etc.nprocessors
+      puts "Auto-detected #{num_processors} available processors" if ENV["FRACTOR_DEBUG"]
+      num_processors
+    rescue StandardError => e
+      puts "Failed to detect processors: #{e.message}. Using default of 2 workers." if ENV["FRACTOR_DEBUG"]
+      2
+    end
+
     # Helper method to send the next available work item to a specific Ractor.
+    # Returns true if work was sent, false otherwise.
     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?
-          work_item = @work_queue.pop # Now directly a Work object
-
-          puts "Sending next work #{work_item.inspect} to Ractor: #{wrapped_ractor.name}" if ENV["FRACTOR_DEBUG"]
-          wrapped_ractor.send(work_item) # Send the Work object
-          puts "Work sent to #{wrapped_ractor.name}." if ENV["FRACTOR_DEBUG"]
-        else
+        if @work_queue.empty?
           puts "Work queue empty. Not sending new work to Ractor #{wrapped_ractor.name}." if ENV["FRACTOR_DEBUG"]
           # In continuous mode, don't close workers as more work may come
           unless @continuous_mode
@@ -247,11 +418,23 @@ module Fractor
             #   puts "Closed idle Ractor: #{wrapped_ractor.name}"
             # end
           end
+          false
+        else
+          work_item = @work_queue.pop # Now directly a Work object
+
+          puts "Sending next work #{work_item.inspect} to Ractor: #{wrapped_ractor.name}" if ENV["FRACTOR_DEBUG"]
+          wrapped_ractor.send(work_item) # Send the Work object
+          puts "Work sent to #{wrapped_ractor.name}." if ENV["FRACTOR_DEBUG"]
+
+          # Remove from idle workers list since it's now busy
+          @idle_workers.delete(wrapped_ractor)
+          true
         end
       else
-        puts "Attempted to send work to an invalid or closed Ractor: #{wrapped_ractor&.name || "unknown"}." if ENV["FRACTOR_DEBUG"]
+        puts "Attempted to send work to an invalid or closed Ractor: #{wrapped_ractor&.name || 'unknown'}." if ENV["FRACTOR_DEBUG"]
         # Remove from map if found but closed
         @ractors_map.delete(wrapped_ractor.ractor) if wrapped_ractor && @ractors_map.key?(wrapped_ractor.ractor)
+        false
       end
     end
   end

data/lib/fractor/version.rb

@@ -2,5 +2,5 @@
 
 module Fractor
   # Fractor version
-  VERSION = "0.1.3"
+  VERSION = "0.1.6"
 end

data/lib/fractor/work_queue.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Fractor
+  # Thread-safe work queue for continuous mode applications.
+  # Provides a simple interface for adding work items and retrieving them
+  # in batches, with automatic integration with Fractor::Supervisor.
+  class WorkQueue
+    attr_reader :queue
+
+    def initialize
+      @queue = Thread::Queue.new
+      @mutex = Mutex.new
+    end
+
+    # Add a work item to the queue (thread-safe)
+    # @param work_item [Fractor::Work] The work item to add
+    # @return [void]
+    def <<(work_item)
+      unless work_item.is_a?(Fractor::Work)
+        raise ArgumentError,
+              "#{work_item.class} must be an instance of Fractor::Work"
+      end
+
+      @queue << work_item
+    end
+
+    # Retrieve multiple work items from the queue in a single operation
+    # @param max_items [Integer] Maximum number of items to retrieve
+    # @return [Array<Fractor::Work>] Array of work items (may be empty)
+    def pop_batch(max_items = 10)
+      items = []
+      max_items.times do
+        break if @queue.empty?
+
+        begin
+          items << @queue.pop(true)
+        rescue ThreadError
+          # Queue became empty between check and pop
+          break
+        end
+      end
+      items
+    end
+
+    # Check if the queue is empty
+    # @return [Boolean] true if the queue is empty
+    def empty?
+      @queue.empty?
+    end
+
+    # Get the current size of the queue
+    # @return [Integer] Number of items in the queue
+    def size
+      @queue.size
+    end
+
+    # Register this work queue as a work source with a supervisor
+    # @param supervisor [Fractor::Supervisor] The supervisor to register with
+    # @param batch_size [Integer] Number of items to retrieve per poll
+    # @return [void]
+    def register_with_supervisor(supervisor, batch_size: 10)
+      supervisor.register_work_source do
+        items = pop_batch(batch_size)
+        items.empty? ? nil : items
+      end
+    end
+  end
+end

data/lib/fractor/work_result.rb

@@ -28,7 +28,7 @@ module Fractor
       {
         result: @result,
         error: @error,
-        work: @work&.to_s # Use safe navigation for work
+        work: @work&.to_s, # Use safe navigation for work
       }
     end
   end

data/lib/fractor/worker.rb

@@ -10,7 +10,8 @@ module Fractor
     end
 
     def process(work)
-      raise NotImplementedError, "Subclasses must implement the 'process' method."
+      raise NotImplementedError,
+            "Subclasses must implement the 'process' method."
     end
   end
 end

data/lib/fractor/wrapped_ractor.rb

@@ -35,6 +35,8 @@ module Fractor
           # Handle shutdown message
           if work == :shutdown
             puts "Received shutdown message in Ractor #{name}, terminating..." if ENV["FRACTOR_DEBUG"]
+            # Yield a shutdown acknowledgment before terminating
+            Ractor.yield({ type: :shutdown, processor: name })
             break
           end
 
@@ -44,15 +46,23 @@ module Fractor
             # Process the work using the instantiated worker
             result = worker.process(work)
             puts "Sending result #{result.inspect} from Ractor #{name}" if ENV["FRACTOR_DEBUG"]
+            # Wrap the result in a WorkResult object if not already wrapped
+            work_result = if result.is_a?(Fractor::WorkResult)
+                            result
+                          else
+                            Fractor::WorkResult.new(result: result, work: work)
+                          end
             # Yield the result back
-            Ractor.yield({ type: :result, result: result, processor: name })
+            Ractor.yield({ type: :result, result: work_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")}" if ENV["FRACTOR_DEBUG"]
             # 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 })
+            Ractor.yield({ type: :error, result: error_result,
+                           processor: name })
           end
         end
       rescue Ractor::ClosedError

data/lib/fractor.rb

@@ -8,6 +8,8 @@ require_relative "fractor/work_result"
 require_relative "fractor/result_aggregator"
 require_relative "fractor/wrapped_ractor"
 require_relative "fractor/supervisor"
+require_relative "fractor/work_queue"
+require_relative "fractor/continuous_server"
 
 # Fractor: Function-driven Ractors framework
 module Fractor