ractor-wrapper 0.2.0 → 0.4.0

data/README.md

@@ -1,123 +1,458 @@
 # Ractor::Wrapper
 
-`Ractor::Wrapper` is an experimental class that wraps a non-shareable object,
-allowing multiple Ractors to access it concurrently. This can make it possible
-for multiple ractors to share an object such as a database connection.
+Ractor::Wrapper is an experimental class that wraps a non-shareable object in
+an actor, allowing multiple Ractors to access it concurrently.
+
+**WARNING:** This is an experimental library, and currently _not_ recommended
+for production use. (As of Ruby 4.0, the same can still be said of Ractors in
+general.)
 
 ## Quick start
 
 Install ractor-wrapper as a gem, or include it in your bundle.
 
-    gem install ractor-wrapper
+```sh
+gem install ractor-wrapper
+```
 
 Require it in your code:
 
-    require "ractor/wrapper"
+```ruby
+require "ractor/wrapper"
+```
 
 You can then create wrappers for objects. See the example below.
 
-`Ractor::Wrapper` requires Ruby 3.0.0 or later.
+Ractor::Wrapper requires Ruby 4.0.0 or later.
+
+## What is Ractor::Wrapper?
+
+For the most part, unless an object is _shareable_, which generally means
+deeply immutable along with a few other restrictions, it cannot be accessed
+directly from a Ractor other than the one in which it was constructed. This
+makes it difficult for multiple Ractors to share a resource that is stateful,
+such as a database connection.
+
+    +----Main-Ractor----+       +-Another-Ractor-+
+    |                   |       |                |
+    |      client1      |       |                |
+    |         |         |       |                |
+    |         | ok      |       |                |
+    |         v         |       |                |
+    |     my_db_conn <------X------ client2      |
+    |                   | fails |                |
+    +-------------------+       +----------------+
+
+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
+a shareable proxy.
+
+    +--Main-Ractor--+    +-Wrapper-Ractor-+    +-Another-Ractor-+
+    |               |    |                |    |                |
+    |    client1    |    |                |    |    client2     |
+    |       |       |    |                |    |       |        |
+    |       v       |    |                |    |       v        |
+    |     +----------------------------------------------+      |
+    |     |             SHAREABLE    WRAPPER             |      |
+    |     +----------------------------------------------+      |
+    |               |    |        |       |    |                |
+    |               |    |        v       |    |                |
+    |               |    |   my_db_conn   |    |                |
+    +---------------+    +----------------+    +----------------+
+
+The wrapper provides a shareable stub object that reproduces the method
+interface of the original object, so, with a few caveats, the wrapper is almost
+fully transparent. Behind the scenes, the wrapper "runs" the wrapped object in
+a controlled single-Ractor environment, and uses port messaging to communicate
+method calls, arguments, and return values between Ractors.
+
+Ractor::Wrapper can be used to adapt non-shareable objects to a multi-Ractor
+world. It can also be used to implement a simple actor by writing a "plain"
+Ruby object and wrapping it with a Ractor.
+
+## Examples
+
+Below are some illustrative examples showing how to use Ractor::Wrapper.
+
+### Net::HTTP example
+
+The following example shows how to share a single Net::HTTP session object
+among multiple Ractors.
 
-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 Ractors in
-general.)
-
-## About Ractor::Wrapper
+```ruby
+# Net::HTTP example
 
-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.
+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
 
-`Ractor::Wrapper` makes it possible for such a shared resource to be
-implemented as an ordinary 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.
+# Wait for the two above Ractors to finish.
+r1.join
+r2.join
 
-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.
+# 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
+```
 
-### Example usage
+### SQLite3 example
 
