Module: Farce

Defined in:: lib/farce/map.rb,
lib/farce/_yard/ractor.rb,
lib/farce/_yard/internal.rb,
lib/farce/set.rb,
lib/farce/atom.rb,
lib/farce/flag.rb,
lib/farce/lazy.rb,
lib/farce/lock.rb,
lib/farce/pool.rb,
lib/farce/port.rb,
lib/farce/task.rb,
lib/farce/clock.rb,
lib/farce/error.rb,
lib/farce/lease.rb,
lib/farce/local.rb,
lib/farce/proxy.rb,
lib/farce/queue.rb,
lib/farce/config.rb,
lib/farce/ractor.rb,
lib/farce/resolv.rb,
lib/farce/signal.rb,
lib/farce/strict.rb,
lib/farce/system.rb,
lib/farce/unsafe.rb,
lib/farce/vector.rb,
lib/farce/walker.rb,
lib/farce/counter.rb,
lib/farce/deduper.rb,
lib/farce/lfu_map.rb,
lib/farce/lru_map.rb,
lib/farce/memoize.rb,
lib/farce/mutable.rb,
lib/farce/version.rb,
lib/farce/abstract.rb,
lib/farce/envelope.rb,
lib/farce/lazy_ref.rb,
lib/farce/molecule.rb,
lib/farce/tree_map.rb,
lib/farce/unshared.rb,
lib/farce/weak_map.rb,
lib/farce/weak_ref.rb,
lib/farce/weak_set.rb,
lib/farce/backports.rb,
lib/farce/exchanger.rb,
lib/farce/extension.rb,
lib/farce/lease_map.rb,
lib/farce/local/map.rb,
lib/farce/local/set.rb,
lib/farce/null_port.rb,
lib/farce/publisher.rb,
lib/farce/reference.rb,
lib/farce/scheduler.rb,
lib/farce/shareable.rb,
lib/farce/weak_atom.rb,
lib/farce/concurrent.rb,
lib/farce/lease_pool.rb,
lib/farce/local/atom.rb,
lib/farce/local/flag.rb,
lib/farce/local/lazy.rb,
lib/farce/local/pool.rb,
lib/farce/resolv/dns.rb,
lib/farce/sorted_set.rb,
lib/farce/strict/map.rb,
lib/farce/strict/set.rb,
lib/farce/weak_value.rb,
lib/farce/local/lease.rb,
lib/farce/local/queue.rb,
lib/farce/strict/atom.rb,
lib/farce/strict/flag.rb,
lib/farce/strict/lazy.rb,
lib/farce/strict/port.rb,
lib/farce/timer_queue.rb,
lib/farce/transaction.rb,
lib/farce/unshareable.rb,
lib/farce/abstract/map.rb,
lib/farce/abstract/set.rb,
lib/farce/class_mirror.rb,
lib/farce/integrations.rb,
lib/farce/local/scoped.rb,
lib/farce/local/vector.rb,
lib/farce/mode_manager.rb,
lib/farce/strict/lease.rb,
lib/farce/strict/queue.rb,
lib/farce/subscription.rb,
lib/farce/unshared/map.rb,
lib/farce/unshared/set.rb,
lib/farce/weak_key_map.rb,
lib/farce/abstract/atom.rb,
lib/farce/abstract/flag.rb,
lib/farce/abstract/lazy.rb,
lib/farce/abstract/pool.rb,
lib/farce/abstract/port.rb,
lib/farce/local/counter.rb,
lib/farce/local/lfu_map.rb,
lib/farce/local/lru_map.rb,
lib/farce/proxy/wrapper.rb,
lib/farce/strict/vector.rb,
lib/farce/unshared/atom.rb,
lib/farce/unshared/flag.rb,
lib/farce/unshared/lazy.rb,
lib/farce/unshared/pool.rb,
lib/farce/abstract/lease.rb,
lib/farce/abstract/queue.rb,
lib/farce/abstract/value.rb,
lib/farce/local/lazy_ref.rb,
lib/farce/local/molecule.rb,
lib/farce/local/tree_map.rb,
lib/farce/local/weak_map.rb,
lib/farce/local/weak_set.rb,
lib/farce/priority_queue.rb,
lib/farce/proxy/register.rb,
lib/farce/strict/counter.rb,
lib/farce/strict/lfu_map.rb,
lib/farce/strict/lru_map.rb,
lib/farce/unsafe/lfu_map.rb,
lib/farce/unsafe/lru_map.rb,
lib/farce/unshared/lease.rb,
lib/farce/unshared/queue.rb,
lib/farce/weak_value_map.rb,
lib/farce/abstract/vector.rb,
lib/farce/integrations/oj.rb,
lib/farce/local/lease_map.rb,
lib/farce/local/publisher.rb,
lib/farce/local/scheduler.rb,
lib/farce/local/weak_atom.rb,
lib/farce/read_write_lock.rb,
lib/farce/strict/lazy_ref.rb,
lib/farce/strict/molecule.rb,
lib/farce/strict/tree_map.rb,
lib/farce/strict/weak_map.rb,
lib/farce/strict/weak_set.rb,
lib/farce/thread_executor.rb,
lib/farce/transaction/map.rb,
lib/farce/transaction/set.rb,
lib/farce/unsafe/tree_map.rb,
lib/farce/unshared/vector.rb,
lib/farce/abstract/counter.rb,
lib/farce/abstract/lfu_map.rb,
lib/farce/abstract/lru_map.rb,
lib/farce/concurrent/event.rb,
lib/farce/concurrent/tuple.rb,
lib/farce/local/lease_pool.rb,
lib/farce/local/sorted_set.rb,
lib/farce/proxy/supervisor.rb,
lib/farce/strict/exchanger.rb,
lib/farce/strict/lease_map.rb,
lib/farce/strict/publisher.rb,
lib/farce/strict/weak_atom.rb,
lib/farce/transaction/atom.rb,
lib/farce/unshared/counter.rb,
lib/farce/unshared/lfu_map.rb,
lib/farce/unshared/lru_map.rb,
lib/farce/abstract/executor.rb,
lib/farce/abstract/molecule.rb,
lib/farce/abstract/tree_map.rb,
lib/farce/abstract/weak_map.rb,
lib/farce/abstract/weak_set.rb,
lib/farce/integrations/bson.rb,
lib/farce/integrations/cbor.rb,
lib/farce/local/timer_queue.rb,
lib/farce/strict/lease_pool.rb,
lib/farce/strict/sorted_set.rb,
lib/farce/strict/weak_cache.rb,
lib/farce/unshared/lazy_ref.rb,
lib/farce/unshared/molecule.rb,
lib/farce/unshared/tree_map.rb,
lib/farce/unshared/weak_map.rb,
lib/farce/unshared/weak_set.rb,
lib/farce/abstract/exchanger.rb,
lib/farce/abstract/lease_map.rb,
lib/farce/abstract/publisher.rb,
lib/farce/abstract/scheduler.rb,
lib/farce/abstract/weak_atom.rb,
lib/farce/integrations/psych.rb,
lib/farce/local/weak_key_map.rb,
lib/farce/strict/timer_queue.rb,
lib/farce/transaction/vector.rb,
lib/farce/unshared/lease_map.rb,
lib/farce/unshared/publisher.rb,
lib/farce/unshared/scheduler.rb,
lib/farce/unshared/weak_atom.rb,
lib/farce/walker/definitions.rb,
lib/farce/abstract/collection.rb,
lib/farce/abstract/lease_pool.rb,
lib/farce/abstract/sorted_set.rb,
lib/farce/strict/weak_key_map.rb,
lib/farce/transaction/mutable.rb,
lib/farce/transaction/wrapper.rb,
lib/farce/unshared/lease_pool.rb,
lib/farce/unshared/sorted_set.rb,
lib/farce/walker/modification.rb,
lib/farce/abstract/bounded_map.rb,
lib/farce/abstract/timer_queue.rb,
lib/farce/concurrent/local_var.rb,
lib/farce/integrations/msgpack.rb,
lib/farce/integrations/weakref.rb,
lib/farce/local/priority_queue.rb,
lib/farce/local/weak_value_map.rb,
lib/farce/transaction/molecule.rb,
lib/farce/transaction/tree_map.rb,
lib/farce/unshared/timer_queue.rb,
lib/farce/abstract/weak_key_map.rb,
lib/farce/strict/priority_queue.rb,
lib/farce/strict/weak_value_map.rb,
lib/farce/unshared/weak_key_map.rb,
lib/farce/integrations/dry_types.rb,
lib/farce/transaction/sorted_set.rb,
lib/farce/abstract/concurrent_map.rb,
lib/farce/abstract/duplicable_map.rb,
lib/farce/abstract/priority_queue.rb,
lib/farce/abstract/weak_value_map.rb,
lib/farce/integrations/concurrent.rb,
lib/farce/integrations/sorted_set.rb,
lib/farce/mode_manager/smart_rule.rb,
lib/farce/unshared/priority_queue.rb,
lib/farce/unshared/weak_value_map.rb,
lib/farce/subscription/definitions.rb,
lib/farce/concurrent/cyclic_barrier.rb,
lib/farce/integrations/ractor_tmvar.rb,
lib/farce/concurrent/fiber_local_var.rb,
lib/farce/transaction/map_operations.rb,
lib/farce/transaction/set_operations.rb,
lib/farce/concurrent/count_down_latch.rb,
lib/farce/concurrent/thread_local_var.rb,
lib/farce/integrations/ractor_sharing.rb,
lib/farce/integrations/shared/to_json.rb,
lib/farce/integrations/active_support/map.rb,
lib/farce/integrations/active_support/set.rb,
lib/farce/integrations/active_support/blank.rb,
lib/farce/integrations/active_support/clock.rb,
lib/farce/integrations/active_support/vector.rb,
lib/farce/integrations/active_support/duplicable.rb,
lib/farce/integrations/active_support/value_serialization.rb,
lib/farce.rb

