ractor-wrapper 0.3.0 → 0.4.0

data/lib/ractor/wrapper.rb

@@ -1,7 +1,8 @@
 # frozen_string_literal: true
 
 ##
-# See ruby-doc.org for info on Ractors.
+# See https://docs.ruby-lang.org/en/4.0/language/ractor_md.html for info on
+# Ractors.
 #
 class Ractor
   ##
@@ -98,7 +99,7 @@ class Ractor
   #
   #     # Create a wrapper around the database. A SQLite3::Database object
   #     # cannot be moved between Ractors, so we configure the wrapper to run
-  #     # in the current Ractor. You can also configure it to run multiple
+  #     # in the current Ractor. We can also configure it to run multiple
   #     # worker threads because the database object itself is thread-safe.
   #     wrapper = Ractor::Wrapper.new(db, use_current_ractor: true, threads: 2)
   #
@@ -111,17 +112,16 @@ class Ractor
   #     rows = wrapper.stub.execute("select * from numbers")
   #
   #     # Here, we start two Ractors, and pass the stub to each one. The
-  #     # wrapper's two worker threads will handle the requests in the order
-  #     # received.
-  #     r1 = Ractor.new(wrapper.stub) do |db_stub|
+  #     # wrapper's worker threads will handle the requests concurrently.
+  #     r1 = Ractor.new(wrapper.stub) do |stub|
   #       5.times do
-  #         rows = db_stub.execute("select * from numbers")
+  #         stub.execute("select * from numbers")
   #       end
   #       :ok
   #     end
-  #     r2 = Ractor.new(wrapper.stub) do |db_stub|
+  #     r2 = Ractor.new(wrapper.stub) do |stub|
   #       5.times do
-  #         rows = db_stub.execute("select * from numbers")
+  #         stub.execute("select * from numbers")
   #       end
   #       :ok
   #     end
@@ -138,7 +138,7 @@ class Ractor
   #     # When running a wrapper with :use_current_ractor, you do not need to
   #     # recover the object, because it was never moved. The recover_object
   #     # method is not available.
-  #     #     db2 = wrapper.recover_object  # <= raises Ractor::Error
+  #     #     db2 = wrapper.recover_object  # <= raises Ractor::Wrapper::Error
   #
   # ## Features
   #
@@ -172,6 +172,22 @@ class Ractor
   #     through a wrapper.
   #
   class Wrapper
+    ##
+    # Base class for errors raised by {Ractor::Wrapper}.
+    #
+    class Error < ::Ractor::Error; end
+
+    ##
+    # Raised when a {Ractor::Wrapper} server has crashed unexpectedly.
+    #
+    class CrashedError < Error; end
+
+    ##
+    # Raised when calling a method on a {Ractor::Wrapper} whose server has
+    # stopped and is no longer accepting calls.
+    #
+    class StoppedError < Error; end
+
     ##
     # A stub that forwards calls to a wrapper.
     #
@@ -206,234 +222,341 @@ class Ractor
     end
 
     ##
-    # Settings for a method call. Specifies how a method's arguments and
-    # return value are communicated (i.e. copy or move semantics.)
+    # Configuration for a {Ractor::Wrapper}. An instance of this class is
+    # yielded by {Ractor::Wrapper#initialize} if a block is provided. Any
+    # settings made to the Configuration before the block returns take
+    # effect when the Wrapper is constructed.
     #
-    class MethodSettings
-      # @private
-      def initialize(move_data: false,
-                     move_arguments: nil,
-                     move_results: nil,
-                     move_block_arguments: nil,
-                     move_block_results: nil,
-                     execute_blocks_in_place: nil)
-        @move_arguments = interpret_setting(move_arguments, move_data)
-        @move_results = interpret_setting(move_results, move_data)
-        @move_block_arguments = interpret_setting(move_block_arguments, move_data)
-        @move_block_results = interpret_setting(move_block_results, move_data)
-        @execute_blocks_in_place = interpret_setting(execute_blocks_in_place, false)
-        freeze
+    class Configuration
+      ##
+      # Set the name of the wrapper. This is shown in logging and is also
+      # used as the name of the wrapping Ractor.
+      #
+      # @param value [String, nil]
+      #
+      def name=(value)
+        @name = value ? value.to_s.freeze : nil
       end
 
       ##
-      # @return [Boolean] Whether to move arguments
+      # Enable or disable internal debug logging.
       #
-      def move_arguments?
-        @move_arguments
+      # @param value [Boolean]
+      #
+      def enable_logging=(value)
+        @enable_logging = value ? true : false
       end
 
       ##
-      # @return [Boolean] Whether to move return values
+      # Set the number of worker threads. If the underlying object is
+      # thread-safe, a value of 2 or more allows concurrent calls. Leave at
+      # the default of 0 to handle calls sequentially without worker threads.
+      #
+      # @param value [Integer]
       #
-      def move_results?
-        @move_results
+      def threads=(value)
+        value = value.to_i
+        value = 0 if value.negative?
+        @threads = value
       end
 
       ##
