ractor-wrapper 0.2.0 → 0.4.0

data/lib/ractor/wrapper.rb

@@ -1,247 +1,595 @@
+# 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
   ##
-  # An experimental class that wraps a non-shareable object, allowing multiple
-  # Ractors to access it concurrently.
+  # An experimental class that wraps a non-shareable object in an actor,
+  # allowing multiple Ractors to access it concurrently.
   #
   # WARNING: This is a highly experimental library, and currently _not_
-  # recommended for production use. (As of Ruby 3.0.0, the same can be said of
+  # recommended for production use. (As of Ruby 4.0.0, the same can be said of
   # Ractors in general.)
   #
   # ## What is Ractor::Wrapper?
   #
-  # Ractors for the most part cannot access objects concurrently with other
-  # Ractors unless the object is _shareable_ (that is, deeply immutable along
-  # with a few other restrictions.) If multiple Ractors need to interact with a
-  # shared resource that is stateful or otherwise not Ractor-shareable, that
-  # resource must itself be implemented and accessed as a Ractor.
+  # For the most part, unless an object is _sharable_, which generally means
+  # deeply immutable along with a few other restrictions, it cannot be accessed
+  # directly from another Ractor. This makes it difficult for multiple Ractors
+  # to share a resource that is stateful. Such a resource must typically itself
+  # be implemented as a Ractor and accessed via message passing.
+  #
+  # Ractor::Wrapper makes it possible for an ordinary non-shareable object to
+  # be accessed from multiple Ractors. It does this by "wrapping" the object
+  # with an actor that listens for messages and invokes the object's methods in
+  # a controlled single-Ractor environment. It then provides a stub object that
+  # reproduces the interface of the original object, but responds to method
+  # calls by sending messages to the wrapper. Ractor::Wrapper can be used to
+  # implement simple actors by writing "plain" Ruby objects, or to adapt
+  # existing non-shareable objects to a multi-Ractor world.
+  #
+  # ## Net::HTTP example
+  #
+  # The following example shows how to share a single Net::HTTP session object
+  # among multiple Ractors.
+  #
+  #     require "ractor/wrapper"
+  #     require "net/http"
+  #
+  #     # Create a Net::HTTP session. Net::HTTP sessions are not shareable,
+  #     # so normally only one Ractor can access them at a time.
+  #     http = Net::HTTP.new("example.com")
+  #     http.start
+  #
+  #     # Create a wrapper around the session. This moves the session into an
+  #     # internal Ractor and listens for method call requests. By default, a
+  #     # wrapper serializes calls, handling one at a time, for compatibility
+  #     # with non-thread-safe objects.
+  #     wrapper = Ractor::Wrapper.new(http)
+  #
+  #     # At this point, the session object can no longer be accessed directly
+  #     # because it is now owned by the wrapper's internal Ractor.
+  #     #     http.get("/whoops")  # <= raises Ractor::MovedError
+  #
+  #     # However, you can access the session via the stub object provided by
+  #     # the wrapper. This stub proxies the call to the wrapper's internal
+  #     # Ractor. And it's shareable, so any number of Ractors can use it.
+  #     response = wrapper.stub.get("/")
+  #
+  #     # Here, we start two Ractors, and pass the stub to each one. Each
+  #     # Ractor can simply call methods on the stub as if it were the original
+  #     # connection object. Internally, of course, the calls are proxied to
+  #     # the original object via the wrapper, and execution is serialized.
+  #     r1 = Ractor.new(wrapper.stub) do |stub|
+  #       5.times do
+  #         stub.get("/hello")
+  #       end
+  #       :ok
+  #     end
+  #     r2 = Ractor.new(wrapper.stub) do |stub|
+  #       5.times do
+  #         stub.get("/ruby")
+  #       end
+  #       :ok
+  #     end
+  #
+  #     # Wait for the two above Ractors to finish.
+  #     r1.join
+  #     r2.join
+  #
+  #     # After you stop the wrapper, you can retrieve the underlying session
+  #     # object and access it directly again.
+  #     wrapper.async_stop
+  #     http = wrapper.recover_object
+  #     http.finish
   #
-  # `Ractor::Wrapper` makes it possible for such a shared resource to be
-  # implemented as an object and accessed using ordinary method calls. It does
-  # this by "wrapping" the object in a Ractor, and mapping method calls to
-  # message passing. This may make it easier to implement such a resource with
-  # a simple class rather than a full-blown Ractor with message passing, and it
-  # may also useful for adapting existing legacy object-based implementations.
+  # ## SQLite3 example
   #
-  # Given a shared resource object, `Ractor::Wrapper` starts a new Ractor and
-  # "runs" the object within that Ractor. It provides you with a stub object
-  # on which you can invoke methods. The wrapper responds to these method calls
-  # by sending messages to the internal Ractor, which invokes the shared object
-  # and then sends back the result. If the underlying object is thread-safe,
-  # you can configure the wrapper to run multiple threads that can run methods
-  # concurrently. Or, if not, the wrapper can serialize requests to the object.
+  # The following example shows how to share a SQLite3 database among multiple
+  # Ractors.
   #
-  # ## Example usage
+  #     require "ractor/wrapper"
+  #     require "sqlite3"
   #