Overview

Namespace for everything provided by Farce.

Including Farce

Including Farce in a class or module will include all public camel-case constants defined under the Farce namespace.

require "farce"

# This could also be done under a class or module, to avoid polluting the global namespace.
include Farce

# Now Ractor is available, even on JRuby or TruffleRuby!
Ractor.new { puts "Hello from a Ractor!" }

# Other constants are also available.
Clock.parse(1.minute.from_now)

# VERSION is not exposed. This is to avoid polluting other libraries with it.
defined?(VERSION) # => false

Defined Under Namespace

Modules: Abstract, Backports, Clock, Concurrent, Local, Memoize, MessagePack, Ractor, Resolv, Shareable, Strict, System, Unsafe, Unshareable, Unshared Classes: Atom, ClassMirror, Config, Counter, Deduper, Envelope, Exchanger, Extension, Flag, LFUMap, LRUMap, Lazy, LazyRef, Lease, LeaseMap, LeasePool, Lock, Map, ModeManager, Molecule, Mutable, Pool, Port, PriorityQueue, Proxy, Publisher, Queue, ReadWriteLock, Reference, Scheduler, Set, Signal, SortedSet, Subscription, Task, ThreadExecutor, TimerQueue, Transaction, TreeMap, Vector, Walker, WeakAtom, WeakKeyMap, WeakMap, WeakRef, WeakSet, WeakValue, WeakValueMap

