farce 0 → 0.1.0

data/lib/farce/internal.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+require "farce/internal/autoloads"
+require "timeout"
+
+experimental = Warning[:experimental]
+
+# simplecov:disable
+begin
+  Warning[:experimental] = false
+  IO::Buffer.new(0) if defined?(IO::Buffer)
+  Ractor.new {} if defined?(Ractor) # rubocop:disable Lint/EmptyBlock
+ensure
+  Warning[:experimental] = experimental
+end
+# simplecov:enable
+
+module Farce
+  # @!visibility private
+  module Internal # :nodoc: all
+    EMPTY_ARRAY    = [].freeze
+    INTERRUPT_MASK = { Exception => :never }.freeze
+    MAP_KEEP       = Object.new.freeze
+    MAP_DELETE     = Object.new.freeze
+
+    # A non-main Ractor cannot call CONFIG.frozen if the main Ractor didn't do so before,
+    # as CONFIG is not shareable yet. We don't want to eagerly freeze it, otherwise a user can't change
+    # any configuration options after loading Farce.
+    #
+    # We can't do so via `Farce.on_main`, as creating the MainScheduler already needs the configuration.
+    # So we rely on the fact that autoloads run on the main Ractor.
+    autoload :FROZEN_CONFIG, "farce/internal/_frozen_config"
+
+    include Autoloads
+    extend self
+
+    # @api private
+    def marshal_protocol_method?(name) = MarshalSupport.protocol_method?(name)
+
+    # @api private
+    def marshal_shareable?(value) = Ractor.shareable?(value)
+
+    # Get the value from an options hash with only the `:self` key, and raise an error if there are any other keys.
+    def self_option(options, default = nil)
+      new_self = options.key?(:self) ? options.delete(:self) : (block_given? ? yield : default)
+
+      if options.any?
+        raise ArgumentError, "unknown keyword: #{options.keys.first.inspect}" if options.size == 1
+        raise ArgumentError, "unknown keywords: #{options.keys.map(&:inspect).join(", ")}"
+      end
+
+      new_self
+    end
+
+    def timeout_deadline(timeout)
+      return if timeout.nil?
+
+      timeout = Float(timeout)
+      unless timeout.finite? && !timeout.negative?
+        raise ArgumentError, "timeout must be a finite, non-negative number or nil"
+      end
+      Clock.now + timeout
+    end
+
+    def remaining_timeout(deadline)
+      return unless deadline
+      remaining = deadline - Clock.now
+      remaining.negative? ? 0 : remaining
+    end
+
+    # Repeat with one timeout budget. Even a zero timeout permits the first check.
+    def with_timeout(timeout)
+      raise LocalJumpError, "no block given" unless block_given?
+      deadline = timeout_deadline(timeout)
+      loop do
+        yield remaining_timeout(deadline), deadline
+        return if deadline && Clock.now >= deadline
+      end
+    end
+
+    def wait_until(receiver, *keys, timeout: nil)
+      raise LocalJumpError, "no block given" unless block_given?
+      with_timeout(timeout) do |_, deadline|
+        current = keys.empty? ? receiver.value : receiver[*keys]
+        return current if yield(current)
+        receiver.wait_until_changed(*keys, current, timeout: remaining_timeout(deadline)) { return }
+      end
+    end
+
+    def garbage_collectable?(object)
+      case object
+      when Integer, Float, Complex, Rational, Symbol, true, false, nil then false
+      else true
+      end
+    end
+
+    def walker_constants(object, inherit) = object.constants(inherit)
+    def storage_thread(thread)            = thread
+    def prepare_mutable_numeric(_)        = nil
+    def prepare_map_access(_klass, _kind) = nil
+    def finalize_engine                   = nil
+
+    def delegate(from, to, *methods)
+      methods.each do |method|
+        if to.is_a?(Module)
+          name  = to.name
+          const = Object.const_get(name, false) if name && Object.const_defined?(name, false)
+          to    = "::#{name}" if const.equal?(to)
+        end
+
+        if to.is_a?(String) || to.is_a?(Symbol)
+          from.class_eval <<-RUBY, __FILE__, __LINE__ + 1
+            # simplecov:disable
+            def #{method}(...)
+              #{to}.#{method}(...)
+            end
+            # simplecov:enable
+          RUBY
+        else
+          from.define_method(method) do |*args, **kwargs, &block|
+            to.send(method, *args, **kwargs, &block)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/farce/lazy.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  # A ractor-shareable lazy value that is computed on demand.
+  # The factory runs once. Its result is transferred according to {#mode}.
+  # With the default `:copy` mode, each Ractor receives its own cached copy.
+  # The factory and its bound receiver must remain Ractor-shareable.
+  # Use {Strict::Lazy} for direct shareable results or {Unshared::Lazy} for local factories.
+  #
+  # You can use it to make the following, common Ruby idiom ractor-safe:
+  #
+  # ```ruby
+  # class MyClass
+  #   def expensive_attribute = @expensive_attribute ||= compute_expensive_attribute
+  #
+  #   private
+  #
+  #   def compute_expensive_attribute
+  #     sleep 0.5 # pretend like we're working
+  #     42
+  #   end
+  # end
+  #
+  # # this will freeze the object without the expensive attribute being computed
+  # object = Ractor.make_shareable(MyClass.new)
+  #
+  # # this will fail
+  # Ractor.new(object) { it.expensive_attribute }
+  #
+  #
+  # object = MyClass.new
+  #
+  # # this will work, but compute the expensive attribute five times, and also deep-copy any other
+  # # unshareable data the object might hold
+  # 5.times { Ractor.new(object) { it.expensive_attribute } }
+  # ```
+  #
+  # You can use `Farce::Lazy` to make expensive attributes ractor-safe:
+  #
+  # ```ruby
+  # class MyClass
+  #   include Farce::Shareable
+  #
+  #   def initialize
+  #     @expensive_attribute = Farce::Lazy.new do
+  #       sleep 0.5 # pretend like we're working
+  #       42
+  #     end
+  #     super
+  #   end
+  #
+  #   def expensive_attribute = @expensive_attribute.value
+  # end
+  #
+  # object = MyClass.new
+  #
+  # # Will only compute the expensive attribute once, and return the same value to all Ractors.
+  # 5.times { Ractor.new(object) { it.expensive_attribute } }
+  # ```
+  class Lazy < Farce::Abstract::Lazy
+    include Shareable::Tracked
+
+    # @!macro modes
+    # @overload initialize(factory, mode: :copy)
+    #   @param factory [Class, Proc, #call] the shareable factory for the value
+    #   @param mode [Symbol] the transfer mode for the computed result
+    # @overload initialize(mode: :copy, self: nil)
+    #   @param mode [Symbol] the transfer mode for the computed result
+    #   @param self [BasicObject] the shareable receiver to bind to the block
+    #   @yield computes the value on first access
+    #   @yieldreturn [BasicObject] the result to transfer
+    def initialize(factory = nil, mode: :copy, **, &)
+      @manager = marshal_mode_manager(mode)
+      super(factory, **, &)
+    end
+
+    # @return [Symbol] the transfer mode for the computed result
+    def mode = @manager.mode
+
+    # Compute once and return the result according to the configured transfer mode.
+    # Repeated reads return the same value within the current Ractor.
+    # @return [BasicObject] the computed result
+    def value = @manager.unwrap(super)
+
+    # Resolve the slot before freezing it. This does not freeze the result.
+    # @return [self]
+    def freeze
+      value
+      internal_atom.freeze
+      super
+    end
+
+    private
+
+    def compute_value            = @manager.wrap(super)
+    def display_value(inspector) = super(inspector, @manager)
+  end
+end