-  # The following example shows how to share a single `Faraday::Conection`
-  # object among multiple Ractors. Because `Faraday::Connection` is not itself
-  # thread-safe, this example serializes all calls to it.
+  #     # Create a SQLite3 database. These objects are not shareable, so
+  #     # normally only one Ractor can access them.
+  #     db = SQLite3::Database.new($my_database_path)
   #
-  #     require "faraday"
+  #     # 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. 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)
   #
-  #     # Create a Faraday connection and a wrapper for it.
-  #     connection = Faraday.new "http://example.com"
-  #     wrapper = Ractor::Wrapper.new(connection)
+  #     # At this point, the database object can still be accessed directly
+  #     # because it hasn't been moved to a different Ractor.
+  #     rows = db.execute("select * from numbers")
   #
-  #     # At this point, the connection object cannot be accessed directly
-  #     # because it has been "moved" to the wrapper's internal Ractor.
-  #     #     connection.get("/whoops")  # <= raises an error
+  #     # You can also access the database via the stub object provided by the
+  #     # wrapper.
+  #     rows = wrapper.stub.execute("select * from numbers")
   #
-  #     # However, any number of Ractors can now access it through the wrapper.
-  #     # By default, access to the object is serialized; methods will not be
-  #     # invoked concurrently.
-  #     r1 = Ractor.new(wrapper) do |w|
-  #       10.times do
-  #         w.stub.get("/hello")
+  #     # Here, we start two Ractors, and pass the stub to each one. The
+  #     # wrapper's worker threads will handle the requests concurrently.
+  #     r1 = Ractor.new(wrapper.stub) do |stub|
+  #       5.times do
+  #         stub.execute("select * from numbers")
   #       end
   #       :ok
   #     end
-  #     r2 = Ractor.new(wrapper) do |w|
-  #       10.times do
-  #         w.stub.get("/ruby")
+  #     r2 = Ractor.new(wrapper.stub) do |stub|
+  #       5.times do
+  #         stub.execute("select * from numbers")
   #       end
   #       :ok
   #     end
   #
   #     # Wait for the two above Ractors to finish.
-  #     r1.take
-  #     r2.take
+  #     r1.join
+  #     r2.join
   #
-  #     # After you stop the wrapper, you can retrieve the underlying
-  #     # connection object and access it directly again.
+  #     # After stopping the wrapper, you can call the join method to wait for
+  #     # it to completely finish.
   #     wrapper.async_stop
-  #     connection = wrapper.recover_object
-  #     connection.get("/finally")
+  #     wrapper.join
+  #
+  #     # 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::Wrapper::Error
   #
   # ## Features
   #
-  # *   Provides a method interface to an object running in a different Ractor.
+  # *   Provides a Ractor-shareable method interface to a non-shareable object.
   # *   Supports arbitrary method arguments and return values.
-  # *   Supports exceptions thrown by the method.
-  # *   Can be configured to copy or move arguments, return values, and
-  #     exceptions, per method.
-  # *   Can serialize method calls for non-concurrency-safe objects, or run
-  #     methods concurrently in multiple worker threads for thread-safe objects.
+  # *   Can be configured to run in its own isolated Ractor or in a Thread in
+  #     the current Ractor.
+  # *   Can be configured per method whether to copy or move arguments and
+  #     return values.
+  # *   Blocks can be run in the calling Ractor or in the object Ractor.
+  # *   Raises exceptions thrown by the method.
+  # *   Can serialize method calls for non-thread-safe objects, or run methods
+  #     concurrently in multiple worker threads for thread-safe objects.
   # *   Can gracefully shut down the wrapper and retrieve the original object.
   #
   # ## Caveats
   #
-  # Ractor::Wrapper is subject to some limitations (and bugs) of Ractors, as of
-  # Ruby 3.0.0.
-  #
-  # *   You cannot pass blocks to wrapped methods.
   # *   Certain types cannot be used as method arguments or return values
-  #     because Ractor does not allow them to be moved between Ractors. These
-  #     include threads, procs, backtraces, and a few others.
-  # *   You can call wrapper methods from multiple Ractors concurrently, but
-  #     you cannot call them from multiple Threads within a single Ractor.
-  #     (This is due to https://bugs.ruby-lang.org/issues/17624)
-  # *   If you close the incoming port on a Ractor, it will no longer be able
-  #     to call out via a wrapper. If you close its incoming port while a call
-  #     is currently pending, that call may hang. (This is due to
-  #     https://bugs.ruby-lang.org/issues/17617)
+  #     because they cannot be moved between Ractors. As of Ruby 4.0.0, these
+  #     include threads, backtraces, procs, and a few others.
+  # *   As of Ruby 4.0.0, any exceptions raised are always copied (rather than
+  #     moved) back to the calling Ractor, and the backtrace is cleared out.
+  #     This is due to https://bugs.ruby-lang.org/issues/21818
+  # *   Blocks can be run "in place" (i.e. in the wrapped object context) only
+  #     if the block does not access any data outside the block. Otherwise, the
+  #     block must be run in caller's context.
+  # *   Blocks configured to run in the caller's context can only be run while
+  #     a method is executing. They cannot be "saved" as a proc to be run
+  #     later unless they are configured to run "in place". In particular,
+  #     using blocks as a syntax to define callbacks can generally not be done
+  #     through a wrapper.
   #
   class Wrapper
     ##
-    # Create a wrapper around the given object.
+    # Base class for errors raised by {Ractor::Wrapper}.
     #