Constant Summary collapse

ClosedQueueError = Raised when an operation cannot proceed because a queue is closed.

Class.new(::ClosedQueueError)

SealedQueueError = Raised when a push cannot proceed because a queue is sealed.

Class.new(ClosedQueueError)

SchedulerClosedError = Raised when attempting to schedule a task on a closed scheduler.

Class.new(StandardError)

PoolClosedError = Raised when attempting to schedule a task on a closed pool.

Class.new(SchedulerClosedError)

TimeoutError = Raised when a timed operation does not complete before its timeout.

Class.new(StandardError)

OwnershipError = Raised when an operation requires ownership by the current Fiber.

Class.new(StandardError)

RetiredLeaseError = Raised when attempting to use a permanently retired lease.

Class.new(StandardError)

WeakRefError = Raised when a weak reference is no longer valid because the referenced object has been garbage collected.

Class.new(defined?(::WeakRef::RefError) ? ::WeakRef::RefError : StandardError)

VERSION = Returns the current version of Farce. Returns: (String) — the current version of Farce

"0.6.0"

NULL_PORT = Special, write-only port that discards all messages. If the Ruby environment supports ports, this will be a real Port object. It can therefore be passed to any API expecting a Ractor::Port, including C code. Cannot be read from, but does not accumulate messages in memory. Returns: (Ractor::Port) — Write-only port

Internal::NullPort.new

SCOPES = The valid storage scopes for local values and collections. Returns: (::Set<Symbol>)

::Set[:ractor, :thread_group, :thread, :fiber_storage, :fiber].freeze

MODES = The valid transfer modes for values that are not Ractor-shareable. Returns: (::Set<Symbol>)

::Set[
  :copy, :marshal, :move, :local, :make_shareable, :mutable, :raise, :shareable_copy, :dedup, :proxy,
  :smart, :smart_raise, :smart_move, :smart_copy,
].freeze

Class Method Summary collapse

.clock ⇒ Float
Monotonic clock time in seconds, from when clock was called the first time.
.config ⇒ Config
.configure {|config| ... } ⇒ BasicObject
Configures Farce.
.dedup(object = UNDEFINED) ⇒ BasicObject
Deduplicate values using the default Deduper.
.DryTypes(*namespaces, default: UNDEFINED, variant: :shared, mode: UNDEFINED, scope: UNDEFINED, **aliases) ⇒ Module
Build a dry-types import for Farce types.
.enfarce(object, freeze: nil, mode: :smart) {|object| ... } ⇒ BasicObject
Converts vanilla Ruby objects into their Farce equivalents.
.freeze_graph(object, freeze_modules: false, traverse_modules: freeze_modules) ⇒ Object
Recursively freeze an object graph using Walker traversal.
.in_parallel(*args, mode: UNDEFINED) ⇒ Abstract::Executor^?
Schedules work without waiting for the block to finish.
.on_main(*args, mode: UNDEFINED) ⇒ Abstract::Executor^?
Allows executing code on the main ractor from other ractors.
.rebind(bindable = nil, lambda: nil, **self_option, &block) ⇒ Proc, Method
Binds a proc, lambda, block, bound or unbound method to a new self.
.schedule(*args, mode: :smart, auto_local: true, **kwargs) {|*args| ... } ⇒ nil
Schedules work to be executed out of band.
.transaction(*objects, retries: nil, backoff_after: 10, max_backoff: 1.0) {|transaction, *objects| ... } ⇒ Boolean
Creates and runs a new transaction attempt.

Class Method Details

.clock ⇒ `Float` .clock(value) ⇒ `Float` .clock(at:) ⇒ `Float` .clock(time:) ⇒ `Float` .clock(timeout_at:) ⇒ `Float` .clock(delay:) ⇒ `Float` .clock(offset:) ⇒ `Float` .clock(timeout:) ⇒ `Float` .clock(wait:) ⇒ `Float`

Returns monotonic clock time in seconds, from when clock was called the first time.

Overloads:

.clock ⇒ Float

The current clock time
.clock(value) ⇒ Float

Parses value into a monotonic clock time.
Parameters:
- value (nil, Numeric, Time, ActiveSupport::Duration, Hash) —
  the value to convert to clock time
See Also:
- Farce::Clock.parse
.clock(at:) ⇒ Float

Gives the clock time for a fixed point in time. Independent of the current time.
Parameters:
- at (Numeric, Time) —
  the value to convert to clock time
.clock(time:) ⇒ Float

Gives the clock time for a fixed point in time. Independent of the current time.
Parameters:
- time (Numeric, Time) —
  the value to convert to clock time
.clock(timeout_at:) ⇒ Float

Gives the clock time for a fixed point in time. Independent of the current time.
Parameters:
- timeout_at (Numeric, Time) —
  the value to convert to clock time
.clock(delay:) ⇒ Float

Gives the clock time for a relative offset from the current time.
Parameters:
- delay (Numeric) —
  the value to convert to clock time
.clock(offset:) ⇒ Float

Gives the clock time for a relative offset from the current time.
Parameters:
- offset (Numeric) —
  the value to convert to clock time
.clock(timeout:) ⇒ Float

Gives the clock time for a relative offset from the current time.
Parameters:
- timeout (Numeric) —
  the value to convert to clock time