data/lib/farce/lazy_ref.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  # @!parse
+  #   # A {Reference} for a {Lazy} value.
+  #   #
+  #   # Results use the lazy value's transfer mode, which defaults to `:copy`.
+  #   #
+  #   # Calling `freeze` resolves and freezes the target. Checking `frozen?` before
+  #   # the first successful freeze does not resolve it.
+  #   #
+  #   # @example
+  #   #   initialized = Farce::Counter.new
+  #   #
+  #   #   lazy_ref = Farce::LazyRef.new do
+  #   #     initialized.increment
+  #   #     Farce::Map.new
+  #   #   end
+  #   #
+  #   #   initialized.value # => 0
+  #   #   lazy_ref[:key] = :value
+  #   #   initialized.value # => 1
+  #   class LazyRef < Farce::Reference
+  #     # @!macro modes
+  #     # @overload initialize(factory, mode: :copy)
+  #     #   @param mode [Symbol] the transfer mode for the computed result
+  #     #   @param [Class, Proc, #call] factory The factory to use for creating the value. Must be ractor-shareable.
+  #     #
+  #     # @overload initialize(self: nil, mode: :copy)
+  #     #   @param mode [Symbol] the transfer mode for the computed result
+  #     #   @yield The block to use for creating the value. Must be ractor-shareable.
+  #     #   @yieldreceiver [BasicObject] The `self` parameter provided, or `nil` if not provided.
+  #     #   @yieldreturn [BasicObject] The value to be returned by the lazy instance.
+  #     #   @param [BasicObject] self The `self` parameter to be provided to the block. Must be ractor-shareable.
+  #     def initialize(...) = nil
+  #   end
+  LazyRef = Reference[Lazy]
+end