-    # If you pass an optional block, the wrapper itself will be yielded to it
-    # at which time you can set additional configuration options. (The
-    # configuration is frozen once the object is constructed.)
-    #
-    # @param object [Object] The non-shareable object to wrap.
-    # @param threads [Integer] The number of worker threads to run.
-    #     Defaults to 1, which causes the worker to serialize calls.
+    class Error < ::Ractor::Error; end
+
+    ##
+    # Raised when a {Ractor::Wrapper} server has crashed unexpectedly.
     #
-    def initialize(object,
-                   threads: 1,
-                   move: false,
-                   move_arguments: nil,
-                   move_return: nil,
-                   logging: false,
-                   name: nil)
-      @method_settings = {}
-      self.threads = threads
-      self.logging = logging
-      self.name = name
-      configure_method(move: move, move_arguments: move_arguments, move_return: move_return)
-      yield self if block_given?
-      @method_settings.freeze
-
-      maybe_log("Starting server")
-      @ractor = ::Ractor.new(name: name) { Server.new.run }
-      opts = {
-        object: object,
-        threads: @threads,
-        method_settings: @method_settings,
-        name: @name,
-        logging: @logging,
-      }
-      @ractor.send(opts, move: true)
-
-      maybe_log("Server ready")
-      @stub = Stub.new(self)
-      freeze
-    end
+    class CrashedError < Error; end
 
     ##
-    # Set the number of threads to run in the wrapper. If the underlying object
-    # is thread-safe, this allows concurrent calls to it. If the underlying
-    # object is not thread-safe, you should leave this set to its default of 1,
-    # which effectively causes calls to be serialized.
+    # Raised when calling a method on a {Ractor::Wrapper} whose server has
+    # stopped and is no longer accepting calls.
     #
-    # This method can be called only during an initialization block.
-    # All settings are frozen once the wrapper is active.
+    class StoppedError < Error; end
+
+    ##
+    # A stub that forwards calls to a wrapper.
     #
-    # @param value [Integer]
+    # This object is shareable and can be passed to any Ractor.
     #
-    def threads=(value)
-      value = value.to_i
-      value = 1 if value < 1
-      @threads = value
+    class Stub
+      ##
+      # Create a stub given a wrapper.
+      #
+      # @param wrapper [Ractor::Wrapper]
+      #
+      def initialize(wrapper)
+        @wrapper = wrapper
+        freeze
+      end
+
+      ##
+      # Forward calls to {Ractor::Wrapper#call}.
+      # @private
+      #
+      def method_missing(name, ...)
+        @wrapper.call(name, ...)
+      end
+
+      ##
+      # Forward respond_to queries.
+      # @private
+      #
+      def respond_to_missing?(name, include_all)
+        @wrapper.call(:respond_to?, name, include_all)
+      end
     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.
+    # 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.
     #
-    # @param value [Boolean]
+    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
+
+      ##
+      # Enable or disable internal debug logging.
+      #
+      # @param value [Boolean]
+      #
+      def enable_logging=(value)
+        @enable_logging = value ? true : false
+      end
+
+      ##
+      # 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 threads=(value)
+        value = value.to_i
+        value = 0 if value.negative?
+        @threads = value
+      end
+
+      ##
+      # 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 use_current_ractor=(value)
+        @use_current_ractor = value ? true : false
+      end
+
+      ##
+      # 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:
+      #
+      # * `: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
+
+      ##
+      # @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.
+      #
+      # @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
+      # 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
+
+    ##
+    # Settings for a method call. Specifies how a method's arguments and
+    # return value are communicated (i.e. copy or move semantics.)
     #
-    def logging=(value)
-      @logging = value ? true : false
+    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
 
     ##
-    # Set the name of this wrapper. This is shown in logging, and is also used
-    # as the name of the wrapping Ractor.
+    # Create a wrapper around the given object.
     #
-    # This method can be called only during an initialization block.
-    # All settings are frozen once the wrapper is active.
+    # 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.
     #
-    # @param value [String, nil]
+    # See {Configuration} for more information about the method communication
+    # and block settings.
     #
-    def name=(value)
-      @name = value ? value.to_s.freeze : nil
-    end
+    # @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. 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. 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. 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,
+                   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
 
-    ##
-    # 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 [Boolean] Whether to move all communication. This value, if
-    #     given, is used if `move_arguments`, `move_return`, or
-    #     `move_exceptions` are not set.
-    # @param move_arguments [Boolean] Whether to move arguments.
-    # @param move_return [Boolean] Whether to move return values.
-    #
-    def configure_method(method_name = nil,
-                         move: false,
-                         move_arguments: nil,
-                         move_return: nil)
-      method_name = method_name.to_sym unless method_name.nil?
-      @method_settings[method_name] =
-        MethodSettings.new(move: move, move_arguments: move_arguments, move_return: move_return)
+      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
     end
 
     ##
-    # Return the wrapper stub. This is an object that responds to the same
-    # methods as the wrapped object, providing an easy way to call a wrapper.
+    # Return the name of this wrapper.
     #
-    # @return [Ractor::Wrapper::Stub]
+    # @return [String]
     #
-    attr_reader :stub
+    attr_reader :name
 
     ##
-    # Return the number of threads used by the wrapper.
+    # Determine whether this wrapper runs in the current Ractor
     #
