farce 0.4.1 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: daac1fc9dbb66e9473f1a61dc6fcaf4a4a0875a9c9f98670d47759d450f2b248
-  data.tar.gz: 3991bfd67d083fe58cd0e808f810e49809d667c11a005f68e63887cd29038b79
+  metadata.gz: 0010e09d494cac546062e8d36c1a5f4479b31210f429ab07ec02d7fa04044418
+  data.tar.gz: d09a395c757a2ad0e90725b53a45703706a092c94f800b59b6fdd51611939697
 SHA512:
-  metadata.gz: 0cbcf7e5769c5084198c06576d27d919501c5a54eafaacd0dccb8d268db416e784ac3556e773a64a4380a4f5c18cbe65fdedfb040ec5c4b0342c75d68eddaae0
-  data.tar.gz: 142f08011fd2704395a1d7ed3f04366e425f9f6a539ef525206b41c14707b03abc4f71d62c53ddcd1a634d11ddf1bcf14f62da034eec94b86ff31905069c78b2
+  metadata.gz: '019155c1fdddbbb9a26aef82fcb399cb409e7e3aa25b462961b3b8b9998ec6ec7b077ceb44e71177a9ab5c2d2952cfe21affe9b989fecc6c4c1f390b2765219a'
+  data.tar.gz: 0babf9eccef51c77c3a936322f105789c724ffb3a43412250fd781e4292e1ca4f341fdba35f9989599625b38fc8020439813c20b666160b21e557dcd37f2700b

data/CHANGELOG.md