-      # @return [Boolean] Whether to move arguments to a block
+      # If set to true, the wrapper server runs as Thread(s) inside the
+      # current Ractor rather than spawning a new isolated Ractor. Use this
+      # for objects that cannot be moved between Ractors.
+      #
+      # @param value [Boolean]
       #
-      def move_block_arguments?
-        @move_block_arguments
+      def use_current_ractor=(value)
+        @use_current_ractor = value ? true : false
       end
 
       ##
-      # @return [Boolean] Whether to move block results
+      # Configure how argument and return values are communicated for the given
+      # method.
+      #
+      # In general, the following values are recognized for the data-moving
+      # settings:
+      #
+      # * `:copy` - Method arguments or return values that are not shareable,
+      #   are *deep copied* when communicated between the caller and the object.
+      # * `:move` - Method arguments or return values that are not shareable,
+      #   are *moved* when communicated between the caller and the object. This
+      #   means they are no longer available to the source; that is, the caller
+      #   can no longer access objects that were moved to method arguments, and
+      #   the wrapped object can no longer access objects that were used as
+      #   return values.
+      # * `:void` - This option is available for return values and block
+      #   results. It disables return values for the given method, and is
+      #   intended to avoid copying or moving objects that are not intended to
+      #   be return values. The recipient will receive `nil`.
+      #
+      # The following settings are recognized for the `block_environment`
+      # setting:
       #
-      def move_block_results?
-        @move_block_results
+      # * `:caller` - Blocks are executed in the caller's context. This means
+      #   the wrapper sends a message back to the caller to execute the block
+      #   in its original context. This means the block will have access to its
+      #   lexical scope and any other data available to the calling Ractor.
+      # * `:wrapped` - Blocks are executed directly in the wrapped object's
+      #   context. This does not require any communication, but it means the
+      #   block is removed from the caller's environment and does not have
+      #   access to the caller's lexical scope or Ractor-accessible data.
+      #
+      # All settings are optional. If not provided, they will fall back to a
+      # default. If you are configuring a particular method, by specifying the
+      # `method_name` argument, any unspecified setting will fall back to the
+      # method default settings (which you can set by omitting the method name.)
+      # If you are configuring the method default settings, by omitting the
+      # `method_name` argument, unspecified settings will fall back to `:copy`
+      # for the data movement settings, and `:caller` for the
+      # `block_environment` setting.
+      #
+      # @param method_name [Symbol,nil] The name of the method being configured,
+      #     or `nil` to set defaults for all methods not configured explicitly.
+      # @param arguments [:move,:copy] How to communicate method arguments.
+      # @param results [:move,:copy,:void] How to communicate method return
+      #     values.
+      # @param block_arguments [:move,:copy] How to communicate block arguments.
+      # @param block_results [:move,:copy,:void] How to communicate block
+      #     result values.
+      # @param block_environment [:caller,:wrapped] How to execute blocks, and
+      #     what scope blocks have access to.
+      #
+      def configure_method(method_name = nil,
+                           arguments: nil,
+                           results: nil,
+                           block_arguments: nil,
+                           block_results: nil,
+                           block_environment: nil)
+        method_name = method_name.to_sym unless method_name.nil?
+        @method_settings[method_name] =
+          MethodSettings.new(arguments: arguments,
+                             results: results,
+                             block_arguments: block_arguments,
+                             block_results: block_results,
+                             block_environment: block_environment)
+        self
       end
 
       ##
-      # @return [Boolean] Whether to call blocks in-place
+      # @private
+      # Return the name of the wrapper.
+      #
+      # @return [String, nil]
+      #
+      attr_reader :name
+
+      ##
+      # @private
+      # Return whether logging is enabled.
+      #
+      # @return [Boolean]
+      #
+      attr_reader :enable_logging
+
+      ##
+      # @private
+      # Return the number of worker threads.
+      #
+      # @return [Integer]
+      #
+      attr_reader :threads
+
+      ##
+      # @private
+      # Return whether the wrapper runs in the current Ractor.
+      #
+      # @return [Boolean]
+      #
+      attr_reader :use_current_ractor
+
+      ##
+      # @private
+      # Resolve the method settings by filling in the defaults for all fields
+      # not explicitly set, and return the final settings keyed by method name.
+      # The `nil` key will contain defaults for method names not explicitly
+      # configured. This hash will be frozen and shareable.
       #
-      def execute_blocks_in_place?
-        @execute_blocks_in_place
+      # @return [Hash{(Symbol,nil)=>MethodSettings}]
+      #
+      def final_method_settings
+        fallback = MethodSettings.new(arguments: :copy, results: :copy,
+                                      block_arguments: :copy, block_results: :copy,
+                                      block_environment: :caller)
+        defaults = MethodSettings.with_fallback(@method_settings[nil], fallback)
+        results = {nil => defaults}
+        @method_settings.each do |name, settings|
+          next if name.nil?
+          results[name] = MethodSettings.with_fallback(settings, defaults)
+        end
+        results.freeze
       end
 