.clock(wait:) ⇒ Float

Gives the clock time for a relative offset from the current time.
Parameters:
- wait (Numeric) —
  the value to convert to clock time

Returns:

(Float) —
monotonic clock time in seconds, from when clock was called the first time

147	# File 'lib/farce.rb', line 147 def self.clock(...) = Clock.parse(...)

.config ⇒ `Config`

Returns the global Farce configuration.

Returns:

(Config) —
the global Farce configuration

# File 'lib/farce/config.rb', line 341

def self.config(&)
  configure(&) if block_given?
  CONFIG
end

.configure {|config| ... } ⇒ `BasicObject`

Configures Farce.

Examples:

Farce.configure do |config|
  config.fiber_scheduler = :carbon_fiber
end

Yields:

(config) —
the configuration object

337	# File 'lib/farce/config.rb', line 337 def self.configure = yield CONFIG

.dedup(object, copy: false, skip: nil) ⇒ `Object` .dedup ⇒ `Deduper`

Deduplicate values using the default Deduper. Cached values are held weakly, so retaining only an object_id does not keep its canonical object alive. Keep the returned object to preserve its identity.

Overloads:

.dedup(object, copy: false, skip: nil) ⇒ Object

Reuse equal strings and frozen containers throughout an object graph.
Examples:

Preserve the input
```
first = Farce.dedup(["foo"], copy: true)
Farce.dedup(["foo"]).equal?(first) # => true
```
Parameters:
- object (Object) —
  the root object
- copy (Boolean, Symbol) (defaults to: false) —
  false to update the input, true to copy it, or a copy method such as :clone
- skip (Module, Array<Module>, nil) (defaults to: nil) —
  additional classes or modules to skip
Returns:
- (Object) —
  the deduplicated result
.dedup ⇒ Deduper

Return the default deduper to configure subsequent calls.
Examples:

Exclude a class and its children
```
Farce.dedup.skip(SomeClass)
```
Cache another value class
```
Farce.dedup.store(MyValue)
```
Returns:
- (Deduper)

See Also:

Farce::Deduper#dedup

# File 'lib/farce.rb', line 172

def self.dedup(object = UNDEFINED, **)
  return DEDUPER if UNDEFINED.equal?(object)
  DEDUPER.dedup(object, **)
end

.DryTypes(*namespaces, default: UNDEFINED, variant: :shared, mode: UNDEFINED, scope: UNDEFINED, **aliases) ⇒ `Module`

Note:

This methods is only available if dry-types has been loaded.

Build a dry-types import for Farce types.

With no dry namespace options, the import uses the nearest Dry.Types() import already included in the receiving module. Without one, it uses the same strict defaults as Dry.Types(). Dry namespace arguments, default:, and aliases select an independent source import using Dry.Types() rules.

Parameters:

namespaces (Array<Symbol>) —
Dry type namespaces to import Farce counterparts for.
default (Symbol) (defaults to: UNDEFINED) —
The Dry namespace used for root Farce type constants.
variant (Symbol) (defaults to: :shared) —
The output variant: :shared, :strict, :unshared, or :local.
mode (Symbol) (defaults to: UNDEFINED) —
The transfer mode for the shared variant.
scope (Symbol) (defaults to: UNDEFINED) —
The storage scope for the local variant.
aliases (Hash{Symbol => Symbol}) —
Dry namespace aliases.

Returns:

(Module) —
A module for inclusion beside Dry.Types().

# File 'lib/farce/integrations/dry_types.rb', line 691

def self.DryTypes( # rubocop:disable Naming/MethodName
  *namespaces, default: UNDEFINED, variant: :shared, mode: UNDEFINED, scope: UNDEFINED, **aliases
)
  internal = const_get(:Internal, false).const_get(:DryTypes, false)
  internal.import(namespaces, default:, aliases:, variant:, mode:, scope:)
end

.enfarce(object, freeze: nil, mode: :smart) {|object| ... } ⇒ `BasicObject`

Converts vanilla Ruby objects into their Farce equivalents.

Valid modes are:

:smart - Applies smart rules or a dedicated proxy. Raises for unsupported values. This is the default for most mode-backed classes.
:smart_raise - Applies smart rules or a dedicated proxy, with a raising fallback.
:smart_copy - Applies smart rules or a dedicated proxy, then falls back to copying or Marshal. This is the default for Port.
:smart_move - Applies smart rules or a dedicated proxy, then falls back to moving.
:copy - The value will be copied between Ractors.
:marshal - The value will be serialized immediately and reconstructed once per Ractor with Ruby's Marshal protocol. Contents must support Marshal. Nested shareable values may be reconstructed too.
:make_shareable - The value will be made Ractor-shareable using Farce::Ractor.make_shareable.
:move - The value will be moved between Ractors. This saves memory compared to copying, and supports values that can't be copied but moved (like IO objects). However, the value will no longer be accessible on the Ractor that pushed it.
:mutable - A Mutable instance will be created for the value. This isn't done recursively and thus will fail for nested unshareable values.
:local - The value will be kept local to the Ractor that pushed it. Another ractor trying to receive it will get an error. Useful for usage contained within a single Ractor.
:proxy - The value will be wrapped in a Farce::Proxy that executes calls in the original Ractor.
:raise - An error will be raised if the value is not Ractor-shareable. Useful for enforcing shareability.
:dedup - The value will be deduplicated using dedup, then made Ractor-shareable. This may update and freeze the original. Already-shareable values pass through unchanged.
:shareable_copy - The value will be copied and the copy will be made Ractor-shareable.

Examples:

