farce 0.3.0-arm-linux-gnu → 0.4.0-arm-linux-gnu

data/docs/sharing.md

@@ -0,0 +1,211 @@
+<!--
+# @title Sharing Unshareable Data
+-->
+
+# Sharing Unshareable Data
+
+Ruby's `Ractor::Port#send` and related methods share Ruby objects between Ractors with this logic:
+
+1. If the object is Ractor shareable, pass it by reference.
+2. If the object isn't Ractor shareable and the `move` option hasn't been set to `true`, pass it by value (copy it).
+3. Otherwise move it from the sending Ractor to the receiving Ractor, invalidating any previous references.
+
+This is a great start but has some complications:
+* Copying can lead to a lot of data duplication, as large object trees may be copied between Ractors over and over again.
+* Moving may invalidate nested references unexpectedly, breaking code in the sending Ractor.
+* If you want to prevent sending unshareable objects to other Ractors, you have to manually check them every time.
+
+Farce has mechanisms and tools to improve the situation.
+
+## Sharing Modes
+
+> [!TIP]
+> Learn more in the dedicated  [modes documentation](modes.md).
+
+The [default variants](variants-and-scopes.md#variants-and-scopes) of most [data structures](data-structures.md#data-structures), as well as [`Farce::Port`](shims.md#port), implement a range of sharing modes, typically as a keyword argument for initialization as well as for methods that modify their content.
+
+These modes are:
+
+| 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:
+
+```ruby
+map = Farce::Map.new(mode: :mutable)
+map[:content] = "Hi there!"
+
+Ractor.new(map) { it[:content] << " How are you doing?" }.join
+
+# Hi there! How are you doing?
+puts map[:content]
+```
+
+## Envelopes
+
+Farce allows you to explicitly wrap an object in an envelope. This is useful if you want to pass a value around between multiple Ractors (or multiple times between the same Ractors) without copying, wrapping, converting, or moving it every single time.
+
+Instead, you can wrap it in an envelope, and then later explicitly retrieve the value again.
+
+```ruby
+# We don't want to copy this over and over again.
+big_array = 10_000.times.map { rand }
+envelope  = Farce::Envelope.new(big_array) # copied in once, copied out on demand
+
+Ractor.new(envelope) do |envelope|
+  # we have a reference to envelope, but not a copy of its data
+  # this allows us to pass it on easily
+  queue = Farce::Queue.new(mode: :raise)
+  queue.push(envelope) # this is okay, the envelope is shareable
+
+  # We can pass the envelope by other means, like a queue!
+  Ractor.new(queue) do |queue|
+    message = queue.pop
+    # okay, let's get the copy, bypassing the outer ractor
+    copy_of_array = message.value
+    puts "Size of the array: #{copy_of_array.size}"
+  end
+end
+```
+
+Envelopes support `copy`, `move`, `local`, as well as a dummy envelope for wrapping shareable objects.
+
+## Mutables
+
+Mutables are special wrappers for Ruby objects that are Ractor-shareable when frozen but can be modified when not.
+
+```ruby
+mutable = Farce::Mutable.new("content")
+Ractor.new(mutable) { it << " & additional content" }.join
+mutable # => #<Farce::Mutable[String] "content & additional content">
+```
+
+They expose a mutable API by keeping a frozen snapshot of the wrapped object, atomically unfreezing, mutating, and freezing it whenever a method otherwise throws a `FrozenError`. This means non-mutating methods have almost no additional cost, and in contrast to [proxies](#proxies), method calls do not have to be dispatched across Ractors, even when modifying the object. However, mutating methods will copy the wrapped object's content. This may be fine, but could be expensive when used repeatedly on large objects.
+
+## Proxies
+
+A proxy mimics the API of another object, executing method calls within the Ractor that created it. This is an easy way to have drop-in replacements for objects that cannot be shared across Ractors.
+
+```ruby
+# Mutable arrays aren't Ractor-shareable
+array   = []
+proxied = []
+proxy   = Farce::Proxy.new(proxied)
+
+Farce::Ractor.new(array, proxy) do |*list|
+  list.each { it << 42 }
+end.join
+
+# The array got copied instead of being modified in place
+array # => []
+
+# The proxy didn't get copied
+proxied # => [42]
+```
+
+Use this for very large objects, where copying the object would be more expensive than the Ractor-coordination overhead, or objects that can not be moved or copied between Ractors.
+
+The downside is a dispatch to another Ractor on every method call.
+If copying on writes is an option, consider [`Farce::Mutable`](#mutables) instead.
+If the object may be moved across Ractors, maybe a [`Farce::Lease`](#leases) is a better option.
+
+There is an advanced [customization API](https://rkh.github.io/farce/main/Farce/Proxy.html), which allows fine-tuning and reducing overhead.
+
+## Mode Managers
+
+You can use a mode manager if you want to support sharing modes for a custom object.
+
+The mode manager might wrap objects in an envelope. It also exposes a method to unwrap objects again, which will only do so for envelopes created by the specific mode manager. That's why we were able to pass an envelope through the queue in the [example above](#envelopes) without it getting opened automatically.
+
+```ruby
+manager = Farce::ModeManager.new(mode: :move)
+payload = ["inside a mutable array"]
+Ractor.shareable?(payload) # => false
+
+shareable = manager.wrap(payload) # => #<Farce::Envelope::Move>
+Ractor.shareable?(shareable) # => true
+
+payload = shareable.value
+Ractor.shareable?(payload) # => false
+```
+
+## Leases
+
+You can think of a `Farce::Lease` as a reusable `move` envelope. Or [Haskell's MVar](https://hackage-content.haskell.org/package/base-4.22.0.0/docs/Control-Concurrent-MVar.html) if that's more your jam.
+
+You can store any object in it, including non-shareable ones (if they are movable). A Ractor can check objects out (at which point they get moved into that Ractor), work with them, and move them back into the lease container. The checkout call will block while another Ractor holds the lease, serializing any operations.
+
+This is very useful for objects that can be moved but can't be copied, especially IO-based objects like database connections.
+
+```ruby
+file_lease = Farce::Lease.new { File.open("example.txt", "w") }
+
+Ractor.new(file_lease) do |file_lease|
+  file_lease.checkout do |file|
+    file.puts "Written from another Ractor!"
+  end
+end.join
+
+# make sure we close the file
+file_lease.checkout(&:close)
+
+# dereference the lease so it can be garbage collected
+file_lease = nil
+```
+
+However, this might not be enough for handling database connections, where you'd usually have a pool of connections. You can use `Farce::LeasePool` which will manage multiple objects, only blocking on `checkout` if all objects have been leased.
+
+Moreover, it can generate these objects for you on demand (until a certain number has been reached).
+
+```ruby
+# db connections are created on demand if there are fewer than five
+pool = Farce::LeasePool.new(max_size: 5) { DB.connect }
+pool.size     # => 0
+pool.max_size # => 5
+
+pool.checkout do |db|
+  # ... do something with db ...
+end
+```
+
+Or, if you want to associate leasable values with keys, you can use a `LeaseMap`:
+
+```ruby
+leases = Farce::LeaseMap.new { { primary: [], replica: [] } }
+leases.checkout(:primary) { |items| items << :updated }
+leases.checkout(:primary, &:dup) # => [:updated]
+```
+
+At first glance, this looks just like a [map](data-structures.md#maps) of `Lease` instances. And it pretty much is, except it has some nice tooling on top of it, where it can automatically check values out and back in:
+
+```ruby
+leases = Farce::LeaseMap.new { { primary: [], replica: [] } }
+
+leases.auto_lease do
+  leases[:primary] << :updated
+  leases[:replica] << :replicated
+  leases[:primary] << :verified # Reuses the same checkout
+end
+
+# Both resources are checked back in when the block exits, even on an exception.
+leases.available?(:primary) # => true
+leases.checkout(:primary, &:dup) # => [:updated, :verified]
+```
+
+## Read Next
+
+[README](../README.md#features) · [Transfer modes](modes.md) · [Data Structures](data-structures.md)

data/docs/shims.md

@@ -0,0 +1,144 @@
+<!--
+# @title Shims, Polyfills, and Extensions
+-->
+
+# Shims, Polyfills, and Extensions
+
+Farce adapts Ruby APIs for use across Ractors and with Fiber schedulers. Its Ractor and Port implementations also provide fallbacks on Ruby engines without native Ractors.
+
+## Ractor
+
+Farce includes `Farce::Ractor`, which will either delegate to `Ractor` or supply a polyfill for it.
+
+On platforms that don't support Ractors, a Thread-based implementation is provided that tracks Ractor-membership via Thread
+groups.
+
+```ruby
+ractor = Farce::Ractor.new do
+  value = receive
+  puts "Received #{value.inspect}"
+end
+
+ractor.send 42
+```
+
+## Port
+
+Farce includes `Farce::Port`, which is either an extended subclass of `Ractor::Port` if it is available, or a polyfill if it isn't.
+
+In addition to `Ractor::Port` it supports the following features:
+* [Sharing modes](sharing.md#sharing-modes) both for `.new` and `#send`.
+* Opt-in auto-local sharing: If the port belongs to the current Ractor, any object can be sent to it without copying or moving it.
+* `#receive` supports a `timeout` option on all Ruby implementations and versions, not just CRuby 4.1+
+* You can use `#owned?` to check if the current Ractor owns a port.
+* `#receive` does not block a Fiber scheduler when called from a non-blocking Fiber.
+
+```ruby
+# reject unshareable values except if they are being sent from the ractor owning the port
+port   = Farce::Port.new(mode: :raise, auto_local: true)
+object = Object.new
+
+port.send(object)
+port.receive.equal?(object) # => true
+```
+
+## Backports
+
+While Farce includes `Farce::Ractor` and `Farce::Port`, it does not backport any methods to the standard `Ractor` class.
+
+Instead, backports are provided by `Farce::Backports`.
+
+### Available Backports
+
+#### From Ruby 4.0
+
+The following methods are added to `Ractor` on Ruby versions prior to 4.0:
+
+- [`default_port`](https://docs.ruby-lang.org/en/4.0/Ractor.html#method-i-default_port)
+- [`join`](https://docs.ruby-lang.org/en/4.0/Ractor.html#method-i-join)
+- [`monitor`](https://docs.ruby-lang.org/en/4.0/Ractor.html#method-i-monitor)
+- [`unmonitor`](https://docs.ruby-lang.org/en/4.0/Ractor.html#method-i-unmonitor)
+- [`value`](https://docs.ruby-lang.org/en/4.0/Ractor.html#method-i-value)
+
+#### From Ruby 4.1
+
+The following methods are added to `Ractor` on Ruby versions prior to 4.1:
+
+- [`alive?`](https://docs.ruby-lang.org/en/master/Ractor.html#method-i-alive-3F)
+
+It also extends the following methods with optional timeout support:
+
+- [`Ractor.select`](https://docs.ruby-lang.org/en/master/Ractor.html#method-c-select)
+- [`Ractor#receive`](https://docs.ruby-lang.org/en/master/Ractor.html#method-i-receive)
+- [`Ractor::Port#receive`](https://docs.ruby-lang.org/en/master/Ractor/Port.html#method-i-receive)
+
+No breaking changes are backported. This includes the updated [`monitor`](https://docs.ruby-lang.org/en/master/Ractor.html#method-i-monitor) behavior. The [polyfill](#ractor) will choose its `monitor` implementation based on `RUBY_VERSION` (so that any code checking the Ruby version will see the behavior it should).
+
+### Without Activating Backports
+
+You can call these methods on `Farce::Backports`, directly, passing in the Ractor instance as a first argument.
+
+```ruby
+ractor     = Farce::Ractor.new { sleep 1; raise "I'm not happy!" }
+supervisor = Farce::Ractor.new { puts "status: #{receive}" }
+port       = Farce::Backports.default_port(supervisor)
+
+# This will print "status: aborted" in approximately one second
+Farce::Backports.monitor(ractor, port)
+
+# Wait for the supervisor to receive the status
+Farce::Backports.join(supervisor)
+```
+
+### Using Backports via Refinements
+
+You can activate the backports for a lexical scope (within a file, or even just within a module within a file, or starting with Ruby 4.1 for an individual block) using them as a [refinement](https://docs.ruby-lang.org/en/master/syntax/refinements_rdoc.html):
+
+```ruby
+# only activates the backports for the current file
+using Farce::Backports
+
+# Refinements can't install constants, so we still need to use Farce::Ractor for JRuby/TruffleRuby
+# If you know you're on CRuby, you can replace Farce::Ractor with Ractor
+ractor     = Farce::Ractor.new { sleep 1; raise "I'm not happy!" }
+supervisor = Farce::Ractor.new { puts "status: #{receive}" }
+
+# These methods now work regardless of whether you used Ractor or Farce::Ractor
+port = supervisor.default_port
+ractor.monitor(port)
+supervisor.join
+```
+
+### Activating Backports Globally
+
+You can activate backports globally. As these don't override built-in methods, doing so should only cause issues for code expecting these methods not to be defined based on the `RUBY_VERSION` string.
+
+Anywhere before executing your code, like an initializer:
+
+```ruby
+Farce::Backports.install
+```
+
+Now you can do this in any file:
+
+```ruby
+# After installing backports globally, Ractor will always be defined
+ractor     = Ractor.new { sleep 1; raise "I'm not happy!" }
+supervisor = Ractor.new { puts "status: #{receive}" }
+ractor.monitor(supervisor.default_port)
+supervisor.join
+```
+
+## WeakRef
+
+`Farce::WeakRef` is a drop-in replacement for Ruby's [`WeakRef`](https://docs.ruby-lang.org/en/4.0/WeakRef.html), which at the time of writing cannot be used outside of the main Ractor at all.
+
+Farce implements a version based on weak [atoms](data-structures.md#atoms). Not only can it be used on non-main Ractors, `Farce::WeakRef` instances themselves are Ractor-shareable if the value they reference is also Ractor-shareable (or has been garbage collected). Moreover, calling `Ractor.make_shareable(weak_ref)` will propagate through to the referenced value.
+
+## Resolv
+
+`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.
+
+## Read Next
+
+[README](../README.md#features) · [Sharing Unshareable Data](sharing.md) · [Scheduling Code](scheduling.md)

data/docs/utilities.md

@@ -0,0 +1,93 @@
+<!--
+# @title Utilities and Custom Classes
+-->
+
+# Utilities and Custom Classes
+
+Farce provides helpers for converting object graphs, sharing custom classes, timing work, and coordinating access to values. Use these when adapting an existing library or building your own concurrency tools.
+
+## Top Level Methods
+
+* `Farce.clock` returns the monotonic clock time in seconds as a Float.
+* `Farce.config` returns the global configuration object.
+* `Farce.configure` allows you to configure Farce.
+* `Farce.dedup` de-duplicates the given object based on a deduplication cache shared by all Ractors.
+* `Farce.enfarce` turns a vanilla data structure into its Farce equivalent.
+* `Farce.freeze_graph` recursively freezes an object graph.
+* `Farce.in_parallel`, `Farce.on_main`, and `Farce.schedule`, see [Scheduling Code](scheduling.md#scheduling-code)
+* `Farce.rebind` rebinds a proc or lambda while preserving its Ractor-shareability.
+* `Farce.transaction` creates and runs a [transaction](concurrency.md#transactions).
+
+Some examples:
+
+```ruby
+a = { a: [+"b"] }
+b = { a: [+"b"] }
+
+# Farce.clock
+Farce.clock         # => 0.017476999908685684
+Farce.clock(in: 10) # => 10.017520000003278
+
+# Farce.dedup
+a.equal? b                           # => false
+Farce.dedup(a).equal? Farce.dedup(b) # => true
+
+# Farce.enfarce
+Farce.enfarce(a)         # => #<Farce::Map {a: #<Farce::Vector ["b"]>}>
+Farce::Strict.enfarce(a) # => #<Farce::Strict::Map {a: #<Farce::Strict::Vector ["b"]>}>
+
+# Farce.freeze_graph
+Farce.freeze_graph(a)
+
+# Farce.rebind
+callback = ->(add) { self + add }
+rebound  = Farce.rebind(callback, self: 42)
+rebound.call(18) # => 60
+```
+
+## Additional Classes
+
+Other classes Farce provides include:
+* `Config`: Configuration class, see [Third-Party Fiber Schedulers](scheduling.md#third-party-fiber-schedulers) example.
+* `ClassMirror`: inheritance-aware registry for classes
+* `Clock`: Timing functions based on a monotonic clock rather than on `Time`.
+* `Deduper`: Create your own deduplication cache. Direct usage isn't recommended, use [`Farce.dedup`](#top-level-methods) instead.
+* `Exchanger`: A synchronization point for two-way data swapping between Threads, Ractors, and/or Fibers. Drop-in replacement for concurrent-ruby's exchanger.
+* `Extension`: Defines extensions for existing classes that can either be activated globally or used as refinements.
+* `Lazy`: Lazily initialized value.
+* `LazyRef`: A [reference](data-structures.md#references) for a lazily initialized value.
+* `ThreadExecutor`: A [task executor](scheduling.md#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`](shims.md#weakref). Allows handling references more explicitly, without automatic method delegation.
+
+In addition, Farce includes a range of error classes not listed here. Check the [API documentation](https://rkh.github.io/farce/) or [code base](https://github.com/rkh/farce/blob/main/lib/farce/error.rb) for these.
+
+## Shareability Mixins
+
+Farce includes mixins to help you make your custom classes shareable:
+
+* `Shareable` automatically marks objects as shareable (via `Ractor.make_shareable`) after initialization.
+* `Shareable::Delegated` delegates `freeze` and `frozen?` to another object holding your object's state.
+* `Shareable::Immutable` instances are always immutable, being frozen after initialization.
+* `Shareable::Native` is for objects implemented in a native extension, which allows setting the frozen and shareable state separately.
+* `Shareable::Tracked` for objects implementing frozen tracking (via an internal [flag](data-structures.md#flags)).
+* `Shareable::Unfreezable` for objects that cannot be frozen (like [queues](data-structures.md#queues)).
+
+And also mixins to prevent them from being shareable:
+
+* `Unshareable`: Instances aren't shareable and cannot be made shareable. By default, they also cannot be copied or moved between Ractors.
+* `Unshareable::Copyable`: Instances aren't shareable but may be copied to another Ractor.
+* `Unshareable::Movable`: Instances aren't shareable but may be moved to another Ractor.
+
+`Unshareable::Copyable` and `Unshareable::Movable` may be combined.
+
+## Constants
+
+* `Farce::MODES`: List of supported [sharing modes](sharing.md#sharing-modes).
+* `Farce::NULL_PORT`: A special `Ractor::Port` that acts as a sink for messages and never closes.
+* `Farce::SCOPES`: List of [provided scopes](variants-and-scopes.md#provided-scopes).
+* `Farce::VERSION`: The current version.
+
+## Read Next
+
+[README](../README.md#features) · [Sharing Unshareable Data](sharing.md) · [Integrations](integrations.md)

data/docs/variants-and-scopes.md

@@ -0,0 +1,92 @@
+<!--
+# @title Variants and Scopes
+-->
+
+# Variants and Scopes
+
+Many classes, including all [data structures](data-structures.md#data-structures), implement multiple variants as separate subclasses within module namespaces.
+
+`Farce::Map`, `Farce::Strict::Map`, `Farce::Local::Map`, and `Farce::Unshared::Map` all support the same API, except that:
+
+* `Farce::Map` accepts an optional `mode` keyword for its initializer and many methods.
+* `Farce::Strict::Map` will not allow any non-shareable data to be stored in it. It is slightly faster than `Farce::Map`.
+* `Farce::Local::Map` will accept an optional `scope`  keyword for its initializer, and will have different content for each [scope](#provided-scopes).
+* `Farce::Unshared::Map` cannot be shared across Ractors, but in turn can store any Ruby object directly, including unshareable objects. It is as fast as `Farce::Strict::Map`.
+
+## Available Variants
+
+> [!TIP]
+> Learn more in the dedicated [variants documentation](variants.md).
+
+These variants are provided by Farce:
+
+1. **Default** variants, under the `Farce` namespace:
+   * Can **store unshareable values**, usually via [modes](sharing.md#sharing-modes).
+     For maps, this is only supported for values. Keys must be shareable.
+   * Instances are **Ractor-shareable**.
+   * The data structure is **thread-safe**.
+2. **Strict** variants, under the `Farce::Strict` namespace:
+   * **Forbid unshareable values**
+   * Instances are **Ractor-shareable**.
+   * The data structure is **thread-safe**.
+   * May provide performance benefits over the default variant.
+3. **Local** variants, under the `Farce::Local` namespace:
+   * Will have **different content** for each [scope](#provided-scopes).
+   * Can **store unshareable values**, including unshareable map keys.
+   * Instances are **Ractor-shareable**.
+   * The data structure is **thread-safe**.
+4. **Unshared** variants, under `Farce::Unshared` namespace:
+   * Can **store unshareable values**, including unshareable map keys.
+   * Instances are **<u>not</u> Ractor-shareable**.
+   * The data structure is **thread-safe**.
+   * May provide performance benefits over the default variant.
+5. **Unsafe** variants, under `Farce::Unsafe` namespace:
+   * Same as Unshared, except they do **<u>not</u> guarantee thread-safety**
+   * May provide performance benefits over all other variants.
+6. **Transaction** variants, under `Farce::Transaction` namespace:
+   * Created as mirrors of another object within a [transaction](concurrency.md#transactions).
+   * Should not be shared across transaction boundaries.
+   * Should not be initialized directly.
+
+The following is true for all variants:
+* Blocking operations will suspend a non-blocking fiber, but not block the underlying scheduler.
+* The return value of `frozen?` will correctly reflect whether an instance is mutable or not.
+
+However, keep the following in mind:
+* Not all classes implement all variants. Check out the [full list](variants.md#classes-implementing-variants)
+* Other classes that don't implement variants are also nested under the `Farce` namespace.
+
+## Provided scopes
+
+> [!TIP]
+> Learn more in the dedicated [scopes documentation](scopes.md).
+
+Local variants support scopes:
+
+```ruby
+map      = Farce::Local::Map.new(scope: :thread)
+map[:id] = 1
+
+Thread.new do
+  map[:id] = 2
+  map[:id] # => 2
+end.join
+
+map[:id] # => 1
+```
+
+The following scopes are available:
+
+ | Scope              | Description                                                                                      |
+ | ------------------ | ------------------------------------------------------------------------------------------------ |
+ | `ractor` (default) | Content varies by [Ractor](https://docs.ruby-lang.org/en/4.0/Ractor.html)                        |
+ | `thread_group`     | Content varies by [ThreadGroup](https://docs.ruby-lang.org/en/4.0/ThreadGroup.html)              |
+ | `thread`           | Content varies by [Thread](https://docs.ruby-lang.org/en/4.0/Thread.html)                        |
+ | `fiber_storage`    | Content varies by [Fiber storage](https://docs.ruby-lang.org/en/4.0/Fiber.html#method-i-storage) |
+ | `fiber`            | Content varies by [Fiber](https://docs.ruby-lang.org/en/4.0/Fiber.html)                          |
+
+Fiber storage is typically inherited by a blocking fiber from the fiber creating it.
+
+## Read Next
+
+[README](../README.md#features) · [Variants](variants.md) · [Local scopes](scopes.md) · [Sharing Unshareable Data](sharing.md)

data/lib/farce/abstract/flag.rb

@@ -59,6 +59,12 @@ module Farce
       include Internal::ValueSerialization
       include Internal::Inspect
 
+      # @return [Boolean] whether the flag is set
+      def set? = value
+
+      # @return [Boolean] whether the flag is unset
+      def unset? = !value
+
       # Wait until the flag becomes true.
       # @param timeout [Numeric, nil] the total seconds available
       # @yield called when the timeout expires