farce 0 → 0.1.0

data/lib/farce/integrations/weakref.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+# @!group WeakRef Integration
+require "farce"   unless defined?(Farce::Walker)
+require "weakref" unless defined?(WeakRef)
+
+module Farce
+  # Traverse the live referent. Collected references have no children.
+  Walker.define(::WeakRef) do |object, walker|
+    value = begin
+      object.__getobj__
+    rescue ::WeakRef::RefError
+      next object
+    end
+
+    walker.update(object, [value]) do |target, results|
+      # WeakRef has no setter, so replacement values need a new reference.
+      target.class.new(results.first)
+    end
+  end
+
+  Internal::Converter.define(::WeakRef, WeakRef) do
+    def convert!(ref)
+      @seen.fetch(ref) do
+        begin
+          value = ref.__getobj__
+        rescue ::WeakRef::RefError
+          next @seen[ref] = Farce::WeakRef::RECYCLED
+        end
+        converted = convert(value)
+        # Return new values directly so they have a strong owner.
+        @seen[ref] = converted.equal?(value) ? Farce::WeakRef.new(converted) : converted
+      end
+    end
+  end
+end

data/lib/farce/integrations/yajl.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+# @!group Yajl Integration
+# Yajl 1.4.3 cannot encode or parse inside non-main native Ractors.
+require "farce"
+require "yajl" unless defined?(Yajl::Encoder)
+require "json" unless [].respond_to?(:to_json)
+require_relative "shared/to_json"

data/lib/farce/integrations.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  # @api private
+  module Integrations
+    # Dependency entry points, ending with the feature that activates each integration.
+    INTEGRATIONS = {
+      active_support: %w[active_support active_support/core_ext].freeze,
+      bson:           %w[bson].freeze,
+      cbor:           %w[cbor].freeze,
+      dry_types:      %w[dry/types].freeze,
+      concurrent:     %w[concurrent/map concurrent/tvar concurrent].freeze,
+      json:           %w[json].freeze,
+      msgpack:        %w[msgpack].freeze,
+      psych:          %w[psych].freeze,
+      oj:             %w[oj].freeze,
+      sorted_set:     %w[sorted_set].freeze,
+      weakref:        %w[weakref].freeze,
+      yajl:           %w[yajl].freeze,
+      ractor_tmvar:   %w[ractor/tvar ractor/tmvar].freeze,
+      ractor_sharing: %w[
+        ractor/tvar
+        ractor/lockvar
+        ractor/lockhash
+        ractor/keylockhash
+        ractor/active_object
+        ractor/actor_hash
+        ractor/sharing
+      ].freeze,
+    }.freeze
+
+    PATHS = INTEGRATIONS.to_h { [_2.last, _1] }.merge(
+      "concurrent/tvar" => :concurrent,
+      "ractor/tvar"     => :ractor_sharing,
+      "oj/json"         => :oj,
+      "yajl/json_gem"   => :yajl,
+    ).freeze
+
+    # Zeitwerk aliases Kernel#require. Prepending there can leave the aliased
+    # wrapper without a valid super target on TruffleRuby. Define the instance
+    # hook above Object so Kernel#require remains available for those aliases
+    # and Ruby's Ractor-aware Object#require stays in the lookup chain.
+    module RequireHook
+      private
+
+      # Load a feature and its integration while preserving require's result.
+      # @param path [String, #to_path] The feature to load.
+      # @return [Boolean] Whether the requested feature was newly loaded.
+      def require(path, ...)
+        path        = File.path(path)
+        result      = Integrations.loading(path) { super }
+        integration = PATHS[path.delete_suffix(".rb")]
+        if integration && !Integrations.loading?(integration) && Farce.config.autoload_integrations
+          integration_path = "farce/integrations/#{integration}"
+          Integrations.loading(integration_path) { super(integration_path) }
+        end
+        result
+      end
+    end
+    private_constant :RequireHook
+
+    # A prepended singleton hook can recurse when Zeitwerk aliases it. Preserve
+    # the original method explicitly instead of relying on super here.
+    class << Kernel
+      alias farce_original_require require
+      private :farce_original_require
+
+      # Load a feature and its integration through Kernel.require.
+      # @api private
+      # @param path [String, #to_path] The feature to load.
+      # @return [Boolean] Whether the requested feature was newly loaded.
+      def require(path, ...)
+        path        = File.path(path)
+        result      = Integrations.loading(path) { farce_original_require(path, ...) }
+        integration = PATHS[path.delete_suffix(".rb")]
+        if integration && !Integrations.loading?(integration) && Farce.config.autoload_integrations
+          integration_path = "farce/integrations/#{integration}"
+          Integrations.loading(integration_path) { farce_original_require(integration_path) }
+        end
+        result
+      end
+    end
+
+    private_constant :INTEGRATIONS, :PATHS
+
+    extend self
+
+    # Avoid requiring an integration again while it loads its own dependencies.
+    # @api private
+    def loading(path)
+      return yield unless path.start_with?("farce/integrations/")
+      previous = Thread.current[:farce_loading_integration]
+      Thread.current[:farce_loading_integration] = path.delete_prefix("farce/integrations/").delete_suffix(".rb").to_sym
+      begin
+        yield
+      ensure
+        Thread.current[:farce_loading_integration] = previous
+      end
+    end
+
+    # @api private
+    def loading?(integration) = Thread.current[:farce_loading_integration] == integration
+
+    # Activate integrations at startup when automatic loading is enabled.
+    # @api private
+    def setup
+      Object.prepend(RequireHook)
+      load_active if Farce.config.autoload_integrations
+    end
+
+    # Loads all integrations for gems that have already been loaded.
+    # @return [Array<Symbol>] the list of integrations that were loaded
+    # @!scope class
+    def load_active
+      result = []
+      INTEGRATIONS.each_key do |integration|
+        next unless loaded?("farce/integrations/#{integration}") ||
+          PATHS.any? { |path, target| target == integration && loaded?(path) }
+        require "farce/integrations/#{integration}"
+        result << integration
+      end
+      result
+    end
+
+    # Attempts to load all available integrations.
+    # If the integration could be loaded, it will be included in the result.
+    # @return [Array<Symbol>] the list of integrations that were loaded
+    # @!scope class
+    def load_available
+      result = []
+      INTEGRATIONS.each do |integration, require_paths|
+        next unless try_require("farce/integrations/#{integration}", *require_paths)
+        result << integration
+      end
+      result
+    end
+
+    private
+
+    def loaded?(path)
+      path  = "#{path}.rb" unless path.end_with?(".rb")
+      paths = $LOAD_PATH.map { File.expand_path(path, it) }
+      paths.any? { $LOADED_FEATURES.include?(it) }
+    end
+
+    def try_require(path, *ignore)
+      require path
+      true
+    rescue LoadError => e
+      raise e unless e.path == path || ignore.include?(e.path)
+      false
+    end
+  end
+end

