farce 0.0.1.alpha2-x86-linux-gnu

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

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  # @!visibility private
+  module Internal # :nodoc: all
+    class Vault
+      class Manager
+        def initialize
+          @data       = ObjectSpace::WeakKeyMap.new
+          @weak_maps  = ObjectSpace::WeakKeyMap.new
+          @weak_atoms = ObjectSpace::WeakKeyMap.new
+        end
+
+        def run = (run_once while true)
+
+        def move(key, _value, port)
+          respond(port, [true, @data.delete(key)].freeze, move: true)
+        end
+
+        def copy(key, _value, port)
+          respond(port, [true, @data[key]].freeze, move: false)
+        end
+
+        def same_value(key, value, port)
+          right, identity, right_stored = value
+          left   = @data[key]
+          right  = @data[right] if right_stored
+          result = identity ?
+            BasicObject.instance_method(:equal?).bind_call(left, right) :
+            !!(left == right) # rubocop:disable Style/DoubleNegation
+          respond(port, [true, result].freeze)
+        end
+
+        def delete(key, _value, port)
+          @data.delete(key)
+          respond(port, true)
+        end
+
+        def set(key, value, port)
+          @data[key] = value
+          respond(port, true)
+        end
+
+        def weak_atom(key, value, port)
+          command, *arguments = value
+          if command == :create
+            @weak_atoms[key] = VaultWeakAtomSlot.new(*arguments)
+            return respond(port, [true, nil].freeze)
+          end
+          slot = @weak_atoms[key]
+          raise ArgumentError, "unknown weak atom" unless slot
+          result = case command
+                   when :read then slot.value
+                   when :store then slot.store(arguments.first)
+                   else raise ArgumentError, "unknown weak-atom action: #{command.inspect}"
+                   end
+          respond(port, [true, result].freeze)
+        end
+
+        def weak_map(key, value, port)
+          command, *arguments = value
+          if command == :create
+            options = arguments.first
+            @weak_maps[key] = VaultWeakMapState.new(**options)
+            return respond(port, [true, [:ok].freeze].freeze)
+          end
+          map = @weak_maps[key]
+          raise ArgumentError, "unknown weak map" unless map
+          respond(port, [true, map.dispatch(command, *arguments)].freeze)
+        end
+
+        private
+
+        def run_once
+          request = receive_request
+          action, key, value, port = request
+          # Ractor.receive can retain its last result while waiting for another
+          # message. Clear the copied request shell before it becomes idle.
+          request.clear unless request.frozen?
+          public_send(action, key, value, port)
+        rescue StandardError => e
+          begin
+            respond_error(port, e)
+          rescue StandardError => e
+            warn "Vault error: #{e.class}: #{e.message}\n#{e.backtrace.join("\n")}"
+          end
+        end
+
+        def respond_error(port, error)
+          payload = if port.is_a?(Atom)
+                      [error.class, error.message.freeze, error.backtrace&.map(&:freeze)&.freeze].freeze
+                    else
+                      error
+                    end
+          respond(port, [false, payload].freeze)
+        rescue StandardError
+          # Preserve diagnostics when the exception or its cause cannot cross Ractors.
+          remote = ::Ractor::RemoteError.new("#{error.class}: #{error.message}")
+          remote.instance_variable_set(:@ractor, ::Ractor.current)
+          remote.set_backtrace(error.backtrace&.map { |line| String.new(line) })
+          respond(port, ::Ractor.make_shareable([false, remote].freeze))
+        end
+      end
+
+      def move_in(key, value) = execute(:set, key, value, move: true)
+      def copy_in(key, value) = execute(:set, key, value, move: false)
+      def move_out(key)       = execute(:move, key)
+      def copy_out(key)       = execute(:copy, key)
+
+      def same_value?(left, right, identity: false, right_stored: true)
+        execute(:same_value, left, [right, identity, right_stored].freeze)
+      end
+
+      def delete(key) = execute(:delete, key)
+
+      def weak_map(key, action, *) = shared_request(:weak_map, key, action, *)
+      def weak_atom(key, action, *) = shared_request(:weak_atom, key, action, *)
+
+      private
+
+      def shared_request(kind, key, action, *arguments)
+        raise ThreadError, "deadlock; recursive access from the Vault Ractor" if ::Ractor.current.equal?(@ractor)
+        raise Ractor::IsolationError, "key must be shareable" unless ::Ractor.shareable?(key)
+
+        pending = Object.new.freeze
+        reply = Atom.new(pending, compare_by_identity: true)
+        @ractor.send([kind, key, [action, *arguments].freeze, reply])
+        success, payload = reply.wait_until_changed(pending)
+        return payload if success
+
+        raise payload if payload.is_a?(Exception)
+
+        error_class, message, backtrace = payload
+        error_class = RuntimeError unless error_class.is_a?(Class) && error_class <= StandardError
+        error = error_class.allocate
+        Exception.instance_method(:initialize).bind_call(error, message)
+        error.set_backtrace(backtrace) if backtrace
+        raise error
+      end
+    end
+  end
+end

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