Farce.enfarce({ foo: ["bar"] }) # =>  #<Farce::Map {foo: #<Farce::Vector ["bar"]>}>

Parameters:

object (BasicObject) —
The root object to convert
freeze (Boolean, nil) (defaults to: nil) —
Whether to freeze the converted objects. If set to nil (default), the freezing behavior will depend on the original object's frozen state.
mode (Symbol) (defaults to: :smart) —
The conversion mode, e.g., :copy.

Yields:

(object) —
Optional block, called with any object that doesn't have a specific conversion defined.

Yield Parameters:

object (BasicObject) —
the object to convert

Yield Returns:

(BasicObject) —
the converted object

Returns:

(BasicObject) —
the converted object

See Also:

198	# File 'lib/farce.rb', line 198 def self.enfarce(object, , &) = Internal::Converter.new(self, , &).convert(object)

.freeze_graph(object, freeze_modules: false, traverse_modules: freeze_modules) ⇒ `Object`

Recursively freeze an object graph using Walker traversal.

Visits container elements, hash keys and values, and instance variables. Shared children and cycles are preserved.

Classes and modules are skipped by default. If it is enabled, then traversal visits instance variables, directly defined public constants, and directly defined class variables. Autoloads are skipped.

Freezes objects in place and returns the original root. Already frozen objects are still traversed so their mutable children are frozen too.

Examples:

Freeze nested values in place

values = { tags: [+"ruby"] }
Farce.freeze_graph(values).equal?(values)        # => true
values[:tags].frozen?                           # => true
values[:tags].first.frozen?                     # => true

Freeze children of an already frozen container

values = [+"ruby"].freeze
Farce.freeze_graph(values).equal?(values)        # => true
values.first.frozen?                            # => true

Freeze module state while allowing new methods

mod = Module.new
mod.instance_variable_set(:@tags, [+"ruby"])
Farce.freeze_graph(mod, traverse_modules: true)
mod.instance_variable_get(:@tags).first.frozen? # => true
mod.frozen?                                     # => false

Parameters:

object (Object) —
the root object
freeze_modules (Boolean) (defaults to: false) —
whether to freeze classes and modules
traverse_modules (Boolean) (defaults to: freeze_modules) —
whether to visit class and module instance variables. Defaults to freeze_modules, but can be set independently.

Returns:

(Object) —
the original root. Skipped modules retain their frozen state.

See Also:

Walker

# File 'lib/farce.rb', line 236

def self.freeze_graph(object, freeze_modules: false, traverse_modules: freeze_modules)
  Walker.visit(object) do |node, walker|
    if Module === node
      traverse = traverse_modules
      freeze   = freeze_modules
    else
      traverse = true
      freeze   = true
    end

    walker.traverse if traverse
    node.freeze if freeze
    node
  end
end

.in_parallel(args, mode: :smart) {|args| ... } ⇒ `nil` .in_parallel ⇒ `Abstract::Executor`

Schedules work without waiting for the block to finish. On CRuby, uses a shared Ractor pool with at most Farce::System.cpu_count workers by default. Set Config's parallel_pool_* options before creating a scheduler to configure its worker limits, growth and shrink delays, per-worker task limit, and queue capacity. On JRuby and TruffleRuby, starts a new thread for each task.

Without a block, returns the shared scheduler. The CRuby pool starts workers when tasks arrive. Pass mutable task data as arguments so it can be transferred based on the given mode.

Valid modes are:

:smart - Applies smart rules or a dedicated proxy. Raises for unsupported values. This is the default for most mode-backed classes.
:smart_raise - Applies smart rules or a dedicated proxy, with a raising fallback.
:smart_copy - Applies smart rules or a dedicated proxy, then falls back to copying or Marshal. This is the default for Port.
:smart_move - Applies smart rules or a dedicated proxy, then falls back to moving.
:copy - The value will be copied between Ractors.
:marshal - The value will be serialized immediately and reconstructed once per Ractor with Ruby's Marshal protocol. Contents must support Marshal. Nested shareable values may be reconstructed too.
:make_shareable - The value will be made Ractor-shareable using Farce::Ractor.make_shareable.
:move - The value will be moved between Ractors. This saves memory compared to copying, and supports values that can't be copied but moved (like IO objects). However, the value will no longer be accessible on the Ractor that pushed it.
:mutable - A Mutable instance will be created for the value. This isn't done recursively and thus will fail for nested unshareable values.
:local - The value will be kept local to the Ractor that pushed it. Another ractor trying to receive it will get an error. Useful for usage contained within a single Ractor.
:proxy - The value will be wrapped in a Farce::Proxy that executes calls in the original Ractor.
:raise - An error will be raised if the value is not Ractor-shareable. Useful for enforcing shareability.
:dedup - The value will be deduplicated using dedup, then made Ractor-shareable. This may update and freeze the original. Already-shareable values pass through unchanged.
:shareable_copy - The value will be copied and the copy will be made Ractor-shareable.

Examples:

Farce.in_parallel("hello") { |message| puts message.upcase }
Farce.in_parallel.schedule { puts "another task" }

Overloads:

.in_parallel(*args, mode: :smart) {|*args| ... } ⇒ nil
Parameters:
- args (Array<Object>) —
  Arguments passed to the block.
- mode (Symbol) (defaults to: :smart) —
  Argument transfer mode. Ignored on JRuby and TruffleRuby.
Yields:
- (*args) —
  The task to schedule.
Returns:
- (nil)
.in_parallel ⇒ Abstract::Executor

Returns The shared scheduler.
Returns:
- (Abstract::Executor) —
  The shared scheduler.