-    # @return [Integer]
+    # @return [boolean]
     #
-    attr_reader :threads
+    def use_current_ractor?
+      @ractor.nil?
+    end
 
     ##
     # Return whether logging is enabled for this wrapper.
     #
     # @return [Boolean]
     #
-    attr_reader :logging
+    def enable_logging?
+      @enable_logging
+    end
 
     ##
-    # Return the name of this wrapper.
+    # Return the number of worker threads used by the wrapper.
     #
-    # @return [String, nil]
+    # @return [Integer]
     #
-    attr_reader :name
+    attr_reader :threads
 
     ##
     # Return the method settings for the given method name. This returns the
@@ -253,10 +601,17 @@ 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
 
+    ##
+    # Return the wrapper stub. This is an object that responds to the same
+    # methods as the wrapped object, providing an easy way to call a wrapper.
+    #
+    # @return [Ractor::Wrapper::Stub]
+    #
+    attr_reader :stub
+
     ##
     # A lower-level interface for calling methods through the wrapper.
     #
@@ -265,407 +620,681 @@ class Ractor
     # @param kwargs [keywords] The keyword arguments
     # @return [Object] The return value
     #
-    def call(method_name, *args, **kwargs)
-      request = Message.new(:call, data: [method_name, args, kwargs])
-      transaction = request.transaction
-      move = method_settings(method_name).move_arguments?
-      maybe_log("Sending method #{method_name} (move=#{move}, transaction=#{transaction})")
-      @ractor.send(request, move: move)
-      reply = ::Ractor.receive_if { |msg| msg.is_a?(Message) && msg.transaction == transaction }
-      case reply.type
-      when :result
-        maybe_log("Received result for method #{method_name} (transaction=#{transaction})")
-        reply.data
-      when :error
-        maybe_log("Received exception for method #{method_name} (transaction=#{transaction})")
-        raise reply.data
+    def call(method_name, *args, **kwargs, &)
+      reply_port = ::Ractor::Port.new
+      transaction = make_transaction
+      settings = method_settings(method_name)
+      block_arg = make_block_arg(settings, &)
+      message = CallMessage.new(method_name: method_name,
+                                args: args,
+                                kwargs: kwargs,
+                                block_arg: block_arg,
+                                transaction: transaction,
+                                settings: settings,
+                                reply_port: reply_port)
+      maybe_log("Sending method", method_name: method_name, transaction: transaction)
+      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
+        when YieldMessage
+          handle_yield(reply_message, transaction, settings, method_name, &)
+        when ReturnMessage
+          maybe_log("Received result", method_name: method_name, transaction: transaction)
+          return reply_message.value
+        when ExceptionMessage
+          maybe_log("Received exception", method_name: method_name, transaction: transaction)
+          raise reply_message.exception
+        end
       end
+    ensure
+      reply_port.close
     end
 
     ##
     # Request that the wrapper stop. All currently running calls will complete
     # before the wrapper actually terminates. However, any new calls will fail.
     #
-    # This metnod is idempotent and can be called multiple times (even from
+    # This method is idempotent and can be called multiple times (even from
     # different ractors).
     #
     # @return [self]
     #
     def async_stop
-      maybe_log("Stopping #{name}")
-      @ractor.send(Message.new(:stop))
+      maybe_log("Stopping wrapper")
+      @port.send(StopMessage.new.freeze)
       self
     rescue ::Ractor::ClosedError
       # Ignore to allow stops to be idempotent.
       self
     end
 
+    ##
+    # 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
+      if @ractor
+        @ractor.join
+      else
+        reply_port = ::Ractor::Port.new
+        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
+    end
+
     ##
     # Retrieves the original object that was wrapped. This should be called
     # only after a stop request has been issued using {#async_stop}, and may
     # block until the wrapper has fully stopped.
     #
-    # Only one ractor may call this method; any additional calls will fail.
+    # This can be called only if the wrapper was *not* configured with
+    # `use_current_ractor: true`. If the wrapper had that configuration, the
+    # object will not be moved, and does not need to be recovered. In such a
+    # 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::Wrapper::Error.
     #
     # @return [Object] The original wrapped object
     #
-    def recovered_object
-      @ractor.take
+    def recover_object
+      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
+    #### private items below ####
 
-    def maybe_log(str)
-      return unless logging
-      time = ::Time.now.utc.strftime("%Y-%m-%dT%H:%M:%S.%L")
-      $stderr.puts("[#{time} Ractor::Wrapper/#{name}]: #{str}")
-      $stderr.flush
-    end
+    ##
+    # @private
+    # Message sent to initialize a server.
+    #
+    InitMessage = ::Data.define(:object, :stub)
 
     ##
-    # A stub that forwards calls to a wrapper.
+    # @private
+    # Message sent to a server to call a method
     #
-    class Stub
-      ##
-      # Create a stub given a wrapper.
-      #
-      # @param wrapper [Ractor::Wrapper]
-      #
-      def initialize(wrapper)
-        @wrapper = wrapper
-        freeze
-      end
+    CallMessage = ::Data.define(:method_name, :args, :kwargs, :block_arg,
+                                :transaction, :settings, :reply_port)
 