-      private
+      ##
+      # @private
+      # Create an empty configuration.
+      #
+      def initialize
+        @method_settings = {}
+        configure_method(arguments: nil,
+                         results: nil,
+                         block_arguments: nil,
+                         block_results: nil,
+                         block_environment: nil)
+      end
+    end
 
-      def interpret_setting(setting, default)
-        if setting.nil?
-          default ? true : false
-        else
-          setting ? true : false
+    ##
+    # Settings for a method call. Specifies how a method's arguments and
+    # return value are communicated (i.e. copy or move semantics.)
+    #
+    class MethodSettings
+      # @private
+      def initialize(arguments: nil,
+                     results: nil,
+                     block_arguments: nil,
+                     block_results: nil,
+                     block_environment: nil)
+        unless [nil, :copy, :move].include?(arguments)
+          raise ::ArgumentError, "Unknown `arguments`: #{arguments.inspect} (must be :copy or :move)"
+        end
+        unless [nil, :copy, :move, :void].include?(results)
+          raise ::ArgumentError, "Unknown `results`: #{results.inspect} (must be :copy, :move, or :void)"
+        end
+        unless [nil, :copy, :move].include?(block_arguments)
+          raise ::ArgumentError, "Unknown `block_arguments`: #{block_arguments.inspect} (must be :copy or :move)"
+        end
+        unless [nil, :copy, :move, :void].include?(block_results)
+          raise ::ArgumentError, "Unknown `block_results`: #{block_results.inspect} (must be :copy, :move, or :void)"
+        end
+        unless [nil, :caller, :wrapped].include?(block_environment)
+          raise ::ArgumentError,
+                "Unknown `block_environment`: #{block_environment.inspect} (must be :caller or :wrapped)"
         end
+        @arguments = arguments
+        @results = results
+        @block_arguments = block_arguments
+        @block_results = block_results
+        @block_environment = block_environment
+        freeze
+      end
+
+      ##
+      # @return [:copy,:move] How to communicate method arguments
+      # @return [nil] if not set (will not happen in final settings)
+      #
+      attr_reader :arguments
+
+      ##
+      # @return [:copy,:move,:void] How to communicate method return values
+      # @return [nil] if not set (will not happen in final settings)
+      #
+      attr_reader :results
+
+      ##
+      # @return [:copy,:move] How to communicate arguments to a block
+      # @return [nil] if not set (will not happen in final settings)
+      #
+      attr_reader :block_arguments
+
+      ##
+      # @return [:copy,:move,:void] How to communicate block results
+      # @return [nil] if not set (will not happen in final settings)
+      #
+      attr_reader :block_results
+
+      ##
+      # @return [:caller,:wrapped] What environment blocks execute in
+      # @return [nil] if not set (will not happen in final settings)
+      #
+      attr_reader :block_environment
+
+      # @private
+      def self.with_fallback(settings, fallback)
+        new(
+          arguments: settings.arguments || fallback.arguments,
+          results: settings.results || fallback.results,
+          block_arguments: settings.block_arguments || fallback.block_arguments,
+          block_results: settings.block_results || fallback.block_results,
+          block_environment: settings.block_environment || fallback.block_environment
+        )
       end
     end
 
     ##
     # Create a wrapper around the given object.
     #
-    # If you pass an optional block, the wrapper itself will be yielded to it,
-    # at which time you can set additional configuration options. In
-    # particular, method-specific configuration must be set in this block.
-    # The configuration is frozen once the object is constructed.
+    # If you pass an optional block, a {Ractor::Wrapper::Configuration} object
+    # will be yielded to it, allowing additional configuration before the wrapper
+    # starts. In particular, per-method configuration must be set in this block.
+    # Block-provided settings override keyword arguments.
+    #
+    # See {Configuration} for more information about the method communication
+    # and block settings.
     #
     # @param object [Object] The non-shareable object to wrap.
     # @param use_current_ractor [boolean] If true, the wrapper is run in a
     #     thread in the current Ractor instead of spawning a new Ractor (the
     #     default behavior). This option can be used if the wrapped object
-    #     cannot be moved or must run in the main Ractor.
-    # @param name [String] A name for this wrapper. Used during logging.
+    #     cannot be moved or must run in the main Ractor. Can also be set via
+    #     the configuration block.
+    # @param name [String] A name for this wrapper. Used during logging. Can
+    #     also be set via the configuration block. Defaults to the object_id.
     # @param threads [Integer] The number of worker threads to run.
     #     Defaults to 0, which causes the wrapper to run sequentially without
