farce 0.0.1.alpha2-x86_64-linux-gnu

data/lib/farce/engine/shared/weak_atom/base.rb

@@ -0,0 +1,189 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  # @!visibility private
+  module Internal # :nodoc: all
+    # Atom coordinates updates. The backend owns the weak slot and publishes
+    # changes, including writes whose requesting thread was interrupted.
+    class WeakAtomBase
+      TIMED_OUT = Object.new.freeze
+      private_constant :TIMED_OUT
+
+      def initialize(value = nil, compare_by_identity: false)
+        identity = BasicObject.instance_method(:equal?)
+        unless identity.bind_call(compare_by_identity, true) || identity.bind_call(compare_by_identity, false)
+          raise ArgumentError, "compare_by_identity must be a boolean"
+        end
+        validate_value(value)
+        @compare_by_identity = compare_by_identity
+        @lock                = Atom.new
+        @changes             = Atom.new(0)
+        @freeze_state        = Flag.new(false)
+        initialize_storage(value)
+      end
+
+      def value                = read_value
+      def compare_by_identity? = @compare_by_identity
+
+      def freeze
+        @freeze_state.set
+        self
+      end
+
+      def frozen? = @freeze_state.value
+
+      def value=(new_value)
+        store(new_value)
+      end
+
+      def get(timeout: nil, &fallback)
+        result = with_value(timeout) { read_value }
+        result.equal?(TIMED_OUT) ? fallback&.call : result
+      end
+
+      def store(new_value, timeout: nil, &fallback)
+        check_frozen!
+        validate_value(new_value)
+        result = with_value(timeout) do
+          check_frozen!
+          write_value(new_value)
+          new_value
+        end
+        result.equal?(TIMED_OUT) ? fallback&.call : result
+      end
+
+      def swap(new_value, timeout: nil, &fallback)
+        check_frozen!
+        validate_value(new_value)
+        result = with_value(timeout) do
+          check_frozen!
+          previous = read_value
+          write_value(new_value)
+          previous
+        end
+        result.equal?(TIMED_OUT) ? fallback&.call : result
+      end
+
+      def store_if_absent(timeout: nil)
+        raise LocalJumpError, "no block given" unless block_given?
+        check_frozen!
+        result = with_value(timeout) do
+          check_frozen!
+          current = read_value
+          next current unless current.nil?
+          replacement = yield
+          check_frozen!
+          validate_value(replacement)
+          write_value(replacement)
+          replacement
+        end
+        result.equal?(TIMED_OUT) ? nil : result
+      end
+
+      def compare_and_set(expected, replacement, timeout: nil)
+        check_frozen!
+        validate_value(expected)
+        validate_value(replacement)
+        result = with_value(timeout) do
+          matches = values_equal?(read_value, expected)
+          check_frozen!
+          next false unless matches
+          write_value(replacement)
+          true
+        end
+        !result.equal?(TIMED_OUT) && result
+      end
+
+      def update(timeout: nil)
+        raise LocalJumpError, "no block given" unless block_given?
+        check_frozen!
+        result = with_value(timeout) do
+          replacement = yield(read_value)
+          check_frozen!
+          validate_value(replacement)
+          write_value(replacement)
+          replacement
+        end
+        result.equal?(TIMED_OUT) ? nil : result
+      end
+
+      def upsert(initial, timeout: nil)
+        raise LocalJumpError, "no block given" unless block_given?
+        check_frozen!
+        validate_value(initial)
+        result = with_value(timeout) do
+          current = read_value
+          replacement = current.nil? ? initial : yield(current)
+          check_frozen!
+          validate_value(replacement)
+          write_value(replacement)
+          replacement
+        end
+        result.equal?(TIMED_OUT) ? nil : result
+      end
+
+      def wait_until_changed(expected, timeout: nil, &fallback)
+        validate_value(expected)
+        wait_for_value(expected, timeout, fallback, non_nil: false)
+      end
+
+      def wait_until_non_nil(timeout: nil, &fallback)
+        wait_for_value(nil, timeout, fallback, non_nil: true)
+      end
+
+      private
+
+      def check_frozen!
+        return unless frozen?
+
+        raise FrozenError.new("can't modify frozen #{self.class}", receiver: self)
+      end
+
+      def validate_value(_value); end
+
+      def with_value(timeout)
+        deadline = timeout_deadline(timeout)
+        result = TIMED_OUT
+        @lock.update(timeout: remaining_timeout(deadline)) do
+          result = yield
+          nil
+        end
+        result
+      end
+
+      def wait_for_value(expected, timeout, fallback, non_nil:)
+        deadline = timeout_deadline(timeout)
+        loop do
+          generation = @changes.value
+          current    = read_value
+          return current if non_nil ? !current.nil? : !values_equal?(current, expected)
+          # Detect recursive waits without waiting for another owner's update.
+          @lock.get(timeout: 0)
+          return fallback&.call if remaining_timeout(deadline)&.zero?
+          @changes.wait_until_changed(generation, timeout: remaining_timeout(deadline))
+        end
+      end
+
+      def values_equal?(left, right)
+        return left == right unless compare_by_identity?
+        BasicObject.instance_method(:equal?).bind_call(left, right)
+      end
+
+      def timeout_deadline(timeout)
+        return if timeout.nil?
+        timeout = Float(timeout)
+        raise ArgumentError, "timeout must be finite and non-negative" unless timeout.finite? && !timeout.negative?
+        Clock.now + timeout
+      end
+
+      def remaining_timeout(deadline)
+        return unless deadline
+        remaining = deadline - Clock.now
+        remaining.negative? ? 0 : remaining
+      end
+    end
+    private_constant :WeakAtomBase
+  end
+end

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

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+require "farce/engine/shared/unshared_weak_atom"
+
+module Farce
+  # @!visibility private
+  module Internal # :nodoc: all
+    class WeakAtom < UnsharedWeakAtom
+      private
+
+      def validate_value(value)
+        return if Farce::Ractor.shareable?(value)
+
+        raise Ractor::IsolationError, "value must be Ractor-shareable"
+      end
+    end
+  end
+end

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

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+require "farce/engine/shared/weak_map/reference"
+
+module Farce
+  # @!visibility private
+  module Internal # :nodoc: all
+    # The common cell holds its value directly. The index supplies key ownership.
+    # A WeakKeyMap index owns this cell and controls its collection lifetime.
+    class UnsharedWeakMapCell < UnsharedWeakMapLock
+      attr_reader :token
+
+      def initialize(key_reference)
+        super()
+        @token = Object.new
+        @key = key_reference
+        @value = nil
+        @present = @retired = false
+        @changes = nil
+      end
+
+      def lookup_key
+        @mutex.synchronize do
+          return [false, nil] if @retired
+          alive, key = @key.read
+          return [false, nil] unless alive
+          [@reserved || !@present || read_value.first, key]
+        end
+      end
+
+      def state
+        @mutex.synchronize do
+          return [:retired, false, nil] if @retired
+          return [:dead, false, nil] unless @key.read.first
+          return [:ok, false, nil] unless @present
+          alive, value = read_value
+          [alive ? :ok : :dead, alive, value]
+        end
+      end
+
+      def present? = @mutex.synchronize { @present }
+      def retired? = @mutex.synchronize { @retired }
+
+      def store(value)
+        @mutex.synchronize do
+          return false if @retired || !@key.read.first
+          write_value(value)
+          @present = true
+          @changes&.broadcast
+          true
+        end
+      end
+
+      def retire = retire_state(force: true).first
+      def retire_if_dead = retire_state(force: false)
+
+      def change_generation
+        @mutex.synchronize { (@changes ||= Signal.new).generation }
+      end
+
+      def wait_for_change?(observed, deadline)
+        timeout = deadline - Clock.now if deadline
+        return false if timeout && !timeout.positive?
+        !!@changes.wait(observed, timeout:) { false }
+      end
+
+      private
+
+      def unavailable? = @retired
+      def read_value = [true, @value]
+      def write_value(value) = @value = value
+
+      def retire_state(force:)
+        @mutex.synchronize do
+          return [false, false, nil] if @retired || (!force && @reserved)
+          alive, key = @key.read
+          return [false, false, nil] if !force && alive && (!@present || read_value.first)
+          @retired = true
+          @present = false
+          @key = @value = nil
+          @changes&.broadcast
+          @signal&.broadcast
+          [true, alive, key]
+        end
+      end
+    end
+    private_constant :UnsharedWeakMapCell
+
+    class UnsharedWeakValueMapCell < UnsharedWeakMapCell
+      private
+
+      def read_value = @value.read
+      def write_value(value) = @value = UnsharedWeakMapWeakReference.for(value)
+    end
+    private_constant :UnsharedWeakValueMapCell
+  end
+end

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