-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.
+The following example shows how to share a SQLite3 database among multiple
+Ractors.
 
 ```ruby
-require "faraday"
-require "ractor/wrapper"
+# SQLite3 example
 
-# Create a Faraday connection and a wrapper for it.
-connection = Faraday.new "http://example.com"
-wrapper = Ractor::Wrapper.new(connection)
-
-# 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
-
-# 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. (To allow concurrent access, set up threads when
-# creating the wrapper.)
-r1 = Ractor.new(wrapper) do |w|
-  10.times do
-    w.stub.get("/hello")
+require "ractor/wrapper"
+require "sqlite3"
+
+# Create a SQLite3 database. These objects are not shareable, so
+# normally only one Ractor can access them.
+db = SQLite3::Database.new($my_database_path)
+
+# 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 instead of an internal 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)
+
+# At this point, the database object can still be accessed directly
+# from the current Ractor because it hasn't been moved.
+rows = db.execute("select * from numbers")
+
+# You can also access the database via the stub object provided by the
+# wrapper.
+rows = wrapper.stub.execute("select * from numbers")
+
+# 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
+```
+
+### Simple actor example
+
+The following example demonstrates how to use Ractor::Wrapper to implement an
+actor as a plain Ruby object. Focus on writing functionality as methods, and
+let Ractor::Wrapper handle all the messaging logic.
+
+```ruby
+# Simple actor example
+
+require "ractor/wrapper"
+
+class SimpleCalculator
+  class EmptyStackError < StandardError
+  end
+
+  def initialize
+    @stack = []
+  end
+
+  def push(number)
+    @stack.push(number)
+    nil
+  end
+
+  def pop
+    raise EmptyStackError if @stack.empty?
+    @stack.pop
+  end
+
+  def add
+    push(pop + pop)
+    nil
+  end
+end
+
+# Create an actor based on SimpleCalculator
+calc_actor = Ractor::Wrapper.new(SimpleCalculator.new)
+
+# You can now send messages by calling methods
+calc_stub = calc_actor.stub
+calc_stub.push(2)
+calc_stub.push(3)
+calc_stub.add
+sum = calc_stub.pop
+
+# Stop the actor by calling async_stop
+calc_actor.async_stop
+# Wait for the actor to shut down
+calc_actor.join
 ```
 