-    #     spawning workers.
-    # @param move_data [boolean] If true, all communication will by default
-    #     move instead of copy arguments and return values. Default is false.
-    #     This setting can be overridden by other `:move_*` settings.
-    # @param move_arguments [boolean] If true, all arguments will be moved
-    #     instead of copied by default. If not set, uses the `:move_data`
-    #     setting.
-    # @param move_results [boolean] If true, return values are moved instead of
-    #     copied by default. If not set, uses the `:move_data` setting.
-    # @param move_block_arguments [boolean] If true, arguments to blocks are
-    #     moved instead of copied by default. If not set, uses the `:move_data`
-    #     setting.
-    # @param move_block_results [boolean] If true, result values from blocks
-    #     are moved instead of copied by default. If not set, uses the
-    #     `:move_data` setting.
-    # @param execute_blocks_in_place [boolean] If true, blocks passed to
-    #     methods are made shareable and passed into the wrapper to be executed
-    #     in the wrapped environment. If false (the default), blocks are
-    #     replaced by a proc that passes messages back out to the caller and
-    #     executes the block in the caller's environment.
+    #     spawning workers. Can also be set via the configuration block.
+    # @param arguments [:move,:copy] How to communicate method arguments by
+    #     default. If not specified, defaults to `:copy`.
+    # @param results [:move,:copy,:void] How to communicate method return
+    #     values by default. If not specified, defaults to `:copy`.
+    # @param block_arguments [:move,:copy] How to communicate block arguments
+    #     by default. If not specified, defaults to `:copy`.
+    # @param block_results [:move,:copy,:void] How to communicate block result
+    #     values by default. If not specified, defaults to `:copy`.
+    # @param block_environment [:caller,:wrapped] How to execute blocks, and
+    #     what scope blocks have access to. If not specified, defaults to
+    #     `:caller`.
     # @param enable_logging [boolean] Set to true to enable logging. Default
-    #     is false.
+    #     is false. Can also be set via the configuration block.
+    # @yield [config] An optional configuration block.
+    # @yieldparam config [Ractor::Wrapper::Configuration]
     #
     def initialize(object,
                    use_current_ractor: false,
                    name: nil,
                    threads: 0,
-                   move_data: false,
-                   move_arguments: nil,
-                   move_results: nil,
-                   move_block_arguments: nil,
-                   move_block_results: nil,
-                   execute_blocks_in_place: nil,
+                   arguments: nil,
+                   results: nil,
+                   block_arguments: nil,
+                   block_results: nil,
+                   block_environment: nil,
                    enable_logging: false)
       raise ::Ractor::MovedError, "cannot wrap a moved object" if ::Ractor::MovedObject === object
 
-      @method_settings = {}
-      self.name = name || object_id.to_s
-      self.enable_logging = enable_logging
-      self.threads = threads
-      configure_method(move_data: move_data,
-                       move_arguments: move_arguments,
-                       move_results: move_results,
-                       move_block_arguments: move_block_arguments,
-                       move_block_results: move_block_results,
-                       execute_blocks_in_place: execute_blocks_in_place)
-      yield self if block_given?
-      @method_settings.freeze
-
-      if use_current_ractor
+      config = Configuration.new
+      config.name = name || object_id.to_s
+      config.enable_logging = enable_logging
+      config.threads = threads
+      config.use_current_ractor = use_current_ractor
+      config.configure_method(arguments: arguments,
+                              results: results,
+                              block_arguments: block_arguments,
+                              block_results: block_results,
+                              block_environment: block_environment)
+      yield config if block_given?
+
+      @name = config.name
+      @enable_logging = config.enable_logging
+      @threads = config.threads
+      @method_settings = config.final_method_settings
+      @stub = Stub.new(self)
+
+      if config.use_current_ractor
         setup_local_server(object)
       else
         setup_isolated_server(object)
       end
-      @stub = Stub.new(self)
-
-      freeze
-    end
-
-    ##
-    # Set the number of threads to run in the wrapper. If the underlying object
-    # is thread-safe, setting a value of 2 or more allows concurrent calls to
-    # it. If the underlying object is not thread-safe, you should leave this
-    # set to its default of 0, which disables worker threads and handles all
-    # calls sequentially.
-    #
-    # This method can be called only during an initialization block.
-    # All settings are frozen once the wrapper is active.
-    #
-    # @param value [Integer]
-    #
-    def threads=(value)
-      value = value.to_i
-      value = 0 if value.negative?
-      @threads = value
-    end
-
-    ##
-    # Enable or disable internal debug logging.
-    #
-    # This method can be called only during an initialization block.
-    # All settings are frozen once the wrapper is active.
-    #
-    # @param value [Boolean]
-    #
-    def enable_logging=(value)
-      @enable_logging = value ? true : false
-    end
-
-    ##
-    # Set the name of this wrapper. This is shown in logging, and is also used
-    # as the name of the wrapping Ractor.
-    #
-    # This method can be called only during an initialization block.
-    # All settings are frozen once the wrapper is active.
-    #
-    # @param value [String, nil]
-    #
-    def name=(value)
-      @name = value ? value.to_s.freeze : nil
-    end
-
-    ##
-    # Configure the move semantics for the given method (or the default
-    # settings if no method name is given.) That is, determine whether
-    # arguments, return values, and/or exceptions are copied or moved when
-    # communicated with the wrapper. By default, all objects are copied.
-    #
-    # This method can be called only during an initialization block.
-    # All settings are frozen once the wrapper is active.
-    #
-    # @param method_name [Symbol, nil] The name of the method being configured,
-    #     or `nil` to set defaults for all methods not configured explicitly.
-    # @param move_data [boolean] If true, communication for this method will
-    #     move instead of copy arguments and return values. Default is false.
-    #     This setting can be overridden by other `:move_*` settings.
-    # @param move_arguments [boolean] If true, arguments for this method are
-    #     moved instead of copied. If not set, uses the `:move_data` setting.
-    # @param move_results [boolean] If true, return values for this method are
-    #     moved instead of copied. If not set, uses the `:move_data` setting.
-    # @param move_block_arguments [boolean] If true, arguments to blocks passed
-    #     to this method are moved instead of copied. If not set, uses the
-    #     `:move_data` setting.
-    # @param move_block_results [boolean] If true, result values from blocks
-    #     passed to this method are moved instead of copied. If not set, uses
-    #     the `:move_data` setting.
-    # @param execute_blocks_in_place [boolean] If true, blocks passed to this
-    #     method are made shareable and passed into the wrapper to be executed
-    #     in the wrapped environment. If false (the default), blocks are
-    #     replaced by a proc that passes messages back out to the caller and
-    #     executes the block in the caller's environment.
-    #
-    def configure_method(method_name = nil,
-                         move_data: false,
-                         move_arguments: nil,
-                         move_results: nil,
-                         move_block_arguments: nil,
-                         move_block_results: nil,
-                         execute_blocks_in_place: nil)
-      method_name = method_name.to_sym unless method_name.nil?
-      @method_settings[method_name] =
-        MethodSettings.new(move_data: move_data,
-                           move_arguments: move_arguments,
-                           move_results: move_results,
-                           move_block_arguments: move_block_arguments,
-                           move_block_results: move_block_results,
-                           execute_blocks_in_place: execute_blocks_in_place)
     end
 
     ##
