farce 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f9534ae8ce778e1baa97d4ea437fb018089cbc304214f4aa5569b32a886dc550
-  data.tar.gz: 6c8a56074af7b93a9966334a64349c7f807a3ae8502a455012bfd93783d98fcb
+  metadata.gz: 606351822ed0519ce92d1027233eec3295633e5107f7f94ac8649222fbb25fc1
+  data.tar.gz: 4f896509b22bd8c18c2864dceda3c46bf8a49f412f88c31ee96eeb00956b9ddb
 SHA512:
-  metadata.gz: ad36956cba3e16dab130e16667a1528ef2d18a623f88f4b3bc9f8283cd4b76fae6dcd6e4f69ce80fe144879ac051f40bc1664917bd572558725c244e90665aee
-  data.tar.gz: c8a548b7e69fc854f791cf6d305e602eebe9f696a3aba21a651a8f7f4e6d721cf3254d93da2ddc4f26db623027c50a93409b673e6472e6cf010b6e3fc31cd30c
+  metadata.gz: 7a0834837c23ed28d44af2a060b0f553f5d41cfdc46b976796cefc1fff5406b976e8358626f51ceabee55755b6589536e39db311c5aeb775077dfe1d99cb97d6
+  data.tar.gz: d74c7e6c959fc09b97c8b5bff1d844b3623c9f698995a05d2f72be175a54f41b769b052287f0dea4e13b7ee97dca0dfcac5925260ee8a6b15443c95c67c20735

data/CHANGELOG.md

