farce 0 → 0.1.0

data/lib/farce/engine/ruby/shared/weak_map.rb

@@ -0,0 +1,413 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+require "farce/engine/ruby/shared/vault_weak_map"
+
+module Farce
+  # @!visibility private
+  module Internal # :nodoc: all
+    class VaultWeakMapBase < Abstract::ConcurrentMap
+      OWNER = Atom.new
+      CLAIM_OWNERS = Object.new.freeze
+      TIMED_OUT = Object.new.freeze
+      private_constant :OWNER, :CLAIM_OWNERS, :TIMED_OUT
+
+      def initialize(
+        initial_mapping = nil,
+        compare_by_identity: false,
+        compare_keys_by_identity: compare_by_identity,
+        compare_values_by_identity: compare_by_identity
+      )
+        validate_boolean(compare_by_identity,        "compare_by_identity")
+        validate_boolean(compare_keys_by_identity,   "compare_keys_by_identity")
+        validate_boolean(compare_values_by_identity, "compare_values_by_identity")
+        raise TypeError, "initial mapping must be a Hash" unless initial_mapping.nil? || initial_mapping.is_a?(Hash)
+
+        super()
+
+        @compare_keys_by_identity   = compare_keys_by_identity
+        @compare_values_by_identity = compare_values_by_identity
+        @token                      = Object.new.freeze
+        @vault                      = OWNER.store_if_absent { Vault.new }
+        @freeze_state               = Flag.new(false)
+        request(:create, {
+          weak_keys:                weak_keys?,
+          weak_values:              weak_values?,
+          compare_keys_by_identity: compare_keys_by_identity?,
+        }.freeze)
+        initial_mapping&.each { self[it.first] = it.last }
+        Object.instance_method(:freeze).bind_call(self)
+      end
+
+      def freeze
+        @freeze_state.set
+        self
+      end
+
+      def frozen? = @freeze_state.value
+
+      def check_mutation = check_frozen!
+
+      def prepare_mutation_key(key)
+        check_frozen!
+        canonical_key(key)
+      end
+
+      def [](key) = read(key, nil)[1]
+
+      def []=(key, value)
+        store(key, value)
+      end
+
+      def fetch(*arguments)
+        unless arguments.length.between?(1, 2)
+          raise ArgumentError, "wrong number of arguments (given #{arguments.length}, expected 1..2)"
+        end
+
+        key, default  = arguments
+        default_given = arguments.length == 2
+        warn "block supersedes default value argument", uplevel: 1 if block_given? && default_given
+        present, value = read(key, nil)
+        return value if present
+        return yield(key) if block_given?
+        return default if default_given
+
+        raise KeyError.new("key not found: #{key.inspect}", receiver: self, key: key)
+      end
+
+      def get(key, timeout: nil, &fallback)
+        result = read(key, timeout_deadline(timeout))
+        result.equal?(TIMED_OUT) ? fallback&.call : result[1]
+      end
+
+      def store(key, value, timeout: nil, &fallback)
+        check_frozen!
+        key = canonical_key(key)
+        check_value(value, "value")
+        result = await_response(deadline: timeout_deadline(timeout)) { request(:store, key, value, false) }
+        result.equal?(TIMED_OUT) ? fallback&.call : value
+      end
+
+      def swap(key, replacement, timeout: nil, &fallback)
+        check_frozen!
+        key = canonical_key(key)
+        check_value(replacement, "value")
+        result = await_response(deadline: timeout_deadline(timeout)) { request(:store, key, replacement, true) }
+        result.equal?(TIMED_OUT) ? fallback&.call : result[1]
+      end
+
+      def store_if_absent(key, timeout: nil, &update)
+        raise LocalJumpError, "no block given" unless update
+
+        claimed_update(key, timeout_deadline(timeout), claim: :absent) { update.call }
+      end
+
+      def compare_and_set(key, expected, replacement, timeout: nil)
+        check_frozen!
+        check_value(expected, "value")
+        check_value(replacement, "value")
+        matched = false
+        claimed_update(key, timeout_deadline(timeout), claim: :present) do |current|
+          next TIMED_OUT unless values_equal?(current, expected)
+
+          check_frozen!
+          matched = true
+          replacement
+        end
+        matched
+      end
+
+      def update(key, timeout: nil, &update)
+        raise LocalJumpError, "no block given" unless update
+
+        claimed_update(key, timeout_deadline(timeout), claim: :always, &update)
+      end
+
+      def upsert(key, initial_value, timeout: nil, &update)
+        raise LocalJumpError, "no block given" unless update
+        check_value(initial_value, "value")
+
+        claimed_update(key, timeout_deadline(timeout), claim: :present, initial: initial_value, &update)
+      end
+
+      # Yield presence and value under the entry claim.
+      # MAP_KEEP and MAP_DELETE are control results. Other results replace the value.
+      # Return whether a change committed.
+      def modify(key)
+        raise LocalJumpError, "no block given" unless block_given?
+        check_frozen!
+        key = canonical_key(key)
+        ticket = Object.new.freeze
+        sent = finished = false
+        begin
+          response = await_response(deadline: nil) do
+            sent = true
+            request(:claim, key, ticket, true)
+          end
+          present, current, signal = response[1], response[2], response[3]
+          owners = claim_owners
+          owners[signal] = Fiber.current
+          value = yield(present, current)
+          check_frozen!
+          action = if MAP_KEEP.equal?(value)
+                     :abort
+                   elsif MAP_DELETE.equal?(value)
+                     :delete
+                   else
+                     :store
+                   end
+          check_value(value, "value") if action == :store
+          result = request(:finish, key, ticket, action, value)
+          finished = true
+          result.first != :stale && (action == :store || (action == :delete && present))
+        ensure
+          owners&.delete(signal)
+          request(:finish, key, ticket, :abort) if sent && !finished
+        end
+      end
+
+      def wait_until_changed(key, expected, timeout: nil, &fallback)
+        wait_for_value(key, expected, timeout_deadline(timeout), fallback, non_nil: false)
+      end
+
+      def wait_until_non_nil(key, timeout: nil, &fallback)
+        wait_for_value(key, nil, timeout_deadline(timeout), fallback, non_nil: true)
+      end
+
+      def key?(key)                   = read(key, nil).first
+      def compare_keys_by_identity?   = @compare_keys_by_identity
+      def compare_values_by_identity? = @compare_values_by_identity
+      def shareable_keys?             = true
+      def shareable_values?           = true
+      def size                        = await_response(deadline: nil) { request(:size) }[1]
+      def keys                        = entries_snapshot.map(&:first)
+
+      def each(&block)
+        return enum_for(__callee__) { size } unless block
+        entries_snapshot.each { block.call(it) }
+        self
+      end
+      alias each_pair each
+
+      def each_live
+        return enum_for(__method__) { size } unless block_given?
+        token = request(:open_cursor)[1]
+        begin
+          while true
+            result = await_response(deadline: nil) { request(:next_live, token) }
+            break if result.first == :done
+            yield [result[1], result[2]]
+          end
+        ensure
+          request(:close_cursor, token)
+        end
+        self
+      end
+
+      def each_key(&block)
+        return enum_for(__callee__) { size } unless block
+        entries_snapshot.each { block.call(it.first) }
+        self
+      end
+
+      def each_value(&block)
+        return enum_for(__callee__) { size } unless block
+        entries_snapshot.each { block.call(it.last) }
+        self
+      end
+
+      def delete(key)
+        check_frozen!
+        key = canonical_key(key)
+        result = await_response(deadline: nil) { request(:delete, key) }
+        result.first == :ok ? result[1] : nil
+      end
+
+      def getkey(key)
+        key = canonical_key(key)
+        result = await_response(deadline: nil) { request(:getkey, key) }
+        result.first == :ok ? result[1] : nil
+      end
+
+      def clear
+        check_frozen!
+        request(:clear)
+        self
+      end
+
+      private
+
+      def check_frozen! = Internal::Freeze.check(self)
+
+      def request(action, *) = @vault.weak_map(@token, action, *)
+
+      def read(key, deadline)
+        key = canonical_key(key)
+        result = await_response(deadline:) { request(:read, key) }
+        return TIMED_OUT if result.equal?(TIMED_OUT)
+        return [false, nil] if result.first == :missing
+
+        [result[1], result[2]]
+      end
+
+      def claimed_update(key, deadline, claim:, initial: TIMED_OUT)
+        check_frozen!
+        key = canonical_key(key)
+        ticket = Object.new.freeze
+        sent   = finished = false
+
+        begin
+          response = await_response(deadline:) do
+            sent = true
+            request(:claim, key, ticket, claim != :present || !initial.equal?(TIMED_OUT))
+          end
+          return if response.equal?(TIMED_OUT)
+          return false if response.first == :missing
+
+          present, current, signal = response[1], response[2], response[3]
+          if claim == :absent && present
+            request(:finish, key, ticket, :abort)
+            finished = true
+            return current
+          end
+
+          owners         = claim_owners
+          owners[signal] = Fiber.current
+          replacement    = present || initial.equal?(TIMED_OUT) ? yield(current) : initial
+          check_frozen!
+
+          if replacement.equal?(TIMED_OUT)
+            request(:finish, key, ticket, :abort)
+            finished = true
+            return false
+          end
+
+          check_value(replacement, "value")
+          result = request(:finish, key, ticket, :store, replacement)
+          finished = true
+          result.first == :stale ? nil : replacement
+        ensure
+          owners&.delete(signal)
+          request(:finish, key, ticket, :abort) if sent && !finished
+        end
+      end
+
+      def entries_snapshot
+        result = await_response(deadline: nil) { request(:snapshot) }
+        result[1]
+      end
+
+      def await_response(deadline:)
+        checked_after_timeout = false
+        loop do
+          response = yield
+          return response unless response.first == :busy
+
+          signal, generation = response[1], response[2]
+          reject_recursive_wait!(signal)
+          timeout = remaining_timeout(deadline)
+          if timeout&.zero?
+            return TIMED_OUT if checked_after_timeout
+            checked_after_timeout = true
+            next
+          end
+          changed = signal.wait_until_changed(generation, timeout:) { TIMED_OUT }
+          if changed.equal?(TIMED_OUT)
+            return TIMED_OUT if checked_after_timeout
+            checked_after_timeout = true
+          end
+        end
+      end
+
+      def wait_for_value(key, expected, deadline, fallback, non_nil:)
+        key = canonical_key(key)
+        check_value(expected, "value")
+        checked_after_timeout = false
+        loop do
+          response = await_response(deadline:) { request(:wait_read, key) }
+          return fallback&.call if response.equal?(TIMED_OUT)
+          # Keep the canonical stored key alive, even when the lookup used a
+          # different equal key. It arrives atomically with the entry's signal.
+          key     = response[5] if response.first == :ok
+          present = response.first == :ok && response[1]
+          current = present ? response[2] : nil
+          return current if non_nil ? !current.nil? : !values_equal?(current, expected)
+
+          signal = response.first == :ok ? response[3] : response[1]
+          generation = response.first == :ok ? response[4] : response[2]
+          changed = signal.wait_until_changed(generation, timeout: remaining_timeout(deadline)) { TIMED_OUT }
+          if changed.equal?(TIMED_OUT)
+            return fallback&.call if checked_after_timeout
+            checked_after_timeout = true
+          end
+        end
+      end
+
+      def claim_owners
+        Storage.thread.store_if_absent(CLAIM_OWNERS) { {}.compare_by_identity }
+      end
+
+      def reject_recursive_wait!(signal)
+        owner = claim_owners[signal]
+        return unless owner
+        raise ThreadError, "deadlock; recursive weak-map access during an update" if owner.equal?(Fiber.current)
+        return if Fiber.respond_to?(:scheduler) && Fiber.scheduler
+
+        raise ThreadError, "deadlock; weak-map update is owned by another unscheduled fiber"
+      end
+
+      def values_equal?(left, right)
+        compare_values_by_identity? ? left.equal?(right) : left == right
+      end
+
+      def canonical_key(key)
+        key = String.instance_method(:-@).bind_call(key) if String === key && !key.frozen? && !compare_keys_by_identity?
+        check_value(key, "key")
+      end
+
+      def check_value(value, name)
+        return value if Ractor.shareable?(value)
+        raise Ractor::IsolationError, "#{name} must be Ractor-shareable"
+      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.positive? ? remaining : 0
+      end
+
+      def validate_boolean(value, name)
+        return if value.equal?(true) || value.equal?(false)
+        raise ArgumentError, "#{name} must be true or false"
+      end
+    end
+    private_constant :VaultWeakMapBase
+
+    class WeakKeyMap < VaultWeakMapBase
+      def weak_keys?   = true
+      def weak_values? = false
+    end
+
+    class WeakValueMap < VaultWeakMapBase
+      def weak_keys?   = false
+      def weak_values? = true
+    end
+
+    class WeakMap < VaultWeakMapBase
+      def weak_keys?   = true
+      def weak_values? = true
+    end
+  end
+end