-      ##
-      # Forward calls to {Ractor::Wrapper#call}.
-      # @private
-      #
-      def method_missing(name, *args, **kwargs)
-        @wrapper.call(name, *args, **kwargs)
-      end
+    ##
+    # @private
+    # Message sent to a server when a worker thread terminates
+    #
+    WorkerStoppedMessage = ::Data.define(:worker_num)
 
-      ##
-      # Forward respond_to queries.
-      # @private
-      #
-      def respond_to_missing?(name, include_all)
-        @wrapper.call(:respond_to?, name, include_all)
-      end
-    end
+    ##
+    # @private
+    # Message sent to a server to request it to stop
+    #
+    StopMessage = ::Data.define
 
     ##
-    # Settings for a method call. Specifies how a method's arguments and
-    # return value are communicated (i.e. copy or move semantics.)
+    # @private
+    # Message sent to a server to request a join response
     #
-    class MethodSettings
-      # @private
-      def initialize(move: false,
-                     move_arguments: nil,
-                     move_return: nil)
-        @move_arguments = interpret_setting(move_arguments, move)
-        @move_return = interpret_setting(move_return, move)
-        freeze
-      end
+    JoinMessage = ::Data.define(:reply_port)
 
-      ##
-      # @return [Boolean] Whether to move arguments
-      #
-      def move_arguments?
-        @move_arguments
-      end
+    ##
+    # @private
+    # Message sent from a server in response to a join request.
+    #
+    JoinReplyMessage = ::Data.define
 
-      ##
-      # @return [Boolean] Whether to move return values
-      #
-      def move_return?
-        @move_return
-      end
+    ##
+    # @private
+    # Message sent to report a return value
+    #
+    ReturnMessage = ::Data.define(:value)
 
-      private
+    ##
+    # @private
+    # Message sent to report an exception result
+    #
+    ExceptionMessage = ::Data.define(:exception)
 
-      def interpret_setting(setting, default)
-        if setting.nil?
-          default ? true : false
-        else
-          setting ? true : false
-        end
+    ##
+    # @private
+    # Message sent from a server to request a yield block run
+    #
+    YieldMessage = ::Data.define(:args, :kwargs, :reply_port)
+
+    private
+
+    ##
+    # Start a server in the current Ractor.
+    # Passes the object directly to the server.
+    #
+    def setup_local_server(object)
+      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?,
+                         threads: threads)
       end
     end
 
     ##
-    # The class of all messages passed between a client Ractor and a wrapper.
-    # This helps the wrapper distinguish these messages from any other messages
-    # that might be received by a client Ractor.
+    # Start a server in an isolated Ractor.
+    # This must send the object separately since it must be moved into the
+    # server's Ractor.
     #
-    # Any Ractor that calls a wrapper may receive messages of this type when
-    # the call is in progress. If a Ractor interacts with its incoming message
-    # queue concurrently while a wrapped call is in progress, it must ignore
-    # these messages (i.e. by by using `receive_if`) in order not to interfere
-    # with the wrapper. (Similarly, the wrapper will use `receive_if` to
-    # receive only messages of this type, so it does not interfere with your
-    # Ractor's functionality.)
-    #
-    class Message
-      # @private
-      def initialize(type, data: nil, transaction: nil)
-        @sender = ::Ractor.current
-        @type = type
-        @data = data
-        @transaction = transaction || new_transaction
-        freeze
+    def setup_isolated_server(object)
+      maybe_log("Starting isolated server")
+      @ractor = ::Ractor.new(name, enable_logging?, threads, name: "wrapper:#{name}") do |name, enable_logging, threads|
+        Server.run_isolated(name: name,
+                            enable_logging: enable_logging,
+                            threads: threads)
       end
+      @port = @ractor.default_port
+      freeze
+      init_message = InitMessage.new(object: object, stub: @stub)
+      @port.send(init_message, move: true)
+    end
 
-      # @private
-      attr_reader :type
-
-      # @private
-      attr_reader :sender
-
-      # @private
-      attr_reader :transaction
-
-      # @private
-      attr_reader :data
-
-      private
+    ##
+    # Create a transaction ID, used for logging
+    #
+    def make_transaction
+      ::Random.rand(7_958_661_109_946_400_884_391_936).to_s(36).rjust(16, "0").freeze
+    end
 
-      def new_transaction
-        ::Random.rand(7958661109946400884391936).to_s(36).freeze
+    ##
+    # Create the shareable object representing a block in a method call
+    #
+    def make_block_arg(settings, &)
+      if !block_given?
+        nil
+      elsif settings.block_environment == :wrapped
+        ::Ractor.shareable_proc(&)
+      else
+        :send_block_message
       end
     end
 
     ##
-    # This is the backend implementation of a wrapper. A Server runs within a
-    # Ractor, and manages a shared object. It handles communication with
-    # clients, translating those messages into method calls on the object. It
-    # runs worker threads internally to handle actual method calls.
+    # Handle a call to a block directed to run in the caller environment.
     #
-    # See the {#run} method for an overview of the Server implementation and
-    # lifecycle.
+    def handle_yield(message, transaction, settings, method_name)
+      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.block_results == :move)
+      rescue ::Exception => e # rubocop:disable Lint/RescueException
+        maybe_log("Sending block exception", method_name: method_name, transaction: transaction)
+        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 block reply", method_name: method_name, transaction: transaction)
+          end
+        end
+      end
+    end
+
+    ##
+    # Prints out a log message
     #