data/lib/farce/lease.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  # A Ractor-shareable lease that moves one resource on checkout and checkin.
+  #
+  # @example Reusing an object across Ractors
+  #   lease = Farce::Lease.new { [] }
+  #   finished = Farce::Port.new
+  #   Farce::Ractor.new(lease, finished) do |shared, result|
+  #     size = shared.checkout do |items|
+  #       items << :processed
+  #       items.length
+  #     end
+  #     result << size
+  #   end
+  #
+  #   finished.receive # => 1
+  #   lease.checkout { |items| items.dup } # => [:processed]
+  class Lease < Farce::Abstract::Lease
+    include Shareable::Unfreezable
+
+    private
+
+    def new_internal_lease(resource) = Internal::Lease.new(resource)
+  end
+end

data/lib/farce/lease_map.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  # A Ractor-shareable map that moves each resource on checkout and checkin.
+  #
+  # @example Updating independently leased resources
+  #   leases = Farce::LeaseMap.new { { primary: [], replica: [] } }
+  #   leases.checkout(:primary) { |items| items << :updated }
+  #   leases.checkout(:primary, &:dup) # => [:updated]
+  #
+  # @example Automatically checking out resources as they are accessed
+  #   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]
+  class LeaseMap < Farce::Abstract::LeaseMap
+    include Shareable::Unfreezable
+
+    private
+
+    def new_internal_lease_map(mapping)
+      Internal::LeaseMap.new(mapping, lease_class: Farce::Lease, registry_class: Farce::Map)
+    end
+  end
+end

data/lib/farce/lease_pool.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  # A Ractor-shareable pool that moves resources on checkout and checkin.
+  #
+  # @example Reusing an object across Ractors
+  #   pool = Farce::LeasePool.new(max_size: 2) { [] }
+  #   result = Farce::Ractor.new(pool) do |shared|
+  #     shared.checkout do |items|
+  #       items << :worker
+  #       items.length
+  #     end
+  #   end.value
+  #
+  #   result # => 1
+  class LeasePool < Farce::Abstract::LeasePool
+    include Shareable::Unfreezable
+
+    private
+
+    def prepare_factory(factory)
+      Ractor.shareable?(factory) ? factory : Ractor.shareable_proc(&factory)
+    end
+
+    def new_internal_pool(max_size) = Internal::LeasePool.new(max_size)
+  end
+end

data/lib/farce/lfu_map.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  # A Ractor-shareable bounded map that evicts the least frequently used entry.
+  # Equal-frequency victims are selected by recency. Transfer modes apply to values.
+  # Individual reads and writes increment frequency. Observation does not.
+  class LFUMap < Farce::Abstract::LFUMap
+    include Shareable::Delegated
+
+    # @!macro modes
+    # @param entries [Hash, Array<Array(BasicObject, BasicObject)>, Abstract::Map, #each, nil]
+    #   Optional initial entries. Entries are stored sequentially and may be evicted.
+    # @param mode [Symbol] The default value transfer mode.
+    def initialize(entries = nil, mode: :copy, **)
+      @manager = marshal_mode_manager(mode)
+      super(entries, **)
+    end
+
+    # The default transfer mode for values.
+    # @return [Symbol]
+    def mode = @manager.mode
+
+    # Keys must be shareable, except equality-mode strings that can be snapshotted.
+    # @return [true]
+    def shareable_keys? = true
+
+    # Values are stored in Ractor-shareable representations.
+    # @return [true]
+    def shareable_values? = true
+
+    protected
+
+    def unwrap_value(value) = @manager.unwrap(value)
+
+    def wrap_value(value)
+      check_frozen!
+      @manager.wrap(value)
+    end
+
+    private
+
+    def each_for_inspect(&)             = internal_map.each(&)
+    def inspect_value(inspector, value) = super(inspector, value, @manager)
+    def new_bounded_map(...)            = Internal::StrictLFUMap.new(...)
+    def freeze_backend                  = internal_map
+
+    def new_key_locks(compare_keys_by_identity:)
+      Internal::KeyLockMap.new(registry_class: Farce::Strict::Map, compare_keys_by_identity:)
+    end
+  end
+end

