farce 0 → 0.1.0

data/lib/farce/engine/jruby/map.rb

@@ -0,0 +1,505 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+require "farce/engine/shared/map_key_coordination"
+
+module Farce
+  # @!visibility private
+  module Internal # :nodoc: all
+    class Map
+      include MapKeyCoordination
+      include TransactionMapBackend
+
+      BASIC_OBJECT_EQUAL_METHOD = BasicObject.instance_method(:equal?)
+      private_constant :BASIC_OBJECT_EQUAL_METHOD
+
+      class Key
+        attr_accessor :mutation_owner
+        attr_reader :value
+
+        def initialize(value) = @value = value
+
+        def hash
+          result = value.hash
+          owner = mutation_owner
+          Internal::Freeze.check(owner) if owner
+          result
+        end
+
+        def eql?(other)
+          result = other.is_a?(Key) && value.eql?(other.value)
+          owner = mutation_owner || (other.mutation_owner if other.is_a?(Key))
+          Internal::Freeze.check(owner) if owner
+          result
+        end
+
+        alias == eql?
+      end
+      private_constant :Key
+
+      # The Java bridge converts objects such as Ruby strings unless they are boxed.
+      class Value
+        attr_reader :value
+
+        def initialize(value) = @value = value
+      end
+      private_constant :Value
+
+      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)
+
+        @compare_keys_by_identity   = compare_keys_by_identity
+        @compare_values_by_identity = compare_values_by_identity
+        @freeze_state = Flag.new(false)
+        @map           = java.util.concurrent.ConcurrentHashMap.new
+        # Native operations may overlap. Block updates reserve one logical key.
+        @state_mutex   = Mutex.new
+        @change_signal = Signal.new
+        @active_owner_fiber  = nil
+        @active_owner_thread = nil
+        @active_owners = nil
+        initialize_key_coordination
+        initial_mapping&.each do |key, value|
+          check_frozen!
+          wrapped = wrap_key(key)
+          with_mutation_callback_guard(wrapped) { concurrent_store(wrapped, value) }
+        end
+      end
+
+      def freeze
+        state = @freeze_state
+        return super unless state
+
+        state.set
+        self
+      end
+
+      def frozen?
+        state = @freeze_state
+        state ? state.value : super
+      end
+
+      def check_mutation = check_frozen!
+
+      def prepare_mutation_key(key)
+        check_frozen!
+        normalize_external_key(key)
+      end
+
+      def [](key) = concurrent_get(wrap_key(key))
+
+      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
+        stored = @map.get(wrap_key(key))
+        return stored.value if stored
+        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 []=(key, value)
+        check_frozen!
+        wrapped = wrap_key(key)
+        _, result = with_mutating_key_operation(wrapped, nil) do |reservation|
+          commit_mutation(reservation) do
+            native_operation { concurrent_store(wrapped, value) }
+            changed!
+          end
+          value
+        end
+        result
+      end
+
+      def get(key, timeout: nil, &fallback)
+        wrapped = wrap_key(key)
+        completed, result = with_key_operation(wrapped, timeout_deadline(timeout)) do
+          native_operation { concurrent_get(wrapped) }
+        end
+        completed ? result : fallback&.call
+      end
+
+      def store(key, value, timeout: nil, &fallback)
+        check_frozen!
+        wrapped = wrap_key(key)
+        completed, result = with_mutating_key_operation(wrapped, timeout_deadline(timeout)) do |reservation|
+          commit_mutation(reservation) do
+            native_operation { concurrent_store(wrapped, value) }
+            changed!
+          end
+          value
+        end
+        completed ? result : fallback&.call
+      end
+
+      def swap(key, replacement, timeout: nil, &fallback)
+        check_frozen!
+        wrapped = wrap_key(key)
+        completed, result = with_mutating_key_operation(wrapped, timeout_deadline(timeout)) do |reservation|
+          previous = nil
+          commit_mutation(reservation) do
+            previous = native_operation { concurrent_swap(wrapped, replacement) }
+            changed!
+          end
+          previous
+        end
+        completed ? result : fallback&.call
+      end
+
+      def store_if_absent(key, timeout: nil)
+        raise LocalJumpError, "no block given" unless block_given?
+        check_frozen!
+
+        wrapped = wrap_key(key)
+        completed, result = with_mutating_key_operation(wrapped, timeout_deadline(timeout)) do |reservation|
+          if native_operation { concurrent_key?(wrapped) }
+            native_operation { concurrent_get(wrapped) }
+          else
+            value = yield
+            stored = commit_mutation(reservation) do
+              native_operation { concurrent_store(wrapped, value) }
+              changed!
+            end
+            value if stored
+          end
+        end
+        completed ? result : nil
+      end
+
+      def compare_and_set(key, expected, replacement, timeout: nil)
+        check_frozen!
+        wrapped = wrap_key(key)
+        completed, result = with_mutating_key_operation(wrapped, timeout_deadline(timeout)) do |reservation|
+          next false unless native_operation { concurrent_key?(wrapped) }
+
+          current = native_operation { concurrent_get(wrapped) }
+          next false unless values_equal?(current, expected)
+
+          replaced = commit_mutation(reservation) do
+            native_operation { concurrent_store(wrapped, replacement) }
+            changed!
+          end
+          replaced
+        end
+        completed && result
+      end
+
+      def update(key, timeout: nil)
+        raise LocalJumpError, "no block given" unless block_given?
+        check_frozen!
+
+        wrapped = wrap_key(key)
+        completed, result = with_mutating_key_operation(wrapped, timeout_deadline(timeout)) do |reservation|
+          value = yield(native_operation { concurrent_get(wrapped) })
+          stored = commit_mutation(reservation) do
+            native_operation { concurrent_store(wrapped, value) }
+            changed!
+          end
+          value if stored
+        end
+        completed ? result : nil
+      end
+
+      # Yield presence and value under the key reservation.
+      # MAP_KEEP and MAP_DELETE are control results. Other results replace the value.
+      # Return whether a change committed.
+      def modify(key) # rubocop:disable Naming/PredicateMethod
+        raise LocalJumpError, "no block given" unless block_given?
+        check_frozen!
+        wrapped = wrap_key(key)
+        _, result = with_mutating_key_operation(wrapped, nil) do |reservation|
+          present, current = native_operation { [concurrent_key?(wrapped), concurrent_get(wrapped)] }
+          value = yield(present, current)
+          next false if MAP_KEEP.equal?(value)
+          remove = MAP_DELETE.equal?(value)
+          next false if remove && !present
+          commit_mutation(reservation) do
+            native_operation do
+              remove ? concurrent_delete(wrapped) : concurrent_store(wrapped, value)
+            end
+            changed!
+          end
+        end
+        !!result
+      end
+
+      def upsert(key, initial_value, timeout: nil)
+        raise LocalJumpError, "no block given" unless block_given?
+        check_frozen!
+
+        wrapped = wrap_key(key)
+        completed, result = with_mutating_key_operation(wrapped, timeout_deadline(timeout)) do |reservation|
+          present = native_operation { concurrent_key?(wrapped) }
+          value = present ? yield(native_operation { concurrent_get(wrapped) }) : initial_value
+          stored = commit_mutation(reservation) do
+            native_operation { concurrent_store(wrapped, value) }
+            changed!
+          end
+          value if stored
+        end
+        completed ? result : nil
+      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) = concurrent_key?(wrap_key(key))
+      def size = @map.size
+      def compare_keys_by_identity? = @compare_keys_by_identity
+      def compare_values_by_identity? = @compare_values_by_identity
+
+      def keys = entries_snapshot.map(&:first)
+
+      def each(&block)
+        return enum_for(__callee__) { size } unless block
+
+        entries_snapshot.each { |pair| block.call(pair) }
+        self
+      end
+      alias each_pair each
+
+      def each_live
+        return enum_for(__method__) { size } unless block_given?
+        iterator = @map.entry_set.iterator
+        while iterator.has_next
+          entry = iterator.next
+          yield [entry.key.value, entry.value.value]
+        end
+        self
+      end
+
+      def each_key(&block)
+        return enum_for(__callee__) { size } unless block
+
+        entries_snapshot.each { |pair| block.call(pair.first) }
+        self
+      end
+
+      def each_value(&block)
+        return enum_for(__callee__) { size } unless block
+
+        entries_snapshot.each { |pair| block.call(pair.last) }
+        self
+      end
+
+      def clear
+        check_frozen!
+        clear_key_operations do
+          native_operation { @map.clear }
+          changed!
+        end
+        self
+      end
+
+      def delete(key)
+        check_frozen!
+        wrapped = wrap_key(key)
+        _, result = with_mutating_key_operation(wrapped, nil) do |reservation|
+          value = nil
+          commit_mutation(reservation) do
+            value = native_operation { concurrent_delete(wrapped) }
+            changed!
+          end
+          value
+        end
+        result
+      end
+
+      def getkey(key)
+        wrapped = wrap_key(key)
+        return unless concurrent_key?(wrapped)
+
+        @map.each_pair do |stored, _value|
+          return stored.value if stored.eql?(wrapped)
+        end
+        nil
+      end
+
+      private
+
+      def check_frozen! = Internal::Freeze.check(self)
+
+      def commit_mutation(reservation, &)
+        check_frozen!
+        reservation.commit(&)
+      end
+
+      def with_mutating_key_operation(key, deadline, &)
+        with_key_operation(key, deadline) do |reservation|
+          with_mutation_callback_guard(key) do
+            check_frozen!
+            yield reservation
+          end
+        end
+      end
+
+      def with_mutation_callback_guard(key)
+        return yield unless key.is_a?(Key)
+
+        key.mutation_owner = self
+        yield
+      ensure
+        key.mutation_owner = nil if key.is_a?(Key)
+      end
+
+      def wrap_key(key)
+        return IdentityKey.new(key) if compare_keys_by_identity?
+        key = String.instance_method(:-@).bind_call(key) if String === key && !key.frozen?
+        Key.new(key)
+      end
+
+      def entries_snapshot
+        entries = []
+        @map.each_pair { |key, value| entries << [key.value, value.value] }
+        entries
+      end
+
+      def concurrent_get(key)
+        stored = @map.get(key)
+        stored&.value
+      end
+
+      def concurrent_store(key, value)
+        @map.put(key, Value.new(value))
+        value
+      end
+
+      def concurrent_swap(key, value)
+        previous = @map.put(key, Value.new(value))
+        previous&.value
+      end
+
+      def concurrent_key?(key) = @map.contains_key(key)
+
+      def concurrent_delete(key)
+        previous = @map.remove(key)
+        previous&.value
+      end
+
+      def native_operation(&)
+        entered = false
+        @state_mutex.synchronize do
+          reject_active_operation_reentry!
+          Thread.handle_interrupt(INTERRUPT_MASK) do
+            register_active_operation
+            entered = true
+          end
+        end
+        yield
+      ensure
+        Thread.handle_interrupt(INTERRUPT_MASK) { leave_operation } if entered
+      end
+
+      def validate_boolean(value, name)
+        return if identical?(value, true) || identical?(value, false)
+        raise ArgumentError, "#{name} must be true or false"
+      end
+
+      def leave_operation
+        @state_mutex.synchronize { unregister_active_operation }
+      end
+
+      def changed! = @change_signal.broadcast
+
+      def wait_for_value(key, expected, deadline, fallback, non_nil:)
+        wrapped = wrap_key(key)
+        while true
+          generation = @change_signal.generation
+          completed, current = with_key_operation(wrapped, deadline) do
+            native_operation { concurrent_get(wrapped) }
+          end
+          return fallback&.call unless completed
+          ready = non_nil ? !current.nil? : !values_equal?(current, expected)
+          return current if ready
+          return fallback&.call unless wait_for_signal(@change_signal, generation, deadline)
+        end
+      end
+
+      def wait_for_signal(signal, generation, deadline)
+        return signal.wait(generation) unless deadline
+
+        remaining = deadline - Clock.now
+        return false unless remaining.positive?
+        !signal.wait(generation, timeout: remaining).nil?
+      end
+
+      def timeout_deadline(timeout)
+        return if timeout.nil?
+
+        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 reject_active_operation_reentry!
+        return unless active_operation_owned_by?(Fiber.current)
+
+        raise ThreadError, "deadlock; recursive map access during an operation"
+      end
+
+      def register_active_operation
+        fiber = Fiber.current
+        thread = Thread.current
+        if @active_owners
+          @active_owners[fiber] = thread
+        elsif @active_owner_fiber
+          owners = {}.compare_by_identity
+          owners[@active_owner_fiber] = @active_owner_thread
+          owners[fiber] = thread
+          @active_owners = owners
+          @active_owner_fiber = @active_owner_thread = nil
+        else
+          @active_owner_thread = thread
+          @active_owner_fiber = fiber
+        end
+      end
+
+      def unregister_active_operation
+        if @active_owners
+          removed = @active_owners.delete(Fiber.current)
+          if @active_owners.one?
+            @active_owner_fiber, @active_owner_thread = @active_owners.first
+            @active_owners = nil
+          end
+          removed
+        elsif identical?(@active_owner_fiber, Fiber.current)
+          removed = @active_owner_thread
+          @active_owner_fiber = @active_owner_thread = nil
+          removed
+        end
+      end
+
+      def active_operation_owned_by?(fiber)
+        @active_owners ? @active_owners.key?(fiber) : identical?(@active_owner_fiber, fiber)
+      end
+
+      def values_equal?(left, right)
+        compare_values_by_identity? ? identical?(left, right) : left == right
+      end
+
+      def identical?(left, right) = BASIC_OBJECT_EQUAL_METHOD.bind_call(left, right)
+    end
+  end
+end