Returns:

(Abstract::Executor, nil)

See Also:

on_main

# File 'lib/farce.rb', line 457

def self.in_parallel(*args, mode: UNDEFINED, &)
  unless block_given?
    raise LocalJumpError, "no block given" unless args.empty? && UNDEFINED.equal?(mode)
    return Internal::ParallelScheduler
  end

  mode = :smart if UNDEFINED.equal?(mode)
  Internal::ParallelScheduler.schedule(*args, mode:, &)
  nil
end

.on_main(args, mode: :smart) {|args| ... } ⇒ `nil` .on_main ⇒ `Abstract::Executor`

Allows executing code on the main ractor from other ractors. This allows modifying objects and calling methods only accessible from the main ractor.

If a block is given, executes it on the main ractor, passing any given arguments to it. Blocks the current thread until the block has finished executing.

Arguments are transferred based on the given mode.

Valid modes are:

:smart - Applies smart rules or a dedicated proxy. Raises for unsupported values. This is the default for most mode-backed classes.
:smart_raise - Applies smart rules or a dedicated proxy, with a raising fallback.
:smart_copy - Applies smart rules or a dedicated proxy, then falls back to copying or Marshal. This is the default for Port.
:smart_move - Applies smart rules or a dedicated proxy, then falls back to moving.
:copy - The value will be copied between Ractors.
:marshal - The value will be serialized immediately and reconstructed once per Ractor with Ruby's Marshal protocol. Contents must support Marshal. Nested shareable values may be reconstructed too.
:make_shareable - The value will be made Ractor-shareable using Farce::Ractor.make_shareable.
:move - The value will be moved between Ractors. This saves memory compared to copying, and supports values that can't be copied but moved (like IO objects). However, the value will no longer be accessible on the Ractor that pushed it.
:mutable - A Mutable instance will be created for the value. This isn't done recursively and thus will fail for nested unshareable values.
:local - The value will be kept local to the Ractor that pushed it. Another ractor trying to receive it will get an error. Useful for usage contained within a single Ractor.
:proxy - The value will be wrapped in a Farce::Proxy that executes calls in the original Ractor.
:raise - An error will be raised if the value is not Ractor-shareable. Useful for enforcing shareability.
:dedup - The value will be deduplicated using dedup, then made Ractor-shareable. This may update and freeze the original. Already-shareable values pass through unchanged.
:shareable_copy - The value will be copied and the copy will be made Ractor-shareable. Calls from the main ractor execute directly, preserving the block and arguments.

If no block is given, it returns a scheduler to execute tasks on the main ractor. This allows scheduling without blocking the current thread.

On JRuby and TruffleRuby, blocks run inline because there is no native Ractor isolation. The returned ThreadExecutor starts a new thread for each scheduled task.

Examples:

$results = []

Farce::Ractor.new do
  # maybe computing this string on the main ractor is too expensive?
  my_string = "foo bar baz"

  # can't access $results on the current ractor directly, as it isn't shareable
  Farce.on_main(my_string) { $results << it }
end.join

$results # => ["foo bar baz"]

Blocking vs non-blocking

Farce::Ractor.new do
  # This blocks the current thread until the block has finished executing.
  Farce.on_main do
    sleep 1
    puts "Hi from the main ractor!"
  end

  # This does not block the current thread.
  Farce.on_main.schedule do
    sleep 1
    puts "Hi again from the main ractor!"
  end

  puts "Hi from the current ractor!"
end

sleep 3 # Wait for all scheduled tasks to complete.

# Expected output:
# Hi from the main ractor!
# Hi from the current ractor!
# Hi again from the main ractor!

Overloads:

.on_main(*args, mode: :smart) {|*args| ... } ⇒ nil
Parameters:
- args (Array) —
  The arguments to be passed to the block.
- mode (Symbol) (defaults to: :smart) —
  The argument transfer mode when called from another ractor.
Yields:
- (*args) —
  The block to be executed on the main ractor.
Yield Parameters:
- The (*args) —
  arguments passed to the block.
Returns:
- (nil)
.on_main ⇒ Abstract::Executor

Returns a scheduler that executes tasks on the main ractor.
Returns:
- (Abstract::Executor)

Returns:

(Abstract::Executor, nil)

See Also:

in_parallel

# File 'lib/farce.rb', line 415

def self.on_main(*args, mode: UNDEFINED, &)
  unless block_given?
    raise LocalJumpError, "no block given" unless args.empty? && UNDEFINED.equal?(mode)
    return Internal::MainScheduler
  end

  if Ractor.main?
    yield(*args)
  else
    mode = :smart if UNDEFINED.equal?(mode)
    Internal::MainScheduler.execute(*args, mode:, auto_local: false, &)
  end

  nil
end

.rebind(self: nil, lambda: nil) { ... } ⇒ `Proc` .rebind(bindable, self: nil, lambda: nil) ⇒ `Proc`, `Method`

Binds a proc, lambda, block, bound or unbound method to a new self.

This is similar to the following common approaches:

Ractor: using Ractor.shareable_proc/Ractor.shareable_lambda
BasicObject: using #instance_exec/#instance_eval (used by many DSLs, like Hanami or the dry-rb gems)
Module: using #define_method and method binding (used by many DSLs, like Sinatra or the money gem)

Approach 2 and 3 are very popular for DSLs, but the resulting objects cannot be shared across ractors. The first approach fixes that, but only works on a limited number of procs and receivers, and is not available on all Ruby implementations.

