farce 0 → 0.1.0

data/lib/farce/engine/jvm/tree_map.rb

@@ -0,0 +1,350 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+require "farce/engine/jvm/types"
+
+module Farce
+  # @!visibility private
+  module Internal # :nodoc: all
+    module JVMTreeMapBackend
+      Key            = Struct.new(:key, :mutation_owner)
+      Value          = Data.define(:value)
+      KEY_COMPARATOR = JVMContainers.comparator do |left, right|
+        next 0 if left.equal?(right)
+
+        comparison = JVMContainers.compare(left.key, right.key)
+        owner = left.mutation_owner || right.mutation_owner
+        raise FrozenError, "can't modify frozen #{owner.class}" if owner&.__send__(:mutation_frozen?)
+        comparison
+      end
+
+      INITIALIZATION_LOCK = Mutex.new
+      State = Struct.new(:tree, :revision)
+      private_constant :Key, :Value, :KEY_COMPARATOR, :INITIALIZATION_LOCK, :State
+
+      def initialize(entries = nil)
+        check_uninitialized
+
+        parsed_entries = coerce_entries(entries)
+        check_uninitialized
+        guard = JVMOperationGuard.new(synchronized: synchronized?, label: "tree map")
+        state = build_state(parsed_entries)
+
+        if synchronized?
+          guard.synchronize { publish_initialization(guard, state) }
+        else
+          publish_initialization(guard, state)
+        end
+      end
+
+      # Adapt the existing Java lock only for transaction participants.
+      TransactionLock = Struct.new(:lock) do
+        def try_lock = lock.tryLock
+        def unlock = lock.unlock
+      end
+      private_constant :TransactionLock
+
+      def transaction_snapshot
+        raise TypeError, "unsafe tree maps do not support transactions" unless synchronized?
+        tree, revision = access { [JVMContainers::TreeMap.new(@state.tree), @state.revision] }
+        working = self.class.new
+        working.instance_variable_get(:@state).tree = tree
+        lock = TransactionLock.new(@guard.instance_variable_get(:@lock))
+        PortableTransaction::TreeEntry.new(self, working, revision, lock, :tree)
+      end
+
+      def prepare_key(key) = canonical_key(key)
+
+      def freeze
+        state = @freeze_state
+        return super unless synchronized? && state
+
+        state.set
+        self
+      end
+
+      def frozen?
+        state = @freeze_state
+        synchronized? && state ? state.value : super
+      end
+
+      def [](key)
+        key = canonical_key(key)
+        access do
+          wrapped = JVMContainers.nullable(@state.tree.get(Key.new(key)))
+          wrapped&.value
+        end
+      end
+
+      def fetch(*arguments)
+        unless arguments.length.between?(1, 2)
+          raise ArgumentError, "wrong number of arguments (given #{arguments.length}, expected 1..2)"
+        end
+
+        original_key, default = arguments
+        key = canonical_key(original_key)
+        default_given = arguments.length == 2
+        warn "block supersedes default value argument", uplevel: 1 if block_given? && default_given
+        wrapped = access { JVMContainers.nullable(@state.tree.get(Key.new(key))) }
+        return wrapped.value if wrapped
+        return yield(original_key) if block_given?
+        return default if default_given
+
+        raise KeyError.new(
+          "key not found: #{original_key.inspect}",
+          receiver: self,
+          key:      original_key,
+        )
+      end
+
+      def key?(key)
+        key = canonical_key(key)
+        access { !JVMContainers.nullable(@state.tree.get(Key.new(key))).nil? }
+      end
+
+      def getkey(key)
+        key = canonical_key(key)
+        access do
+          probe = Key.new(key)
+          entry = JVMContainers.nullable(@state.tree.ceilingEntry(probe))
+          next unless entry && KEY_COMPARATOR.compare(probe, entry.getKey).zero?
+
+          entry.getKey.key
+        end
+      end
+
+      def each
+        return enum_for(__method__) { size } unless block_given?
+
+        entries = access do
+          snapshot = []
+          iterator = @state.tree.entrySet.iterator
+          while iterator.hasNext
+            entry = iterator.next
+            snapshot << [entry.getKey.key, entry.getValue.value]
+          end
+          snapshot
+        end
+        entries.each { yield it }
+        self
+      end
+
+      def each_live
+        return enum_for(__method__) { size } unless block_given?
+
+        iterator = nil
+        last_key = nil
+        revision = nil
+        started = false
+        loop do
+          pair = access do
+            current = @state.revision
+            if !started || revision != current
+              entries = started ? @state.tree.tailMap(Key.new(last_key), false).entrySet : @state.tree.entrySet
+              iterator = entries.iterator
+            end
+            next unless iterator.hasNext
+
+            entry = iterator.next
+            last_key = entry.getKey.key
+            revision = current
+            [last_key, entry.getValue.value]
+          end
+          break unless pair
+          started = true
+          yield pair
+        end
+        self
+      end
+
+      def []=(key, value)
+        key = canonical_key(key)
+        access do
+          check_local_frozen
+          wrapped_key = mutation_key(key)
+          begin
+            @state.tree.put(wrapped_key, Value.new(value))
+            @state.revision += 1
+          ensure
+            Thread.handle_interrupt(INTERRUPT_MASK) do
+              wrapped_key.mutation_owner = nil
+            end
+          end
+          value
+        end
+      end
+
+      def delete(key)
+        key = canonical_key(key)
+        access do
+          check_local_frozen
+          wrapped = JVMContainers.nullable(@state.tree.remove(mutation_key(key)))
+          @state.revision += 1 if wrapped
+          wrapped&.value
+        end
+      end
+
+      def first_key
+        access do
+          entry = JVMContainers.nullable(@state.tree.firstEntry)
+          entry&.getKey&.key
+        end
+      end
+
+      def last_key
+        access do
+          entry = JVMContainers.nullable(@state.tree.lastEntry)
+          entry&.getKey&.key
+        end
+      end
+
+      def shift
+        access do
+          check_local_frozen
+          iterator = @state.tree.entrySet.iterator
+          next nil unless iterator.hasNext
+
+          entry = iterator.next
+          result = [entry.getKey.key, entry.getValue.value]
+          iterator.remove
+          @state.revision += 1
+          result
+        end
+      end
+
+      def pop
+        access do
+          check_local_frozen
+          iterator = @state.tree.descendingMap.entrySet.iterator
+          next nil unless iterator.hasNext
+
+          entry = iterator.next
+          result = [entry.getKey.key, entry.getValue.value]
+          iterator.remove
+          @state.revision += 1
+          result
+        end
+      end
+
+      def size = access { @state.tree.size }
+
+      alias length size
+
+      def empty? = access { @state.tree.isEmpty }
+
+      def clear
+        access do
+          check_local_frozen
+          unless @state.tree.isEmpty
+            @state.tree.clear
+            @state.revision += 1
+          end
+        end
+        self
+      end
+
+      def initialize_copy(_other)
+        raise TypeError, "tree maps cannot be copied"
+      end
+
+      private
+
+      def publish_initialization(guard, state)
+        INITIALIZATION_LOCK.synchronize do
+          Thread.handle_interrupt(INTERRUPT_MASK) do
+            raise "tree map is already initialized" if defined?(@state)
+            raise FrozenError, "can't modify frozen #{self.class}" if
+              JVMContainers.frozen_object?(self)
+
+            @state = state
+            @guard = guard
+            @freeze_state = Flag.new(false) if synchronized?
+            JVMContainers.freeze_object(self) if synchronized?
+          end
+        end
+      end
+
+      def access(&)
+        raise "tree map is not initialized" unless defined?(@guard) && @guard
+
+        @guard.synchronize(&)
+      end
+
+      def synchronized? = false
+
+      def check_local_frozen
+        raise FrozenError, "can't modify frozen #{self.class}" if mutation_frozen?
+      end
+
+      def mutation_frozen? = synchronized? ? frozen? : JVMContainers.frozen_object?(self)
+
+      def mutation_key(key)
+        Key.new(key, self)
+      end
+
+      def canonical_key(key)
+        JVMContainers.string?(key) ? JVMContainers.canonical_string(key) : key
+      end
+
+      def build_state(entries)
+        tree = JVMContainers::TreeMap.new(KEY_COMPARATOR)
+        entries&.each do |key, value|
+          check_uninitialized
+
+          stored_key = canonical_key(key)
+          check_uninitialized
+
+          wrapped_key = Key.new(stored_key, self)
+          begin
+            tree.put(wrapped_key, Value.new(value))
+          ensure
+            Thread.handle_interrupt(INTERRUPT_MASK) do
+              wrapped_key.mutation_owner = nil
+            end
+          end
+          check_uninitialized
+        end
+        State.new(tree, 0)
+      end
+
+      def check_uninitialized
+        raise "tree map is already initialized" if defined?(@state)
+        raise FrozenError, "can't modify frozen #{self.class}" if JVMContainers.frozen_object?(self)
+      end
+
+      def coerce_entries(entries)
+        return if entries.nil?
+        return entries if JVMContainers.is_a?(entries, Hash)
+
+        hash = entries.to_hash if entries.respond_to?(:to_hash)
+        return hash if JVMContainers.is_a?(hash, Hash)
+
+        raise TypeError, "entries must be a Hash or respond to #to_hash"
+      end
+    end
+
+    # Explicit unsynchronized JVM implementation.
+    class UnsafeTreeMap
+      include JVMTreeMapBackend
+    end
+
+    # Default JVM implementation: ordinary TreeMap under a coarse lock. The
+    # object itself is frozen, while its guarded Java backing map remains the
+    # controlled mutation boundary.
+    class TreeMap
+      include JVMTreeMapBackend
+
+      private
+
+      def synchronized? = true
+    end
+
+    MutableTreeMap = TreeMap
+
+    # No Ractors, no problems :)
+    ShareableTreeMap = TreeMap
+
+    private_constant :JVMTreeMapBackend
+  end
+end