@@ -4,6 +4,132 @@ Farce follows [Semantic Versioning 2.0](http://semver.org/). Any public method o
 
 ## Development Releases
 
+### Farce 0.3.0 (2026-10-13)
+
+#### New Features
+
+##### Breaking Changes
+
+* `Abstract::Scheduler` is no longer a superclass of `Pool`. Use `Abstract::Executor` instead.
+
+##### Executor Improvements
+
+`Scheduler` and `Pool` have the following improvements:
+
+* They now support `try_schedule`, which discards tasks and returns `nil` when their internal queues are at capacity.
+* They now have `Unshared` and `Local` variants, running in a Ractor-local context (Pool will manage a Thread pool instead of a Ractor pool).
+
+Creates a thread pool with a maximum size of 2 and a queue capacity of 10:
+
+```ruby
+# A thread pool local to the current Ractor
+thread_pool = Farce::Unshared::Pool.new(max_size: 2, capacity: 10)
+
+# this should only run approximately 10 tasks on CRuby
+500.times { thread_pool.try_schedule { puts "Task executed" } }
+```
+
+##### Tasks
+
+A new class, `Task`, has been introduced to represent asynchronous tasks that can be scheduled and executed within Farce's executor framework,
+executed manually, or handed off to any other executor supporting procs or callable objects.
+
+```ruby
+task = Farce::Task.schedule do
+  puts "Task started"
+  sleep 1
+  :success
+ensure
+  puts "Task finished"
+end
+
+task.alive? # => true
+task.value  # => :success (blocks until the task completes)
+```
+
+#### Bug Fixes
+
+* Calling `wait_*` methods on atoms on JRuby no longer blocks a fiber scheduler.
+
+### Farce 0.2.0 (2026-10-11)
+
+#### New Features
+
+##### Waiting on Flags
+
+You can now wait for a `Farce::Flag` or `Farce::Local::Flag` to change its value:
+
+```ruby
+flag = Farce::Flag.new
+
+Thread.new do
+  flag.wait_until_set
+  puts "Flag has been activated!"
+end
+
+flag.set
+```
+
+##### Timer Queue Entries
+
+`TimerQueue#push` and `TimerQueue#try_push` now return a `TimerQueue::Entry` object on a successful push.
+This allows you to cancel a scheduled value using the returned entry:
+
+```ruby
+queue = Farce::TimerQueue.new
+entry = queue.push(:work, delay: 60)
+entry.delete # => true
+```
+
+##### Expanded Vector Functionality
+
+Improved Array compatibility for `Vector`, `Strict::Vector`, `Unshared::Vector`, and `Local::Vector`:
+
+* Added `to_ary`, `delete`, and `delete_if`.
+* Added range and start/length indexing, slice assignment, multiple-value `push` and `append`, and `pop(count)`.
+* Added `shift`, `unshift`, `prepend`, `insert`, `delete_at`, `slice!`, `replace`, and `fill`.
+* Added `map!`, `collect!`, `keep_if`, `select!`, `filter!`, `reject!`, `compact!`, and `uniq!`.
+* Added `reverse!`, `rotate!`, `shuffle!`, `sort!`, `sort_by!`, and `flatten!`.
+* Added `flatten`, `transpose`, `product`, `combination`, `repeated_combination`, `permutation`, and `repeated_permutation`.
+* Added lexicographic `<=>`. Equality and hashing continue to use object identity.
+
+##### Miscellaneous
+
+* Unshareable objects may now be frozen.
+* Trying to make an unshareable object shareable raises a better error message now (`Ractor::Error` with a descriptive message, instead of a `NoMethodError`).
+* Added a new transfer mode: `:marshal`, which will copy objects between Ractors using Ruby's [Marshal](https://docs.ruby-lang.org/en/4.0/Marshal.html) serialization.
+
+#### Bug Fixes
+
+* Improve compatibility with other gems modifying `Kernel#require`, work around an issue with Ruby 4.0's runtime ractor require patch and alias methods chains not working nicely with `Module#prepend`.
+
+#### Performance Improvements
+
+##### Rework CRuby native extension
+
+Incorporated the advice from ["Tips for updating Ruby C extensions for efficiently using Ruby 4 VM APIs"](https://github.com/ruby/ruby/blob/master/doc/efficient_extensions.md).
+
+With this change, all long-living Farce objects can be compacted and moved to old GC generations. This was not the case previously for maps and vectors that had snapshots taken of them (either for iteration or for transactions). These ended up being permanently kept in young generations. A long-living map or vector would therefore cause frequent GC runs to be quite expensive.
+
+| Operation                                           | Before  | After   | Change      |
+| --------------------------------------------------- | ------- | ------- | ----------- |
+| `Map#each` over 1024 entries                        | 34.1 μs | 35.2 μs | 3% slower   |
+| Transaction with a map with 16 entries              | 25.2 μs | 25.3 μs | 0.4% slower |
+| Transaction with a map with 1024 entries            | 26.7 μs | 29.2 μs | 9% slower   |
+| Transaction with a vector with 10,000 entries       | 26.1 μs | 29.4 μs | 13% slower  |
+| GC while keeping a vector with 10,000 entries alive | 67.6 μs | 28.6 μs | 58% faster  |
+
+Beyond these specific cases:
+* Other iteration methods will have a similar performance impact to `Map#each` (for instance, `Map#transform_values`).
+* Methods not involving iterations, like reading or writing a specific map entry, do not show any measurable performance impact.
+
+Measurements were taken on CRuby 4.0.7 (arm64-darwin23) with YJIT enabled. Measurements taken against Ruby's main branch show similar results.
+
+#### Other changes
+
+* Avoid circular require warnings when automatically loading third-party integrations.
+* Do not install a require hook if automatic integration loading is disabled.
+
 ### Farce 0.1.0 (2026-10-09)
 
-* Initial release
+Initial release.

data/README.md

@@ -117,6 +117,7 @@ puts output
       - [`Farce.schedule`](#farceschedule)
       - [Schedulers](#schedulers)
       - [Ractor Pools](#ractor-pools)
+      - [Tasks](#tasks)
       - [Third-Party Fiber Schedulers](#third-party-fiber-schedulers)
     - [Integrations](#integrations)
       - [Active Support](#active-support)
@@ -133,6 +134,7 @@ puts output
       - [Constants](#constants)
   - [Compatibility and Dependencies](#compatibility-and-dependencies)
     - [Ruby](#ruby)
+    - [Optional Dependencies](#optional-dependencies)
     - [Similar Projects](#similar-projects)
   - [Installation](#installation)
     - [Globally](#globally)
@@ -415,6 +417,23 @@ list.to_a # => [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
 list.sum  # => 45
 ```
 
+There is one important difference to arrays: Bulk mutations, such as `Vector#map!` are atomic. Either the block succeeds for all entries, or if it raises an exception then none of the changes are applied. Such mutations may also not write to the same vector from within the block.
+
+```ruby
+list = Farce::Vector[1, 2, 3, 4]
+
+begin
+  list.map! do |value|
+    raise "error" if value == 2
+    value * 2
+  end
+rescue => e
+end
+
+# This would return 2 if list was an array
+list.first # => 1
+```
+
 #### Sets
 
 `Farce::Set` is to `Set` what `Farce::Map` is to `Hash`. It implements the same interface, with additional atomic operations.
@@ -536,7 +555,7 @@ end
 
 #### Queues
 
-`Farce::Queue` is a drop-in replacement for Ruby's `Queue` and `SizedQueue`. It provides a blocking and a non-blocking API.
+`Farce::Queue` is an alternative to Ruby's `Queue` and `SizedQueue`. It provides a superset of their API, offering both blocking and a non-blocking API, while implementing Ractor-sharing via [sharing modes](#sharing-modes).
 
 ```ruby
 queue = Farce::Queue.new
@@ -569,7 +588,7 @@ queue.pop # => :b
 
 ##### Timer Queues
 
-Timer queues are similar to priority queues, sorted by float values, but these values are timestamps (based on [Farce::Clock](#additional-classes), not on Ruby's Time, which isn't monotonic). Any `pull` will block until the next timestamp has been reached.
+Timer queues are similar to priority queues, sorted by float values, but these values are timestamps (based on [Farce::Clock](#additional-classes), not on Ruby's Time, which isn't monotonic). Any `pop` will block until the next timestamp has been reached.
 
 ```ruby
 queue = Farce::TimerQueue.new
@@ -579,7 +598,16 @@ queue.push(:ok, in: 1.5)
 queue.pop # => :ok
 ```
 
-Timer queues are useful for implementing schedulers (which is what Farce uses them for under the hood), so they have one additional feature: You can delete an entry if you know its timestamp.
+Timer queues are useful for implementing schedulers (which is what Farce uses them for under the hood). Both `push` and `try_push` return a cancellation handle when they succeed. Use `entry.delete` or `queue.delete(entry)` to cancel a scheduled value. The handle exposes its `queue` and scheduled `clock` time.
+
+```ruby
+queue = Farce::TimerQueue.new
+entry = queue.push(:work, in: 60)
+
+entry.delete # => true
+```
+
+You can also delete a value if you know its timestamp:
 
 ```ruby
 queue     = Farce::TimerQueue.new
@@ -589,6 +617,9 @@ queue.push(:first,  at: timestamp - 0.1)
 queue.push(:second, at: timestamp)
 queue.push(:third,  at: timestamp + 0.1)
 
+fourth = queue.push(:fourth, at: timestamp + 0.2)
+queue.delete(fourth)
+
 queue.delete(:second, at: timestamp)
 
 result = []
@@ -601,7 +632,7 @@ result # => [:first, :third]
 Queues support setting a maximum capacity. If the capacity has been reached it will block any pushes to create back pressure.
 
 ```ruby
-queue = Farce::Queue.new(2)
+queue = Farce::Queue.new(capacity: 2)
 
 queue.try_push(:a) # => true
 queue.try_push(:b) # => true
@@ -683,17 +714,22 @@ The [default variants](#variants-and-scopes) of most [data structures](#data-str
 
 These modes are:
 
-| Mode              | What happens to non-shareable data                                                   | A typical use                               |
-| ----------------- | ------------------------------------------------------------------------------------ | ------------------------------------------- |
-| `:copy` (default) | Transfers a copy and leaves the original usable. This is the default.                | Send a snapshot of a request.               |
-| `:move`           | Transfers ownership and makes the original inaccessible.                             | Hand a completed batch to a consumer.       |
-| `:local`          | Keeps the same object in its originating Ractor.                                     | Pass work between local threads or fibers.  |
-| `:make_shareable` | Calls `Ractor.make_shareable` on the original.                                       | Publish finished configuration.             |
-| `:mutable`        | Copies non-shareable objects into a [`Farce::Mutable`](#mutables).                   | Synchronize mutations across Ractors.       |
-| `:shareable_copy` | Makes a shareable copy and leaves the original alone.                                | Publish a snapshot of an editable document. |
-| `:dedup`          | Deduplicates the value, then makes it shareable. May update and freeze the original. | Reuse repeated message contents.            |
-| `:proxy`          | Creates a [`Farce::Proxy`](#proxies) that executes calls in the original Ractor.     | Share access to a mutable object.           |
-| `:raise`          | Raises `Ractor::IsolationError`.                                                     | Enforce a shareable-data boundary.          |
+| Mode | What happens to non-shareable data | A typical use |
+| --- | --- | --- |
+| `:smart` (default) | Applies smart rules or a dedicated proxy, raising for unsupported values. | Share supported values with less copying. |
+| `:smart_raise` | Applies smart rules or a dedicated proxy, with a raising fallback. | Reject unsupported transfers. |
+| `:smart_copy` | Applies smart rules or a dedicated proxy, then tries copying and Marshal. Default for `Farce::Port`. | Send values with a copying fallback. |
+| `:smart_move` | Applies smart rules or a dedicated proxy, then tries moving. | Hand off unsupported values. |
+| `:copy` | Transfers a copy and leaves the original usable. | Send a snapshot of a request. |
+| `:marshal` | Serializes a snapshot and reconstructs it once per receiving Ractor. | Transfer an Unshared container.|
+| `:move` | Transfers ownership and makes the original inaccessible. | Hand a completed batch to a consumer. |
+| `:local` | Keeps the same object in its originating Ractor. | Pass work between local threads or fibers. |
+| `:make_shareable` | Calls `Ractor.make_shareable` on the original. | Publish finished configuration. |
+| `:mutable` | Copies non-shareable objects into a [`Farce::Mutable`](#mutables). | Synchronize mutations across Ractors. |
+| `:shareable_copy` | Makes a shareable copy and leaves the original alone. | Publish a snapshot of an editable document. |
+| `:dedup` | Deduplicates the value, then makes it shareable. May update and freeze the original. | Reuse repeated message contents. |
+| `:proxy` | Creates a [`Farce::Proxy`](#proxies) that executes calls in the original Ractor. | Share access to a mutable object. |
+| `:raise` | Raises `Ractor::IsolationError`. | Enforce a shareable-data boundary. |
 
 Here's an example:
 
@@ -974,7 +1010,7 @@ list = Farce::Vector.new
 list[0] = 42
 
 # Atomically replace list[0] with 256 if the value is still 42
-list.compare_and_swap(0, 42, 256)
+list.compare_and_set(0, 42, 256)
 ```
 
 #### Observability and Signaling
@@ -1187,6 +1223,43 @@ pool = Farce::Pool.new(min_size: 4, max_size: 10, grow_after: 0.1)
 pool.schedule { puts "Hello from the pool!" }
 ```
 
+#### Tasks
+
+If you want to retrieve the result of an asynchronous operation, or monitor if it is still running, you can use `Farce::Task`:
+
+```ruby
+task = Farce::Task.schedule(1, 2) do |a, b|
+  sleep 1 # simulate intense computation
+  a + b
+end
+
+task.alive? # => true
+task.value  # => 3 (after approximately 1 second)
+task.join   # would block, but doesn't, as the task has already completed
+```
+
+Tasks can also be created without immediately scheduling them, allowing you to control when and how they are executed:
+
+```ruby
+task = Farce::Task.new { :success }
+task.alive?     # => true
+task.value(0.1) # => nil (after 100 milliseconds)
+
+Farce.schedule(&task)
+task.value # => :success
+```
+
+This allows you to use third-party executors:
+
+```ruby
+require "concurrent"
+executor = Concurrent.global_fast_executor
+task     = Farce::Task.new { :success }
+executor.post(&task)
+
+task.value # => :success
+```
+
 #### Third-Party Fiber Schedulers
 
 Both `Farce::Scheduler` and `Farce::Pool` run a Fiber scheduler under the hood to execute tasks. This is a Farce-internal scheduler by default, but you can replace it with your own if you want:
@@ -1385,7 +1458,7 @@ Other classes Farce provides include:
 * `Exchanger`: A synchronization point for two-way data swapping between Threads, Ractors, and/or Fibers. Drop-in replacement for concurrent-ruby's exchanger.
 * `Lazy`: Lazily initialized value.
 * `LazyRef`: A [reference](#references) for a lazily initialized value.
-* `ThreadScheduler`: An alternative [scheduler](#scheduling-code) creating a new thread for each unit of work. Used on TruffleRuby.
+* `ThreadExecutor`: A [task executor](#scheduling-code) creating a new thread for each unit of work. Used on TruffleRuby.
 * `Walker`: A tool for walking a Ruby object tree.
 * `WeakValue`: A value object version of [`WeakRef`](#weakref). Allows handling references more explicitly, without automatic method delegation.
 
@@ -1433,6 +1506,27 @@ Moreover:
 * Dropping support for a CRuby version is only done in major releases.
 * If support for an older CRuby version is dropped, Farce will still backport security fixes for at least as long as that CRuby version is [still receiving security fixes](https://www.ruby-lang.org/en/downloads/branches/).
 
+### Optional Dependencies
+
+Farce's optional [integrations](#integrations) depend on external libraries. Automated tests only run against recent versions of these libraries, but the code is written to be compatible with as wide a range as possible.
+
+Farce should be compatible with these versions:
+
+| Gem               | Minimum Version | Release Date |
+|-------------------|-----------------|--------------|
+| `ractor-tmvar`    | 0.3.0           | 2026-10-06   |
+| `msgpack`         | 1.7.0           | 2023-03-29   |
+| `concurrent-ruby` | 1.1.8           | 2021-01-20   |
+| `dry-types`       | 1.0.0           | 2019-04-23   |
+| `activesupport`   | 5.1.0           | 2017-04-27   |
+| `oj`              | 2.8.1           | 2014-04-21   |
+| `bson`            | 2.0.0           | 2013-12-02   |
+| `psych`           | 1.1.0           | 2011-03-30   |
+
+Any version of `cbor`, `json`, `ractor-sharing`, `sorted_set`, and `weakref` should be supported
+
+If you want to use any of these in a version that is incompatible with Farce, you can [disable automatic integration loading](#disable-automatic-loading).
+
 ### Similar Projects
 
 * [ractor-shim](https://github.com/eregon/ractor-shim/) provides similar functionality to `Farce::Ractor`. See [the comparison document](docs/gems/ractor-shim.md) for more details.

data/docs/gems/dry-types.md

@@ -49,7 +49,7 @@ end
 numbers = Types::IntegerVector[["1", 2]]
 numbers.class # => Farce::Vector
 numbers.to_a  # => [1, 2]
-numbers.mode  # => :copy
+numbers.mode  # => :smart
 ```
 
 The bare `Vector` accepts any Array members. Imported dry namespaces control
@@ -243,8 +243,7 @@ and dry-types' `Strict` namespace configure separate parts of the conversion.
 | `:local` | `Farce::Local::Vector`, `Farce::Local::Map`, `Farce::Local::Set`, `Farce::Local::Counter`, `Farce::Local::Flag`, `Farce::Local::Atom` |
 
 The integration imports only classes that Farce provides for the selected
-variant. Strict has an Atom but no Counter or Flag. Unshared has none of these
-three scalar-backed types.
+variant.
 
 For a single shared collection type, use `.with(mode: ...)`:
 
@@ -258,10 +257,11 @@ vector = Types::LocalValueVector[[payload]]
 vector[0].equal?(payload) # => true
 ```
 
-The supported shared modes are `:copy`, `:local`, `:make_shareable`,
-`:shareable_copy`, and `:raise`. They apply to collections and Atom. Counter and
-Flag have no transfer mode. `:move` is rejected because dry-types creates and
-examines intermediate values during coercion.
+The supported shared modes are `:smart`, `:smart_raise`, `:smart_copy`,
+`:copy`, `:local`, `:make_shareable`, `:shareable_copy`, and `:raise`.
+The default is `:smart`. They apply to collections and Atom. Counter and Flag have
+no transfer mode. `:move` and `:smart_move` are rejected because dry-types creates
+and examines intermediate values during coercion.
 
 ## Farce input and ownership
 
@@ -278,7 +278,7 @@ converted.to_a # => [1]
 ```
 
 The explicit read establishes where transfer and ownership happen. This rule
-also applies when the container's default mode is `:copy` because an individual
+also applies when the container's default mode is `:smart` because an individual
 entry might have been inserted with `mode: :move`.
 
 Vector materialization uses its normal snapshot. Map and set materialization

data/docs/modes.md

@@ -14,7 +14,9 @@ This improves over the default control via `Ractor::Port`'s `move:` option.
   - [Introduction: What Ruby gives you](#introduction-what-ruby-gives-you)
       - [What `move: true` does on `Ractor::Port`](#what-move-true-does-on-ractorport)
   - [Farce's Modes](#farces-modes)
+    - [Smart modes: apply rules before transferring](#smart-modes-apply-rules-before-transferring)
     - [`:copy`: keep working with the original](#copy-keep-working-with-the-original)
+    - [`:marshal`: reconstruct a serialized snapshot](#marshal-reconstruct-a-serialized-snapshot)
     - [`:move`: hand off a finished batch](#move-hand-off-a-finished-batch)
     - [`:local`: preserve object identity](#local-preserve-object-identity)
     - [`:make_shareable`: publish the original](#make_shareable-publish-the-original)
@@ -76,7 +78,7 @@ port.receive # => [4, 5]
 port.close
 ```
 
-Farce extends this choice with nine named modes.
+Farce extends this choice with fourteen named modes.
 
 ## Farce's Modes
 
@@ -84,7 +86,12 @@ The following modes are accepted by `Farce::Port`. They apply to non-shareable v
 
 | Mode | What happens to non-shareable data | A typical use |
 | --- | --- | --- |
-| `:copy` (default) | Transfers a copy and leaves the original usable. This is the default. | Send a snapshot of a request. |
+| `:smart` | Applies smart rules or a dedicated proxy. Raises for unsupported values. Default for most mode-backed classes. | Share supported values with less copying. |
+| `:smart_raise` | Applies smart rules or a dedicated proxy, with a raising fallback. | Reject unsupported transfers. |
+| `:smart_copy` | Applies smart rules or a dedicated proxy, then tries copying and Marshal. Default for `Farce::Port`. | Send values with a copying fallback. |
+| `:smart_move` | Applies smart rules or a dedicated proxy, then tries moving. | Hand off unsupported values. |
+| `:copy` | Transfers a copy and leaves the original usable. | Send a snapshot of a request. |
+| `:marshal` | Serializes a snapshot and reconstructs it once per receiving Ractor. | Transfer an Unshared container with fresh storage. |
 | `:move` | Transfers ownership and makes the original inaccessible. | Hand a completed batch to a consumer. |
 | `:local` | Keeps the same object in its originating Ractor. | Pass work between local threads or fibers. |
 | `:make_shareable` | Calls `Ractor.make_shareable` on the original. | Publish finished configuration. |
@@ -94,12 +101,38 @@ The following modes are accepted by `Farce::Port`. They apply to non-shareable v
 | `:proxy` | Creates a `Farce::Proxy` that executes calls in the original Ractor. | Share access to a mutable object. |
 | `:raise` | Raises `Ractor::IsolationError`. | Enforce a shareable-data boundary. |
 
+### Smart modes: apply rules before transferring
+
+Most mode-backed classes default to `:smart`. `Farce::Port` defaults to `:smart_copy` so values without a suitable rule or dedicated proxy can still be copied. Classes with restricted weak-value modes keep their `:raise` default.
+
+Smart modes pass already-shareable values through unchanged. Mutable strings become frozen, deduplicated strings without freezing the source string. Time values are made shareable in place. The Date integration does the same for Date and DateTime values.
+
+With `:smart`, arrays and Ruby sets containing only shareable elements are made shareable in place. Symbol-keyed hashes containing only shareable values are made shareable in every smart mode. This can freeze the original, including with `:smart_copy` and `:smart_move`.
+
+For arrays and Ruby sets, `:smart_copy` makes a shallow copy and tries to prepare each element with `:smart_raise`. If all results are directly usable, it makes that copy shareable. Otherwise, it copies the original graph, preserving aliases and cycles. If native copying raises a standard error, it tries Marshal reconstruction. If both fail, it raises the original copying error. It does not recursively insert managed envelopes into the container. Identity-based Farce sets use the prepared element for membership and reject a copying envelope fallback.
+
+A dedicated proxy applies only to the exact registered class. Smart rules inherit through the source class hierarchy and can customize individual smart modes. Without applicable behavior, `:smart` and `:smart_raise` raise `Ractor::IsolationError`, `:smart_copy` tries copying and Marshal, and `:smart_move` tries moving.
+
+```ruby
+class Job
+  attr_reader :id
+  def initialize(id) = @id = id
+end
+
+Farce::ModeManager::SmartRule.define(Job, :marshal)
+queue = Farce::Queue.new
+queue << Job.new(42)
+queue.pop.id # => 42
+```
+
+Use an explicit `:copy` mode when callers need independently mutable copies even for values that smart rules could make shareable. On JRuby and TruffleRuby, ordinary values are already shareable and pass through unchanged.
+
 ### `:copy`: keep working with the original
 
 Copying is a good starting point for ordinary hashes, arrays, and strings. The receiver can change its copy without changing the sender's data. Shareable parts of the message can still be reused.
 
 ```ruby
-port = Farce::Port.new
+port = Farce::Port.new(mode: :copy)
 request = { ids: [10, 20] }
 port.send(request)
 request[:ids] << 30
@@ -113,6 +146,27 @@ port.close
 
 Copying is not a way to serialize every Ruby object. Some objects cannot be copied across Ractors. Choose a mode that fits the value, or send ordinary data from which the receiver can build what it needs.
 
+### `:marshal`: reconstruct a serialized snapshot
+
+Use `:marshal` for values with a Marshal representation, including `Farce::Unshared` containers whose backends cannot be copied directly between native Ractors. Farce calls `Marshal.dump` when preparing the value. A shareable envelope holds the frozen bytes. The first read in each Ractor calls `Marshal.load`, then caches that Ractor's reconstructed value.
+
+```ruby
+port = Farce::Port.new(mode: :marshal)
+source = Farce::Unshared::Map.new({ jobs: [] })
+port.send(source)
+source[:jobs] << :sender_change
+
+received = port.receive
+received[:jobs] # => []
+received[:jobs] << :receiver_change
+source[:jobs]   # => [:sender_change]
+port.close
+```
+
+Farce's Marshal hooks rebuild containers from logical contents and settings. The receiver gets fresh backend storage and synchronization state. Repeated references and supported cycles within the serialized graph are preserved. A reconstructed Unshared container remains unshareable.
+
+Contents must support Marshal. Procs, anonymous classes, and live coordination objects such as queues and leases cannot be serialized. A serialization failure raises `TypeError` before the value is sent or stored. Unlike native Ractor copying, Marshal may also reconstruct nested shareable objects. Top-level shareable values still pass through unchanged.
+
 ### `:move`: hand off a finished batch
 
 Moving is useful when a producer has finished building a message and will never use it again. It avoids copying the payload. Do not retain a plan to reuse the original or its moved nested objects after sending.
@@ -262,7 +316,7 @@ proxy.length # => 1
 port.close
 ```
 
-Each delegated call involves a request and response. Non-shareable arguments and return values are copied by default, while methods that return the original object return its proxy. Keep the owning Ractor alive while callers use the proxy. Calls raise `Farce::Ractor::RemoteError` after the owner exits. Access through other references to the original object still needs its own coordination.
+Each delegated call involves a request and response. Arguments and return values use `:smart` rules by default. Unsupported values raise unless a wrapper selects another mode. Methods that return the original object return its proxy. Keep the owning Ractor alive while callers use the proxy. Calls raise `Farce::Ractor::RemoteError` after the owner exits. Access through other references to the original object still needs its own coordination.
 
 On JRuby and TruffleRuby, ordinary values are already shareable, so this mode passes them through without creating a proxy.
 
@@ -326,7 +380,7 @@ Automatic local transfer takes precedence even over an explicit `mode:` or `move
 
 ## Other classes that support modes
 
-The same choices appear in several Farce APIs. Containers normally default to `:copy` and unwrap their managed values when you read them. Setting a container's mode does not make the values it returns shareable.
+The same choices appear in several Farce APIs. Containers normally default to `:smart` and unwrap their managed values when you read them. Setting a container's mode does not make the values it returns shareable.
 
 | Class | Where to select a mode | What it controls |
 | --- | --- | --- |
@@ -337,6 +391,7 @@ The same choices appear in several Farce APIs. Containers normally default to `:
 | `Farce::WeakAtom` | `new`, `store`, `update`, and other replacement operations | Weakly held values. Supports only `:raise`, `:make_shareable`, and `:dedup`. Defaults to `:raise`. |
 | `Farce::Atom` | `new`, `store`, `swap`, `update`, and other replacement operations | The stored value. |
 | `Farce::Lazy`, `Farce::LazyRef` | `new` | The result computed once by the factory. |
+| `Farce::Task` | `new`, `schedule`, `try_schedule`, `in_parallel`, `on_main`, `add_argument` | Arguments and the successful result. `add_argument` overrides the mode for one argument. Scheduling can select local mode automatically. |
 | `Farce::Molecule` | `define`, `new` | Newly created field atoms. |
 | `Farce::Vector` | `new`, `push`, `store`, `update`, and other replacement operations | Element values. |
 | `Farce::WeakSet` | `new`, `add`, `add?` | Weakly held elements. Supports only `:raise`, `:make_shareable`, and `:dedup`. Defaults to `:raise`. |
@@ -346,9 +401,11 @@ The same choices appear in several Farce APIs. Containers normally default to `:
 | `Farce::TreeMap` | `new` | Values only. Keys follow the tree map's own rules. |
 | `Farce::LRUMap` | `new` | Values only. Individual value hits and writes update eviction order. |
 | `Farce::LFUMap` | `new` | Values only. Individual value hits and writes update eviction frequency. |
-| `Farce::Scheduler` | `schedule` | Task arguments, with automatic local transfer enabled by default. |
-| `Farce::ThreadScheduler` | `schedule`, `execute` | Accepts scheduler options but always keeps arguments local. |
-| `Farce::Pool` | `schedule` | Task arguments. `:local` is rejected. |
+| `Farce::Scheduler` | `schedule`, `try_schedule` | Task arguments, with automatic local transfer enabled by default. |
+| `Farce::Unshared::Scheduler`, `Farce::Local::Scheduler` | `schedule`, `try_schedule`, `execute` | Always local. With `auto_local: false`, only `:local` and smart modes are accepted. |
+| `Farce::ThreadExecutor` | `schedule`, `try_schedule`, `execute` | Accepts scheduler options but always keeps arguments local. |
+| `Farce::Pool` | `schedule`, `try_schedule` | Task arguments. `:local` is rejected. |
+| `Farce::Unshared::Pool`, `Farce::Local::Pool` | `schedule`, `try_schedule`, `execute` | Always local. With `auto_local: false`, only `:local` and smart modes are accepted. |
 
 `Farce::Lazy` runs its shareable factory once and applies the mode to the result. With
 `:copy`, each Ractor receives its own cached copy. Use `Farce::Strict::Lazy` when the
@@ -394,7 +451,7 @@ retries.push({ attempt: 2 }, at: Farce::Clock.now, mode: :make_shareable)
 Farce::Ractor.shareable?(retries.pop) # => true
 ```
 
-Wrapping happens before waiting for queue space or an exchange partner. A failed `try_push` or a timeout can therefore leave a value moved or frozen. Use copying when you need to retain the original for a retry. Also, reading a moved payload can claim it: `TimerQueue#peek` opens the payload even though it leaves the item queued.
+Wrapping happens before waiting for queue space or an exchange partner. A failed `try_push` or a timeout can therefore leave a value moved or frozen. Use copying when you need to retain the original for a retry. Also, reading a moved payload can claim it: `TimerQueue#peek` opens the payload even though it leaves the item queued. Cancelling a timer through the handle returned by `push` or `try_push` does not open or claim the payload.
 
 ### Exchange mutable messages with a partner
 
@@ -487,7 +544,7 @@ For containers that retain values, `:copy` gives each Ractor its own copy of a s
 
 ### Pass task data as arguments
 
-`Scheduler#schedule` and `Pool#schedule` accept `mode:` for task arguments. Pass mutable data as arguments instead of capturing it from the surrounding scope. A non-local task's block must be convertible to a shareable proc.
+Schedulers and pools accept `mode:` for task arguments in `schedule` and `try_schedule`. Pass mutable data as arguments instead of capturing it from the surrounding scope. A non-local task's block must be convertible to a shareable proc.
 
 ```ruby
 pool = Farce::Pool.new(max_size: 2)
@@ -503,7 +560,7 @@ pool.close
 results.close
 ```
 
-A scheduler defaults to `auto_local: true`, preserving the block and its arguments when scheduling from its owning Ractor. Set `auto_local: false` to enforce the requested mode there. A pool may choose another Ractor for any task, so it rejects `:local` and does not apply automatic local transfer.
+A scheduler defaults to `auto_local: true`, preserving the block and its arguments when scheduling from its owning Ractor. Set `auto_local: false` to enforce the requested mode there. `Farce::Pool` may choose another Ractor for any task, so it rejects `:local` and does not apply automatic local transfer. If you want a Pool with `local` support, use `Farce::Unshared::Pool` or `Farce::Local::Pool` instead.
 
 ## Under the hood
 
@@ -521,20 +578,23 @@ envelope.value[:ids]                  # => [1, 2]
 envelope.value.equal?(envelope.value) # => true
 ```
 
-`Envelope.new` defaults to `:copy` and accepts `:copy`, `:move`, or `:local`. These are envelope types, not the full set of manager modes. A shareable payload produces an `Envelope::Share`. The other manager modes either prepare shareable data directly or raise an error.
+`Envelope.new` defaults to `:copy` and accepts `:copy`, `:marshal`, `:move`, or `:local`. These are envelope types, not the full set of manager modes. A shareable payload produces an `Envelope::Share`. The other manager modes either prepare shareable data directly or raise an error.
 
 ### When copying and moving happen
 
 A copy envelope copies its non-shareable payload into internal storage when created. Each Ractor that opens it gets another copy, cached for that Ractor. A move envelope moves the payload into storage immediately, then moves it out when the winning Ractor first opens it. Forwarding either envelope does not add a payload copy or move at every hop.
 
+A Marshal envelope serializes its payload when created. Each Ractor that opens it reconstructs one value from the same frozen bytes and caches it. Forwarding the envelope does not serialize or reconstruct its payload again.
+
 | Envelope | Who can open it? | What repeated reads return |
 | --- | --- | --- |
 | `Envelope::Copy` | Any Ractor. | That Ractor's cached copy. |
+| `Envelope::Marshal` | Any Ractor. | That Ractor's cached reconstruction. |
 | `Envelope::Move` | The first Ractor to claim it. | The owning Ractor's received object. |
 | `Envelope::Local` | Its creating Ractor. | The original object. |
 | `Envelope::Share` | Any Ractor. | The shared payload. |
 
-A claim belongs to a Ractor, not a thread or fiber, and cannot be revoked. `claim` returns the envelope on success or `nil` if another Ractor owns it. `claim!` and `value` raise `Farce::Envelope::AlreadyClaimed` on failure. Use `claimed?` to ask whether it has an owner and `owned?` to ask whether the current Ractor can open it. Copy and share envelopes report both as true because every Ractor can open them.
+A claim belongs to a Ractor, not a thread or fiber, and cannot be revoked. `claim` returns the envelope on success or `nil` if another Ractor owns it. `claim!` and `value` raise `Farce::Envelope::AlreadyClaimed` on failure. Use `claimed?` to ask whether it has an owner and `owned?` to ask whether the current Ractor can open it. Copy, Marshal, and share envelopes report both as true because every Ractor can open them.
 
 ### Forward envelopes without opening them
 
@@ -573,7 +633,7 @@ Both queues accept the envelope in `:raise` mode because the wrapper is shareabl
 
 ### Mode managers prepare values and open their own envelopes
 
-`Farce::ModeManager` provides two core operations: `wrap` prepares a value for shared storage, and `unwrap` retrieves values from envelopes that this manager created. It passes already-shareable values through unchanged. For non-shareable values, `:copy`, `:move`, and `:local` create managed envelopes. The remaining modes prepare shareable data directly, create a `Farce::Mutable` or `Farce::Proxy`, or raise. Mutable and proxy wrappers remain wrapped when read.
+`Farce::ModeManager` provides two core operations: `wrap` prepares a value for shared storage, and `unwrap` retrieves values from envelopes that this manager created. It passes already-shareable values through unchanged. For non-shareable values, `:copy`, `:marshal`, `:move`, and `:local` create managed envelopes. Smart modes choose their representation through rules, dedicated proxies, and their fallback behavior. The remaining modes prepare shareable data directly, create a `Farce::Mutable` or `Farce::Proxy`, or raise. Mutable and proxy wrappers remain wrapped when read.
 
 ```ruby
 manager = Farce::ModeManager.new(mode: :copy)
@@ -602,7 +662,7 @@ Keep one manager per instance when building an abstraction around shareable stor
 class WorkInbox
   include Farce::Shareable
 
-  def initialize(mode: :copy)
+  def initialize(mode: :smart)
     @manager = Farce::ModeManager.new(mode: mode)
     @storage = Farce::Queue.new(mode: :raise)
     super()

data/docs/scopes.md

@@ -238,7 +238,7 @@ Pass the needed data as task arguments when crossing an execution boundary. Use
 
 ## Classes that support scopes
 
-These classes accept the same five scopes. The scope determines which backing container or resource an operation uses. Each class retains its own behavior, such as queue ordering or weak references.
+The classes in this table accept the same five scopes. The scope determines which backing container or resource an operation uses. Each class retains its own behavior, such as queue ordering or weak references.
 
 | Class | What each scope gets |
 | --- | --- |
@@ -266,6 +266,8 @@ These classes accept the same five scopes. The scope determines which backing co
 | `Farce::Local::Lease` | An independently initialized resource to borrow. |
 | `Farce::Local::LeaseMap` | An independently initialized set of named resources. |
 | `Farce::Local::LeasePool` | A pool with its own resources and capacity. |
+| `Farce::Local::Scheduler` | A task scheduler with its own worker and lifecycle. |
+| `Farce::Local::Pool` | An elastic pool of thread workers with independent scaling and lifecycle. |
 
 ### Count within each scope