Property	`Ractor`	`BasicObject`	`Module`	`Farce`
Works with every proc	🚫 no	✅ yes	✅ yes	✅ yes
Results can be made shareable	✅ yes	🚫 no	🚫 no	✅ yes
Preserves parameters	✅ yes	🚫 no	✅ yes	✅ yes
Procs can accept blocks	✅ yes	🚫 no	✅ yes	✅ yes
Preserves lambda-ness	⚠️ manually	🚫 no	🚫 no	✅ yes
Works on JRuby and TruffleRuby	🚫 no	✅ yes	✅ yes	✅ yes
Performance overhead	✅ none	⚠️ up to 200%	⚠️ up to 80%	✅ none

If you want the proc to also be shareable, use Farce::Ractor.shareable_proc instead.

The performance overhead of BasicObject#instance_exec/BasicObject#instance_eval is the most significant on the official Ruby implementation, but is still present on JRuby, which does not exhibit a performance penalty for Module#define_method. On TruffleRuby, all approaches have similar performance. The more work is done inside the proc, the less significant the overhead becomes.

Examples:

# Rebinding a block to a new self
callback = Farce.rebind(self: 42) { self * 10 }
callback.call # => 420

# Rebound procs preserve parameters and can accept blocks
block   = ->(key, &fallback) { fetch(key, &fallback) }
rebound = Farce.rebind(block, self: { a: 1, b: 2 })
rebound.call(:a) { 0 } # => 1
rebound.call(:c) { 0 } # => 0
rebound.parameters == block.parameters # => true

# Rebinding an unbound method to a new self returns a bound method
method = Object.instance_method(:inspect) # => #<UnboundMethod>
method = Farce.rebind(method, self: 42)   # => #<Method>
method.receiver # => 42
method.call     # => "42"

# lambda-ness is preserved
Farce.rebind(proc {}).lambda?   # => false
Farce.rebind(lambda {}).lambda? # => true

# If there is no binding change, identity is preserved
Farce.rebind(&:to_s) == :to_s.to_proc # => true

Overloads:

.rebind(self: nil, lambda: nil) { ... } ⇒ Proc

Returns The bound proc.
Parameters:
- self (BasicObject) (defaults to: nil) —
  The new self to bind to.
Yields:
- The block to bind to the new self.
Returns:
- (Proc) —
  The bound proc.
Yield Receiver:
- (BasicObject) —
  The object passed as self (or nil)
.rebind(bindable, self: nil, lambda: nil) ⇒ Proc, Method

Returns The bound proc or method. A method is returned if the argument was a Method or UnboundMethod, otherwise a Proc is returned.
Parameters:
- bindable (Proc, Method, UnboundMethod) —
  The proc or method to bind to the new self.
- self (Object) (defaults to: nil) —
  The new self to bind to.
Returns:
- (Proc, Method) —
  The bound proc or method. A method is returned if the argument was a Method or UnboundMethod, otherwise a Proc is returned.

Returns:

(Proc, Method) —
The bound proc or method.

Raises:

(ArgumentError)

# File 'lib/farce.rb', line 326

def self.rebind(bindable = nil, lambda: nil, **self_option, &block)
  raise ArgumentError, "more than one block given" if bindable && block
  raise ArgumentError, "tried to create Proc object without a block" unless bindable ||= block
  new_self = Internal.self_option(self_option)

  if bindable.is_a? Proc
    return bindable if !Internal.rebindable?(bindable) || bindable.binding.receiver.equal?(new_self)
    rebound = Internal.rebind(bindable, new_self, lambda)
    rebound.freeze if bindable.frozen?
    return rebound
  end

  if bindable.is_a? Method
    return bindable if bindable.receiver.equal?(new_self)
    bindable = bindable.unbind
  end

  return bindable.bind(new_self) if bindable.is_a? UnboundMethod
  raise ArgumentError, "invalid bindable: #{bindable.inspect}"
end

.schedule(*args, mode: :smart, auto_local: true, **kwargs) {|*args| ... } ⇒ `nil`

Schedules work to be executed out of band.

If the mode is set to :local, it will use the current thread's fiber scheduler to schedule the task. If no fiber scheduler is available, it will create or reuse a Ractor-local scheduler (on the main Ractor, this is the same scheduler as on_main uses).

If auto_local is set to true (but with a different mode), the same logic is used as in local mode, except it will not create a new ractor-local scheduler if one is not already available.

Examples:

Scheduling work

# just run this asynchronously, don't care how
Farce.schedule("hello") { |message| puts message.upcase }

Using a fiber scheduler

Async do
  # this is basically the same as calling Async { do_something }
  Farce.schedule { do_something }
end

Parameters:

args (Array<Object>) —
Arguments passed to the block.
mode (Symbol) (defaults to: :smart) —
Argument transfer mode. Ignored on JRuby and TruffleRuby.
auto_local (Boolean) (defaults to: true) —
Whether to automatically use the local scheduler if available.
kwargs (Hash) —
Additional keyword arguments passed to the scheduler.

Yields:

(*args) —
The task to schedule.

Returns:

(nil)

Raises:

(LocalJumpError)

# File 'lib/farce.rb', line 494

def self.schedule(*, mode: :smart, auto_local: true, **, &)
  raise LocalJumpError, "no block given" unless block_given?

  if auto_local || mode == :local
    scheduler = Internal.local_scheduler(create: mode == :local)
    if scheduler && !scheduler.is_a?(Abstract::Executor)
      scheduler.fiber(**) { yield(*) }
      return
    end
  end

  scheduler ||= Internal::ParallelScheduler
  scheduler.schedule(*, mode:, auto_local:, **, &)
  nil
