fractor 0.1.4 → 0.1.7

data/lib/fractor/wrapped_ractor.rb

@@ -1,103 +1,70 @@
 # frozen_string_literal: true
 
 module Fractor
-  # Wraps a Ruby Ractor to manage a worker instance.
-  # Handles communication and error propagation.
+  # Base class for wrapped Ractors with shared functionality.
+  # Subclasses implement Ruby 3.x and Ruby 4.0+ specific communication patterns.
   class WrappedRactor
-    attr_reader :ractor, :name
+    attr_reader :ractor, :name, :worker_class
+
+    # Factory method to create the appropriate WrappedRactor implementation
+    # based on the current Ruby version.
+    #
+    # @param name [String] Name for the ractor
+    # @param worker_class [Class] Worker class to instantiate
+    # @param kwargs [Hash] Additional keyword arguments for subclass initialization
+    # @return [WrappedRactor] The appropriate subclass instance
+    def self.create(name, worker_class, **kwargs)
+      ruby_4_0 = Gem::Version.new(RUBY_VERSION) >= Gem::Version.new("4.0.0")
+      if ruby_4_0
+        WrappedRactor4.new(name, worker_class, **kwargs)
+      else
+        WrappedRactor3.new(name, worker_class, **kwargs)
+      end
+    end
 
-    # Initializes the WrappedRactor with a name and the Worker class to instantiate.
-    # The worker_class parameter allows flexibility in specifying the worker type.
+    # Initializes the WrappedRactor with a name and the Worker class.
+    #
+    # @param name [String] Name for the ractor
+    # @param worker_class [Class] Worker class to instantiate
     def initialize(name, worker_class)
       puts "Creating Ractor #{name} with worker #{worker_class}" if ENV["FRACTOR_DEBUG"]
       @name = name
-      @worker_class = worker_class # Store the worker class
-      @ractor = nil # Initialize ractor as nil
+      @worker_class = worker_class
+      @ractor = nil
     end
 
-    # Starts the underlying Ractor.
+    # Starts the underlying Ractor. Must be implemented by subclasses.
     def start
-      puts "Starting Ractor #{@name}" if ENV["FRACTOR_DEBUG"]
-      # 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}" if ENV["FRACTOR_DEBUG"]
-        # Yield an initialization message
-        Ractor.yield({ type: :initialize, processor: name })
-
-        # Instantiate the specific worker inside the Ractor
-        worker = worker_cls.new(name: name)
-
-        loop do
-          # Ractor.receive will block until a message is received
-          puts "Waiting for work in #{name}" if ENV["FRACTOR_DEBUG"]
-          work = Ractor.receive
-
-          # Handle shutdown message
-          if work == :shutdown
-            puts "Received shutdown message in Ractor #{name}, terminating..." if ENV["FRACTOR_DEBUG"]
-            break
-          end
-
-          puts "Received work #{work.inspect} in #{name}" if ENV["FRACTOR_DEBUG"]
-
-          begin
-            # Process the work using the instantiated worker
-            result = worker.process(work)
-            puts "Sending result #{result.inspect} from Ractor #{name}" if ENV["FRACTOR_DEBUG"]
-            # 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")}" 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 })
-          end
-        end
-      rescue Ractor::ClosedError
-        puts "Ractor #{name} closed." if ENV["FRACTOR_DEBUG"]
-      rescue StandardError => e
-        puts "Unexpected error in Ractor #{name}: #{e.message}\n#{e.backtrace.join("\n")}" if ENV["FRACTOR_DEBUG"]
-        # Optionally yield a critical error message if needed
-      ensure
-        puts "Ractor #{name} shutting down." if ENV["FRACTOR_DEBUG"]
-      end
-      puts "Ractor #{@name} instance created: #{@ractor}" if ENV["FRACTOR_DEBUG"]
+      raise NotImplementedError, "Subclasses must implement #start"
     end
 