@@ -0,0 +1,336 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+require "farce/engine/shared/unshared_weak_map"
+
+module Farce
+  # @!visibility private
+  module Internal # :nodoc: all
+    # A map entry owned by the Vault Ractor. Its change counter is the only
+    # part used directly by callers in other Ractors.
+    class VaultWeakMapCell
+      attr_reader :token
+
+      def initialize(key_reference, weak_values:)
+        @token = Object.new
+        @key = key_reference
+        @weak_values = weak_values
+        @value = nil
+        @present = @retired = false
+        @claim = nil
+        @changes = Atom.new(0)
+      end
+
+      def read(retain_key: false)
+        return [:retired] if @retired
+        return busy if @claim
+        alive, key = @key.read
+        return [:dead] unless alive
+        unless @present
+          state = [:ok, false, nil, @changes, @changes.value]
+          state << key if retain_key
+          return state
+        end
+
+        alive, value = read_value
+        return [:dead] unless alive
+
+        state = [:ok, true, value, @changes, @changes.value]
+        state << key if retain_key
+        state
+      end
+
+      def claim(ticket)
+        current = read(retain_key: true)
+        return current unless current.first == :ok
+
+        @claim = ticket
+        current[0] = :claimed
+        current.freeze
+      end
+
+      def finish(ticket, action, value = nil)
+        return [:stale] unless @claim.equal?(ticket)
+
+        remove = false
+        if action == :store && @key.read.first
+          write_value(value)
+          @present = true
+        elsif action == :delete || (action == :abort && !@present)
+          remove = true
+          retire
+        end
+        @claim = nil
+        changed unless @retired
+        [remove ? :remove : :ok, @changes, @changes.value].freeze
+      end
+
+      def store(value)
+        return if @retired || @claim || !@key.read.first
+
+        write_value(value)
+        @present = true
+        changed
+      end
+
+      def delete
+        state = read
+        return state if state.first == :busy
+        return [:missing] unless state.first == :ok && state[1]
+
+        value = state[2]
+        retire
+        [:ok, value].freeze
+      end
+
+      def lookup_key
+        return [false, nil] if @retired
+        alive, key = @key.read
+        return [false, nil] unless alive
+        return [true, key] if @claim || !@present
+
+        [read_value.first, key]
+      end
+
+      def retired? = @retired
+      def release; end
+
+      def retire
+        return if @retired
+
+        @retired = true
+        @present = false
+        @claim = @key = @value = nil
+        changed
+      end
+
+      def retire_if_dead
+        return [false, false, nil] if @retired || @claim
+
+        alive, key = @key.read
+        return [false, false, nil] if alive && (!@present || read_value.first)
+
+        retire
+        [true, alive, key]
+      end
+
+      private
+
+      def busy = [:busy, @changes, @changes.value].freeze
+
+      def changed = @changes.update { |generation| generation + 1 }
+
+      def read_value
+        return [true, @value] unless @weak_values
+        @value.read
+      end
+
+      def write_value(value)
+        @value = @weak_values ? UnsharedWeakMapWeakReference.for(value) : value
+      end
+    end
+    private_constant :VaultWeakMapCell
+
+    # Owner-side state for one fallback weak map. It does not retain the token
+    # used by the Vault registry.
+    class VaultWeakMapState
+      def initialize(weak_keys:, weak_values:, compare_keys_by_identity:)
+        @weak_values  = weak_values
+        @changes      = Atom.new(0)
+        @claims       = {}.compare_by_identity
+        @live_cursors = {}.compare_by_identity
+        index_class   =
+          if weak_keys
+            compare_keys_by_identity ? UnsharedWeakIdentityMapIndex : UnsharedWeakKeyMapIndex
+          else
+            compare_keys_by_identity ? UnsharedStrongIdentityMapIndex : UnsharedStrongKeyMapIndex
+          end
+        @index = index_class.new
+      end
+
+      def dispatch(action, *arguments)
+        case action
+        when :read         then read(arguments.first, retain_key: false)
+        when :wait_read    then read(arguments.first, retain_key: true)
+        when :getkey       then getkey(arguments.first)
+        when :claim        then claim(*arguments)
+        when :finish       then finish(*arguments)
+        when :store        then store(*arguments)
+        when :delete       then delete(arguments.first)
+        when :size         then size
+        when :snapshot     then snapshot
+        when :open_cursor  then open_cursor
+        when :next_live    then next_live(arguments.first)
+        when :close_cursor then close_cursor(arguments.first)
+        when :clear        then clear
+        else raise ArgumentError, "unknown weak-map action: #{action.inspect}"
+        end
+      end
+
+      private
+
+      def read(key, retain_key:)
+        with_entry(key) do |entry|
+          next missing unless entry
+
+          entry.read(retain_key:)
+        end
+      end
+
+      def getkey(key)
+        with_entry(key) do |entry|
+          next missing unless entry
+
+          state = entry.read
+          next state unless state.first == :ok && state[1]
+
+          alive, stored_key = entry.lookup_key
+          alive ? [:ok, stored_key].freeze : [:dead]
+        end
+      end
+
+      def claim(key, ticket, create)
+        with_entry(key, create:) do |entry|
+          next missing unless entry
+
+          result = entry.claim(ticket)
+          next result unless result.first == :claimed
+
+          # Retain the canonical key through the callback without placing it in
+          # the reply, which can outlive a completed operation.
+          @claims[ticket] = [entry, result[5]]
+          result.first(5).freeze
+        end
+      end
+
+      def finish(_key, ticket, action, value = nil)
+        claim = @claims.delete(ticket)
+        return [:stale].freeze unless claim
+
+        entry, key = claim
+        result = entry.finish(ticket, action, value)
+        remove(key, entry) if result.first == :remove
+        result
+      end
+
+      def store(key, value, swap)
+        with_entry(key, create: true) do |entry|
+          state = entry.read
+          next state if state.first == :busy
+
+          present, current = state[1], state[2]
+          entry.store(value)
+          [:ok, swap && present ? current : nil].freeze
+        end
+      end
+
+      def delete(key)
+        with_entry(key) do |entry|
+          next [:missing] unless entry
+
+          result = entry.delete
+          remove(key, entry) if result.first == :ok
+          result
+        end
+      end
+
+      # Count in the owner Ractor so size replies do not keep weak entries alive.
+      def size
+        entries = @index.snapshot
+        count = 0
+        entries.each do |entry|
+          state = entry.read
+          return state if state.first == :busy
+          count += 1 if state.first == :ok && state[1]
+        end
+        @index.sweep(entries)
+        [:ok, count].freeze
+      end
+
+      def open_cursor
+        token = Object.new.freeze
+        @live_cursors[token] = [@index.live_cursor, nil]
+        [:ok, token].freeze
+      end
+
+      def next_live(token)
+        cursor = @live_cursors.fetch(token)
+        while true
+          begin
+            entry = cursor[1] ||= @index.next_live(cursor[0])
+          rescue StopIteration
+            return [:done].freeze
+          end
+          state = entry.read
+          return state if state.first == :busy
+          cursor[1] = nil
+          next unless state.first == :ok && state[1]
+          alive, key = entry.lookup_key
+          return [:ok, key, state[2]].freeze if alive
+        end
+      end
+
+      def close_cursor(token)
+        cursor = @live_cursors.delete(token)
+        @index.close_cursor(cursor[0]) if cursor
+        [:ok].freeze
+      end
+
+      def snapshot
+        entries = @index.snapshot
+        pairs = []
+        entries.each do |entry|
+          state = entry.read
+          return state if state.first == :busy
+          next unless state.first == :ok && state[1]
+
+          alive, key = entry.lookup_key
+          pairs << [key, state[2]].freeze if alive
+        end
+        @index.sweep(entries)
+        [:ok, pairs.freeze].freeze
+      end
+
+      def clear
+        @claims.clear
+        @index.clear
+        changed
+        [:ok].freeze
+      end
+
+      def with_entry(key, create: false)
+        @index.sweep_one
+        loop do
+          entry, created = @index.resolve(key, create:) do |key_reference|
+            VaultWeakMapCell.new(key_reference, weak_values: @weak_values)
+          end
+          return yield(nil) unless entry
+          changed if created
+
+          state = yield(entry)
+          if state.first == :dead || state.first == :retired
+            entry.retire
+            remove(key, entry)
+            next
+          end
+          if created && state.first != :claimed && !entry.read.fetch(1, false)
+            remove(key, entry)
+            entry.retire
+          end
+          return state
+        end
+      end
+
+      def missing = [:missing, @changes, @changes.value].freeze
+
+      def remove(key, entry)
+        @index.remove(key, entry)
+        changed
+      end
+
+      def changed = @changes.update { |generation| generation + 1 }
+    end
+    private_constant :VaultWeakMapState
+  end
+end

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

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+require "farce/engine/shared/weak_atom/base"
+require "farce/engine/shared/weak_map/reference"
+
+module Farce
+  # @!visibility private
+  module Internal # :nodoc: all
+    # Only the Vault accesses this slot. Publishing belongs here so interrupted
+    # callers cannot leave a committed value without notifying its observers.
+    class VaultWeakAtomSlot
+      def initialize(value, changes, freeze_state)
+        @reference = UnsharedWeakMapWeakReference.for(value)
+        @changes = changes
+        @freeze_state = freeze_state
+      end
+
+      def value = @reference.read.last
+
+      def store(value)
+        raise FrozenError, "can't modify frozen weak atom" if @freeze_state.value
+
+        @reference = UnsharedWeakMapWeakReference.for(value)
+        @changes.update { |generation| generation + 1 }
+        nil
+      end
+    end
+    private_constant :VaultWeakAtomSlot
+
+    class WeakAtom < WeakAtomBase
+      OWNER = Atom.new
+      private_constant :OWNER
+
+      private
+
+      def initialize_storage(value)
+        @token = Object.new.freeze
+        @vault = OWNER.store_if_absent { Vault.new }
+        @vault.weak_atom(@token, :create, value, @changes, @freeze_state)
+        Internal::Freeze.publish(self)
+      end
+
+      def validate_value(value)
+        return if ::Ractor.shareable?(value)
+        raise Ractor::IsolationError, "value must be Ractor-shareable"
+      end
+
+      def read_value = @vault.weak_atom(@token, :read)
+      def write_value(value) = @vault.weak_atom(@token, :store, value)
+    end
+  end
+end