+    def maybe_log(str, transaction: nil, method_name: nil)
+      return unless enable_logging?
+      metadata = [::Time.now.utc.strftime("%Y-%m-%dT%H:%M:%S.%L"), "Ractor::Wrapper/#{name}"]
+      metadata << "Transaction/#{transaction}" if transaction
+      metadata << "Method/#{method_name}" if method_name
+      metadata = metadata.join(" ")
+      $stderr.puts("[#{metadata}] #{str}")
+      $stderr.flush
+    end
+
+    ##
     # @private
     #
+    # Server is the backend implementation of a wrapper. It listens for method
+    # call requests on a port, and calls the wrapped object in a controlled
+    # environment.
+    #
+    # It can run:
+    #
+    # * Either hosted by an external Ractor or isolated in a dedicated Ractor
+    # * Either sequentially or concurrently using worker threads.
+    #
     class Server
       ##
-      # Handle the server lifecycle, running through the following phases:
+      # @private
+      # Create and run a server hosted in the current Ractor
       #
-      # *   **init**: Setup and spawning of worker threads.
-      # *   **running**: Normal operation, until a stop request is received.
-      # *   **stopping**: Waiting for worker threads to terminate.
-      # *   **cleanup**: Clearing out of any lingering meessages.
+      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
+
+      ##
+      # @private
+      # Create and run a server in an isolated Ractor
       #
-      # The server returns the wrapped object, allowing one client Ractor to
-      # take it.
+      def self.run_isolated(name:, enable_logging: false, threads: 0)
+        port = ::Ractor.current.default_port
+        server = new(isolated: true, object: nil, stub: nil, port:, name:, enable_logging:, threads:)
+        server.run
+      end
+
+      # @private
+      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_requested = threads.positive? ? threads : false
+        @join_requests = []
+      end
+
+      ##
+      # @private
+      # Handle the server lifecycle.
+      # Returns the wrapped object, so it can be recovered if the server is run
+      # in a Ractor.
       #
       def run
-        init_phase
-        running_phase
-        stopping_phase
-        cleanup_phase
+        receive_remote_object if @isolated
+        start_workers if @threads_requested
+        main_loop
+        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
 
       ##
-      # In the **init phase**, the Server:
-      #
-      # *   Receives an initial message providing the object to wrap, and
-      #     server configuration such as thread count and communications
-      #     settings.
-      # *   Initializes the job queue and the pending request list.
-      # *   Spawns worker threads.
+      # Receive the moved remote object. Called if the server is run in a
+      # separate Ractor.
       #
-      def init_phase
-        opts = ::Ractor.receive
-        @object = opts[:object]
-        @logging = opts[:logging]
-        @name = opts[:name]
-        @method_settings = opts[:method_settings]
-        @thread_count = opts[:threads]
-        @queue = ::Queue.new
-        @mutex = ::Mutex.new
-        @current_calls = {}
-        maybe_log("Spawning #{@thread_count} threads")
-        (1..@thread_count).map do |worker_num|
-          ::Thread.new { worker_thread(worker_num) }
-        end
-        maybe_log("Server initialized")
+      def receive_remote_object
+        maybe_log("Waiting for initialization")
+        init_message = @port.receive
+        @object = init_message.object
+        @stub = init_message.stub
       end
 
       ##
-      # A worker thread repeatedly pulls a method call requests off the job
-      # queue, handles it, and sends back a response. It also removes the
-      # request from the pending request list to signal that it has responded.
-      # If no job is available, the thread blocks while waiting. If the queue
-      # is closed, the worker will send an acknowledgement message and then
-      # terminate.
+      # Start the worker threads. Each thread picks up methods to run from a
+      # shared queue. Called only if worker threading is enabled.
       #
-      def worker_thread(worker_num)
-        maybe_worker_log(worker_num, "Starting")
-        loop do
-          maybe_worker_log(worker_num, "Waiting for job")
-          request = @queue.deq
-          break if request.nil?
-          handle_method(worker_num, request)
-          unregister_call(request.transaction)
+      def start_workers
+        maybe_log("Spawning #{@threads_requested} worker threads")
+        @queue = ::Queue.new
+        @active_workers = {}
+        (1..@threads_requested).each do |worker_num|
+          @active_workers[worker_num] = ::Thread.new { worker_thread(worker_num) }
         end
-      ensure
-        maybe_worker_log(worker_num, "Stopping")
-        ::Ractor.current.send(Message.new(:thread_stopped, data: worker_num), move: true)
       end
 
       ##
-      # In the **running phase**, the Server listens on the Ractor's inbox and
-      # handles messages for normal operation:
+      # This is the main loop, listening on the inbox and handling messages for
+      # normal operation:
       #
-      # *   If it receives a `call` request, it adds it to the job queue from
-      #     which a worker thread will pick it up. It also adds the request to
-      #     a list of pending requests.
-      # *   If it receives a `stop` request, we proceed to the stopping phase.
-      # *   If it receives a `thread_stopped` message, that indicates one of
-      #     the worker threads has unexpectedly stopped. We don't expect this
-      #     to happen until the stopping phase, so if we do see it here, we
-      #     conclude that something has gone wrong, and we proceed to the
-      #     stopping phase.
+      # *   If it receives a CallMessage, it either runs the method (when in
+      #     sequential mode) or adds it to the job queue (when in worker mode).
+      # *   If it receives a StopMessage, it exits the main loop and proceeds
+      #     to the termination logic.
+      # *   If it receives a JoinMessage, it adds it to the list of join ports
+      #     to notify once the wrapper completes.
+      # *   If it receives a WorkerStoppedMessage, that indicates a worker
+      #     thread has unexpectedly stopped. We conclude something has gone
+      #     wrong with a worker, and we bail, stopping the remaining workers
+      #     and proceeding to termination logic.
       #