-    # Sends work to the Ractor if it's active.
+    # Sends work to the Ractor. Must be implemented by subclasses.
+    #
+    # @param work [Fractor::Work] The work item to process
+    # @return [Boolean] true if sent successfully, false otherwise
     def send(work)
-      if @ractor
-        begin
-          @ractor.send(work)
-          true
-        rescue Exception => e
-          puts "Warning: Error sending work to Ractor #{@name}: #{e.message}" if ENV["FRACTOR_DEBUG"]
-          false
-        end
-      else
-        puts "Warning: Attempted to send work to nil Ractor #{@name}" if ENV["FRACTOR_DEBUG"]
-        false
-      end
+      raise NotImplementedError, "Subclasses must implement #send"
+    end
+
+    # Receives a message from the Ractor. Must be implemented by subclasses.
+    #
+    # @return [Hash, nil] The message received or nil
+    def receive_message
+      raise NotImplementedError, "Subclasses must implement #receive_message"
     end
 
     # Closes the Ractor.
-    # Ruby 3.0+ has different ways to terminate Ractors, we try the available methods
+    #
+    # @return [Boolean] true if closed successfully
     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
+        # Send a nil message to signal we're done
         begin
-          begin
-            @ractor.send(nil)
-          rescue StandardError
-            nil
-          end
+          @ractor.send(nil)
         rescue StandardError
-          # Ignore errors when sending nil
+          nil
         end
 
         # Mark as closed in our object
@@ -123,25 +90,33 @@ module Fractor
     end
 
     # Checks if the Ractor is closed or unavailable.
+    # Uses a timeout to avoid blocking on Windows Ruby 3.4 where
+    # Ractor#inspect can block if the ractor is waiting on receive.
+    #
+    # @return [Boolean] true if closed, false otherwise
     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}" if ENV["FRACTOR_DEBUG"]
+      # Use a timeout to avoid blocking indefinitely on Windows Ruby 3.4
+      result = Timeout.timeout(0.1) do
+        @ractor.inspect
+      rescue Timeout::Error
+        # Timeout means ractor is still running (not terminated)
+        "#<Ractor:blocked>"
+      end
+
+      if result.include?("terminated")
+        # If terminated, clean up our reference
         @ractor = nil
-        true
+        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}" if ENV["FRACTOR_DEBUG"]
+      @ractor = nil
+      true
     end
   end
 end