@@ -478,8 +601,7 @@ class Ractor
     # @return [MethodSettings]
     #
     def method_settings(method_name)
-      method_name = method_name.to_sym
-      @method_settings[method_name] || @method_settings[nil]
+      (method_name && @method_settings[method_name.to_sym]) || @method_settings[nil]
     end
 
     ##
@@ -500,7 +622,7 @@ class Ractor
     #
     def call(method_name, *args, **kwargs, &)
       reply_port = ::Ractor::Port.new
-      transaction = ::Random.rand(7_958_661_109_946_400_884_391_936).to_s(36).freeze
+      transaction = make_transaction
       settings = method_settings(method_name)
       block_arg = make_block_arg(settings, &)
       message = CallMessage.new(method_name: method_name,
@@ -511,7 +633,11 @@ class Ractor
                                 settings: settings,
                                 reply_port: reply_port)
       maybe_log("Sending method", method_name: method_name, transaction: transaction)
-      @port.send(message, move: settings.move_arguments?)
+      begin
+        @port.send(message, move: settings.arguments == :move)
+      rescue ::Ractor::ClosedError
+        raise StoppedError, "Wrapper has stopped"
+      end
       loop do
         reply_message = reply_port.receive
         case reply_message
@@ -519,14 +645,14 @@ class Ractor
           handle_yield(reply_message, transaction, settings, method_name, &)
         when ReturnMessage
           maybe_log("Received result", method_name: method_name, transaction: transaction)
-          reply_port.close
           return reply_message.value
         when ExceptionMessage
           maybe_log("Received exception", method_name: method_name, transaction: transaction)
-          reply_port.close
           raise reply_message.exception
         end
       end
+    ensure
+      reply_port.close
     end
 
     ##
@@ -550,6 +676,10 @@ class Ractor
     ##
     # Blocks until the wrapper has fully stopped.
     #
+    # Unlike `Thread#join` and `Ractor#join`, if a Wrapper crashes, the
+    # exception generally does *not* get raised out of `Wrapper#join`. Instead,
+    # it just returns self in the same way as normal termination.
+    #
     # @return [self]
     #
     def join
@@ -557,13 +687,16 @@ class Ractor
         @ractor.join
       else
         reply_port = ::Ractor::Port.new
-        @port.send(JoinMessage.new(reply_port))
-        reply_port.receive
-        reply_port.close
+        begin
+          @port.send(JoinMessage.new(reply_port))
+          reply_port.receive
+        rescue ::Ractor::ClosedError
+          # Assume the wrapper has stopped if the port is not sendable
+        ensure
+          reply_port.close
+        end
       end
       self
-    rescue ::Ractor::ClosedError
-      self
     end
 
     ##
@@ -577,13 +710,17 @@ class Ractor
     # case, any calls to this method will raise Ractor::Error.
     #
     # Only one ractor may call this method; any additional calls will fail with
-    # a Ractor::Error.
+    # a Ractor::Wrapper::Error.
     #
     # @return [Object] The original wrapped object
     #
     def recover_object
-      raise ::Ractor::Error, "cannot recover an object from a local wrapper" unless @ractor
-      @ractor.value
+      raise Error, "cannot recover an object from a local wrapper" unless @ractor
+      begin
+        @ractor.value
+      rescue ::Ractor::Error => e
+        raise ::Ractor::Wrapper::Error, e.message, cause: e
+      end
     end
 
     #### private items below ####
@@ -592,7 +729,7 @@ class Ractor
     # @private
     # Message sent to initialize a server.
     #