data/lib/farce/engine/jvm/types.rb

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+# Loaded only by JRuby and TruffleRuby in JVM mode. The two runtimes expose
+# different Java interop namespaces, so the rest of the container code goes
+# through this deliberately small bridge.
+
+module Farce
+  # @!visibility private
+  module Internal # :nodoc: all
+    module JVMContainers
+      CLASS_ALLOCATE_METHOD               = Class.instance_method(:allocate)
+      BASIC_OBJECT_EQUAL_METHOD           = BasicObject.instance_method(:equal?)
+      OBJECT_CLASS_METHOD                 = Object.instance_method(:class)
+      OBJECT_FREEZE_METHOD                = Object.instance_method(:freeze)
+      OBJECT_FROZEN_METHOD                = Object.instance_method(:frozen?)
+      OBJECT_ID_METHOD                    = BasicObject.instance_method(:__id__)
+      OBJECT_INSTANCE_VARIABLES_METHOD    = Object.instance_method(:instance_variables)
+      OBJECT_INSTANCE_VARIABLE_GET_METHOD = Object.instance_method(:instance_variable_get)
+      OBJECT_INSTANCE_VARIABLE_SET_METHOD = Object.instance_method(:instance_variable_set)
+      OBJECT_IS_A_METHOD                  = Object.instance_method(:is_a?)
+      STRING_INITIALIZE_COPY_METHOD       = String.instance_method(:initialize_copy)
+
+      if RUBY_ENGINE == "jruby"
+        ConcurrentHashMap = Java::JavaUtilConcurrent::ConcurrentHashMap
+        TreeMap           = Java::JavaUtil::TreeMap
+        ArrayDeque        = Java::JavaUtil::ArrayDeque
+        AtomicBoolean     = Java::JavaUtilConcurrentAtomic::AtomicBoolean
+        AtomicLong        = Java::JavaUtilConcurrentAtomic::AtomicLong
+        Comparator        = Java::JavaUtil::Comparator
+        ReentrantLock     = Java::JavaUtilConcurrentLocks::ReentrantLock
+      else
+        ConcurrentHashMap = Java.type("java.util.concurrent.ConcurrentHashMap")
+        TreeMap           = Java.type("java.util.TreeMap")
+        ArrayDeque        = Java.type("java.util.ArrayDeque")
+        AtomicBoolean     = Java.type("java.util.concurrent.atomic.AtomicBoolean")
+        AtomicLong        = Java.type("java.util.concurrent.atomic.AtomicLong")
+        Comparator        = Java.type("java.util.Comparator")
+        ReentrantLock     = Java.type("java.util.concurrent.locks.ReentrantLock")
+      end
+
+      module_function
+
+      def compare(left, right)
+        comparison = left <=> right
+        raise ArgumentError, "comparison failed" if comparison.nil?
+
+        # Match rb_cmpint: comparator results only need ordering against zero,
+        # they need not implement Numeric's #positive?/#negative?.
+        return 1  if comparison > 0 # rubocop:disable Style/NumericPredicate
+        return -1 if comparison < 0 # rubocop:disable Style/NumericPredicate
+
+        0
+      end
+
+      # Passing a Ruby lambda through this Java method produces a concrete SAM
+      # proxy. This avoids TruffleRuby choosing TreeMap's Map constructor when
+      # a bare Ruby lambda could also look map-like to polyglot interop.
+      def comparator(&block) = Comparator.nullsFirst(block)
+
+      # TruffleRuby represents a Java null as Polyglot::ForeignNull. It reports
+      # nil? but is not the VM's Qnil, so safe navigation still invokes methods
+      # on it. Always normalize Java-returned nullable references explicitly.
+      def nullable(value) = value.nil? ? nil : value
+
+      # Call BasicObject's primitive directly so a payload cannot destabilize
+      # the cancellation index by overriding #__id__.
+      def identity_token(value) = OBJECT_ID_METHOD.bind_call(value)
+
+      # Identity deletion is part of the container contract, so it must not
+      # dispatch an overridable payload #equal?.
+      def identical?(left, right) = BASIC_OBJECT_EQUAL_METHOD.bind_call(left, right)
+
+      # Match rb_obj_freeze rather than dispatching to an overridable Ruby
+      # method while an initialized shared container is being published.
+      def freeze_object(value) = OBJECT_FREEZE_METHOD.bind_call(value)
+
+      # Frozen local containers must remain immutable even when a subclass
+      # overrides #frozen? and lies about the VM's object flag.
+      def frozen_object?(value) = OBJECT_FROZEN_METHOD.bind_call(value)
+
+      def is_a?(value, klass) = OBJECT_IS_A_METHOD.bind_call(value, klass)
+
+      def string?(value) = is_a?(value, String)
+
+      # Match String#-@ for ordinary Strings without dispatching an override.
+      # String subclasses retain the explicit primitive snapshot path because
+      # JRuby and TruffleRuby differ from CRuby around subclass #freeze hooks.
+      def canonical_string(value)
+        klass = OBJECT_CLASS_METHOD.bind_call(value)
+        return -value if identical?(klass, String)
+
+        copy_frozen_string(value)
+      end
+
+      # Preserve String subclasses and their comparison methods while
+      # bypassing overridable #dup, #initialize_copy, #class, and #freeze.
+      # This mirrors the primitive String snapshot used by native containers.
+      def copy_frozen_string(value)
+        klass = OBJECT_CLASS_METHOD.bind_call(value)
+        copy = CLASS_ALLOCATE_METHOD.bind_call(klass)
+        STRING_INITIALIZE_COPY_METHOD.bind_call(copy, value)
+        OBJECT_INSTANCE_VARIABLES_METHOD.bind_call(value).each do |name|
+          instance_value = OBJECT_INSTANCE_VARIABLE_GET_METHOD.bind_call(value, name)
+          OBJECT_INSTANCE_VARIABLE_SET_METHOD.bind_call(copy, name, instance_value)
+        end
+        freeze_object(copy)
+      end
+    end
+
+    class JVMOperationGuard
+      def initialize(synchronized:, label:, recursive_error: nil)
+        @lock            = JVMContainers::ReentrantLock.new if synchronized
+        @label           = label
+        @owner           = nil
+        @recursive_error = recursive_error || (synchronized ? ThreadError : RuntimeError)
+      end
+
+      def synchronize(&)
+        # JRuby exposes a distinct Ruby Thread wrapper to sibling Fibers on the
+        # same Java thread. Normalize it before checking logical ownership so a
+        # reentrant Java lock cannot admit a sibling while callbacks hold state.
+        current = Internal.storage_thread(Thread.current)
+        if JVMContainers.identical?(@owner, current)
+          message = @recursive_error == ThreadError ? "recursive #{@label} access" :
+            "container cannot be modified during comparison"
+          raise @recursive_error, message
+        end
+
+        if @lock
+          synchronize_locked(current, &)
+        else
+          begin
+            @owner = current
+            yield
+          ensure
+            Thread.handle_interrupt(INTERRUPT_MASK) { @owner = nil }
+          end
+        end
+      end
+
+      private
+
+      # Querying the Java lock in ensure closes the tiny async-exception gap
+      # between ReentrantLock#lock returning and Ruby recording ownership.
+      # A cancellation while waiting sees false; one after acquisition always
+      # releases the lock, even if it arrived before @owner was assigned.
+      def synchronize_locked(current)
+        acquired = @lock.tryLock
+        unless acquired
+          # A blocking Java lock can strand the backing thread that must run the
+          # lock owner. CRuby uses a scheduler-aware native gate; JVM engines do
+          # not promise that extension, so fail safely on the contended path.
+          raise ThreadError, "shared JVM container contention cannot block a scheduled Fiber" if scheduled_fiber?
+
+          @lock.lock
+        end
+        @owner = current
+        yield
+      ensure
+        Thread.handle_interrupt(INTERRUPT_MASK) do
+          if @lock.isHeldByCurrentThread
+            @owner = nil
+            @lock.unlock
+          end
+        end
+      end
+
+      def scheduled_fiber?
+        return false unless Fiber.respond_to?(:scheduler)
+        return false if Fiber.current.respond_to?(:blocking?) && Fiber.current.blocking?
+
+        scheduler = Fiber.current_scheduler if Fiber.respond_to?(:current_scheduler)
+        scheduler ||= Fiber.scheduler
+        !scheduler.nil?
+      end
+    end
+  end
+end