data/lib/farce/internal/_frozen_config.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Internal # :nodoc: all
+    # Autoload runs on the main Ractor, where CONFIG can still be accessed before
+    # freezing. Keep this lazy so requiring Farce leaves configuration mutable.
+    FROZEN_CONFIG = CONFIG.freeze
+  end
+end

data/lib/farce/internal/autoloads.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  # @!visibility private
+  module Internal # :nodoc: all
+    # @!visibility private
+    module Autoloads
+      def self.[](*, **)
+        Module.new do
+          define_singleton_method(:append_features) do |namespace|
+            Autoloads.define(namespace, *, **)
+          end
+        end
+      end
+
+      SEGMENTS = { "io" => "IO", "lru" => "LRU", "lfu" => "LFU" }.freeze
+      private_constant :SEGMENTS
+
+      def self.inflect(name, **inflections)
+        name.split(%r{::|/}).map do |part|
+          next if part.empty?
+          inflections.fetch(part.to_sym) { part.split("_").map { SEGMENTS.fetch(it, it.sub(/^./, &:upcase)) }.join }
+        end.compact.join("::")
+      end
+
+      def self.define(namespace, path = nil, skip: nil, **)
+        path ||= namespace.name.gsub(/([a-z])([A-Z])/, "\\1_\\2").gsub("::", "/").downcase
+        path = File.expand_path(path, "#{__dir__}/../..")
+        skip = ::Set[*skip]
+
+        skip.map!(&:to_s)
+
+        Dir.glob("#{path}/*.rb").each do |file|
+          base_name = File.basename(file, ".rb")
+          next if base_name.start_with?("_") || base_name.start_with?(".") || skip.include?(base_name)
+          const_name = inflect(base_name, **)
+          next if namespace.const_defined?(const_name, false) || $LOADED_FEATURES.include?(file)
+          namespace.autoload(const_name, file)
+        end
+      end
+
+      def self.append_features(namespace) = define(namespace)
+    end
+  end
+end