-    InitMessage = ::Data.define(:object, :enable_logging, :threads)
+    InitMessage = ::Data.define(:object, :stub)
 
     ##
     # @private
@@ -619,6 +756,12 @@ class Ractor
     #
     JoinMessage = ::Data.define(:reply_port)
 
+    ##
+    # @private
+    # Message sent from a server in response to a join request.
+    #
+    JoinReplyMessage = ::Data.define
+
     ##
     # @private
     # Message sent to report a return value
@@ -647,8 +790,12 @@ class Ractor
       maybe_log("Starting local server")
       @ractor = nil
       @port = ::Ractor::Port.new
+      freeze
+      wrapper_id = object_id
       ::Thread.new do
+        ::Thread.current.name = "ractor-wrapper:server:#{wrapper_id}"
         Server.run_local(object: object,
+                         stub: @stub,
                          port: @port,
                          name: name,
                          enable_logging: enable_logging?,
@@ -669,14 +816,16 @@ class Ractor
                             threads: threads)
       end
       @port = @ractor.default_port
-      @port.send(object, move: true)
+      freeze
+      init_message = InitMessage.new(object: object, stub: @stub)
+      @port.send(init_message, move: true)
     end
 
     ##
     # Create a transaction ID, used for logging
     #
     def make_transaction
-      ::Random.rand(7_958_661_109_946_400_884_391_936).to_s(36).freeze
+      ::Random.rand(7_958_661_109_946_400_884_391_936).to_s(36).rjust(16, "0").freeze
     end
 
     ##
@@ -685,7 +834,7 @@ class Ractor
     def make_block_arg(settings, &)
       if !block_given?
         nil
-      elsif settings.execute_blocks_in_place?
+      elsif settings.block_environment == :wrapped
         ::Ractor.shareable_proc(&)
       else
         :send_block_message
@@ -699,8 +848,9 @@ class Ractor
       maybe_log("Yielding to block", method_name: method_name, transaction: transaction)
       begin
         block_result = yield(*message.args, **message.kwargs)
+        block_result = nil if settings.block_results == :void
         maybe_log("Sending block result", method_name: method_name, transaction: transaction)
-        message.reply_port.send(ReturnMessage.new(block_result), move: settings.move_block_results?)
+        message.reply_port.send(ReturnMessage.new(block_result), move: settings.block_results == :move)
       rescue ::Exception => e # rubocop:disable Lint/RescueException
         maybe_log("Sending block exception", method_name: method_name, transaction: transaction)
         begin
@@ -745,8 +895,8 @@ class Ractor
       # @private
       # Create and run a server hosted in the current Ractor
       #
-      def self.run_local(object:, port:, name:, enable_logging: false, threads: 0)
-        server = new(isolated: false, object:, port:, name:, enable_logging:, threads:)
+      def self.run_local(object:, stub:, port:, name:, enable_logging: false, threads: 0)
+        server = new(isolated: false, object:, stub:, port:, name:, enable_logging:, threads:)
         server.run
       end
 
@@ -756,18 +906,19 @@ class Ractor
       #
       def self.run_isolated(name:, enable_logging: false, threads: 0)
         port = ::Ractor.current.default_port
-        server = new(isolated: true, object: nil, port:, name:, enable_logging:, threads:)
+        server = new(isolated: true, object: nil, stub: nil, port:, name:, enable_logging:, threads:)
         server.run
       end
 
       # @private
-      def initialize(isolated:, object:, port:, name:, enable_logging:, threads:)
+      def initialize(isolated:, object:, stub:, port:, name:, enable_logging:, threads:)
         @isolated = isolated
         @object = object
+        @stub = stub
         @port = port
         @name = name
         @enable_logging = enable_logging
-        @threads = threads.positive? ? threads : nil
+        @threads_requested = threads.positive? ? threads : false
         @join_requests = []
       end
 
@@ -779,14 +930,16 @@ class Ractor
       #
       def run
         receive_remote_object if @isolated
-        start_workers if @threads
+        start_workers if @threads_requested
         main_loop
-        stop_workers if @threads
+        stop_workers if @threads_requested
         cleanup
         @object
-      rescue ::StandardError => e
-        maybe_log("Unexpected error: #{e.inspect}")
+      rescue ::Exception => e # rubocop:disable Lint/RescueException
+        @crash_exception = e
         @object
+      ensure
+        crash_cleanup if @crash_exception
       end
 
       private
@@ -796,8 +949,10 @@ class Ractor
       # separate Ractor.
       #
       def receive_remote_object
-        maybe_log("Waiting for remote object")
-        @object = @port.receive
+        maybe_log("Waiting for initialization")
+        init_message = @port.receive
+        @object = init_message.object
+        @stub = init_message.stub
       end
 
       ##
@@ -805,10 +960,11 @@ class Ractor
       # shared queue. Called only if worker threading is enabled.
       #
       def start_workers
+        maybe_log("Spawning #{@threads_requested} worker threads")
         @queue = ::Queue.new