data/lib/farce/engine/ruby.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+# Load the scheduler dependency before native initialization.
+# Late Resolv loading can crash RubyGems for some reason
+require "resolv"
+require "farce/strict"
+
+module Farce
+  # @!visibility private
+  module Internal # :nodoc: all
+    # Compiled extensions and Ruby helpers share one directory for each CRuby ABI.
+    ENGINE_PATH = "farce/engine/ruby/#{RUBY_VERSION[/^\d+\.\d+/]}".freeze
+    private_constant :ENGINE_PATH
+
+    begin
+      require "#{ENGINE_PATH}/rebind"
+      require "#{ENGINE_PATH}/farce"
+    rescue LoadError => e
+      # simplecov:disable
+      warn <<~WARNING
+        Farce: Failed to load native extension for Ruby #{RUBY_VERSION}.
+        Please run `rake compile` to build the extension.
+      WARNING
+      raise e
+      # simplecov:enable
+    end
+
+    unless const_defined?(:NATIVE_WEAK_MAPS, false) && NATIVE_WEAK_MAPS
+      autoload :WeakMap,      "farce/engine/ruby/shared/weak_map"
+      autoload :WeakKeyMap,   "farce/engine/ruby/shared/weak_map"
+      autoload :WeakValueMap, "farce/engine/ruby/shared/weak_map"
+    end
+
+    StrictAtom    = Atom
+    StrictLFUMap  = ShareableLFUMap
+    StrictLRUMap  = ShareableLRUMap
+    StrictTreeMap = ShareableTreeMap
+
+    autoload :ProxyOwner,           "farce/engine/ruby/shared/proxy_owner"
+    autoload :ParallelScheduler,    "farce/engine/ruby/shared/parallel_scheduler"
+    autoload :MainScheduler,        "farce/engine/ruby/shared/main_scheduler"
+    autoload :Lease,                "farce/engine/ruby/shared/lease"
+    autoload :LeasePool,            "farce/engine/ruby/shared/lease_pool"
+    autoload :StrictMap,            "farce/engine/ruby/shared/strict_map"
+    autoload :StrictWeakKeyMap,     "farce/engine/ruby/shared/strict_map"
+    autoload :StrictWeakMap,        "farce/engine/ruby/shared/strict_map"
+    autoload :StrictWeakValueMap,   "farce/engine/ruby/shared/strict_map"
+    autoload :WeakAtom,             "farce/engine/ruby/shared/weak_atom"     unless const_defined?(:WeakAtom)
+    autoload :UnsharedWeakAtom,     "farce/engine/shared/unshared_weak_atom" unless const_defined?(:UnsharedWeakAtom)
+    autoload :UnsharedAtom,         "farce/engine/shared/unshared_atom"
+    autoload :UnsharedVector,       "farce/engine/ruby/shared/unshared_vector"
+    autoload :UnsharedMap,          "farce/engine/shared/unshared_weak_map"
+    autoload :UnsharedWeakMap,      "farce/engine/shared/unshared_weak_map"
+    autoload :UnsharedWeakKeyMap,   "farce/engine/shared/unshared_weak_map"
+    autoload :UnsharedWeakValueMap, "farce/engine/shared/unshared_weak_map"
+    autoload :FiberScheduler,       "farce/engine/ruby/fiber_scheduler"
+
+    autoload :BasePort,       "#{ENGINE_PATH}/port"
+    autoload :Port,           "#{ENGINE_PATH}/port"
+    autoload :RactorMethods,  "#{ENGINE_PATH}/ractor_methods"
+    autoload :Vault,          "#{ENGINE_PATH}/vault"
+
+    def native_ractors? = true
+
+    class << self
+      alias commit_native_transaction commit_transaction
+    end
+
+    def self.commit_transaction(entries, guards = [], transaction = nil)
+      external, entries = entries.partition { it.respond_to?(:commit_group) }
+      return ExternalTransaction.commit(entries, external, guards, transaction) unless external.empty?
+      guards = guards.map { it.respond_to?(:native_flag) ? it.native_flag : it }
+      native, portable = entries.partition { NativeTransactionEntry === it }
+      return commit_native_transaction(native, guards) if portable.empty?
+      PortableTransaction.commit(portable, guards) { commit_native_transaction(native, guards) }
+    end
+
+    def self.notify_transaction(entries)
+      entries.each { it.notify unless NativeTransactionEntry === it }
+    end
+
+    def prepare_method_definition(&) = Ractor.shareable_proc(&)
+
+    if ::Ractor.const_defined?(:Port, false)
+      def native_ports? = true
+    else
+      def native_ports? = false
+    end
+
+    # Native waits opt in through the scheduler's ractor_selector method.
+    # Blocking fibers use Ruby directly, including the helper's result retrieval.
+    # Version-specific hooks retain native timeout support and method visibility.
+    patch = lambda do |namespace, *methods, signature: "...", schedule: "self, ...", before: nil|
+      methods.each do |method|
+        visibility = namespace.private_method_defined?(method) ? "private" : "public"
+        namespace.class_eval <<~RUBY, __FILE__, __LINE__ + 1
+          alias #{method}! #{method}
+          private :#{method}!
+
+          def #{method}(#{signature})
+            #{before}
+            scheduler = Fiber.scheduler unless Fiber.blocking?
+            selector = scheduler.ractor_selector if scheduler.respond_to?(:ractor_selector)
+            return #{method}!(#{signature}) unless selector
+            selector.ractor_#{method}(#{schedule})
+          end
+          #{visibility} :#{method}
+        RUBY
+      end
+    end
+
+    require "#{ENGINE_PATH}/ractor_selector"
+    RactorSelector.install_hooks(patch)
+    ::Ractor.singleton_class.alias_method :recv, :receive
+    ::Ractor.alias_method :recv, :receive
+
+    if defined?(Darwin.main_qos_class) && defined?(Darwin.get_qos_class)
+      def prepare_thread
+        main_qos_class      = Darwin.main_qos_class
+        qos_class, priority = Darwin.get_qos_class
+        Darwin.set_qos_class(main_qos_class, priority) if main_qos_class > qos_class
+      end
+    end
+  end
+end
+
+require "farce/engine/ruby/key_lock_map"
+require "farce/engine/shared/trie_builder"