-      def running_phase
+      def main_loop
         loop do
-          maybe_log("Waiting for message")
-          request = ::Ractor.receive
-          next unless request.is_a?(Message)
-          case request.type
-          when :call
-            @queue.enq(request)
-            register_call(request)
-            maybe_log("Queued method #{request.data.first} (transaction=#{request.transaction})")
-          when :thread_stopped
-            maybe_log("Thread unexpectedly stopped: #{request.data}")
-            @thread_count -= 1
+          maybe_log("Waiting for message in running phase")
+          message = @port.receive
+          case message
+          when CallMessage
+            maybe_log("Received CallMessage", call_message: message)
+            if @threads_requested
+              @queue.enq(message)
+            else
+              handle_method(message)
+            end
+          when WorkerStoppedMessage
+            maybe_log("Received unexpected WorkerStoppedMessage")
+            @active_workers.delete(message.worker_num) if @threads_requested
             break
-          when :stop
+          when StopMessage
             maybe_log("Received stop")
             break
+          when JoinMessage
+            maybe_log("Received and queueing join request")
+            @join_requests << message.reply_port
           end
         end
       end
 
       ##
-      # In the **stopping phase**, we close the job queue, which signals to all
-      # worker threads that they should finish their current task and then
-      # terminate. We then wait for acknowledgement messages from all workers
-      # before proceeding to the next phase. Any `call` requests received
-      # during stopping are refused (i.e. we send back an error response.) Any
-      # further `stop` requests are ignored.
+      # This signals workers to stop by closing the queue, and then waits for
+      # all workers to report in that they have stopped. It is called only if
+      # worker threading is enabled.
+      #
+      # Responds to messages to indicate the wrapper is stopping and no longer
+      # accepting new method requests:
+      #
+      # *   If it receives a CallMessage, it sends back a refusal exception.
+      # *   If it receives a StopMessage, it does nothing (i.e. the stop
+      #     operation is idempotent).
+      # *   If it receives a JoinMessage, it adds it to the list of join ports
+      #     to notify once the wrapper completes. At this point the wrapper is
+      #     not yet considered complete because workers are still processing
+      #     earlier method calls.
+      # *   If it receives a WorkerStoppedMessage, it updates its count of
+      #     running workers.
       #
-      def stopping_phase
+      # This phase continues until all workers have signaled that they have
+      # stopped.
+      #
+      def stop_workers
         @queue.close
-        while @thread_count.positive?
-          maybe_log("Waiting for message while stopping")
-          message = ::Ractor.receive
-          next unless request.is_a?(Message)
-          case message.type
-          when :call
+        until @active_workers.empty?
+          maybe_log("Waiting for message in stopping phase")
+          message = @port.receive
+          case message
+          when CallMessage
             refuse_method(message)
-          when :thread_stopped
-            @thread_count -= 1
+          when WorkerStoppedMessage
+            maybe_log("Acknowledged WorkerStoppedMessage: #{message.worker_num}")
+            @active_workers.delete(message.worker_num)
+          when StopMessage
+            maybe_log("Stop received when already stopping")
+          when JoinMessage
+            maybe_log("Received and queueing join request")
+            @join_requests << message.reply_port
           end
         end
       end
 
       ##
-      # In the **cleanup phase**, The Server closes its inbox, and iterates
-      # through one final time to ensure it has responded to all remaining
-      # requests with a refusal. It also makes another pass through the pending
-      # requests; if there are any left, it probably means a worker thread died
-      # without responding to it preoprly, so we send back an error message.
+      # This is called when the Server is ready to terminate completely.
+      # It closes the inbox and responds to any remaining contents.
       #
-      def cleanup_phase
-        ::Ractor.current.close_incoming
-        maybe_log("Checking message queue for cleanup")
+      def cleanup
+        maybe_log("Closing inbox")
+        @port.close
+        maybe_log("Draining inbox")
         loop do
-          message = ::Ractor.receive
-          refuse_method(message) if message.is_a?(Message) && message.type == :call
+          message = begin
+            @port.receive
+          rescue ::Ractor::ClosedError
+            maybe_log("Inbox is empty")
+            nil
+          end
+          break if message.nil?
+          case message
+          when CallMessage
+            refuse_method(message)
+          when WorkerStoppedMessage
+            maybe_log("Unexpected WorkerStoppedMessage when in cleanup")
+          when StopMessage
+            maybe_log("Stop received when already stopping")
+          when JoinMessage
+            maybe_log("Received and responding immediately to join request")
+            send_join_reply(message.reply_port)
+          end
         end
-        maybe_log("Checking current calls for cleanup")
-        @current_calls.each_value do |request|
-          refuse_method(request)
+        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 ::Ractor::ClosedError
-        maybe_log("Message queue is empty")
+      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
 
       ##