data/lib/farce/internal/blocking_priority_queue.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  # @!visibility private
+  module Internal # :nodoc: all
+    # Shared blocking wrapper behavior for the public priority-based queues.
+    module BlockingPriorityQueue
+      # Remove all values and wake waiters.
+      def clear
+        internal_queue.clear
+        self
+      end
+
+      # Close the queue and wake waiters.
+      def close
+        internal_queue.close
+        self
+      end
+
+      # Stop new pushes and close after the final value is removed.
+      def seal
+        internal_queue.seal
+        self
+      end
+
+      # Wait until capacity is available without adding a value.
+      def wait_push(timeout: nil)
+        raise_unwritable if sealed?
+        return true unless capacity
+
+        wait(timeout) do
+          raise_unwritable if sealed?
+          size < capacity
+        end
+      end
+
+      # The approximate number of waiting execution contexts.
+      def num_waiting = internal_signal.num_waiting
+
+      Internal.delegate(
+        self, :internal_queue, :age_tracking?, :capacity, :closed?, :empty?, :generation,
+        :oldest_age, :oldest_enqueued_at, :sealed?, :size,
+      )
+
+      private
+
+      def initialize_copy(_other)
+        raise TypeError, "priority queues cannot be copied"
+      end
+
+      def initialize(capacity:, reverse_order: false, track_age: false)
+        @reverse_order = reverse_order
+        @signal        = queue_signal
+        @queue         = queue_storage_class.new(capacity:, signal: internal_signal, track_age:)
+        super()
+      end
+
+      def internal_signal = @signal
+
+      def queue_storage_class = Internal::PriorityQueue
+      def queue_signal = Signal.new
+
+      def delete_from_storage(priority, value, compare_by_identity:)
+        if compare_by_identity
+          internal_queue.delete_identity(priority, value)
+        else
+          internal_queue.delete(priority, value)
+        end
+      end
+
+      def push_to_storage(priority, non_block, value, timeout:)
+        deadline = timeout_at(timeout) unless timeout.nil?
+
+        while true
+          return true if internal_queue.push(priority, value)
+          raise ThreadError, "queue full" if non_block
+          return false unless wait_push(timeout: remaining_timeout(deadline))
+        end
+      end
+
+      def normalize_timeout(timeout)
+        return nil if timeout.nil?
+
+        timeout = Float(timeout)
+        raise ArgumentError, "timeout must be non-negative" if timeout.negative?
+        raise ArgumentError, "timeout must be finite" unless timeout.finite?
+        raise ArgumentError, "timeout must be a number" if timeout.nan?
+
+        timeout
+      end
+
+      def wait(timeout)
+        deadline = timeout_at(timeout)
+
+        while true
+          generation = internal_signal.generation
+          raise ::Farce::ClosedQueueError, "queue is closed" if closed?
+          return true if yield
+          return false unless internal_signal.wait(generation, timeout: remaining_timeout(deadline))
+        end
+      end
+
+      def raise_unwritable
+        closed = closed?
+        error = closed ? ::Farce::ClosedQueueError : ::Farce::SealedQueueError
+        raise error, closed ? "queue is closed" : "queue is sealed"
+      end
+
+      def timeout_at(timeout)
+        Clock.timeout(normalize_timeout(timeout)) unless timeout.nil?
+      end
+
+      def remaining_timeout(timeout_at)
+        return unless timeout_at
+        timeout = timeout_at - Clock.now
+        timeout.positive? ? timeout : 0
+      end
+    end
+  end
+end

data/lib/farce/internal/converter.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  # @!visibility private
+  module Internal # :nodoc: all
+    class Converter
+      class Factory
+        class << self
+          attr_writer :target_name
+        end
+
+        def self.target_name
+          return @target_name if defined?(@target_name) && @target_name
+          superclass.target_name if superclass.respond_to?(:target_name)
+        end
+
+        attr_reader :target_class, :namespace, :options, :converter
+
+        def initialize(converter)
+          @converter = converter
+          @namespace = converter.namespace
+          @options   = converter.options
+          @seen      = {}.compare_by_identity
+
+          case target_name = self.class.target_name
+          when Symbol, String then @target_class = @namespace.const_get(target_name)
+          when Class          then @target_class = target_name
+          else raise TypeError, "Unsupported target name: #{target_name.inspect}"
+          end
+        end
+
+        def convert(value) = @converter.convert(value)
+
+        def convert!(value)
+          @seen.fetch(value) do
+            instance = @seen[value] = prepare(value)
+            apply(instance, value)
+            yield instance
+            instance
+          end
+        end
+
+        def prepare(_, **) = @target_class.new(**, **@options)
+      end
+
+      REGISTER = ClassMirror.new(Factory)
+      private_constant :REGISTER
+
+      def self.define(klass, target_name, &block)
+        if block && block.arity != 0
+          definition = Internal.prepare_method_definition(&block)
+          block      = proc { define_method(:apply, &definition) }
+        end
+        factory_class             = REGISTER.define(klass, &block)
+        factory_class.target_name = target_name
+        factory_class
+      end
+
+      define(Hash, :Map) do
+        def apply(instance, value) = value.each { instance[_1] = convert(_2) }
+
+        def prepare(value, **)
+          return super unless value.compare_by_identity?
+          super(value, compare_keys_by_identity: true, **)
+        end
+      end
+
+      define(Array, :Vector) { |instance, value| value.each { instance << convert(it) } }
+
+      define(::Set, :Set) do
+        def apply(instance, value) = value.each { instance << convert(it) }
+
+        def prepare(value, **)
+          return super unless value.compare_by_identity?
+          super(value, compare_by_identity: true, **)
+        end
+      end
+
+      define(ObjectSpace::WeakMap, :WeakMap) do
+        def apply(instance, value) = value.each { instance[_1] = convert(_2) }
+        def prepare(value, **) = super(value, compare_keys_by_identity: true, **)
+      end
+
+      attr_reader :options, :namespace
+
+      def initialize(namespace, freeze: nil, **options, &callback)
+        @namespace = namespace
+        @options   = options
+        @freeze    = freeze
+        @factories = {}
+        @callback  = callback
+      end
+
+      def convert(value)
+        factory_class = REGISTER[value.class]
+        return @callback ? @callback.call(value) : value unless factory_class.target_name
+        factory = @factories[factory_class] ||= factory_class.new(self)
+        factory.convert!(value) do |result|
+          result.freeze if @freeze.nil? ? value.frozen? : @freeze
+        end
+      end
+    end
+  end
+end