@@ -0,0 +1,249 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  # @!visibility private
+  module Internal # :nodoc: all
+    # Shared coordination for indexes. Reference ownership belongs to the
+    # concrete index and cell classes, never to flags in this class.
+    class UnsharedWeakMapIndex
+      attr_reader :change_signal
+
+      def initialize
+        @lock            = UnsharedWeakMapLock.new
+        @registry_mutex  = Mutex.new
+        @change_signal   = Signal.new
+        @sweep_cursor    = 0
+        @iteration_epoch = 0
+        @registry_holes  = 0
+        reset
+      end
+
+      def resolve(key, deadline: nil, create: false)
+        completed, result = @lock.synchronize(deadline) do
+          data = data_for(key)
+          indexed_key = index_key(key)
+          entry = data[indexed_key]
+          if entry
+            retired, = entry.retire_if_dead
+            if retired || entry.retired?
+              data.delete(indexed_key)
+              forget(entry)
+              entry = nil
+            end
+          end
+          created = false
+          if !entry && create
+            begin
+              entry = yield(key_reference(key))
+              data[indexed_key] = entry
+              register(entry)
+              created = true
+              @change_signal.broadcast
+            ensure
+              unless created
+                entry&.retire
+                entry&.release
+              end
+            end
+          end
+          [entry, created]
+        end
+        completed ? result : [nil, :timed_out]
+      end
+
+      def remove(key, entry)
+        @lock.synchronize do
+          unlink(entry, key)
+          forget(entry)
+        end
+        @change_signal.broadcast
+      end
+
+      def clear
+        _, entries = @lock.synchronize do
+          entries = snapshot
+          reset
+          entries
+        end
+        entries.each(&:retire)
+        @change_signal.broadcast
+      end
+
+      def sweep(entries)
+        stale = entries.reject { it.lookup_key.first }
+        return if stale.empty?
+        @lock.synchronize { stale.each { sweep_entry(it) } }
+      end
+
+      def sweep_one
+        entry = @registry_mutex.synchronize do
+          next if @entries.empty?
+          @sweep_cursor %= @entries.size
+          @entries[@sweep_cursor].tap { @sweep_cursor += 1 }
+        end
+        return unless entry && !entry.lookup_key.first
+        @lock.try_synchronize { sweep_entry(entry) }
+      end
+
+      def snapshot = @registry_mutex.synchronize { @entries.compact }
+
+      def live_cursor
+        @registry_mutex.synchronize do
+          [registry_enumerator, @iteration_epoch]
+        end
+      end
+
+      def next_live(cursor)
+        @registry_mutex.synchronize do
+          raise "map structurally changed during live iteration" if cursor[1] != @iteration_epoch
+          while (entry = cursor[0].next).nil?
+            # Deletion leaves a hole while an array cursor is active.
+          end
+          entry
+        end
+      end
+
+      def close_cursor(cursor)
+        cursor[0] = nil
+      end
+
+      private
+
+      def data_for(_key) = @data
+      def index_key(key) = key
+      def key_reference(key) = UnsharedWeakMapReference.new(key)
+      def registry_enumerator = @entries.to_enum(:each)
+
+      def register(entry)
+        @registry_mutex.synchronize do
+          @iteration_epoch += 1
+          @entries << entry
+        end
+      end
+
+      def forget(entry)
+        @registry_mutex.synchronize do
+          if (index = @entries.index(entry))
+            @entries[index] = nil
+            @registry_holes += 1
+            if @registry_holes > @entries.size / 4
+              # Existing cursors keep their old array. Retired cells release
+              # their keys and values, so abandoning a cursor retains no
+              # registration in the map and requires no finalizer.
+              @entries = @entries.compact
+              @registry_holes = 0
+            end
+          end
+        end
+      end
+
+      def sweep_entry(entry)
+        retired, alive, key = entry.retire_if_dead
+        return unless retired
+        unlink(entry, key) if alive
+        forget(entry)
+        @change_signal.broadcast
+      end
+
+      def unlink(entry, key)
+        data = data_for(key)
+        indexed_key = index_key(key)
+        data.delete(indexed_key) if data[indexed_key].equal?(entry)
+      end
+    end
+    private_constant :UnsharedWeakMapIndex
+
+    # WeakKeyMap is the only owner of heap-keyed cells. The enumerable registry
+    # is weak and cannot prolong a cell's lifetime. Immediate keys need a Hash.
+    # Comparison and cleanup follow the primitive. JRuby currently uses ==
+    # instead of eql?, and JVM runtimes defer stale value cleanup until access.
+    class UnsharedWeakKeyMapIndex < UnsharedWeakMapIndex
+      def snapshot = @registry_mutex.synchronize { @entries.values }
+
+      def sweep_one
+        return unless @entries.respond_to?(:sweep_one)
+        @registry_mutex.synchronize { @entries.sweep_one }
+      end
+
+      private
+
+      def reset
+        @data = ObjectSpace::WeakKeyMap.new
+        @immediate = {}
+        @registry_mutex.synchronize do
+          @entries = if Internal.const_defined?(:ConcurrentWeakRegistry, false)
+                       ConcurrentWeakRegistry.new
+                     else
+                       ObjectSpace::WeakMap.new
+                     end
+          @iteration_epoch += 1
+        end
+      end
+
+      def data_for(key) = Internal.garbage_collectable?(key) ? @data : @immediate
+      def key_reference(key) = UnsharedWeakMapWeakReference.for(key)
+      def registry_enumerator = @entries.to_enum(:each_value)
+
+      def register(entry)
+        @registry_mutex.synchronize do
+          @iteration_epoch += 1
+          @entries[entry.token] = entry
+        end
+      end
+
+      def forget(entry) = @registry_mutex.synchronize { @entries.delete(entry.token) }
+    end
+    private_constant :UnsharedWeakKeyMapIndex
+
+    # WeakMap has weak values too, so this index must retain its cells. Its
+    # strong side is reclaimed by housekeeping after an identity key disappears.
+    class UnsharedWeakIdentityMapIndex < UnsharedWeakMapIndex
+      private
+
+      def reset
+        @data = ObjectSpace::WeakMap.new
+        @registry_mutex.synchronize do
+          @entries = []
+          @registry_holes = 0
+          @iteration_epoch += 1
+        end
+      end
+
+      def key_reference(key) = UnsharedWeakMapWeakReference.for(key)
+    end
+    private_constant :UnsharedWeakIdentityMapIndex
+
+    class UnsharedStrongKeyMapIndex < UnsharedWeakMapIndex
+      private
+
+      def reset
+        @data = {}
+        @registry_mutex.synchronize do
+          @entries = []
+          @registry_holes = 0
+          @iteration_epoch += 1
+        end
+      end
+    end
+    private_constant :UnsharedStrongKeyMapIndex
+
+    class UnsharedStrongIdentityMapIndex < UnsharedStrongKeyMapIndex
+      # Ruby numeric identity can differ from a JVM object's identity.
+      class Key
+        attr_reader :value
+
+        def initialize(value) = @value = value
+        def hash = BasicObject.instance_method(:__id__).bind_call(value)
+        def eql?(other) = other.is_a?(Key) && BasicObject.instance_method(:equal?).bind_call(value, other.value)
+      end
+      private_constant :Key
+
+      private
+
+      def index_key(key) = Key.new(key)
+    end
+    private_constant :UnsharedStrongIdentityMapIndex
+  end
+end

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

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  # @!visibility private
+  module Internal # :nodoc: all
+    # A per-key reservation. User code runs without holding the state mutex.
+    # The same lock protects creation in a key index, as in Storage::ThreadSafe.
+    class UnsharedWeakMapLock
+      def initialize
+        @mutex = Mutex.new
+        @reserved = false
+        @owner_fiber = nil
+        @owner_thread = nil
+        @signal = nil
+      end
+
+      def reserve(deadline)
+        while true
+          signal, observed = @mutex.synchronize do
+            return :retired if unavailable?
+            unless @reserved
+              @reserved = true
+              @owner_fiber = Fiber.current
+              @owner_thread = Internal.storage_thread(Thread.current)
+              return :acquired
+            end
+            reject_recursive_wait!
+            @signal ||= Signal.new
+            [@signal, @signal.generation]
+          end
+          return :timed_out unless ReservationWaiting.wait(signal, observed, deadline)
+        end
+      end
+
+      def release
+        signal = @mutex.synchronize do
+          @reserved    = false
+          @owner_fiber = @owner_thread = nil
+          @signal
+        end
+        signal&.broadcast
+      end
+
+      def synchronize(deadline = nil)
+        acquired = reserve(deadline) == :acquired
+        acquired ? [true, yield] : [false, nil]
+      ensure
+        release if acquired
+      end
+
+      def try_synchronize
+        acquired = @mutex.synchronize do
+          next false if @reserved
+          @reserved     = true
+          @owner_fiber  = Fiber.current
+          @owner_thread = Internal.storage_thread(Thread.current)
+          true
+        end
+        acquired ? [true, yield] : [false, nil]
+      ensure
+        release if acquired
+      end
+
+      private
+
+      def unavailable? = false
+
+      def reject_recursive_wait!
+        raise ThreadError, "deadlock; recursive weak-map access during an update" if @owner_fiber.equal?(Fiber.current)
+        scheduler = Fiber.scheduler if Fiber.respond_to?(:scheduler)
+        return unless @owner_thread.equal?(Internal.storage_thread(Thread.current)) && !scheduler
+
+        raise ThreadError, "deadlock; weak-map update is owned by another unscheduled fiber"
+      end
+    end
+    private_constant :UnsharedWeakMapLock
+  end
+end

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

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  # @!visibility private
+  module Internal # :nodoc: all
+    class UnsharedWeakMapReference
+      def initialize(value) = @value = value
+      def read              = [true, @value]
+    end
+    private_constant :UnsharedWeakMapReference
+
+    # A weak value slot also supplies reverse key lookup for enumeration.
+    class UnsharedWeakMapWeakReference
+      def self.for(value)
+        Internal.garbage_collectable?(value) ? new(value) : UnsharedWeakMapReference.new(value)
+      end
+
+      def initialize(value)
+        @token        = Object.new
+        @data         = ObjectSpace::WeakMap.new
+        @data[@token] = value
+      end
+
+      def read
+        value = @data[@token]
+        [!value.nil?, value]
+      end
+    end
+    private_constant :UnsharedWeakMapWeakReference
+  end
+end