-      # This is called within a worker thread to handle a method call request.
+      # 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
+
+      ##
+      # A worker thread repeatedly pulls a method call requests off the job
+      # queue, handles it, and sends back a response. It also removes the
+      # request from the pending request list to signal that it has responded.
+      # If no job is available, the thread blocks while waiting. If the queue
+      # is closed, the worker will send an acknowledgement message and then
+      # terminate.
+      #
+      def worker_thread(worker_num)
+        maybe_log("Worker starting", worker_num: worker_num)
+        loop do
+          maybe_log("Waiting for job", worker_num: worker_num)
+          message = @queue.deq
+          break if message.nil?
+          handle_method(message, worker_num: worker_num)
+        end
+      ensure
+        maybe_log("Worker stopping", worker_num: worker_num)
+        begin
+          @port.send(WorkerStoppedMessage.new(worker_num))
+        rescue ::Ractor::ClosedError
+          maybe_log("Worker unable to report stop, possibly due to server crash", worker_num: worker_num)
+        end
+      end
+
+      ##
+      # This is called to handle a method call request.
       # It calls the method on the wrapped object, and then sends back a
       # response to the caller. If an exception was raised, it sends back an
       # error response. It tries very hard always to send a response of some
       # kind; if an error occurs while constructing or sending a response, it
-      # will catch the exception and try to send a simpler response.
+      # will catch the exception and try to send a simpler response. If a block
+      # was passed to the method, it is also handled here.
       #
-      def handle_method(worker_num, request)
-        method_name, args, kwargs = request.data
-        transaction = request.transaction
-        sender = request.sender
-        maybe_worker_log(worker_num, "Running method #{method_name} (transaction=#{transaction})")
+      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(method_name, *args, **kwargs)
-          maybe_worker_log(worker_num, "Sending result (transaction=#{transaction})")
-          sender.send(Message.new(:result, data: result, transaction: transaction),
-                      move: (@method_settings[method_name] || @method_settings[nil]).move_return?)
-        rescue ::Exception => e # rubocop:disable Lint/RescueException
-          maybe_worker_log(worker_num, "Sending exception (transaction=#{transaction})")
+          message.reply_port.send(ExceptionMessage.new(e))
+        rescue ::Exception # rubocop:disable Lint/RescueException
           begin
-            sender.send(Message.new(:error, data: e, transaction: transaction))
-          rescue ::StandardError
-            safe_error = begin
-              ::StandardError.new(e.inspect)
-            rescue ::StandardError
-              ::StandardError.new("Unknown error")
-            end
-            sender.send(Message.new(:error, data: safe_error, transaction: transaction))
+            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
 
       ##
-      # This is called from the main Ractor thread to report to a caller that
-      # the wrapper cannot handle a requested method call, likely because the
-      # wrapper is shutting down.
+      # Creates a block appropriate to the block specification received with
+      # the method call message. This could return:
       #
-      def refuse_method(request)
-        maybe_log("Refusing method call (transaction=#{message.transaction})")
-        error = ::Ractor::ClosedError.new
-        request.sender.send(Message.new(:error, data: error, transaction: message.transaction))
-      end
-
-      def register_call(request)
-        @mutex.synchronize do
-          @current_calls[request.transaction] = request
+      # *   nil if there was no block
+      # *   the proc itself, if a shareable proc was received
+      # *   otherwise a proc that sends a message back to the caller, along
+      #     with the block arguments, to run the block in the caller's
+      #     environment
+      #
+      def make_block(message)
+        return message.block_arg unless message.block_arg == :send_block_message
+        proc do |*args, **kwargs|
+          reply_port = ::Ractor::Port.new
+          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
+          when ReturnMessage
+            reply_message.value
+          end
         end
       end
 
-      def unregister_call(transaction)
-        @mutex.synchronize do
-          @current_calls.delete(transaction)
+      ##
+      # This is called from the main Ractor thread to report to a caller that
+      # the wrapper cannot handle a requested method call, likely because the
+      # wrapper is shutting down.
+      #
+      def refuse_method(message)
+        maybe_log("Refusing method call", call_message: message)
+        begin
+          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)
         end
       end
 
-      def maybe_log(str)
-        return unless @logging
-        time = ::Time.now.utc.strftime("%Y-%m-%dT%H:%M:%S.%L")
-        $stderr.puts("[#{time} Ractor::Wrapper/#{@name} Server]: #{str}")
-        $stderr.flush
+      ##
+      # This attempts to send a signal that a wrapper join has completed.
+      #
+      def send_join_reply(port)
+        port.send(JoinReplyMessage.new.freeze)
+      rescue ::Ractor::ClosedError
+        maybe_log("Join reply port is closed")
       end
 
-      def maybe_worker_log(worker_num, str)
-        return unless @logging
-        time = ::Time.now.utc.strftime("%Y-%m-%dT%H:%M:%S.%L")
-        $stderr.puts("[#{time} Ractor::Wrapper/#{@name} Worker/#{worker_num}]: #{str}")
+      ##
+      # Print out a log message
+      #
+      def maybe_log(str, call_message: nil, worker_num: nil, transaction: nil, method_name: nil)
+        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 = metadata.join(" ")
+        $stderr.puts("[#{metadata}] #{str}")
         $stderr.flush
+      rescue ::StandardError
+        # Swallow any errors during logging
       end
     end
   end