data/lib/farce/engine/jruby/mutable_numeric_copy.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Internal
+    # RubyNumeric's final Java clone methods return self. Invoke Object's copy
+    # setup on a fresh Numeric to preserve Ruby's hooks and singleton methods.
+    module MutableNumericCopy
+      DUP_SETUP = org.jruby.RubyBasicObject.java_class.declared_method(
+        "dupSetup", org.jruby.runtime.ThreadContext.java_class, org.jruby.RubyBasicObject.java_class,
+      )
+
+      CLONE_SETUP = org.jruby.RubyBasicObject.java_class.declared_method(
+        "cloneSetup", org.jruby.runtime.ThreadContext.java_class, org.jruby.RubyBasicObject.java_class,
+        org.jruby.runtime.builtin.IRubyObject.java_class,
+      )
+
+      DUP_SETUP.accessible = CLONE_SETUP.accessible = true
+
+      private_constant :DUP_SETUP, :CLONE_SETUP
+
+      def dup = copy_numeric(DUP_SETUP)
+
+      def clone(freeze: nil)
+        unless freeze.nil? || freeze.equal?(true) || freeze.equal?(false)
+          raise ArgumentError, "unexpected value for freeze: #{freeze.class}"
+        end
+        copy_numeric(CLONE_SETUP, JRuby.reference(freeze))
+      end
+
+      private
+
+      def copy_numeric(method, *)
+        copy = JRuby.reference(self.class.allocate)
+        method.invoke(JRuby.reference(self), JRuby.runtime.current_context, copy, *)
+      rescue Java::JavaLangReflect::InvocationTargetException => e
+        raise e.cause
+      end
+    end
+  end
+end

