ractor-wrapper 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9fec3af2b1b8b9c105260fe2fca50d69e48de205dd2dd791592317ee41286af3
-  data.tar.gz: e7b4487502427ec05f3dc530925e9efecd8d599e75f4dc2b82c7371592986f59
+  metadata.gz: 0ceddba72640a063108102f44bf7cf8276305dcfcc4b2807ec24c474997d5dc4
+  data.tar.gz: ec46f0323abf7a8468ae8f4b8db82e47d4f6f906ed169d8853f86c82ba50414b
 SHA512:
-  metadata.gz: 0ab154c16e2ed53f65a042bf18b85448cb0115e6b1616db5cce96084767ae1f00c23392ba48560177f34c43d757b59e282c05891702af927f40f72fe989b33e1
-  data.tar.gz: 8e16f5694e46c571deac8d66f56bb23467572bad838038d941955f2edaca76537ef741df79b63da0bc28c31708a31ac3ba699e3a2a661b56552dc6b1050625a0
+  metadata.gz: 91057acf2a760454fe5864f113f63eadabf54e229b23816784ebdca931be280e85152879ad986ba68100ca49a88d854b856f0af19d69b316a4bcfef09b3d7cdc
+  data.tar.gz: 29b1f2b0713bae3737d168578e832d2c4edabf13181ef927dc8473e5b2eee02357eb61c938eccdf1afec5e803af5add40e35c550530d067178e5493cf67abf84

data/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Release History
 
+### v0.3.0 / 2026-01-05
+
+This is a major update, and the library, while still experimental, is finally somewhat usable. The examples in the README now actually work!
+
+Earlier versions were severely hampered by limitations of the Ractor implementation in Ruby 3. Many of these were fixed in Ruby 4.0, and Ractor::Wrapper has been updated to take advantage of it. This new version requires Ruby 4.0.0 or later, and includes a number of enhancements:
+
+* Support for running a wrapper in the current Ractor, useful for wrapping objects that cannot be moved, or that must run in the main Ractor. (By default, wrapped objects are still moved into an isolated Ractor to maximize cleanliness and concurrency.)
+* Support for running a wrapper sequentially without worker threads. This is now the default behavior, which does not spawn any extra threads in the wrapper. (Earlier behavior would spawn exactly one worker thread by default.)
+* Limited support for passing blocks to a wrapped object. You can cause a block to run "in place" within the wrapper, as long as the block can be made shareable (i.e. does not access any outside data), or have the block run in the caller's context with the cost of some additional communication. You can also configure that communication to move or copy data.
+* Provided Ractor::Wrapper#join for waiting for a wrapper to complete without asking for the wrapped object back.
+* Some of the configuration parameters have been renamed.
+
+Some caveats remain, so please consult the README for details. This library should still be considered experimental, and not suitable for production use. I reserve the right to make breaking changes at any time.
+
 ### v0.2.0 / 2021-03-08
 
 * BREAKING CHANGE: The wrapper now copies (instead of moves) arguments and return values by default.

data/LICENSE.md

@@ -1,6 +1,6 @@
 # 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/README.md

@@ -1,8 +1,11 @@
 # 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 a highly experimental library, and currently _not_
+recommended for production use. (As of Ruby 4.0.0, the same can be said of
+Ractors in general.)
 
 ## Quick start
 
@@ -16,108 +19,170 @@ Require it in your code:
 
 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 _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.
 
-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.)
+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.
 
-## About Ractor::Wrapper
+### 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.
+The following example shows how to share a single Net::HTTP session object
+among multiple Ractors.
+
+```ruby
+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"
-
-# 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 "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. You 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
+# because it hasn't been moved to a different Ractor.
+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 two worker threads will handle the requests in the order
+# received.
+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::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.
 
 ## Contributing
 
@@ -132,11 +197,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.3.0"
   end
 end