https://github.com/dazuma/ractor-wrapper
An experimental Ruby class that wraps a non-shareable object in a Ractor so it can be accessed by multiple Ractors concurrently.
https://github.com/dazuma/ractor-wrapper
ractor ruby
Last synced: 2 months ago
JSON representation
An experimental Ruby class that wraps a non-shareable object in a Ractor so it can be accessed by multiple Ractors concurrently.
- Host: GitHub
- URL: https://github.com/dazuma/ractor-wrapper
- Owner: dazuma
- License: other
- Created: 2021-03-02T07:32:39.000Z (over 5 years ago)
- Default Branch: main
- Last Pushed: 2021-03-12T20:25:16.000Z (about 5 years ago)
- Last Synced: 2024-04-27T02:25:57.998Z (about 2 years ago)
- Topics: ractor, ruby
- Language: Ruby
- Homepage:
- Size: 27.3 KB
- Stars: 2
- Watchers: 2
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.md
Awesome Lists containing this project
README
# Ractor::Wrapper
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.
```sh
gem install ractor-wrapper
```
Require it in your code:
```ruby
require "ractor/wrapper"
```
You can then create wrappers for objects. See the example below.
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.
```ruby
# Net::HTTP example
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
```
### SQLite3 example
The following example shows how to share a SQLite3 database among multiple
Ractors.
```ruby
# SQLite3 example
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.stub) do |stub|
5.times do
stub.execute("select * from numbers")
end
:ok
end
# Wait for the two above Ractors to finish.
r1.join
r2.join
# After stopping the wrapper, you can call the join method to wait for
# it to completely finish.
wrapper.async_stop
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
```
## 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
Development is done in GitHub at https://github.com/dazuma/ractor-wrapper.
* To file issues: https://github.com/dazuma/ractor-wrapper/issues.
* For questions and discussion, please do not file an issue. Instead, use the
discussions feature: https://github.com/dazuma/ractor-wrapper/discussions.
* Pull requests are welcome, but the library is highly experimental at this
stage, and I recommend discussing features or design changes first before
implementing.
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 build tests independently.
## License
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
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
IN THE SOFTWARE.