data/lib/farce/internal/copyable.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Internal
+    # Preserve the publication guarantees of public shareable wrappers.
+    module Copyable
+      private
+
+      def initialize_dup(other)
+        super
+        publish_copy(other, operation: :dup) if is_a?(Shareable)
+      end
+
+      def initialize_clone(other, freeze: nil)
+        super
+        publish_copy(other, operation: :clone, freeze:) if is_a?(Shareable)
+      end
+
+      def publish_copy(other, operation:, freeze: nil)
+        if respond_to?(:publish_shareable_copy, true)
+          publish_shareable_copy(other, operation:, freeze:)
+        elsif operation == :dup || freeze != false
+          Ractor.make_shareable(self) if Internal.native_ractors?
+          self.freeze
+        end
+      end
+    end
+  end
+end

data/lib/farce/internal/delegation.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Internal
+    # Mixin to have some BasicObject methods still trigger method_missing
+    # Notable exceptions: #equal?, #__send__, #__id__
+    module Delegation
+      def ==(other)          = method_missing(:==, other)
+      def !                  = method_missing(:!)
+      def instance_eval(...) = method_missing(:instance_eval, ...)
+      def instance_exec(...) = method_missing(:instance_exec, ...)
+
+      def !=(other)
+        method_missing(:!=, other)
+      end
+    end
+  end
+end

data/lib/farce/internal/external_transaction.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Internal # :nodoc: all
+    # Own portable locks while native participants hold logical reservations.
+    # Portable replacements remain hidden until the foreign commit is resolved.
+    class ExternalTransaction
+      def self.commit(entries, external, guards, transaction)
+        groups = external.map(&:commit_group).uniq
+        raise TypeError, "only one external commit integration may participate" unless groups.size == 1
+
+        native, portable = entries.partition { NativeTransactionEntry === it }
+        context = new(portable, guards, groups.first.new(external), transaction)
+        flags = guards.map { it.respond_to?(:native_flag) ? it.native_flag : it }
+        Internal.reserve_transaction(native, flags, context)
+      end
+
+      def initialize(entries, guards, group, transaction)
+        @entries, @guards, @group, @transaction = entries, guards, group, transaction
+        @acquired = []
+        @attempted = nil
+        @entries.each(&:prepare)
+        @locks = (@entries.flat_map(&:locks) + @guards.filter_map { it.lock if it.respond_to?(:native_flag) })
+          .uniq.sort_by(&:object_id)
+      end
+
+      def acquire?
+        @locks.each do |lock|
+          return false if lock.owned?
+          @attempted = lock
+          return false unless lock.try_lock
+          @acquired << lock
+          @attempted = nil
+        end
+        @guards.none?(&:value) && @entries.all?(&:valid?)
+      end
+
+      def publish_external
+        @entries.each { it.reserve if it.respond_to?(:reserve) }
+        @entries.each(&:apply)
+        @group.commit
+      end
+
+      def committed? = @group.committed?
+      def restore = @entries.reverse_each(&:restore)
+
+      # Repeatable even if a return TracePoint interrupted a completed unlock.
+      def finish
+        @entries.each { it.unreserve if it.respond_to?(:unreserve) }
+        [*@acquired, @attempted].compact.uniq.reverse_each do |lock|
+          lock.unlock if lock.owned?
+        end
+        @entries.each(&:notify) if committed?
+      end
+    end
+  end
+end