data/lib/farce/local/atom.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Local
+    # A shareable atomic reference with an independent mutable value in each scope.
+    #
+    # @!method initialize(value = nil, compare_by_identity: false, scope: :ractor)
+    #   @!macro scopes
+    #   @param value [BasicObject, nil] the initial value
+    #   @param compare_by_identity [Boolean] whether comparisons use object identity instead of equality
+    #   @param scope [Symbol] the scope of the atomic reference
+    #   @return [Atom]
+    class Atom < Abstract::Atom
+      include Shareable::Tracked
+      include Scoped::Tracked
+
+      protected def internal_atom = scoped_value
+      private def new_scoped_value(...) = Internal::UnsharedAtom.new(...)
+    end
+  end
+end

data/lib/farce/local/counter.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Local
+    # A shareable atomic counter with an independent value in each scope.
+    # Each scope starts at the initial integer. Reset affects only the current scope.
+    class Counter < Numeric
+      include Abstract::Counter
+      include Shareable::Tracked
+      include Scoped::Tracked
+
+      # The initial value used for new scopes and by {#reset}.
+      # @return [Integer]
+      attr_reader :initial
+
+      # @!macro scopes
+      # @param value [Numeric, String, #to_int] the initial value, converted to an Integer
+      # @param scope [Symbol] the scope of the counter
+      def initialize(value = 0, scope: :ractor)
+        raise FrozenError.new("can't initialize a frozen counter", receiver: self) if frozen?
+        @initial = Integer(value)
+        super(@initial, scope:)
+      end
+
+      # Return the current integer value.
+      # @return [Integer]
+      def value = internal_counter.value
+
+      alias get value
+
+      # Store an integer value.
+      # @param value [Integer] the replacement value
+      # @return [Integer] the stored value
+      def store(value) = internal_counter.store(value)
+
+      alias value= store
+
+      # Replace the value and return the previous integer.
+      # @param value [Integer] the replacement value
+      # @return [Integer]
+      def swap(value) = internal_counter.swap(value)
+
+      # Replace the value atomically if it matches the expected integer.
+      # @param expected [Integer] the expected value
+      # @param replacement [Integer] the replacement value
+      # @return [Boolean] whether the value changed
+      def compare_and_set(expected, replacement) = internal_counter.compare_and_set(expected, replacement)
+
+      # Increment the counter atomically.
+      # @param by [Numeric, String, #to_int] the amount, converted to an Integer
+      # @return [self]
+      def increment(by = 1)
+        internal_counter.increment(by)
+        self
+      end
+
+      # Decrement the counter atomically.
+      # @param by [Numeric, String, #to_int] the amount, converted to an Integer
+      # @return [self]
+      def decrement(by = 1)
+        internal_counter.decrement(by)
+        self
+      end
+
+      alias subtract decrement
+      alias remove   decrement
+
+      private
+
+      def marshal_initialize(arguments, options, configuration)
+        @initial = Integer(arguments.first)
+        super
+      end
+
+      def initialize_copy(other)
+        # Numeric#initialize_copy cannot copy mutable Numeric subclasses on JRuby.
+        @farce_freeze_state = Internal::Flag.new(false)
+        Internal::Storage.scope(scope)[self] = Internal::Counter.new(other.value)
+      end
+
+      def change_signal         = internal_counter.change_signal
+      def internal_counter      = scoped_value
+      def new_scoped_value(...) = Internal::Counter.new(...)
+    end
+  end
+end