data/lib/fractor/wrapped_ractor3.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+require "timeout"
+require_relative "wrapped_ractor"
+require_relative "logger"
+
+module Fractor
+  # Ruby 3.x specific implementation of WrappedRactor.
+  # Uses Ractor.yield for sending messages back from workers.
+  class WrappedRactor3 < WrappedRactor
+    # Initializes the WrappedRactor3.
+    # The response_port parameter is accepted for API compatibility but not used in Ruby 3.x.
+    #
+    # @param name [String] Name for the ractor
+    # @param worker_class [Class] Worker class to instantiate
+    # @param response_port [Object, nil] Unused in Ruby 3.x (for API compatibility with Ruby 4.0)
+    def initialize(name, worker_class, response_port: nil)
+      super(name, worker_class)
+      # response_port is not used in Ruby 3.x
+    end
+
+    # Starts the underlying Ractor using Ractor.yield pattern.
+    def start
+      RactorLogger.info("Starting Ractor #{@name} (Ruby 3.x mode)",
+                        ractor_name: @name)
+
+      # Capture timeout value before entering ractor (Ractors can't access Fractor.config)
+      # Get class-level timeout, or fall back to default of nil (no timeout)
+      # Note: We avoid accessing Fractor.config from ractor creation context
+      class_level_timeout = @worker_class.worker_timeout
+
+      # Pass worker_class and timeout to the Ractor block
+      @ractor = Ractor.new(@name, @worker_class,
+                           class_level_timeout) do |name, worker_cls, timeout_val|
+        RactorLogger.debug(
+          "Ractor started with worker class #{worker_cls} and timeout #{timeout_val.inspect}", ractor_name: name
+        )
+        # Yield an initialization message
+        Ractor.yield({ type: :initialize, processor: name })
+
+        # Instantiate the specific worker inside the Ractor
+        # Pass timeout as an option only if it's not nil, to avoid accessing self.class from ractor
+        worker = if timeout_val.nil?
+                   worker_cls.new(name: name)
+                 else
+                   worker_cls.new(name: name, timeout: timeout_val)
+                 end
+
+        loop do
+          # Ractor.receive will block until a message is received
+          RactorLogger.debug("Waiting for work", ractor_name: name)
+          work = Ractor.receive
+
+          # Handle shutdown message
+          if work == :shutdown
+            RactorLogger.debug("Received shutdown message, terminating",
+                               ractor_name: name)
+            # Yield a shutdown acknowledgment before terminating
+            Ractor.yield({ type: :shutdown, processor: name })
+            break
+          end
+
+          RactorLogger.debug("Received work #{work.inspect}", ractor_name: name)
+
+          begin
+            # Get the timeout for this worker (nil means no timeout)
+            worker_timeout = worker.timeout
+
+            # Process the work with timeout if configured
+            # Note: Ruby's Timeout.timeout uses threads which don't work with Ractors.
+            # We measure execution time and raise timeout error afterward if exceeded.
+            result = if worker_timeout
+                       start_time = Time.now
+                       process_result = worker.process(work)
+                       elapsed = Time.now - start_time
+                       if elapsed > worker_timeout
+                         # Raise a timeout error after the fact
+                         # Note: This is a post-facto timeout check - the work has already completed
+                         raise Timeout::Error,
+                               "execution timed out after #{elapsed}s (limit: #{worker_timeout}s)"
+                       end
+
+                       process_result
+                     else
+                       worker.process(work)
+                     end
+
+            RactorLogger.debug("Sending result #{result.inspect}",
+                               ractor_name: name)
+            # 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: work_result,
+                           processor: name })
+          rescue Timeout::Error => e
+            # Handle timeout errors as retriable errors
+            RactorLogger.warn(
+              "Timed out after #{worker.timeout}s processing work #{work.inspect}", ractor_name: name
+            )
+            error_result = Fractor::WorkResult.new(
+              error: "Worker timeout: #{e.message}",
+              work: work,
+              error_category: :timeout,
+            )
+            Ractor.yield({ type: :error, result: error_result,
+                           processor: name })
+          rescue StandardError => e
+            # Handle errors during processing
+            RactorLogger.error("Error processing work #{work.inspect}",
+                               ractor_name: name, exception: e)
+            # 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
+        RactorLogger.debug("Ractor closed", ractor_name: @name)
+      rescue StandardError => e
+        RactorLogger.error("Unexpected error", ractor_name: @name, exception: e)
+      ensure
+        RactorLogger.debug("Ractor shutting down", ractor_name: @name)
+      end
+      RactorLogger.debug("Ractor instance created: #{@ractor}",
+                         ractor_name: @name)
+    end
+
+    # Sends work to the Ractor.
+    #
+    # @param work [Fractor::Work] The work item to process
+    # @return [Boolean] true if sent successfully, false otherwise
+    def send(work)
+      if @ractor
+        begin
+          @ractor.send(work)
+          true
+        rescue Exception => e
+          RactorLogger.warn("Error sending work to Ractor: #{e.message}",
+                            ractor_name: @name)
+          false
+        end
+      else
+        RactorLogger.warn("Attempted to send work to nil Ractor",
+                          ractor_name: @name)
+        false
+      end
+    end
+
+    # Receives a message from the Ractor using Ractor.take.
+    #
+    # @return [Hash, nil] The message received or nil
+    def receive_message
+      @ractor&.take
+    end
+  end
+end

data/lib/fractor/wrapped_ractor4.rb