data/lib/farce/engine/shared/atom.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Internal # :nodoc: all
+    class Atom < UnsharedAtom
+    end
+  end
+end

data/lib/farce/engine/shared/exchanger.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  # @!visibility private
+  module Internal # :nodoc: all
+    class Exchanger
+      include Freeze::Unfreezable
+
+      TIMED_OUT = Object.new.freeze
+      WAITING   = Object.new.freeze
+      Waiter = Struct.new(:condition, :matched, :offered, :reader, :received, :scheduler, :writer)
+      private_constant :TIMED_OUT, :WAITING, :Waiter
+
+      def initialize
+        @mutex   = Mutex.new
+        @waiting = [nil]
+        Freeze.publish(self)
+      end
+
+      def exchange(offered, timeout: nil, &fallback)
+        deadline = timeout_deadline(timeout)
+        waiter   = build_waiter(offered)
+
+        partner = @mutex.synchronize do
+          if partner = @waiting.first
+            @waiting[0] = nil
+            partner.received = offered
+            partner.matched  = true
+            notify(partner)
+            partner
+          elsif deadline && deadline <= Clock.now
+            TIMED_OUT
+          else
+            @waiting[0] = waiter
+            nil
+          end
+        end
+
+        return partner.offered if partner && !TIMED_OUT.equal?(partner)
+        return timed_out(fallback) if TIMED_OUT.equal?(partner)
+
+        result = waiter.scheduler ? wait_with_scheduler(waiter, deadline) : wait_with_condition(waiter, deadline)
+        TIMED_OUT.equal?(result) ? timed_out(fallback) : result
+      ensure
+        remove(waiter) if waiter
+        waiter&.reader&.close
+        waiter&.writer&.close
+      end
+
+      private
+
+      def build_waiter(offered)
+        scheduler = Fiber.current_scheduler if Fiber.respond_to?(:current_scheduler)
+        # JRuby may run a later scheduled fiber on a backing thread where this is nil.
+        scheduler ||= Fiber.scheduler if Fiber.respond_to?(:scheduler) && !Fiber.current.blocking?
+        reader, writer = IO.pipe if scheduler
+        Waiter.new(
+          condition: ConditionVariable.new,
+          matched:   false,
+          offered:   offered,
+          reader:    reader,
+          scheduler: scheduler,
+          writer:    writer,
+        )
+      end
+
+      def notify(waiter)
+        if waiter.scheduler
+          waiter.writer.write_nonblock(".", exception: false)
+        else
+          waiter.condition.broadcast
+        end
+      end
+
+      def wait_with_condition(waiter, deadline)
+        @mutex.synchronize do
+          until waiter.matched
+            remaining = deadline - Clock.now if deadline
+            return cancel(waiter) if remaining && !remaining.positive?
+            waiter.condition.wait(@mutex, remaining)
+          end
+          waiter.received
+        end
+      end
+
+      def wait_with_scheduler(waiter, deadline)
+        loop do
+          state, result = @mutex.synchronize do
+            if waiter.matched
+              [nil, waiter.received]
+            else
+              remaining = deadline - Clock.now if deadline
+              remaining && !remaining.positive? ? [nil, cancel(waiter)] : [WAITING, remaining]
+            end
+          end
+          return result unless WAITING.equal?(state)
+
+          waiter.scheduler.io_wait(waiter.reader, IO::READABLE, result)
+        end
+      end
+
+      def cancel(waiter)
+        remove(waiter)
+        waiter.matched ? waiter.received : TIMED_OUT
+      end
+
+      def remove(waiter)
+        @mutex.owned? ? remove_locked(waiter) : @mutex.synchronize { remove_locked(waiter) }
+      end
+
+      def remove_locked(waiter)
+        @waiting[0] = nil if @waiting.first.equal?(waiter)
+      end
+
+      def timeout_deadline(timeout)
+        return unless timeout
+
+        timeout = Float(timeout)
+        if !timeout.finite? || timeout.negative?
+          raise ArgumentError, "timeout must be a finite, non-negative number or nil"
+        end
+        Clock.now + timeout
+      end
+
+      def timed_out(fallback) = fallback&.call
+    end
+  end
+end

data/lib/farce/engine/shared/identity_key.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  # @!visibility private
+  module Internal # :nodoc: all
+    class IdentityKey
+      BASIC_OBJECT_EQUAL_METHOD = BasicObject.instance_method(:equal?)
+      BASIC_OBJECT_ID_METHOD = BasicObject.instance_method(:__id__)
+      private_constant :BASIC_OBJECT_EQUAL_METHOD, :BASIC_OBJECT_ID_METHOD
+
+      attr_reader :value
+
+      def initialize(value) = @value = value
+      def hash = BASIC_OBJECT_ID_METHOD.bind_call(value)
+      def eql?(other) = other.is_a?(IdentityKey) && BASIC_OBJECT_EQUAL_METHOD.bind_call(value, other.value)
+
+      alias == eql?
+    end
+  end
+end