data/lib/farce/engine/jvm.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+# Common atomic and ordered-container loader for JRuby and TruffleRuby in JVM mode.
+
+module Farce
+  # @!visibility private
+  module Internal # :nodoc: all
+    autoload :ConcurrentWeakRegistry, "farce/engine/jvm/concurrent_weak_registry"
+    autoload :Counter,                "farce/engine/jvm/counter"
+    autoload :Flag,                   "farce/engine/jvm/flag"
+    autoload :UnsafeTreeMap,          "farce/engine/jvm/tree_map"
+    autoload :PriorityQueue,          "farce/engine/jvm/priority_queue"
+    autoload :ShareableTreeMap,       "farce/engine/jvm/tree_map"
+    autoload :TreeMap,                "farce/engine/jvm/tree_map"
+    autoload :MutableTreeMap,         "farce/engine/jvm/tree_map"
+  end
+end

data/lib/farce/engine/ruby/3.4/fiber_scheduler.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Internal
+    class FiberScheduler
+      # Ruby 3.4 can strand a control Ractor started alongside scheduled workers.
+      # Start it before admitting fibers. Ruby 4.x creates the selector lazily.
+      module RactorSelectorSetup
+        def initialize(...)
+          RactorSelector.current
+          super
+        end
+      end
+      private_constant :RactorSelectorSetup
+      prepend RactorSelectorSetup
+    end
+  end
+end