end

.transaction(objects, retries: nil, backoff_after: 10, max_backoff: 1.0) {|transaction, objects| ... } ⇒ `Boolean`

Creates and runs a new transaction attempt.

Automatically retries failed attempts indefinitely unless a retry limit is specified. Starts backing off after the specified number of attempts, up to the maximum delay.

Examples:

Modifying multiple entries in a map

accounts = Farce::Map.new({a: 100, b: 200})

# transfer 80 from :a to :b, but only if both succeed
success = Farce.transaction(accounts) do |tx, accounts|
  tx.abort! if accounts[:b] < 80
  accounts[:a] += 80
  accounts[:b] -= 80
end

if success
  puts "Transaction succeeded"
else
  puts "Transaction failed"
end

Programmatically registering objects for transactions

map     = Farce::Map.new({a: 1, b: 2})
summary = Farce::Atom.new("size not calculated")

# make sure map[:size], map.size, and the summary all match
Farce.transaction do |tx|
  tx_map            = tx[map]
  tx_map[:size]     = size = tx_map.size
  tx[summary].value = "size: #{size}"
end

Parameters:

objects (Array) —
list of objects to enroll in the transaction
retries (Integer, nil) (defaults to: nil) —
maximum additional attempts, or nil for unlimited retries
backoff_after (Integer) (defaults to: 10) —
number of attempts before starting to back off
max_backoff (Numeric) (defaults to: 1.0) —
maximum backoff delay in seconds

Yields:

(transaction, *objects) —
the current transaction and the enrolled objects

Yield Parameters:

transaction (Farce::Transaction) —
the current transaction
objects (Array) —
the enrolled objects

Returns:

(Boolean) —
whether the transaction committed successfully

108	# File 'lib/farce.rb', line 108 def self.transaction(...) = Transaction.run(...)

Module: Farce

Overview

Including Farce

Defined Under Namespace

Constant Summary collapse

Class Method Summary collapse

Class Method Details

.clock ⇒ Float .clock(value) ⇒ Float .clock(at:) ⇒ Float .clock(time:) ⇒ Float .clock(timeout_at:) ⇒ Float .clock(delay:) ⇒ Float .clock(offset:) ⇒ Float .clock(timeout:) ⇒ Float .clock(wait:) ⇒ Float

.config ⇒ Config

.configure {|config| ... } ⇒ BasicObject

Examples:

.dedup(object, copy: false, skip: nil) ⇒ Object .dedup ⇒ Deduper

Examples:

Preserve the input

Examples:

Exclude a class and its children

Cache another value class

.DryTypes(*namespaces, default: UNDEFINED, variant: :shared, mode: UNDEFINED, scope: UNDEFINED, **aliases) ⇒ Module

.enfarce(object, freeze: nil, mode: :smart) {|object| ... } ⇒ BasicObject

Examples:

.freeze_graph(object, freeze_modules: false, traverse_modules: freeze_modules) ⇒ Object

Examples:

Freeze nested values in place

Freeze children of an already frozen container

Freeze module state while allowing new methods

.in_parallel(*args, mode: :smart) {|*args| ... } ⇒ nil .in_parallel ⇒ Abstract::Executor

Examples:

.on_main(*args, mode: :smart) {|*args| ... } ⇒ nil .on_main ⇒ Abstract::Executor

Examples:

Blocking vs non-blocking

.rebind(self: nil, lambda: nil) { ... } ⇒ Proc .rebind(bindable, self: nil, lambda: nil) ⇒ Proc, Method

Examples:

.schedule(*args, mode: :smart, auto_local: true, **kwargs) {|*args| ... } ⇒ nil

Examples:

Scheduling work

Using a fiber scheduler

.transaction(*objects, retries: nil, backoff_after: 10, max_backoff: 1.0) {|transaction, *objects| ... } ⇒ Boolean

Examples:

Modifying multiple entries in a map

Programmatically registering objects for transactions

.clock ⇒ `Float` .clock(value) ⇒ `Float` .clock(at:) ⇒ `Float` .clock(time:) ⇒ `Float` .clock(timeout_at:) ⇒ `Float` .clock(delay:) ⇒ `Float` .clock(offset:) ⇒ `Float` .clock(timeout:) ⇒ `Float` .clock(wait:) ⇒ `Float`

.config ⇒ `Config`

.configure {|config| ... } ⇒ `BasicObject`

.dedup(object, copy: false, skip: nil) ⇒ `Object` .dedup ⇒ `Deduper`

.DryTypes(*namespaces, default: UNDEFINED, variant: :shared, mode: UNDEFINED, scope: UNDEFINED, **aliases) ⇒ `Module`

.enfarce(object, freeze: nil, mode: :smart) {|object| ... } ⇒ `BasicObject`

.freeze_graph(object, freeze_modules: false, traverse_modules: freeze_modules) ⇒ `Object`

.in_parallel(args, mode: :smart) {|args| ... } ⇒ `nil` .in_parallel ⇒ `Abstract::Executor`

.on_main(args, mode: :smart) {|args| ... } ⇒ `nil` .on_main ⇒ `Abstract::Executor`

.rebind(self: nil, lambda: nil) { ... } ⇒ `Proc` .rebind(bindable, self: nil, lambda: nil) ⇒ `Proc`, `Method`

.schedule(*args, mode: :smart, auto_local: true, **kwargs) {|*args| ... } ⇒ `nil`

.transaction(objects, retries: nil, backoff_after: 10, max_backoff: 1.0) {|transaction, objects| ... } ⇒ `Boolean`