-### Features
-
-*   Provides a method interface to an object running in a different Ractor.
-*   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 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)
+## Configuring a wrapper
+
+Ractor::Wrapper supports a fair amount of configuration, which may be needed in
+order to ensure good behavior of the wrapped object. You can configure many
+aspects of Ractor::Wrapper by passing keyword arguments to its constructor.
+Alternatively, you can pass a block to the constructor; the constructor will
+yield a configuration interface to your block, letting you configure the
+wrapper's behavior in detail.
+
+The various configuration options are described below.
+
+### Current Ractor mode
+
+Normally a wrapper will spawn a new Ractor and move the wrapped object into
+that Ractor. We call this default mode the "isolated Ractor" mode. Isolated
+Ractor lets the object function as an actor that can be called uniformly from
+any Ractor.
+
+However, some objects cannot be moved to a different Ractor. This in particular
+can include certain C-based I/O objects such as database connections.
+Additionally, there are other objects that can live only in the main Ractor. If
+the object to be wrapped cannot be moved to its own Ractor, configure it with
+`use_current_ractor`, which will run the wrapper in a Thread in the calling
+Ractor rather than trying to move it to its own Ractor. The SQLite3 example
+above demonstrates wrapping an object that cannot be moved to its own Ractor.
+
+### Sequential vs concurrent execution
+
+By default, wrappers run sequentially in a single Thread. The wrapper will
+handle only a single method call at a time, and any other concurrent requests
+are queued and blocked until their turn. This is the behavior of the classic
+actor model, and in particular is appropriate for wrapped objects that are not
+thread-safe.
+
+You can, however, configure a wrapper with concurrent access. This will spin up
+a configurable number of worker threads within the wrapper, to handle
+potentially concurrent method calls. You should set this configuration only if
+you are certain the wrapped object can handle concurrent access.
+
+### Data communication options
+
+When you call a method on a wrapper, and you pass arguments and receive a
+return value, or you pass a block that can receive arguments and return a
+value, those objects are communicated to and from the wrapper via Ractor ports.
+As such, if they are not shareable, they may be *copied* or *moved*. By
+default, values are copied in order to minimize interference with surrounding
+code, but a wrapper can be configured to move objects instead.
+
+This configuration is done per-method, using the `configure_method` call in the
+configuration block. You can, for particular method names, specify whether each
+type of value: arguments, return values, block arguments, and block return
+values, are copied or moved. For any given method, you must configure all
+arguments to be handled the same way, but different methods can have different
+configurations. You can also provide a default configuration that will apply to
+all method names that are not explicitly configured.
+
+Return values (and block return values) have a third configuration option:
+*void*. This option disables communication of return values, sending `nil`
+instead of what was actually returned from the method. This is intended for
+methods that do not *semantically* need to return anything, but because of
+their implementation they actually do return some internal object. You can use
+the *void* option to prevent those methods from wasting resources copying a
+return object unnecessarily, or worse, moving an object that shouldn't be moved.
+
+### Block execution environment
+
+If a block is passed to a method, it is handled in one of two ways. By default,
+if/when the method yields to the block, the wrapper will send a message *back*
+to the caller, and the block will be executed in the caller's environment. In
+most cases, this is what you want; your block may access information from its
+lexical environment, and that environment would not be available to the wrapped
+object. However, this extra communication can add overhead.
+
+As an alternative, you can configure, per-method, blocks to be executed in the
+context of the *wrapped object*. Effectively, the block itself is *moved* into
+the wrapped object's Ractor/context, and called directly. This will work only
+if the block does not access any information from its lexical context, or
+anything that cannot be accessed from a different Ractor. A block must truly be
+self-contained in order to use this option.
+
+As with data communication options, configuring block execution environment is
+done using the `configure_method` call in the configuration block. You can set
+the environment either to `:caller` or `:wrapped`, and you can do so for an
+individual method or provide a default to apply to all methods not explicitly
+configured.
+
+## Additional features
+
+### Wrapper shutdown
+
+If you are done with a wrapper, you should shut it down by calling `async_stop`.
+This method will initiate a graceful shutdown of the wrapper, finishing any
+pending method calls, and putting the wrapper in a state where it will refuse
+new calls. Any additional method calls will cause a
+`Ractor::Wrapper::StoppedError` to be raised.
+
+Ractor::Wrapper also provides a `join` method that can be called to wait for
+the wrapper to complete its shutdown.
+
+### Wrapped object access
+
+The general intent is that once you've wrapped an object, all access should go
+through the wrapper. In the default "isolated Ractor" mode, the wrapped object
+is in fact *moved* to a different Ractor, so the Ractor system will prevent you
+from accessing it directly. In "current Ractor" mode, the wrapped object is not
+moved, so you technically could continue to access it directly from its
+original Ractor. But beware: the wrapper runs a thread and will be making calls
+to the object from that thread, which may cause you problems if the object is
+not thread-safe.
+
+In "isolated Ractor" mode, after you shut down the wrapper, you can recover the
+original object by calling `recover_object`. Only one Ractor can call this
+method; the object will be moved into the requesting Ractor, and any other
+Ractor that subsequently requests the object will get an exception instead.
+
+In "current Ractor" mode, the object will never have been moved to a different
+Ractor, so any pre-existing references (in the original Ractor) will still be
+valid. In this case, `recover_object` is not necessary and will not be
+available at all.
+
+### Error handling
+
+Ractor::Wrapper provides fairly robust handling of errors. If a method call
+raises an exception, the exception will be passed back to the caller and raised
+there. In the unlikely event that the wrapper itself crashes, it goes through a
+very thorough clean-up process and makes every effort to shut down gracefully,
+notifying any pending method calls that the wrapper has crashed by raising
+`Ractor::Wrapper::CrashedError`.
+
+### Automatic stub conversion
+
+One special case handled by the wrapper is methods that return `self`. This is
+a common pattern in Ruby and is used to allow "chaining" interfaces. However,
+you generally cannot return `self` from a wrapped object because, depending on
+the communication configuration, you'll either get a *copy* of `self`, or
+you'll *move* the object out of the wrapper, thus breaking the wrapper. Thus,
+Ractor::Wrapper explicitly detects when methods return `self`, and instead
+replaces it with the wrapper's stub object. The stub is shareable, and designed
+to have the same usage as the original object, so this should work for most use
+cases.
+
+## Known issues
+
+Ractors are in general somewhat "bolted-on" to Ruby, and there are a lot of
+caveats to their use. This also applies to Ractor::Wrapper, which itself is
+essentially a workaround to the fact that Ruby has a lot of use cases that
+simply don't play well in a Ractor world. Here we'll discuss some of the
+caveats and known issues with Ractor::Wrapper.
+
+### Data communication issues
+
+As of Ruby 4.0, most objects have been retrofitted to play reasonably with
+Ractors. Some objects are shareable across Ractors, and most others can be
+moved from one Ractor to another. However, there are a few objects that,
+because of their semantics or details about their implementation, cannot be
+moved and are confined to their creating Ractor (or in some cases, only the
+main Ractor.) These may include objects such as threads, procs, backtraces, and
+certain C-based objects.
+
+One particular case of note is exception objects, which one might expect to be
+shareable, but are not. Furthermore, they cannot be moved, and even copying an
+exception has issues (in particular the backtrace of a copy gets cleared out).
+See https://bugs.ruby-lang.org/issues/21818 for more info. When a method raises
+an exception, Ractor::Wrapper communicates that exception via copying, which
+means that currently backtraces will not be present.
+
+### Blocks
+
+Ruby blocks pose particular challenges for Ractor::Wrapper because of their
+semantics and some of their common usage patterns. We've already seen above
+that Ractor::Wrapper can run them either in the caller's context or in the
+wrapped object's context, which may limit what the block can do. Additionally,
+the following restrictions apply to blocks:
+
+Blocks configured to run in the caller's context can be run only while the
+method is executing; i.e. they can only be "yielded" to. The wrapped object
+cannot "save" the block as a proc to be run later, unless the block is
+configured to run in the "wrapped object's" context. This is simply because we
+have access to the caller only while the caller is making a method call. After
+the call is done, we no longer have access to that context, and there's no
+guarantee that the caller or its Ractor even exists anymore. In particular,
+this means that the common Ruby idiom of using blocks to define callbacks (that
+run in the context of the code defining the callback) can generally not be done
+through a wrapper.
+
+In Ruby, it is legal (although not considered very good practice) to do a
+non-local `return` from inside a block. Assuming the block isn't being defined
+via a lambda, this causes a return from the method *surrounding* the call that
+includes the block. Ractor::Wrapper cannot reproduce this behavior. Attempting
+to `return` within a block that was passed to Ractor::Wrapper will result in an
+exception.
+
+### Re-entrancy via blocks
+
+One final known issue with Ractor::Wrapper is that it does not currently handle
+re-entrancy resulting from a block making another call to the object. That is,
+if a method on a wrapper is called, and it yields to a block that runs back in
+the caller's context, and that block then makes another method call to the same
+wrapper, now there's a new method call request when the first method is still
+being handled (and blocked because it's yielding to the block). Unless the
+wrapper is configured with enough threads that another thread can pick up the
+new method call, this will deadlock the wrapper: the original method call is
+blocked because the yield is not complete, but the yield will never complete
+because the new method cannot run until the original method has completed.
+
+I believe this issue is solvable by retooling the internal method scheduling to
+use fibers, and I have filed a to-do item to address it in the future
+(https://github.com/dazuma/ractor-wrapper/issues/12). Until then, I do not
+recommend making additional calls to a wrapper from within a yielded block.
 
 ## Contributing
 
@@ -132,11 +467,11 @@ Development is done in GitHub at https://github.com/dazuma/ractor-wrapper.
 
 The library uses [toys](https://dazuma.github.io/toys) for testing and CI. To
 run the test suite, `gem install toys` and then run `toys ci`. You can also run
-unit tests, rubocop, and builds independently.
+unit tests, rubocop, and build tests independently.
 
 ## License
 
-Copyright 2021 Daniel Azuma
+Copyright 2021-2026 Daniel Azuma
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/lib/ractor/wrapper/version.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 class Ractor
   class Wrapper
     ##
@@ -5,6 +7,6 @@ class Ractor
     #
     # @return [String]
     #
-    VERSION = "0.2.0".freeze
+    VERSION = "0.4.0"
   end
 end