data/lib/farce/local/flag.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Local
+    # A shareable atomic boolean with an independent value in each scope.
+    # Only true and false are accepted. Read {#value} to test its state.
+    class Flag
+      include Abstract::Flag
+      include Shareable::Tracked
+      include Scoped::Tracked
+
+      # @!method initialize(value = false, scope: :ractor)
+      #   @!macro scopes
+      #   @param value [Boolean] the initial value
+      #   @param scope [Symbol] the scope of the flag
+      #   @raise [ArgumentError] if the value is not true or false
+
+      # @return [Boolean] the current value
+      def value = scoped_value.value
+
+      alias get value
+
+      # Set the flag to true.
+      # @return [true]
+      def set = scoped_value.set
+
+      # Set the flag to false.
+      # @return [false]
+      def unset = scoped_value.unset
+
+      # Store a boolean value.
+      # @param value [Boolean] the new value
+      # @return [Boolean] the new value
+      def store(value) = scoped_value.store(value)
+
+      alias value= store
+
+      # Replace the value and return its previous state.
+      # @param value [Boolean] the new value
+      # @return [Boolean] the previous value
+      def swap(value) = scoped_value.swap(value)
+
+      # Replace the value atomically if it matches the expected boolean.
+      # @param expected [Boolean] the expected value
+      # @param replacement [Boolean] the replacement value
+      # @return [Boolean] whether the value changed
+      def compare_and_set(expected, replacement) = scoped_value.compare_and_set(expected, replacement)
+
+      # Atomically invert the value.
+      # @return [Boolean] the new value
+      def toggle = scoped_value.toggle
+
+      private
+
+      def initialize_copy(other)
+        super
+        Internal::Storage.scope(scope)[self] = Internal::Flag.new(other.value)
+      end
+
+      def new_scoped_value(...) = Internal::Flag.new(...)
+    end
+  end
+end

data/lib/farce/local/lazy.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Local
+    # A shareable lazy value computed once per scope. Results may be mutable.
+    class Lazy < Abstract::Lazy
+      include Shareable::Unfreezable
+      include Scoped
+
+      # @!macro scopes
+      # @overload initialize(factory, scope: :ractor)
+      #   @param factory [Class, Proc, #call] a shareable factory for each scope's value
+      #   @param scope [Symbol] the scope of the lazy value
+      # @overload initialize(scope: :ractor, self: nil)
+      #   @param scope [Symbol] the scope of the lazy value
+      #   @param self [BasicObject] the shareable receiver to bind to the block
+      #   @yield computes the value on first access in each scope
+      #   @yieldreceiver [BasicObject] the self parameter, or nil if omitted
+      #   @yieldreturn [BasicObject] the initial value for the scope, which may be mutable
+      # @return [Lazy]
+      def initialize(factory = nil, scope: :ractor, **, &)
+        @factory   = prepare_factory(factory, **, &)
+        @state_key = Object.new.freeze
+        super(scope:)
+      end
+
+      private
+
+      def marshal_current_value = Internal::Storage.scope(scope)[@state_key]&.value
+
+      def eager_scoped_value? = false
+      def internal_atom       = Internal::Storage.store_if_absent(@state_key, scope:) { new_scoped_value }
+      def new_scoped_value    = Internal::UnsharedAtom.new
+    end
+  end
+end

data/lib/farce/local/lazy_ref.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Local
+    # @!parse
+    #   # A {Reference} for a {Lazy Local::Lazy} value.
+    #   # Freezing affects the current scope's target. Afterward, `frozen?` reflects
+    #   # the current target and may initialize it when entering another scope.
+    #   #
+    #   # @example
+    #   #   # Delegate to a Ractor-local hash
+    #   #   lazy_ref = Farce::Local::LazyRef.new { {} }
+    #   #
+    #   #   lazy_ref[:key] = :value
+    #   #   lazy_ref[:key] # => :value
+    #   #
+    #   #   Ractor.new(lazy_ref) do |lazy_ref|
+    #   #     lazy_ref[:key] # => nil
+    #   #   end
+    #   class LazyRef < Farce::Reference
+    #     # @overload initialize(factory, scope: :ractor)
+    #     #   @param [Class, Proc, #call] factory The factory to use for creating the value. Must be ractor-shareable.
+    #     #   @param scope [Symbol] the scope of the lazy value
+    #     #
+    #     # @overload initialize(self: nil, scope: :ractor)
+    #     #   @yield The block to use for creating the value. Must be ractor-shareable.
+    #     #   @yieldreceiver [BasicObject] The `self` parameter provided, or `nil` if not provided.
+    #     #   @yieldreturn [BasicObject] The value to be returned by the lazy instance.
+    #     #   @param [BasicObject] self The `self` parameter to be provided to the block. Must be ractor-shareable.
+    #     #   @param scope [Symbol] the scope of the lazy value
+    #   end
+    LazyRef = Reference[Farce::Local::Lazy]
+  end
+end