-        maybe_log("Spawning #{@threads} worker threads")
-        (1..@threads).map do |worker_num|
-          ::Thread.new { worker_thread(worker_num) }
+        @active_workers = {}
+        (1..@threads_requested).each do |worker_num|
+          @active_workers[worker_num] = ::Thread.new { worker_thread(worker_num) }
         end
       end
 
@@ -834,14 +990,14 @@ class Ractor
           case message
           when CallMessage
             maybe_log("Received CallMessage", call_message: message)
-            if @threads
+            if @threads_requested
               @queue.enq(message)
             else
               handle_method(message)
             end
           when WorkerStoppedMessage
             maybe_log("Received unexpected WorkerStoppedMessage")
-            @threads -= 1 if @threads
+            @active_workers.delete(message.worker_num) if @threads_requested
             break
           when StopMessage
             maybe_log("Received stop")
@@ -876,7 +1032,7 @@ class Ractor
       #
       def stop_workers
         @queue.close
-        while @threads.positive?
+        until @active_workers.empty?
           maybe_log("Waiting for message in stopping phase")
           message = @port.receive
           case message
@@ -884,7 +1040,7 @@ class Ractor
             refuse_method(message)
           when WorkerStoppedMessage
             maybe_log("Acknowledged WorkerStoppedMessage: #{message.worker_num}")
-            @threads -= 1
+            @active_workers.delete(message.worker_num)
           when StopMessage
             maybe_log("Stop received when already stopping")
           when JoinMessage
@@ -901,8 +1057,6 @@ class Ractor
       def cleanup
         maybe_log("Closing inbox")
         @port.close
-        maybe_log("Responding to join requests")
-        @join_requests.each { |port| send_join_reply(port) }
         maybe_log("Draining inbox")
         loop do
           message = begin
@@ -924,6 +1078,94 @@ class Ractor
             send_join_reply(message.reply_port)
           end
         end
+        maybe_log("Responding to join requests")
+        @join_requests.each { |port| send_join_reply(port) }
+      end
+
+      ##
+      # Called from the ensure block in run when an unexpected exception
+      # terminated the server. Drains pending requests that are not otherwise
+      # being handled, responding to all pending callers and join requesters,
+      # and also joins any worker threads.
+      #
+      def crash_cleanup
+        maybe_log("Running crash cleanup after: #{@crash_exception.message} (#{@crash_exception.class})")
+        error = CrashedError.new("Server crashed: #{@crash_exception.message} (#{@crash_exception.class})")
+        # `@queue` should not be nil in threaded mode, but we're checking
+        # anyway just in case a crash happened during setup
+        drain_queue_after_crash(@queue, error) if @threads_requested && @queue
+        drain_inbox_after_crash(@port, error)
+        # `@active_workers` should not be nil in threaded mode, but we're
+        # checking anyway just in case a crash happened during setup
+        join_workers_after_crash(@active_workers) if @threads_requested && @active_workers
+        @join_requests.each { |port| send_join_reply(port) }
+      rescue ::Exception => e # rubocop:disable Lint/RescueException
+        maybe_log("Suppressed exception during crash_cleanup: #{e.message} (#{e.class})")
+      end
+
+      ##
+      # Drains any remaining queued call messages after a crash, sending errors
+      # to callers whose calls had not yet been dispatched to a worker thread.
+      #
+      def drain_queue_after_crash(queue, error)
+        queue.close
+        loop do
+          message = queue.deq
+          break if message.nil?
+          begin
+            message.reply_port.send(ExceptionMessage.new(error))
+          rescue ::Ractor::Error
+            maybe_log("Failed to send crash error to queued caller", call_message: message)
+          end
+        end
+      rescue ::Exception => e # rubocop:disable Lint/RescueException
+        maybe_log("Suppressed exception during drain_queue_after_crash: " \
+                  "#{e.message} (#{e.class})")
+      end
+
+      ##
+      # Drains any remaining inbox messages after a crash, sending errors to
+      # pending callers and responding to any join requests.
+      #
+      def drain_inbox_after_crash(port, error)
+        begin
+          port.close
+        rescue ::Ractor::Error
+          # Port was already closed (maybe because it was the cause of the crash)
+        end
+        loop do
+          message = begin
+            port.receive
+          rescue ::Ractor::Error
+            nil
+          end
+          break if message.nil?
+          case message
+          when CallMessage
+            begin
+              message.reply_port.send(ExceptionMessage.new(error))
+            rescue ::Ractor::Error
+              maybe_log("Failed to send crash error to caller", call_message: message)
+            end
+          when JoinMessage
+            send_join_reply(message.reply_port)
+          when WorkerStoppedMessage, StopMessage
+            # Ignore
+          end
+        end
+      rescue ::Exception => e # rubocop:disable Lint/RescueException
+        maybe_log("Suppressed exception during drain_inbox_after_crash: #{e.message} (#{e.class})")
+      end
+
+      ##
+      # Wait until all workers have stopped after a crash
+      #
+      def join_workers_after_crash(workers)
+        workers.each_value do |thread|
+          thread.join
+        rescue ::Exception => e # rubocop:disable Lint/RescueException
+          maybe_log("Suppressed exception during join_workers_after_crash: #{e.message} (#{e.class})")
+        end
       end
 
       ##
