farce 0.3.0 → 0.4.0

data/docs/integrations.md

@@ -0,0 +1,124 @@
+<!--
+# @title Integrations
+-->
+
+# Integrations
+
+Farce ships with a couple of integrations that are automatically loaded if and only if both farce and the other gem have also been loaded (it does not automatically load these gems, even if they are part of the current bundle). This is load-order independent.
+
+## Active Support
+
+The Active Support integration adds the following methods:
+
+* For all data structures: `as_json`, `blank?`, `deep_dup`, and `duplicable?`
+* For maps: `assert_valid_keys`, `compact_blank`, `reverse_merge`, `stringify_keys`, `symbolize_keys`, `to_param`, `to_query`, `with_defaults`, and `with_indifferent_access`
+* For vectors: `compact_blank`, `excluding`, `from`, `including`, `inquiry`, `in_groups`, `in_groups_of`, `in_order_of`, `maximum`, `minimum`, `pluck`, `pick`, `split`, `to`, `to_fs`, `to_param`, `to_sentence`, `to_query`, `to_xml`, `second`, `third`, `fourth`, `fifth`, `forty_two`, `third_to_last`, and `second_to_last`
+
+And the following features:
+* Converting `ActiveSupport::HashWithIndifferentAccess` to a map via [`Farce.enfarce`](utilities.md#top-level-methods) will set up the correct key normalization.
+* [`Farce::Clock`](utilities.md#additional-classes) understands `ActiveSupport::Duration`.
+
+Other methods are already being inherited by various objects via `Object`, `Enumerable` for vectors, sets, and maps, `Numeric` for counters, etc.
+
+```ruby
+require "active_support/all"
+require "farce"
+
+map     = Farce::Map.new.with_indifferent_access
+map[:a] = 10
+
+map.blank? # => false
+map["a"]   # => 10
+```
+
+The integration isn't triggered by loading `active_support`, but instead looks for `active_support/core_ext`, so you should require that (or `active_support/all`, which in turn requires it).
+
+## Dry Types
+
+Adds support for Farce [data structures](data-structures.md#data-structures) to [Dry Types](https://hanakai.org/learn/dry/dry-types):
+
+```ruby
+require "dry-types"
+require "farce"
+
+module Types
+  include Dry.Types()
+  include Farce.DryTypes()
+
+  IntegerVector = Vector.of(Coercible::Integer)
+end
+
+numbers = Types::IntegerVector[["1", 2]]
+numbers.class # => Farce::Vector
+numbers.to_a  # => [1, 2]
+```
+
+Check out the [dedicated documentation](gems/dry-types.md) to learn more.
+
+## JSON, YAML, etc
+
+It ships integrations for serialization (and some deserialization) with the following gems:
+
+* For BSON support: `bson`
+* For CBOR support: `cbor`
+* For JSON support: `json` (from the Ruby standard library), `oj`, and `yajl`
+* For MessagePack: `msgpack`. See the [detailed documentation](gems/msgpack.md)
+* For YAML: `psych` (from the Ruby standard library)
+
+Example:
+
+```ruby
+require "json"
+require "farce"
+
+map = Farce::Map.new
+map[:x] = Farce::Vector[1, 2, 3]
+map.to_json # => '{"x":[1,2,3]}'
+```
+
+## Concurrent Ruby
+
+The integration adds the following features if [concurrent-ruby](https://github.com/ruby-concurrency/concurrent-ruby) has been loaded:
+
+* [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).
+
+## Ractor Sharing
+
+The integration adds the following features if [ractor-sharing](https://github.com/ko1/ractor-sharing) has been loaded:
+
+* [Transaction support for `Ractor::TVar`](concurrency.md#tvars)
+* Support for traversing and deep freezing `Ractor::TVar`, `Ractor::LockVar`, `Ractor::LockHash`, and `Ractor::KeyLockHash`
+* Support for converting `Ractor::LockHash` and `Ractor::KeyLockHash` to [maps](data-structures.md#maps) via [`Farce.enfarce`](utilities.md#top-level-methods).
+
+## Additional Integrations
+
+* [`sorted_set`](https://github.com/knu/sorted_set): Add support for walking and converting them.
+* [`ractor-tmvar`](https://github.com/yoshitsugu/ractor-tmvar): Adds transaction support.
+* [`weakref`](https://github.com/ruby/weakref): Add support for walking and converting them.
+
+## Disable Automatic Loading
+
+You can set the environment variable `FARCE_AUTOLOAD_INTEGRATIONS` to `false` or `0` to disable automatic integration loading.
+
+Or you can use `Farce.configure` to disable it. But you may have to do so before loading `farce` unless you're absolutely certain the other gem has not yet been loaded:
+
+```ruby
+# This could go in an initializer
+require "farce/config"
+
+Farce.configure do |config|
+  config.autoload_integrations = false
+end
+
+require "farce"
+
+# you now need to load any integrations you might want explicitly
+# these are available via "farce/integrations/#{gem_name}"
+require "farce/integrations/json"
+require "farce/integrations/concurrent"
+```
+
+## Read Next
+
+[README](../README.md#features) · [Compatibility and Dependencies](compatibility.md) · [Utilities and Custom Classes](utilities.md)

data/docs/introduction.md

@@ -0,0 +1,266 @@
+<!--
+# @title Introduction
+-->
+
+# Introduction
+
+Ruby 3.0 introduced two powerful concurrency primitives: **Fiber schedulers** and **Ractors**, besides the already existing **Threads**:
+
+* **Threads** are the classic concurrency primitive in Ruby, and mostly map to native operating system threads. This way any system calls, IO, or other blocking operations will block a thread, allowing another one to run. However, on the official Ruby implementation (often referred to as CRuby or MRI), Threads cannot run in parallel due to the Global VM Lock (GVL). This means that even if you have multiple threads, only one of them can execute Ruby code at a time.
+* **Ractors** provide parallelism, even on CRuby. They make it very hard to introduce concurrency issues between them, but put severe limitations on state sharing and cross-ractor communication. Ractors are only supported by CRuby, but that is generally not an issue, as other implementations, such as JRuby and TruffleRuby, support true parallelism with Threads. As of Ruby 4.0, Ractors are still considered experimental.
+* **Fiber schedulers** allow you to run multiple Fibers concurrently on a single Thread, without having to explicitly pass control between them. This is a very efficient way to run concurrent code, especially for IO-bound workloads. As of Ruby 4.0, Fiber schedulers with IO support are still considered experimental.
+
+All three of these need some form of **concurrency coordination** for shared state. These are usually the most complicated for Threads, as state is shared between them freely, and an interrupt can happen at any time. Fibers on the other hand have explicit control transfer (only on blocking operations or when giving up control), so their behavior is much more predictable. Ractors disallow sharing mutable state between them (or have built-in locking for the few cases where they allow it).
+
+## The Problem
+
+> [!NOTE]
+> Please keep in mind that many of these libraries may gain better Ractor support in the future, and that the table might already be outdated. Feel free to open an issue if you find any inaccuracies. This is also in no way meant as a criticism of any of the libraries mentioned. They all have their own scopes, goals and priorities, and largely rely on volunteer contributions.
+
+Both the Ruby core library, and other libraries, like the very popular [concurrent-ruby](https://github.com/ruby-concurrency/concurrent-ruby) gem, provide plenty of primitives to solve this. However, most of them are not compatible with Ractors. And those that are, are then in turn usually not compatible with Fiber schedulers. Due to this, most of the popular frameworks and libraries out there do not support Ractors at all:
+
+<table>
+  <thead>
+    <tr>
+      <th>Library</th>
+      <th>Example classes</th>
+      <th>Multithreading</th>
+      <th>Non-blocking Fibers</th>
+      <th>Cross-Ractor Usage</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td rowspan="5"><a href="https://www.ruby-lang.org/">Ruby</a></td>
+      <td>Array, Hash, String, Set, …</td>
+      <td>⚠️ not thread-safe</td>
+      <td>✅ supported</td>
+      <td>⚠️ immutable/copy/move only</td>
+    </tr>
+    <tr>
+      <td>Thread, Fiber</td>
+      <td>✅ supported</td>
+      <td>✅ supported</td>
+      <td>❌ <b>not supported</b></td>
+    </tr>
+    <tr>
+      <td>Mutex, ConditionVariable, Queue</td>
+      <td>✅ supported</td>
+      <td>⚠️ CRuby only</td>
+      <td>❌ <b>not supported</b></td>
+    </tr>
+    <tr>
+      <td>Ractor, Ractor::Port</td>
+      <td>✅ supported</td>
+      <td>❌ <b>not supported</b></td>
+      <td>✅ supported</td>
+    </tr>
+    <tr>
+      <td>WeakRef, Ruby::Box</td>
+      <td>⚠️ Main Ractor only</td>
+      <td>⚠️ Main Ractor only</td>
+      <td>❌ <b>not supported</b></td>
+    </tr>
+    <tr>
+      <td><a href="https://github.com/ruby-concurrency/concurrent-ruby">concurrent-ruby</a></td>
+      <td>Future, Exchanger, Tuple, …</td>
+      <td>⚠️ Main Ractor only</td>
+      <td>⚠️ Main Ractor only</td>
+      <td>❌ <b>not supported</b></td>
+    </tr>
+    <tr>
+      <td rowspan="2"><a href="https://github.com/socketry/async">async</a></td>
+      <td>Promise, Condition, Queue, …</td>
+      <td>✅ supported</td>
+      <td>✅ supported</td>
+      <td>❌ <b>not supported</b></td>
+    </tr>
+    <tr>
+      <td>Scheduler</td>
+      <td>⚠️ Main Ractor only</td>
+      <td>⚠️ Main Ractor only</td>
+      <td>❌ <b>not supported</b></td>
+    </tr>
+    <tr>
+      <td rowspan="3"><a href="https://github.com/mperham/ratomic">ratomic</a></td>
+      <td>Pool</td>
+      <td>⚠️ CRuby only<b>¹</b></td>
+      <td>❌ <b>not supported</b></td>
+      <td>⚠️ CRuby only<b>¹</b></td>
+    </tr>
+    <tr>
+      <td>LocalPool</td>
+      <td>⚠️ CRuby only<b>¹</b></td>
+      <td>⚠️ CRuby only<b>¹</b></td>
+      <td>⚠️ CRuby only<b>¹</b></td>
+    </tr>
+    <tr>
+      <td>Queue, Map</td>
+      <td>⚠️ CRuby only<b>¹</b></td>
+      <td>❌ <b>not supported</b></td>
+      <td>💣 <b>breaks isolation¹²</b></td>
+    </tr>
+    <tr>
+      <td><a href="https://github.com/MadBomber/ractor_queue">ractor_queue</a></td>
+      <td>RactorQueue</td>
+      <td>⚠️ CRuby only<b>¹</b></td>
+      <td>⚠️ CRuby only<b>¹</b></td>
+      <td>💣 <b>breaks isolation¹²</b></td>
+    </tr>
+    <tr>
+      <td>
+        <a href="https://github.com/hamstergem/hamster">hamster</a> /
+        <a href="https://github.com/immutable-ruby/immutable-ruby">immutable</a>
+      </td>
+      <td>Hash, Vector, Set, List, …</td>
+      <td>⚠️ Main Ractor only</td>
+      <td>⚠️ Main Ractor only</td>
+      <td>❌ <b>not supported</b></td>
+    </tr>
+    <tr>
+      <td><a href="https://github.com/ko1/ractor-sharing">ractor-sharing</a></td>
+      <td>TVar, LockVar, LockHash, …</td>
+      <td>⚠️ CRuby only<b>¹</b></td>
+      <td>❌ <b>not supported</b></td>
+      <td>⚠️ CRuby only<b>¹</b></td>
+    </tr>
+    <tr>
+      <td rowspan="2"><a href="https://github.com/jhawthorn/ractor_safe">ractor_safe</a></td>
+      <td>HashMap, AtomicInteger</td>
+      <td>⚠️ CRuby only</td>
+      <td>⚠️ CRuby only</td>
+      <td>⚠️ CRuby only</td>
+    </tr>
+    <tr>
+      <td>Queue</td>
+      <td>⚠️ CRuby only</td>
+      <td>❌ <b>not supported</b></td>
+      <td>⚠️ CRuby only</td>
+    </tr>
+  </tbody>
+</table>
+
+Notes:
+1. Incorrectly flags mutable objects as frozen.
+2. Breaking Ractor isolation introduces concurrency issues not just in application code, but in Ruby itself, possibly leading to segmentation faults or undefined behavior. Note that `ractor_queue` has the ability to enforce shareability, but this feature is opt-in.
+
+## The Solution
+
+**Farce is an attempt to solve this.** Code relying on Farce will work well with any concurrency primitive. Use an **event loop with the [async](https://github.com/socketry/async)** gem? Farce will fit right in. Running a **pool of Ractors** with [Kino](https://github.com/yaroslav/kino)? Farce got you covered! You manually manage a single **background thread**? Farce solves that, too!
+
+And it does so in a non-invasive way. You should be able to use Farce alongside any other gem!
+
+```ruby
+# Using a counter as an example, there are many more classes provided by Farce
+counter = Farce::Counter.new
+
+# Works in code without concurrency
+counter.add(5)
+counter.to_i # => 5
+
+# Works with threads
+wait_for = 5.times.map do
+  Thread.new { counter.increment }
+end
+
+# Works with ractors
+wait_for += 5.times.map do
+  Ractor.new(counter) { it.increment }
+end
+
+# Works with the async gem
+Async do
+  5.times do
+    Async { counter.increment }
+  end
+end
+
+wait_for.each(&:join)
+counter.to_i # => 20
+```
+
+Farce also aims to be fast and efficient, with performance ranging from minimal overhead to outperforming other options.
+
+It does so by choosing the best implementation for the situation. The counter in the above example will use Java's `AtomicLong` on JRuby and TruffleRuby in GraalVM mode, an `AtomicReference` on TruffleRuby in native mode, and an atomic, native counter on CRuby, so it runs without having to use any locks on any of these platforms.
+
+This is especially useful when coordinating work between Fiber schedulers and Ractors:
+
+```ruby
+queue = Farce::Queue.new
+
+# Background ractor pushing work into the queue
+# This would not work with Ruby's built-in Queue
+Ractor.new(queue) do |queue|
+  loop { queue.push expensive_work }
+end
+
+# This would not work with Ratomic::Queue
+Async do
+  # Task waiting for work from the queue
+  Async { loop { do_something queue.pop  } }
+
+  # Doesn't get blocked by the other task waiting for the queue
+  Async { unrelated_work }
+end
+```
+
+## Example
+
+A map and a mutable string can be shared across Ractors. The transaction keeps their updates together. This example deliberately creates many Ractors. For application workloads, use [a pool](scheduling.md#ractor-pools) to reuse workers.
+
+```ruby
+require "farce"
+
+map    = Farce::Map.new
+output = Farce::Mutable.new "Hello from Farce! The map has 0 entries, with a total sum of 0."
+
+# Mutate output in another Ractor - this would not work with a String.
+# Using Farce::Ractor here instead of Ractor so it also works on JRuby and TruffleRuby.
+ractor = Farce::Ractor.new(output) do |output|
+  sleep rand # I laugh in the face of race conditions. Ha, ha, ha, ha!
+  output.gsub!("Farce", "✨ Farce ✨")
+end
+
+# No idea if the above ractor is done modifying output, but we don't need to worry!
+# We'll just pick a random key one hundred times and increase its counter by one.
+# Oh, and update the output string.
+100.times.map do
+
+  # And of course we need to do it all in parallel for maximum performance!
+  # Let's ignore the fact that this would be much faster if we didn't.
+  # Starting 100 ractors is the main performance issue here.
+  # But that wouldn't be an interesting example, right?
+  Farce::Ractor.new(output, map) do |output, map|
+    key = %i[foo bar baz].sample
+
+    # Wrap the modifications in a transaction, so map and output never disagree
+    Farce.transaction(output, map) do |_, output, map|
+
+      # Increase the value we have for the given key by one!
+      map[key] ||= 0
+      map[key]  += 1
+
+      # Could also replace the lines above with:
+      #
+      #   map.upsert(key, 1) { it + 1 }
+      #
+      # … which would be atomic.
+      # But we're in a transaction, so everything is atomic! ☢️
+
+      output.sub!(/\d+ entries/, "#{map.size} entries")
+      output.sub!(/sum of \d+/, "sum of #{map.values.sum}")
+    end
+  end
+
+end.each(&:join)
+
+# Let's be sure that first ractor has completed its modification
+ractor.join
+
+# Hello from ✨ Farce ✨! The map has 3 entries with a total sum of 100.
+puts output
+```
+
+## Read Next
+
+[README](../README.md#features) · [Data Structures](data-structures.md) · [Concurrency](concurrency.md)

data/docs/scheduling.md

@@ -0,0 +1,176 @@
+<!--
+# @title Scheduling Code
+-->
+
+# Scheduling Code
+
+Use Farce to schedule background work, reuse workers for parallel computation, or dispatch calls to the main Ractor. Tasks retain results, while schedulers and pools control where work runs.
+
+## `Farce.on_main`
+
+Some code has to be executed on the main Ractor, especially when working with legacy code that doesn't support Ractors.
+
+You can pass a block to `Farce.on_main` to run code on the main Ractor. The method call will block until the code has been executed.
+
+```ruby
+# most of concurrent-ruby is not usable outside of the main-ractor
+$tvar = Concurrent::TVar.new(0)
+
+# let's run computation outside of the main ractor
+Ractor.new do
+  value = compute_expensive_value
+
+  # need to report back to the main ractor
+  Farce.on_main(value) { $tvar.value = it }
+end
+```
+
+Sometimes you don't need to wait for the code to be done running on the main Ractor. In such cases, you can use `schedule`, as `on_main` returns a [scheduler](#schedulers) instance when called without a block:
+
+```ruby
+Ractor.new do
+  Farce.on_main.schedule do
+    sleep 1
+    puts "Hello from the main Ractor"
+  end
+  puts "Hello from the nested Ractor"
+end
+
+sleep 1.1
+```
+
+## `Farce.in_parallel`
+
+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.
+
+```ruby
+input = "this is my input"
+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.
+
+## `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?
+
+You can use `Farce.schedule`, which will automatically figure out how to run code off-band. You can use `mode: :local` to force execution inside the current Ractor (which it will prefer by default if there already is some scheduler running, but not enforce).
+
+```ruby
+# just run this asynchronously, don't care how
+Farce.schedule("hello") { |message| puts message.upcase }
+```
+
+"Some scheduler?" you might say? Some scheduler! It will automatically detect if there is a local scheduler. This can either be a Fiber scheduler, like [async](https://socketry.github.io/async/) or [Carbon Fiber](https://yaroslav.io/opensource/carbon_fiber), or an internal scheduler created by Farce:
+
+```ruby
+Async do
+  # this is basically the same as calling Async { do_something }
+  Farce.schedule { do_something }
+end
+```
+
+## Schedulers
+
+You can create your own `Farce::Scheduler`, running on a dedicated Ractor:
+
+```ruby
+scheduler = Farce::Scheduler.create
+scheduler.schedule("hello") { |message| puts message }
+scheduler.close # we're done, shut it down
+```
+
+Or you can set one up as a Fiber scheduler for the current Thread:
+
+```ruby
+scheduler = Farce::Scheduler.new
+Fiber.set_scheduler(scheduler)
+Fiber.schedule { puts "Hello from the scheduler!" }
+scheduler.close
+Fiber.set_scheduler(nil) # drain scheduled work and detach the scheduler
+```
+
+Scheduler instances are Ractor-shareable.
+
+## Ractor Pools
+
+`Farce::Pool` implements the same scheduling interface, but manages a pool of Ractors. This is what [`in_parallel`](#farcein_parallel) uses under the hood.
+
+```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)
+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:
+
+```ruby
+# Use the fiber scheduler from the carbon_fiber gem.
+pool = Farce::Pool.new { CarbonFiber::Scheduler.new }
+pool.schedule { puts "⚡️ Running Carbon Fiber on a pool of Ractors! ⚡️" }
+```
+
+You can also use a different fiber scheduler as the default (in which case it will be picked up by `in_parallel` and `on_main` as well) by setting the `FARCE_FIBER_SCHEDULER` environment variable or using the `fiber_scheduler` configuration setting:
+
+```ruby
+# This needs to happen before the first scheduler call.
+Farce.configure do |config|
+  config.fiber_scheduler = :carbon_fiber
+
+  # or, alternatively:
+  config.fiber_scheduler { CarbonFiber::Scheduler.new }
+end
+
+Farce.in_parallel do
+  Fiber.scheduler.class # => CarbonFiber::Scheduler
+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`.
+
+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`.
+
+## Read Next
+
+[README](../README.md#features) · [Concurrency](concurrency.md) · [Shims, Polyfills, and Extensions](shims.md)