@@ -0,0 +1,242 @@
+# frozen_string_literal: true
+
+require "timeout"
+require_relative "wrapped_ractor"
+require_relative "logger"
+
+module Fractor
+  # Ruby 4.0+ specific implementation of WrappedRactor.
+  # Uses Ractor::Port for communication - main ractor creates response ports
+  # and passes them to workers when sending work.
+  class WrappedRactor4 < WrappedRactor
+    attr_reader :response_port
+
+    # Initializes the WrappedRactor with a name, worker class, and response port.
+    #
+    # @param name [String] Name for the ractor
+    # @param worker_class [Class] Worker class to instantiate
+    # @param response_port [Ractor::Port, nil] The port to receive responses on (created by main ractor)
+    def initialize(name, worker_class, response_port: nil)
+      super(name, worker_class)
+      @response_port = response_port
+    end
+
+    # Sets the response port for this worker.
+    #
+    # @param port [Ractor::Port] The port to receive responses on
+    def response_port=(port)
+      @response_port = port
+    end
+
+    # Starts the underlying Ractor using the port-based pattern.
+    # In Ruby 4.0:
+    # - Main ractor creates response ports (one per worker)
+    # - Main ractor sends [work, response_port] to workers
+    # - Workers receive work and response_port, send results back via response_port
+    def start
+      RactorLogger.info("Starting Ractor #{@name} (Ruby 4.0 mode)",
+                        ractor_name: @name)
+
+      # Capture timeout value before entering ractor (Ractors can't access Fractor.config)
+      # Get class-level timeout, or fall back to default of nil (no timeout)
+      # Note: We avoid accessing Fractor.config from ractor creation context
+      class_level_timeout = @worker_class.worker_timeout
+
+      # In Ruby 4.0, workers don't create their own ports
+      # They receive response_port from main ractor when work is sent
+      @ractor = Ractor.new(@name, @worker_class,
+                           class_level_timeout) do |name, worker_cls, timeout_val|
+        RactorLogger.debug(
+          "Ractor started with worker class #{worker_cls} and timeout #{timeout_val.inspect}", ractor_name: name
+        )
+
+        # Instantiate the specific worker inside the Ractor
+        # Pass timeout as an option only if it's not nil, to avoid accessing self.class from ractor
+        worker = if timeout_val.nil?
+                   worker_cls.new(name: name)
+                 else
+                   worker_cls.new(name: name, timeout: timeout_val)
+                 end
+
+        # Main message processing loop
+        loop do
+          # Receive work from the main ractor (blocks until message available)
+          # In Ruby 4.0, main sends [work, response_port]
+          received = Ractor.receive
+          RactorLogger.debug("Received #{received.inspect}", ractor_name: name)
+
+          # Handle shutdown message
+          if received == :shutdown
+            RactorLogger.debug("Received shutdown message, terminating",
+                               ractor_name: name)
+            break
+          end
+
+          # Extract work and response_port
+          # Main should send [work, response_port]
+          if received.is_a?(Array) && received.size == 2
+            work, response_port = received
+          else
+            # Legacy format for initialization or other messages
+            work = received
+            response_port = nil
+          end
+
+          # Handle initialize message (for backwards compatibility during startup)
+          if work.is_a?(Hash) && work[:type] == :initialize
+            RactorLogger.debug("Worker initialized", ractor_name: name)
+            next
+          end
+
+          begin
+            # Get the timeout for this worker (nil means no timeout)
+            worker_timeout = worker.timeout
+
+            # Process the work with timeout if configured
+            # Note: Ruby's Timeout.timeout uses threads which don't work with Ractors.
+            # We measure execution time and raise timeout error afterward if exceeded.
+            result = if worker_timeout
+                       start_time = Time.now
+                       process_result = worker.process(work)
+                       elapsed = Time.now - start_time
+                       if elapsed > worker_timeout
+                         # Raise a timeout error after the fact
+                         # Note: This is a post-facto timeout check - the work has already completed
+                         raise Timeout::Error,
+                               "execution timed out after #{elapsed}s (limit: #{worker_timeout}s)"
+                       end
+
+                       process_result
+                     else
+                       worker.process(work)
+                     end
+
+            RactorLogger.debug("Sending result #{result.inspect}",
+                               ractor_name: name)
+
+            # 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
+
+            # Send the result back through the response port
+            if response_port
+              response_port << { type: :result, result: work_result,
+                                 processor: name }
+            else
+              RactorLogger.warn("No response port available, result lost",
+                                ractor_name: name)
+            end
+          rescue Timeout::Error => e
+            # Handle timeout errors as retriable errors
+            RactorLogger.warn(
+              "Timed out after #{worker.timeout}s processing work #{work.inspect}", ractor_name: name
+            )
+            error_result = Fractor::WorkResult.new(
+              error: "Worker timeout: #{e.message}",
+              work: work,
+              error_category: :timeout,
+            )
+            if response_port
+              response_port << { type: :error, result: error_result,
+                                 processor: name }
+            end
+          rescue StandardError => e
+            # Handle errors during processing
+            RactorLogger.error("Error processing work #{work.inspect}",
+                               ractor_name: name, exception: e)
+
+            # Send an error message back through the response port
+            # Ensure the original work object is included in the error result
+            error_result = Fractor::WorkResult.new(error: e.message, work: work)
+            if response_port
+              response_port << { type: :error, result: error_result,
+                                 processor: name }
+            end
+          end
+        end
+      rescue Ractor::ClosedError
+        RactorLogger.debug("Ractor closed", ractor_name: name)
+      rescue StandardError => e
+        RactorLogger.error("Unexpected error", ractor_name: name, exception: e)
+      ensure
+        RactorLogger.debug("Ractor shutting down", ractor_name: name)
+      end
+      RactorLogger.debug("Ractor instance created", ractor_name: name)
+    end
+    RactorLogger.debug("Ractor #{@ractor} started", ractor_name: @name)
+
+    # Sends work to the Ractor.
+    # In Ruby 4.0, sends [work, response_port] so worker can reply back.
+    # Special case: sends just :shutdown for shutdown messages.
+    #
+    # @param work [Fractor::Work, Symbol] The work item to process, or :shutdown
+    # @return [Boolean] true if sent successfully, false otherwise
+    def send(work)
+      if @ractor
+        begin
+          # In Ruby 4.0, send [work, response_port] so worker can reply
+          # Special case: shutdown is sent as a symbol, not an array
+          if work == :shutdown
+            @ractor.send(:shutdown)
+          else
+            @ractor.send([work, @response_port])
+          end
+          true
+        rescue Exception => e
+          RactorLogger.warn("Error sending work to Ractor: #{e.message}",
+                            ractor_name: @name)
+          false
+        end
+      else
+        RactorLogger.warn("Attempted to send work to nil Ractor",
+                          ractor_name: @name)
+        false
+      end
+    end
+
+    # Receives a message from the Ractor.
+    # In Ruby 4.0, messages come through response ports in the main loop.
+    # This method is kept for backwards compatibility with tests.
+    #
+    # Note: In Ruby 4.0, this will block if no message is available.
+    # The test should either skip this or ensure a message was sent first.
+    #
+    # @return [Hash, nil] The message received or nil
+    def receive_message
+      # In Ruby 4.0, we receive through the response_port
+      # Try to receive with a small timeout to avoid blocking indefinitely
+      return nil unless @response_port
+
+      # Use a non-blocking receive attempt
+      # In Ruby 4.0, if the port is empty, this would block
+      # For test compatibility, we return nil if no message is available
+      @response_port.receive
+    rescue Ractor::ClosedError, Ractor::Error
+      nil
+    end
+
+    # Closes the Ractor and its response port.
+    # In Ruby 4.0, we need to explicitly close the response port
+    # to prevent Ractor.select from hanging.
+    #
+    # @return [Boolean] true if closed successfully
+    def close
+      # Close the response port first
+      if @response_port
+        begin
+          # Send nil through the port to signal it's closing
+          @response_port.send(nil) if @response_port.respond_to?(:send)
+        rescue StandardError
+          # Port may already be closed
+        end
+        @response_port = nil
+      end
+
+      # Then close the underlying ractor
+      super
+    end
+  end
+end