@@ -947,7 +1189,7 @@ class Ractor
         begin
           @port.send(WorkerStoppedMessage.new(worker_num))
         rescue ::Ractor::ClosedError
-          maybe_log("Orphaned worker thread", worker_num: worker_num)
+          maybe_log("Worker unable to report stop, possibly due to server crash", worker_num: worker_num)
         end
       end
 
@@ -963,20 +1205,20 @@ class Ractor
       def handle_method(message, worker_num: nil)
         block = make_block(message)
         maybe_log("Running method", worker_num: worker_num, call_message: message)
+        result = @object.__send__(message.method_name, *message.args, **message.kwargs, &block)
+        result = @stub if result.equal?(@object)
+        result = nil if message.settings.results == :void
+        maybe_log("Sending return value", worker_num: worker_num, call_message: message)
+        message.reply_port.send(ReturnMessage.new(result), move: message.settings.results == :move)
+      rescue ::Exception => e # rubocop:disable Lint/RescueException
+        maybe_log("Sending exception", worker_num: worker_num, call_message: message)
         begin
-          result = @object.__send__(message.method_name, *message.args, **message.kwargs, &block)
-          maybe_log("Sending return value", worker_num: worker_num, call_message: message)
-          message.reply_port.send(ReturnMessage.new(result), move: message.settings.move_results?)
-        rescue ::Exception => e # rubocop:disable Lint/RescueException
-          maybe_log("Sending exception", worker_num: worker_num, call_message: message)
+          message.reply_port.send(ExceptionMessage.new(e))
+        rescue ::Exception # rubocop:disable Lint/RescueException
           begin
-            message.reply_port.send(ExceptionMessage.new(e))
-          rescue ::StandardError
-            begin
-              message.reply_port.send(ExceptionMessage.new(::StandardError.new(e.inspect)))
-            rescue ::StandardError
-              maybe_log("Failure to send method response", worker_num: worker_num, call_message: message)
-            end
+            message.reply_port.send(ExceptionMessage.new(::RuntimeError.new(e.inspect)))
+          rescue ::Exception # rubocop:disable Lint/RescueException
+            maybe_log("Failure to send method response", worker_num: worker_num, call_message: message)
           end
         end
       end
@@ -995,10 +1237,15 @@ class Ractor
         return message.block_arg unless message.block_arg == :send_block_message
         proc do |*args, **kwargs|
           reply_port = ::Ractor::Port.new
-          yield_message = YieldMessage.new(args: args, kwargs: kwargs, reply_port: reply_port)
-          message.reply_port.send(yield_message, move: message.settings.move_block_arguments?)
-          reply_message = reply_port.receive
-          reply_port.close
+          reply_message = begin
+            args.map! { |arg| arg.equal?(@object) ? @stub : arg }
+            kwargs.transform_values! { |arg| arg.equal?(@object) ? @stub : arg }
+            yield_message = YieldMessage.new(args: args, kwargs: kwargs, reply_port: reply_port)
+            message.reply_port.send(yield_message, move: message.settings.block_arguments == :move)
+            reply_port.receive
+          ensure
+            reply_port.close
+          end
           case reply_message
           when ExceptionMessage
             raise reply_message.exception
@@ -1016,7 +1263,7 @@ class Ractor
       def refuse_method(message)
         maybe_log("Refusing method call", call_message: message)
         begin
-          error = ::Ractor::ClosedError.new("Wrapper is shutting down")
+          error = StoppedError.new("Wrapper is shutting down")
           message.reply_port.send(ExceptionMessage.new(error))
         rescue ::Ractor::Error
           maybe_log("Failed to send refusal message", call_message: message)
@@ -1027,7 +1274,7 @@ class Ractor
       # This attempts to send a signal that a wrapper join has completed.
       #
       def send_join_reply(port)
-        port.send(nil)
+        port.send(JoinReplyMessage.new.freeze)
       rescue ::Ractor::ClosedError
         maybe_log("Join reply port is closed")
       end
@@ -1039,13 +1286,15 @@ class Ractor
         return unless @enable_logging
         transaction ||= call_message&.transaction
         method_name ||= call_message&.method_name
-        metadata = [::Time.now.utc.strftime("%Y-%m-%dT%H:%M:%S.%L"), "Ractor::Wrapper/#{@name}"]
-        metadata << "Worker/#{worker_num}" if worker_num
-        metadata << "Transaction/#{transaction}" if transaction
-        metadata << "Method/#{method_name}" if method_name
+        metadata = [::Time.now.utc.strftime("%Y-%m-%dT%H:%M:%S.%L"), "Ractor::Wrapper:#{@name}"]
+        metadata << "Worker:#{worker_num}" if worker_num
+        metadata << "Transaction:#{transaction}" if transaction
+        metadata << "Method:#{method_name}" if method_name
         metadata = metadata.join(" ")
         $stderr.puts("[#{metadata}] #{str}")
         $stderr.flush
+      rescue ::StandardError
+        # Swallow any errors during logging
       end
     end
   end