data/lib/farce/engine/jruby/signal.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+require "java"
+require "farce/engine/jvm/extension"
+
+module Farce
+  # @!visibility private
+  module Internal # :nodoc: all
+    class Signal < JVMExtension::QueueSignal
+      NANOSECONDS        = java.util.concurrent.TimeUnit::NANOSECONDS
+      READABLE           = IO::READABLE
+      private_constant :NANOSECONDS, :READABLE
+
+      def initialize
+        super
+        @fiber_waiters  = java.util.concurrent.ConcurrentHashMap.new
+        @thread_waiters = java.util.concurrent.atomic.AtomicInteger.new
+        Freeze.publish(self)
+      end
+
+      # JRuby-dev 10.1.2 cannot construct a Java subclass after a module is included.
+      # Keep these methods local until its reifier is fixed.
+      def freeze  = raise(TypeError, "#{self.class} cannot be frozen")
+      def frozen? = false
+
+      def generation = phase
+      def num_waiting = @thread_waiters.get + @fiber_waiters.size
+
+      def broadcast
+        generation = broadcastThreads
+
+        # Publish the generation even with no waiters, so a waiter registering
+        # concurrently can detect the broadcast before it parks.
+        return generation if @fiber_waiters.empty?
+
+        @fiber_waiters.key_set.each do |writer|
+          writer.write_nonblock(".", exception: false)
+        rescue IOError, SystemCallError
+          nil
+        end
+        generation
+      end
+
+      def wait(observed = nil, timeout: nil)
+        validate_generation(observed) unless observed.nil?
+        timeout = parse_timeout(timeout)
+        observed ||= generation
+
+        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.current.blocking? && Fiber.respond_to?(:scheduler)
+        return wait_with_scheduler(scheduler, observed, timeout) { yield if block_given? } if scheduler
+
+        wait_with_phaser(observed, timeout) { yield if block_given? }
+      end
+
+      private
+
+      def validate_generation(generation)
+        raise TypeError, "generation must be an Integer" unless generation.is_a?(::Integer)
+      end
+
+      def parse_timeout(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
+        timeout
+      end
+
+      def wait_with_phaser(observed, timeout)
+        current = generation
+        return current unless current == observed
+
+        deadline = Clock.now + timeout if timeout
+        registered = false
+        begin
+          Thread.handle_interrupt(INTERRUPT_MASK) do
+            @thread_waiters.increment_and_get
+            registered = true
+          end
+          loop do
+            current = generation
+            return current unless current == observed
+
+            remaining = deadline - Clock.now if deadline
+            return yield if remaining && !remaining.positive?
+
+            # Java Phaser waits do not deliver Ruby cancellation until they return.
+            # Retry bounded slices without shortening the caller's deadline.
+            interval = LeaseWaiting.wait_interval(remaining)
+            begin
+              return await_advance_interruptibly(observed, (interval * 1_000_000_000).ceil, NANOSECONDS)
+            rescue Java::JavaUtilConcurrent::TimeoutException
+              # A positive Ruby sleep delivers :on_blocking interrupts too.
+              # JRuby optimizes sleep(0) without entering a blocking region.
+              sleep 0.000001
+            end
+          end
+        ensure
+          Thread.handle_interrupt(INTERRUPT_MASK) do
+            @thread_waiters.decrement_and_get if registered
+          end
+        end
+      end
+
+      def wait_with_scheduler(scheduler, observed, timeout)
+        current = generation
+        return current unless current == observed
+
+        # The Java monitor closes the registration/commit race. Publish the
+        # registration flag under an interrupt mask so cancellation cannot
+        # leak a registration between the Java return and Ruby assignment.
+        registered = false
+        Thread.handle_interrupt(INTERRUPT_MASK) do
+          beginSchedulerWait
+          registered = true
+        end
+        deadline = Clock.now + timeout if timeout
+        reader, writer = IO.pipe
+        @fiber_waiters[writer] = true
+
+        loop do
+          current = generation
+          return current unless current == observed
+
+          remaining = deadline - Clock.now if deadline
+          return yield if remaining && !remaining.positive?
+
+          scheduler.io_wait(reader, READABLE, remaining)
+        end
+      ensure
+        Thread.handle_interrupt(INTERRUPT_MASK) do
+          @fiber_waiters.delete(writer) if writer
+          reader&.close
+          writer&.close
+        ensure
+          endSchedulerWait if registered
+        end
+      end
+    end
+  end
+end