@@ -2,9 +2,87 @@
 
 Farce follows [Semantic Versioning 2.0](http://semver.org/). Any public method on any public class or module documented in the README or via YARD and not declared private is part of the public API.
 
-## Development Releases
+## Overview
 
-### Farce 0.4.1 (2026-10-16)
+ Version                        | Date       | Important Changes
+--------------------------------|------------|--------------------------------------
+ [0.5.0](#farce-050-2026-10-21) | 2026-10-21 | Publishers, memoization, pool and queue resizing, and better concurrent-ruby compatibility
+ [0.4.1](#farce-041-2026-10-18) | 2026-10-18 | Include improved io_uring support in prebuilt Linux binaries
+ [0.4.0](#farce-040-2026-10-16) | 2026-10-16 | Introduce `Farce::Backports`
+ [0.3.0](#farce-030-2026-10-13) | 2026-10-13 | Introduce `Farce::Task` and executor improvements
+ [0.2.0](#farce-020-2026-10-11) | 2026-10-11 | Improvements for flags, vectors, and timer queues, and performance
+ [0.1.0](#farce-010-2026-10-09) | 2026-10-09 | Initial release
+
+## Release History
+
+### Farce 0.5.0 (2026-10-21)
+
+#### New Features
+
+##### Publishers
+
+`Farce::Publisher` broadcasts messages to multiple subscribers. It supports Ractors, ports, queues, atoms, counters, flags, collections, signals, other publishers, and callbacks.
+
+```ruby
+publisher = Farce::Publisher.new
+counter   = Farce::Counter.new
+queue     = Farce::Queue.new
+
+publisher.subscribe(counter)
+publisher.subscribe(queue)
+publisher.publish(:hello)
+
+counter.value # => 1
+queue.pop     # => :hello
+```
+
+##### Memoization
+
+Added `Farce::Memoize` for memoization with scopes, transfer modes, and weak values, including after freezing.
+
+```ruby
+class MyClass
+  include Farce::Memoize
+
+  # Memoize #expensive_method, shared across Ractors
+  memoize def expensive_method = expensive_computation
+
+  # Memoize #method_with_unsharable_value for each Ractor separately
+  def method_with_unsharable_value = unsharable_computation
+  memoize :method_with_unsharable_value, scope: :ractor
+end
+```
+
+##### Better `concurrent-ruby` Compatibility
+
+* Added `Farce::Concurrent`, with replacements for `CountDownLatch`, `CyclicBarrier`, `Event`, `FiberLocalVar`, `ThreadLocalVar`, `LockLocalVar`, and `Tuple`, plus aliases for existing Farce classes.
+* Maps now support all public API methods of `Concurrent::Map`.
+* Added `Counter#update` to atomically replace the value using a block.
+* Added `true?`, `false?`, `make_true`, and `make_false` to flags.
+
+##### Queue and Pool Tuning
+
+* Queues, priority queues, timer queues, schedulers, and pools now support resizing.
+* Pools now support tuning after construction. Increasing the minimum starts workers immediately. Excess workers retire when idle without interrupting running tasks.
+* Added `parallel_pool_*` configuration options for the shared CRuby pool used by `Farce.in_parallel`.
+
+##### Miscellaneous
+
+* Added `timeout:` to executor `schedule` and `execute` methods.
+* Added `Farce::Clock.remaining` and refactored code to use it.
+* Vectors now accept an integer size in their constructors, filling the initial entries with `nil`.
+
+#### Bug Fixes
+
+* Prevent waits from spinning when an unchanged value has non-reflexive equality, such as `Float::NAN`, or overrides `==`, `!=`, or `equal?`. Predicates receive unwrapped values.
+* Prevent graph traversal from retrying indefinitely when a map value cannot be matched using ordinary equality.
+* Fix vector wait timeout fallbacks on CRuby and TruffleRuby.
+
+#### Other changes
+
+* Added `pairing_heap` to the priority queue benchmark and refreshed the published benchmark results. It is the fastest priority queue implementation written in pure Ruby.
+
+### Farce 0.4.1 (2026-10-18)
 
 * Make sure prebuilt Linux binaries include liburing support.
 * Use a Futex for efficient fiber synchronization if possible.

data/README.md

@@ -39,6 +39,7 @@ Use familiar Ruby APIs with coordinated access to shared state:
 - **Maps, vectors, and sets** for collections, with sorted and weak-reference variants.
 - **Atoms, counters, flags, and molecules** for individual values and structured records.
 - **FIFO, priority, and timer queues** for passing work, applying back pressure, or delaying delivery.
+- **Publishers and subscribers** for one-to-many communication, where a single publisher can broadcast messages to multiple subscribers.
 
 For example, use a Vector as a shared list:
 
@@ -68,6 +69,7 @@ cache.key?(:a) # => false, the least recently used entry was evicted
 - **`Farce::Port`** adds transfer modes, receive timeouts, and Fiber scheduler support.
 - **`Farce::WeakRef` and `Farce::Resolv`** work outside the main Ractor.
 - **`Farce::Backports`** backports newer `Ractor` and `Ractor::Port` features to older Ruby versions. Can be invoked directly, used with refinements, or installed globally.
+- **`Farce::Concurrent`** provides Ractor-friendly replacements for some classes provided by `concurrent-ruby`.
 
 Send a result back from a worker:
 
@@ -210,7 +212,7 @@ config.class           # => Farce::Map
 config[:retries].class # => Farce::Vector
 ```
 
-Other helpers freeze object graphs, deduplicate values, and measure monotonic time. Lazy values and exchangers coordinate initialization and handoffs. Shareability mixins define how custom classes can be frozen, shared, copied, or moved.
+Other helpers freeze object graphs, deduplicate values, offer method memoization, and measure monotonic time. Lazy values and exchangers coordinate initialization and handoffs. Shareability mixins define how custom classes can be frozen, shared, copied, or moved.
 
 → [Conversion helpers and extension points](docs/utilities.md).
 

data/docs/benchmarks.md

@@ -57,6 +57,7 @@ Also note that `Ratomic::Map` has a significant performance benefit over all oth
  concurrent-ruby-ext | 1.2x slower | same-ish       | 32-bit       | no ractor support
  ratomic             | 1.5x slower | 1.6x slower    | 64-bit       | no overflow protection
  ractor_safe         | 2.1x slower | 2.1x slower    | 64-bit       |
+ atomic-ruby         | 10x slower  | 2.9x slower    | any          | via `Atom`
  concurrent-ruby     | 12x slower  | 5x slower      | 32-bit       | no ractor support
 
 Performance differences between implementations are consistent between single-threaded and multi-threaded benchmarks.
@@ -101,13 +102,14 @@ In the producer/consumer workload in `benchmark/queue.rb`, Ruby's built-in `Thre
  Implementation                | Performance | Notes
 -------------------------------|-------------|-------------
  `Thread::Queue`               | Fastest     | no ractor support
- `Thread::SizedQueue`          | 1.4x slower | no ractor support
- `Farce::Strict::Queue`        | 1.5x slower | only allows sharable objects
- `Farce::Queue`                | 2.1x slower |
- `RactorSafe::Queue`           | 2.9x slower | only allows sharable objects
- `Ratomic::Queue`              | 9.8x slower | breaks ractor isolation
- `RactorQueue`                 | 30x slower  | breaks ractor isolation
- `Ractor::Port` (multiplexing) | 100x slower |
+ `AtomicQueue`                 | 1.5x slower | no ractor support
+ `Thread::SizedQueue`          | 1.5x slower | no ractor support
+ `Farce::Strict::Queue`        | 1.6x slower | only allows sharable objects
+ `Farce::Queue`                | 2.2x slower |
+ `RactorSafe::Queue`           | 2.8x slower | only allows sharable objects
+ `Ratomic::Queue`              | 12x slower  | breaks ractor isolation
+ `RactorQueue`                 | 29x slower  | breaks ractor isolation
+ `Ractor::Port` (multiplexing) | 110x slower |
 
 ## Priority queue performance
 
@@ -126,14 +128,14 @@ The below numbers compare non-blocking APIs, as only Farce implements a blocking
       <th>↓ Gem</th>
       <th>Insertion order →</th>
       <th>Random</th>
-      <th>Descending</th>
+      <th>Sorted</th>
       <th>Random</th>
-      <th>Descending</th>
+      <th>Sorted</th>
     </tr>
   </thead>
   <tbody>
     <tr>
-      <td colspan="2">farce 0.1.0</td>
+      <td colspan="2">farce 0.4.1</td>
       <td>fastest</td>
       <td>fastest</td>
       <td>fastest</td>
@@ -141,43 +143,57 @@ The below numbers compare non-blocking APIs, as only Farce implements a blocking
     </tr>
     <tr>
       <td colspan="2"><a href="https://github.com/mame/rbtree">rbtree</a> 0.4.7</td>
-      <td>1.1x slower</td>
-      <td>1.2x  slower</td>
+      <td>1.6x slower</td>
+      <td>2.9x  slower</td>
       <td>–</td>
       <td>–</td>
     </tr>
     <tr>
       <td colspan="2"><a href="https://github.com/boborbt/priority_queue_cxx">priority_queue_cxx</a> 0.3.7</td>
-      <td>1.7x slower</td>
-      <td>1.7x slower</td>
+      <td>2.7x slower</td>
+      <td>4.0x slower</td>
       <td>–</td>
       <td>–</td>
     </tr>
     <tr>
-      <td colspan="2"><a href="https://github.com/socketry/io-event">io-event</a> 1.21.1</td>
-      <td>2.6x slower</td>
-      <td>3.9x slower</td>
+      <td colspan="2"><a href="https://github.com/mhib/pairing_heap">pairing_heap</a> 3.1.2 (simple)</td>
+      <td>3.0x slower</td>
+      <td>1.3x slower</td>
+      <td>2.3x slower</td>
+      <td>1.1x slower</td>
+    </tr>
+    <tr>
+      <td colspan="2"><a href="https://github.com/socketry/io-event">io-event</a> 1.22.3</td>
+      <td>4.5x slower</td>
+      <td>9.6x slower</td>
       <td>1.3x slower</td>
       <td>1.7x slower</td>
     </tr>
+    <tr>
+      <td colspan="2"><a href="https://github.com/mhib/pairing_heap">pairing_heap</a> 3.1.2</td>
+      <td>5.6x slower</td>
+      <td>4.1x slower</td>
+      <td>3.6x slower</td>
+      <td>1.9x slower</td>
+    </tr>
     <tr>
       <td colspan="2"><a href="https://github.com/rubyworks/pqueue">pqueue</a> 2.2.0</td>
-      <td>9.5x slower</td>
-      <td>8.0x slower</td>
+      <td>15.1x slower</td>
+      <td>19.7x slower</td>
       <td>2.2x slower</td>
       <td>1.9x slower</td>
     </tr>
     <tr>
       <td colspan="2"><a href="https://github.com/matiasbattocchia/lazy-priority-queue">lazy_priority_queue</a> 0.1.1</td>
       <td>9.9x slower</td>
-      <td>7.9x slower</td>
+      <td>20x slower</td>
       <td>3.9x slower</td>
       <td>3.2x slower</td>
     </tr>
     <tr>
       <td colspan="2"><a href="https://github.com/philiprehberger/rb-priority-queue">philiprehberger-priority_queue</a> 0.5.0</td>
       <td>13x slower</td>
-      <td>19x slower</td>
+      <td>48x slower</td>
       <td>7.6x slower</td>
       <td>11x slower</td>
     </tr>

data/docs/compatibility.md

@@ -69,6 +69,19 @@ This means:
 * `Kernel.instance_method(:frozen?).bind_call(object)` might report a different value from `object.frozen?`
 * C-level checks for frozen state, such as `RB_OBJ_FROZEN`, might differ from what Ruby-level methods report.
 
+### Fiber schedulers and Ractors don't play nice on Ruby 3.4
+
+Fiber schedulers running in a non-main Ractor have a chance of causing a segmentation fault on x86_64 Linux with Ruby 3.4.11 and earlier.
+
+This issue is [unrelated to Farce itself](https://gist.github.com/rkh/f330bd5c4accc9718f5ca227ae020c94) and typically only surfaces irregularly under a high number of Ractor shutdowns.
+It does however surface from time to time when running the Farce test suite on affected Ruby versions and platforms.
+
+Installing and loading Farce, using Farce data structures, etc, does not increase the likelihood of encountering this issue.
+
+### GC related tests are flaky in certain environments
+
+Garbage collection related tests may exhibit flakiness on some Ruby versions and platforms. This can lead to unexpected failures when running the test suite.
+
 ## Read Next
 
 [README](../README.md#features) · [Installation](installation.md) · [Integrations](integrations.md)

data/docs/data-structures.md

@@ -22,6 +22,7 @@ Farce provides a range of data structures that are ractor-safe, mutable, and exp
     - [Priority Queues](#priority-queues)
     - [Timer Queues](#timer-queues)
     - [Queue capacity](#queue-capacity)
+  - [Publishers](#publishers)
   - [Read Next](#read-next)
 
 ## Maps
@@ -308,6 +309,42 @@ queue.try_push(:c) # => false
 Normal queues have a default capacity of 1024. You can explicitly set the capacity to `nil` to create an unbounded queue.
 Priority queues and timer queues do not have a default capacity, so earlier entries are not getting blocked unexpectedly.
 
+## Publishers
+
+Both ports and queues deliver messages exactly ones. Multiple receivers can read from the same port (if they are running inside the same ractor) or queue, but each message will only be delivered once.
+
+A publisher allows one-to-many communication, where a single publisher can broadcast messages to multiple subscribers. Published messages are sent to enabled subscribers.
+
+Subscribers can be:
+
+* Ractors, ports, queues, or other publishers, using their respective message sending mechanisms.
+* A [vector](#vectors) or [set](#sets), in which case each message will be added to the collection.
+* A [counter](#counters), incrementing it for each message received. This avoids potential copying of the message itself.
+* A [flag](#flags), setting it to true whenever a message is received. This avoids potential copying of the message itself.
+* A `Farce::Concurrent::Event`, setting it for each message received.
+* A `Farce::Concurrent::CountDownLatch`, counting down for each message received.
+* A callback, executed for each message received.
+
+For unshared and local publisher [variants](variants-and-scopes.md) subscribers may also include:
+
+* Any unshared variant of the subscriber list above.
+* Ruby's `Thread::Queue` or `Thread::SizedQueue`
+* `Concurrent::AtomicReference`, `Concurrent::AtomicFixnum`, `Concurrent::AtomicBoolean`, `Concurrent::Event`, and `Concurrent::CountDownLatch` if the [concurrent-ruby integration](integrations.md#concurrent-ruby) is active.
+
+```ruby
+publisher = Farce::Publisher.new
+counter   = Farce::Counter.new
+
+publisher.subscribe do |message|
+  puts "Received: #{message}"
+end
+
+publisher.publish(:hello)
+publisher.publish(:world)
+
+counter.to_i # => 2
+```
+
 ## Read Next
 
 [README](../README.md#features) · [Sharing Unshareable Data](sharing.md) · [Concurrency](concurrency.md) · [Variants and Scopes](variants-and-scopes.md)

data/docs/integrations.md

@@ -82,6 +82,7 @@ The integration adds the following features if [concurrent-ruby](https://github.
 
 * [Transaction support for `Concurrent::TVar`](concurrency.md#tvars)
 * Automatic conversion of `Concurrent::Map` instances to [maps](data-structures.md#maps) via [`Farce.enfarce`](utilities.md#top-level-methods).
+* [Subscriber support](data-structures.md#publishers) for `Concurrent::AtomicReference`, `Concurrent::AtomicFixnum`, `Concurrent::AtomicBoolean`, `Concurrent::Event`, and `Concurrent::CountDownLatch` with unshared and local publishers.
 
 ## Ractor Sharing
 

data/docs/introduction.md

@@ -137,6 +137,25 @@ Both the Ruby core library, and other libraries, like the very popular [concurre
       <td>❌ <b>not supported</b></td>
       <td>⚠️ CRuby only</td>
     </tr>
+    <tr>
+      <td rowspan="3"><a href="https://github.com/joshuay03/atomic-ruby">atomic-ruby</a></td>
+      <td>AtomicQueue, AtomicThreadPool</td>
+      <td>⚠️ CRuby only</td>
+      <td>⚠️ CRuby only</td>
+      <td>❌ <b>not supported</b></td>
+    </tr>
+    <tr>
+      <td>Atom, AtomicCountDownLatch, AtomicBoolean</td>
+      <td>⚠️ CRuby only<b>¹</b></td>
+      <td>⚠️ CRuby only<b>¹</b></td>
+      <td>⚠️ CRuby only<b>¹</b></td>
+    </tr>
+    <tr>
+      <td>AtomicConditionVariable</td>
+      <td>⚠️ CRuby only</td>
+      <td>❌ <b>not supported</b></td>
+      <td>❌ <b>not supported</b></td>
+    </tr>
   </tbody>
 </table>
 

data/docs/modes.md

@@ -390,8 +390,10 @@ The same choices appear in several Farce APIs. Containers normally default to `:
 | `Farce::Exchanger` | `new`, `exchange` | The value offered to a partner. |
 | `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::Memoize` | `memoize`, `[]` | Memoized results with `scope: :global` (the default). With `weak: true`, supports only `:raise`, `:make_shareable`, and `:dedup`, and defaults to `:raise`. Other scopes ignore the mode. |
 | `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::Publisher`, `Farce::Unshared::Publisher`, `Farce::Local::Publisher` | `subscribe` with a block | Callback arguments and queued payloads. Defaults to `:smart` for `Publisher` and `:local` for its Unshared and Local variants. |
 | `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`. |

data/docs/scheduling.md

@@ -43,7 +43,7 @@ sleep 1.1
 
 As you can see in the [shared-state example](introduction.md#example), creating Ractors ad hoc because you want to run something in parallel is quite expensive.
 
-Use `Farce.in_parallel` to schedule parallel work. On CRuby, it manages a shared [Ractor pool](#ractor-pools), starting workers when the current ones cannot keep up with the load, up to the number of CPU cores. It shuts unused workers down after some inactivity. On JRuby and TruffleRuby, it starts a new thread for each task.
+Use `Farce.in_parallel` to schedule parallel work. On CRuby, it manages a shared [Ractor pool](#ractor-pools), starting workers when the current ones cannot keep up with the load, up to the number of CPU cores by default. It shuts unused workers down after some inactivity. On JRuby and TruffleRuby, it starts a new thread for each task.
 
 ```ruby
 input = "this is my input"
@@ -52,6 +52,21 @@ Farce.in_parallel(input) { expensive_computation(it) }
 
 Like most of Farce, this is completely opt-in. If you never use this feature, no pool is being set up and no extra Ractors are created.
 
+Configure the CRuby pool before creating any scheduler:
+
+```ruby
+Farce.config do |config|
+  config.parallel_pool_min_size     = 0
+  config.parallel_pool_max_size     = 8
+  config.parallel_pool_max_inflight = 64
+  config.parallel_pool_grow_after   = 0.005
+  config.parallel_pool_shrink_after = 30
+  config.parallel_pool_capacity     = 1024
+end
+```
+
+These are the defaults, except `parallel_pool_max_size` defaults to `nil` to use the CPU count. Set `parallel_pool_capacity` to `nil` for an unbounded queue, `parallel_pool_max_inflight` to `nil` to disable the per-worker task limit, or `parallel_pool_shrink_after` to `nil` to retain idle workers. A positive `parallel_pool_min_size` starts workers when the pool is created. These options are ignored on JRuby and TruffleRuby.
+
 ## `Farce.schedule`
 
 `Farce.in_parallel` might not always be what you want. Maybe you are working on a library and don't want to dictate a concurrency model?
@@ -98,6 +113,23 @@ Scheduler instances are Ractor-shareable.
 
 `Farce::Pool` implements the same scheduling interface, but manages a pool of Ractors. This is what [`in_parallel`](#farcein_parallel) uses under the hood.
 
+You can change a pool's settings while it runs:
+
+```ruby
+pool = Farce::Pool.new
+pool.max_size     = 8
+pool.min_size     = 2
+pool.max_inflight = 32
+pool.grow_after   = 0.01
+pool.shrink_after = 10
+pool.capacity     = 2048
+```
+
+Increasing `min_size` starts workers immediately. Lowering `max_size` retires excess workers as they become idle. Busy workers continue servicing queued work so running tasks can wait for tasks queued on the same pool. The size can remain above the new maximum while workers stay busy. Running tasks are never interrupted. `min_size` must not exceed `max_size`. Changes to growth and idle delays recheck queued work and restart idle waits. Setting `max_inflight` or `shrink_after` to `nil` disables that limit.
+
+On CRuby, these settings are also available through `Farce.in_parallel`, such as `Farce.in_parallel.max_size = 8`. Its initial values come from `Farce::Config`. `Farce::Unshared::Pool` supports the same setters. Changes to `Farce::Local::Pool` affect only the current scope. New scopes retain the constructor settings.
+
+
 ```ruby
 # At least four Ractors, up to ten. Launch a new one if a task waits longer than 100 milliseconds.
 pool = Farce::Pool.new(min_size: 4, max_size: 10, grow_after: 0.1)
@@ -167,9 +199,9 @@ Farce.in_parallel do
 end
 ```
 
-If a string or symbol is provided (like `carbon_fiber`), it will first resolve this to a constant (i.e., `CarbonFiber`). If that constant is a class, it will use that for creating the fiber scheduler. If it is a module, it will look for a `Scheduler` constant inside it, which matches the established pattern implemented by most gems, including `farce`, `async`, `carbon_fiber`, `libev_scheduler` (use `libev` as value), `itsi_scheduler` (use `itsi` as value), but it also works for gems that define their scheduler class at top level, like `fiber_scheduler`.
+If a string or symbol is provided (like `carbon_fiber`), it will first resolve this to a constant (i.e., `CarbonFiber`). If that constant is a class, it will use that for creating the fiber scheduler. If it is a module, it will look for a `Scheduler` constant inside it, which matches the established pattern implemented by most gems, including `farce`, `async`, `carbon_fiber`, `libev_scheduler` (use `libev` as value), `itsi-scheduler` (use `itsi` as value), but it also works for gems that define their scheduler class at top level, like `fiber_scheduler`.
 
-Note that most of these are outdated and don't work with any recent Ruby version, with the notable exception of `async` and `carbon_fiber`.
+Note that most of these are outdated and don't work with any recent Ruby version, with the notable exception of `async`, `carbon_fiber`, and `itsi-scheduler`.
 
 ## Read Next
 

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
 
-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.
+The classes and modules 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 |
 | --- | --- |
@@ -259,8 +259,10 @@ The classes in this table accept the same five scopes. The scope determines whic
 | `Farce::Local::WeakSet` | A set that retains its elements weakly. |
 | `Farce::Local::Vector` | An indexed collection. |
 | `Farce::Local::Queue` | A FIFO queue with independent capacity and lifecycle. |
+| `Farce::Local::Publisher` | An independent set of subscriptions. |
 | `Farce::Local::PriorityQueue` | A queue ordered by priority. |
 | `Farce::Local::TimerQueue` | A queue whose values become available at scheduled times. |
+| `Farce::Memoize` | A cached result per instance and method. Also accepts `:global` (the default) for a shared cache or `:unshared` for a cache within one Ractor. |
 | `Farce::Local::Lazy` | A value computed on first access in that scope. |
 | `Farce::Local::LazyRef` | A reference that delegates to a scoped lazy value. |
 | `Farce::Local::Lease` | An independently initialized resource to borrow. |

data/docs/shims.md

@@ -139,6 +139,59 @@ Farce implements a version based on weak [atoms](data-structures.md#atoms). Not
 
 `Farce::Resolv` is a version of Ruby's [`Resolv`](https://docs.ruby-lang.org/en/4.0/Resolv.html), using [counters](data-structures.md#counters) instead of a global instance variable, and can therefore be used outside the main Ractor.
 
+## Concurrent
+
+`Farce::Concurrent` includes the following classes:
+
+ Class            | Description
+------------------|---------------------------------------------------------------
+ `Array`          | Alias for `Farce::Vector`
+ `Atom`           | Alias for `Farce::Atom`
+ `AtomicBoolean`  | Alias for `Farce::Flag`
+ `AtomicFixnum`   | Alias for `Farce::Counter`
+ `CountDownLatch` | Drop-in replacement for `concurrent-ruby`'s `CountDownLatch`
+ `CyclicBarrier`  | Replacement for `concurrent-ruby`'s `CyclicBarrier`
+ `Event`          | Drop-in replacement for `concurrent-ruby`'s `Event`
+ `Exchanger`      | Alias for `Farce::Exchanger`
+ `FiberLocalVar`  | Drop-in replacement for `concurrent-ruby`'s `FiberLocalVar`
+ `Hash`           | Alias for `Farce::Map`
+ `Lock`           | Alias for `Farce::Lock`
+ `LockLocalVar`   | Drop-in replacement for `concurrent-ruby`'s `LockLocalVar`
+ `ReadWriteLock`  | Alias for `Farce::ReadWriteLock`
+ `ThreadLocalVar` | Drop-in replacement for `concurrent-ruby`'s `ThreadLocalVar`
+ `Tuple`          | Replacement for `concurrent-ruby`'s `Tuple`
+
+The nice thing is that these are either always Ractor-shareable, or in the case of `FiberLocalVar` and `ThreadLocalVar`, are Ractor-shareable if their default values or blocks are.
+
+For instance, you can replace threads with ractors in concurrent-ruby's own `CountDownLatch` example:
+
+```ruby
+latch = Farce::Concurrent::CountDownLatch.new(3)
+
+waiter = Ractor.new(latch) do |latch|
+  latch.wait
+  puts "Waiter released"
+end
+
+decrementer = Ractor.new(latch) do |latch|
+  sleep 1
+  latch.count_down
+  puts latch.count
+
+  sleep 1
+  latch.count_down
+  puts latch.count
+
+  sleep 1
+  latch.count_down
+  puts latch.count
+end
+
+waiter.join
+decrementer.join
+
+```
+
 ## Read Next
 
 [README](../README.md#features) · [Sharing Unshareable Data](sharing.md) · [Scheduling Code](scheduling.md)

data/docs/utilities.md

@@ -81,6 +81,37 @@ And also mixins to prevent them from being shareable:
 
 `Unshareable::Copyable` and `Unshareable::Movable` may be combined.
 
+## Memoization
+
+`Farce::Memoize` offers Ractor-friendly memoization:
+
+```ruby
+class MyClass
+  include Farce::Memoize
+
+  # Memoize #expensive_method, shared across Ractors
+  memoize def expensive_method = expensive_computation
+
+  # Memoize #method_with_unsharable_value for each Ractor separately
+  def method_with_unsharable_value = unsharable_computation
+  memoize :method_with_unsharable_value, scope: :ractor
+
+  private
+
+  # The memoized method will also be private
+  memoize def private_method = expensive_computation
+end
+```
+
+Or as a one-liner:
+
+```ruby
+class MyClass
+  # Memoize return values of #foo and #bar until they get garbage collected
+  include Farce::Memoize[:foo, :bar, weak: true]
+end
+```
+
 ## Constants
 
 * `Farce::MODES`: List of supported [sharing modes](sharing.md#sharing-modes).

data/docs/variants.md

@@ -201,6 +201,15 @@ end
       <td align="center" style="text-align: center">🔗</td> <!-- Unsafe -->
       <td align="center" style="text-align: center">➖</td> <!-- Transaction -->
     </tr>
+    <tr>
+      <td><tt>Publisher</tt></td>
+      <td align="center" style="text-align: center">✅</td> <!-- Farce -->
+      <td align="center" style="text-align: center">✅</td> <!-- Strict -->
+      <td align="center" style="text-align: center">✅</td> <!-- Local -->
+      <td align="center" style="text-align: center">✅</td> <!-- Unshared -->
+      <td align="center" style="text-align: center">🔗</td> <!-- Unsafe -->
+      <td align="center" style="text-align: center">➖</td> <!-- Transaction -->
+    </tr>
     <tr>
       <td><tt>Queue</tt></td>
       <td align="center" style="text-align: center">✅</td> <!-- Farce -->

data/ext/farce/farce.c

@@ -306,6 +306,14 @@ containers_raise_key_error(VALUE receiver, VALUE key)
     rb_exc_raise(exception);
 }
 
+static VALUE
+farce_value_changed(VALUE namespace, VALUE current, VALUE expected, VALUE identity)
+{
+    if (current == expected) return Qfalse;
+    if (RTEST(identity)) return identity;
+    return RTEST(rb_equal(current, expected)) ? Qfalse : Qtrue;
+}
+
 static VALUE
 farce_futex_supported(VALUE namespace)
 {
@@ -336,6 +344,7 @@ Init_farce(void)
     VALUE mInternal = rb_const_get(mFarce, rb_intern("Internal"));
     VALUE singleton = rb_singleton_class(mInternal);
     eIsolationError = rb_const_get(rb_cRactor, rb_intern("IsolationError"));
+    rb_define_singleton_method(mInternal, "value_changed?", farce_value_changed, 3);
 #if RUBY_API_VERSION_CODE == 30400
     rb_define_singleton_method(mInternal, "lock_native_thread", farce_lock_native_thread, 0);
 #endif

data/ext/farce/map.c

@@ -1417,9 +1417,15 @@ map_modify_body(VALUE opaque)
 }
 
 static VALUE
-map_modify(VALUE self, VALUE key)
+map_modify(int argc, VALUE *argv, VALUE self)
 {
     rb_check_frozen(self);
+    VALUE key;
+    VALUE keywords = Qnil;
+    VALUE keyword_values[1] = {Qundef};
+    ID keyword_ids[] = {rb_intern("timeout")};
+    rb_scan_args(argc, argv, "1:", &key, &keywords);
+    if (!NIL_P(keywords)) rb_get_kwargs(keywords, keyword_ids, 0, 1, keyword_values);
     rb_need_block();
     map_t *map = get_map(self);
     key = map_prepare_key(map, key);
@@ -1432,7 +1438,12 @@ map_modify(VALUE self, VALUE key)
     };
     operation.hash = map_key_hash(map, key);
     rb_check_frozen(self);
-    map_lock_for_key(map, key, operation.hash, &operation.execution);
+    map_timeout_t timeout = map_parse_timeout(
+        keyword_values[0] == Qundef ? Qnil : keyword_values[0]
+    );
+    if (!map_lock_for_key_with_timeout(
+        map, key, operation.hash, &timeout, &operation.execution
+    )) return Qfalse;
     bool found;
     size_t index = map_find_slot(map, key, operation.hash, &found, &operation.execution);
     if (RB_OBJ_FROZEN(self)) {
@@ -2151,7 +2162,7 @@ map_define_methods(VALUE klass)
     rb_define_method(klass, "store", map_store_with_timeout, -1);
     rb_define_method(klass, "swap", map_swap, -1);
     rb_define_method(klass, "update", map_update, -1);
-    rb_define_method(klass, "modify", map_modify, 1);
+    rb_define_method(klass, "modify", map_modify, -1);
     rb_define_method(klass, "wait_until_changed", map_wait_until_changed, -1);
     rb_define_method(klass, "wait_until_non_nil", map_wait_until_non_nil, -1);
     rb_define_method(klass, "store_if_absent", map_store_if_absent, -1);