farce 0.0.1.alpha2-x86_64-linux-gnu

data/lib/farce/internal/marshal_support.rb

@@ -0,0 +1,227 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Internal # :nodoc: all
+    # Portable snapshots of public values. Backing stores never enter the stream.
+    module MarshalSupport
+      extend self
+
+      def protocol_method?(name) = %i[marshal_dump marshal_load _dump _load _dump_data _load_data].include?(name)
+
+      # A version belongs to the public snapshot, not to a backend layout.
+      def payload(data, length)
+        unless data.is_a?(Array) && data.length == length + 1 && data.first == 1
+          raise TypeError, "invalid Farce Marshal snapshot"
+        end
+        data.drop(1)
+      end
+
+      def value(value) = [Internal.marshal_shareable?(value), Kernel.instance_method(:frozen?).bind_call(value), value]
+
+      def restore_value(data)
+        shareable, frozen, value = data
+        if shareable && Shareable === value && !(Shareable::Native === value) &&
+            !Kernel.instance_method(:frozen?).bind_call(value) &&
+            value.respond_to?(:marshal_load, true) && value.method(:marshal_load).owner.name&.start_with?("Farce::")
+          raise TypeError, "recursive shareable snapshots require an initialized value"
+        end
+        value = Ractor.make_shareable(value) if shareable
+        Kernel.instance_method(:freeze).bind_call(value) if frozen
+        value
+      end
+
+      def freeze(object, frozen)
+        return object unless frozen
+        object.freeze
+      end
+
+      module Initialize
+        private
+
+        # @api private
+        def marshal_initialize(arguments, options, _configuration = nil)
+          initialize(*arguments, **options)
+        end
+
+        # @api private
+        def marshal_configuration = nil
+
+        # A restored manager must retain its links to already-loaded envelopes.
+        # @api private
+        def marshal_mode_manager(mode) = @manager || ModeManager.new(mode:)
+
+        def publish_marshaled
+          if is_a?(Shareable)
+            publish_shareable
+          elsif is_a?(Unshareable)
+            pin_unshareable
+          end
+        end
+      end
+
+      module Counter
+        include Initialize
+
+        # @api private
+        def marshal_dump
+          options = respond_to?(:scope) ? { scope: } : {}
+          [1, initial, value, options, marshal_configuration, frozen?]
+        end
+
+        # @api private
+        def marshal_load(data)
+          initial, current, options, configuration, frozen = MarshalSupport.payload(data, 5)
+          marshal_initialize([initial], options, configuration)
+          store(current)
+          MarshalSupport.freeze(self, frozen)
+        end
+      end
+
+      module Flag
+        include Initialize
+
+        # @api private
+        def marshal_dump
+          options = respond_to?(:scope) ? { scope: } : {}
+          [1, value, options, marshal_configuration, frozen?]
+        end
+
+        # @api private
+        def marshal_load(data)
+          current, options, configuration, frozen = MarshalSupport.payload(data, 4)
+          marshal_initialize([current], options, configuration)
+          MarshalSupport.freeze(self, frozen)
+        end
+      end
+
+      module Atom
+        include Initialize
+
+        # @api private
+        def marshal_dump
+          options = { compare_by_identity: compare_by_identity? }
+          options[:mode] = mode if respond_to?(:mode)
+          options[:scope] = scope if respond_to?(:scope)
+          [1, MarshalSupport.value(value), options, marshal_configuration, frozen?]
+        end
+
+        # @api private
+        def marshal_load(data)
+          current, options, configuration, frozen = MarshalSupport.payload(data, 4)
+          marshal_initialize([nil], options, configuration)
+          store(MarshalSupport.restore_value(current))
+          MarshalSupport.freeze(self, frozen)
+        end
+      end
+
+      module Vector
+        include Initialize
+
+        # @api private
+        def marshal_dump
+          options = { compare_by_identity: compare_by_identity? }
+          options[:scope] = scope if respond_to?(:scope)
+          [1, internal_vector.snapshot.map { MarshalSupport.value(it) }, options, marshal_configuration, frozen?]
+        end
+
+        # @api private
+        def marshal_load(data)
+          entries, options, configuration, frozen = MarshalSupport.payload(data, 4)
+          marshal_initialize([[]], options, configuration)
+          entries.each { internal_vector.push(MarshalSupport.restore_value(it)) }
+          MarshalSupport.freeze(self, frozen)
+        end
+      end
+
+      module Map
+        include Initialize
+
+        # @api private
+        def marshal_dump
+          options = {}
+          unless is_a?(Abstract::TreeMap)
+            options[:compare_keys_by_identity] = compare_keys_by_identity?
+            options[:compare_values_by_identity] = compare_values_by_identity?
+          end
+          options[:mode] = mode if respond_to?(:mode)
+          options[:manager] = @manager if defined?(@manager) && !@manager.is_a?(WeakModeManager)
+          options[:scope] = scope if respond_to?(:scope)
+          options[:max_size] = max_size if respond_to?(:max_size)
+          options[:normalize_keys] = KeyNormalizer.dump(@key_normalizer) if @key_normalizer
+          entries = marshal_entries.map do |key, stored|
+            [MarshalSupport.value(key), marshal_map_value(stored)]
+          end
+          [1, entries, options, marshal_configuration, frozen?]
+        end
+
+        # @api private
+        def marshal_load(data)
+          entries, options, configuration, frozen = MarshalSupport.payload(data, 4)
+          @manager = options.delete(:manager) if options.key?(:manager)
+          options[:normalize_keys] = KeyNormalizer.restore(options[:normalize_keys]) if options.key?(:normalize_keys)
+          marshal_initialize([nil], options, configuration)
+          map = marshal_map
+          entries.each do |key, stored|
+            map[MarshalSupport.restore_value(key)] = marshal_restore_map_value(stored)
+          end
+          MarshalSupport.freeze(self, frozen)
+        end
+
+        private
+
+        # @api private
+        def marshal_entries = marshal_map.each
+
+        # @api private
+        def marshal_map
+          map = internal_map
+          KeyNormalizer::ConcurrentMap === map ? map.transaction_source : map
+        end
+
+        # @api private
+        def marshal_map_value(value)
+          MarshalSupport.value(value)
+        end
+
+        # @api private
+        def marshal_restore_map_value(data)
+          MarshalSupport.restore_value(data)
+        end
+      end
+
+      module Reject
+        # @api private
+        def marshal_dump = raise(TypeError, "#{self.class} cannot be marshaled")
+      end
+
+      module WeakValue
+        # @api private
+        def marshal_dump
+          state, current = state_and_value
+          raise TypeError, "moved weak values cannot be marshaled" if state == :moved
+          [1, MarshalSupport.value(current), frozen?]
+        end
+
+        # @api private
+        def marshal_load(data)
+          current, frozen = MarshalSupport.payload(data, 2)
+          initialize(MarshalSupport.restore_value(current))
+          freeze if frozen
+        end
+      end
+
+      module WeakRef
+        # @api private
+        def marshal_dump = [1, @value]
+
+        # @api private
+        def marshal_load(data)
+          @value, = MarshalSupport.payload(data, 1)
+          Kernel.instance_method(:freeze).bind_call(self)
+        end
+      end
+    end
+  end
+end

data/lib/farce/internal/mixin.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  # @!visibility private
+  module Internal # :nodoc: all
+    # When including Farce in a class or module, this module is included instead
+    # This avoids pulling in private constants, like {Farce::Internal} or `UNDEFINED`.
+    module Mixin
+      # This will trigger all autoloads, but any other approach would be complex and fragile.
+      Farce.constants(false).each { const_set(it, Farce.const_get(it)) unless it =~ /\A[A-Z_]+\Z|\ATest/ }
+
+      def self.included(base)
+        return unless base.const_defined?(:Ractor, false) && ractor = base.const_get(:Ractor, false)
+        ractor.const_set(:Port, Farce::Port) unless ractor.const_defined?(:Port, false)
+      end
+    end
+  end
+end

data/lib/farce/internal/mutable_ordered_key_lock_map.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  # @!visibility private
+  module Internal # :nodoc: all
+    # Coordinate mutable keys by ordering within one Ractor.
+    # SortedSet uses this for backing trees whose keys cannot be published.
+    class MutableOrderedKeyLockMap
+      Gate = Struct.new(:lock, :participants)
+      private_constant :Gate
+
+      def initialize
+        @guard        = Farce::Lock.new
+        @entries      = MutableTreeMap.new
+        @participants = 0
+      end
+
+      def synchronize(key, &)
+        raise LocalJumpError, "no block given" unless block_given?
+
+        gate = nil
+        registered = false
+        begin
+          Thread.handle_interrupt(INTERRUPT_MASK) do
+            @guard.synchronize do
+              gate = @entries[key]
+              unless gate
+                gate = Gate.new(KeyLockMap.new(registry_class: Farce::Strict::Map), 0)
+                @entries[key] = gate
+              end
+              gate.participants += 1
+              @participants += 1
+              registered = true
+            end
+          end
+          gate.lock.synchronize(:operation, &)
+        ensure
+          release(key, gate) if registered
+        end
+      end
+
+      def transaction_snapshot = PortableTransaction::ReservationEntry.new(self)
+
+      private
+
+      def release(key, gate)
+        Thread.handle_interrupt(INTERRUPT_MASK) do
+          @guard.synchronize do
+            gate.participants -= 1
+            @participants -= 1
+            if @participants.zero?
+              @entries.clear
+            elsif gate.participants.zero?
+              @entries.delete(key)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/farce/internal/noncopyable.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Internal
+    # Coordination objects own live state that cannot be duplicated.
+    module Noncopyable
+      include MarshalSupport::Reject
+
+      def dup         = initialize_copy(self)
+      def clone(...)  = initialize_copy(self)
+
+      private def initialize_copy(_other) = raise(TypeError, "#{self.class} cannot be copied")
+    end
+  end
+end

data/lib/farce/internal/ordered_key_lock_map.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  # @!visibility private
+  module Internal # :nodoc: all
+    # Coordinate keys using their ordering, independently of their hash values.
+    class OrderedKeyLockMap
+      include Shareable::Unfreezable
+
+      Gate = Data.define(:lock, :participants)
+      private_constant :Gate
+
+      def initialize
+        @guard        = Farce::Lock.new
+        @entries      = ShareableTreeMap.new
+        @participants = Counter.new(0)
+        super
+      end
+
+      def synchronize(key, &)
+        raise LocalJumpError, "no block given" unless block_given?
+
+        gate       = nil
+        registered = false
+
+        begin
+          Thread.handle_interrupt(INTERRUPT_MASK) do
+            @guard.synchronize do
+              gate = @entries[key]
+              unless gate
+                gate = Gate.new(KeyLockMap.new(registry_class: Farce::Strict::Map), Counter.new(0))
+                Ractor.make_shareable(gate) if Internal.native_ractors?
+                @entries[key] = gate
+              end
+              gate.participants.add(1)
+              @participants.add(1)
+              registered = true
+            end
+          end
+          gate.lock.synchronize(:operation, &)
+        ensure
+          release(key, gate) if registered
+        end
+      end
+
+      def transaction_snapshot = PortableTransaction::ReservationEntry.new(self)
+
+      private
+
+      def release(key, gate)
+        Thread.handle_interrupt(INTERRUPT_MASK) do
+          @guard.synchronize do
+            remaining = gate.participants.add(-1)
+            total = @participants.add(-1)
+            # Clearing needs no comparisons. It also reclaims idle records left
+            # behind when a comparator raised during an earlier cleanup.
+            if total.zero?
+              @entries.clear
+            elsif remaining.zero?
+              @entries.delete(key)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/farce/internal/pool_supervisor.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Internal # :nodoc: all
+    # Runs delayed pool control work outside application Ractors.
+    class PoolSupervisorService
+      include Shareable::Unfreezable
+
+      STOP = :stop
+      private_constant :STOP
+
+      def initialize
+        @queue  = TimerQueue.new(mode: :raise)
+        @closed = Atom.new(false)
+        @worker = Ractor.new(@queue, name: "farce-pool-supervisor") do |queue|
+          while (entry = queue.pop) != STOP
+            pool, token = entry
+            pool.scale_if_needed(token)
+          end
+        end
+        super
+      end
+
+      def schedule(pool, token, delay)
+        raise ::Farce::ClosedQueueError, "pool supervisor is closed" if @closed.value
+        @queue.push([pool, token].freeze, delay:)
+      end
+
+      def close
+        return unless @closed.compare_and_set(false, true)
+        @queue.push(STOP, clock: 0)
+        @worker.respond_to?(:join) ? @worker.join : @worker.take
+      end
+    end
+
+    PoolSupervisor = PoolSupervisorService.new
+    at_exit { PoolSupervisor.close }
+  end
+end

data/lib/farce/internal/pool_worker.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Internal # :nodoc: all
+    # Coordinates one scheduler with its pool.
+    class PoolWorker
+      include Shareable::Unfreezable
+
+      def initialize(pool)
+        @pool       = pool
+        @inflight   = Counter.new if pool.max_inflight || pool.shrink_after
+        @pressure   = pool.min_size < pool.max_size
+        @registered = Atom.new(true)
+        super()
+      end
+
+      def idle_timeout = @pool.shrink_after
+
+      def wait_for_admission(scheduler, runnable_count)
+        return false if @pool.drained?
+        limit = @pool.max_inflight
+        return true unless limit
+
+        loop do
+          return false if @pool.drained?
+          return true if @pool.closing? || @pool.at_max_size? || @inflight.value < limit
+          return true if runnable_count && scheduler.public_send(runnable_count).zero?
+
+          generation = @pool.admission_generation
+          next if @pool.closing? || @pool.at_max_size? || @inflight.value < limit
+          @pool.wait_for_admission(generation)
+        end
+      end
+
+      def task_started
+        @inflight&.increment
+        @pool.task_taken if @pressure
+      end
+
+      def task_finished
+        return unless @inflight
+        @inflight.decrement
+        @pool.admission_changed if @pool.max_inflight && !@pool.at_max_size?
+      end
+
+      def retire?
+        return false unless @inflight&.value&.zero?
+        return false unless @pool.retire_worker
+        @registered.compare_and_set(true, false)
+      end
+
+      def stopped(error, replace: true) # rubocop:disable Naming/PredicateMethod
+        return false unless @registered.compare_and_set(true, false)
+        @pool.worker_stopped(error, replace:)
+        true
+      end
+    end
+  end
+end

data/lib/farce/internal/portable_transaction/reservation_entry.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Internal # :nodoc: all
+    module PortableTransaction
+      # Stop new ordered-key reservations and reject initializers already active.
+      # Ordinary TreeMap operations already use this guard and participant count.
+      class ReservationEntry < Entry
+        def initialize(source) # rubocop:disable Lint/MissingSuper
+          @source = source
+          @locks = [source.instance_variable_get(:@guard)]
+        end
+
+        def prepare = nil
+        def apply   = nil
+        def restore = nil
+        def notify  = nil
+
+        def valid?
+          participants = @source.instance_variable_get(:@participants)
+          participants = participants.value unless Integer === participants
+          participants.zero?
+        end
+      end
+    end
+  end
+end

data/lib/farce/internal/portable_transaction/strong_map_entry.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Internal # :nodoc: all
+    module PortableTransaction
+      # Keep the index identity so operations already resolving a key retry
+      # against the installed entries. Retiring old cells invalidates queued
+      # operations without adding checks to ordinary map methods.
+      class StrongMapEntry < Entry
+        FIELDS = %i[@data @entries @registry_holes @sweep_cursor @iteration_epoch].freeze
+        CELL_FIELDS = %i[@retired @present @key @value].freeze
+
+        def self.pairs(index)
+          with_cells(index) do |cells|
+            cells.filter_map do |cell|
+              next if cell.instance_variable_get(:@retired) || !cell.instance_variable_get(:@present)
+              alive, key = cell.instance_variable_get(:@key).read
+              [key, cell.instance_variable_get(:@value)] if alive
+            end
+          end
+        end
+
+        def self.size(index)
+          with_cells(index) do |cells|
+            cells.count { !it.instance_variable_get(:@retired) && it.instance_variable_get(:@present) }
+          end
+        end
+
+        # Read the current registry and cells together, so a concurrent commit
+        # cannot retire cells between enumeration and reading their contents.
+        def self.with_cells(index)
+          loop do
+            cells = index.snapshot
+            registry = index.instance_variable_get(:@registry_mutex)
+            locks = [registry, *cells.map { it.instance_variable_get(:@mutex) }].sort_by(&:object_id)
+            acquired = []
+            Thread.handle_interrupt(INTERRUPT_MASK) do
+              locked = locks.all? do |lock|
+                lock.try_lock && acquired.push(lock)
+              end
+              if locked
+                current = index.instance_variable_get(:@entries).compact
+                if current.size == cells.size &&
+                    current.each_index.all? { PortableTransaction.same?(current[it], cells[it]) }
+                  return yield(cells)
+                end
+              end
+            ensure
+              acquired.reverse_each(&:unlock)
+            end
+            if Fiber.respond_to?(:scheduler) && Fiber.scheduler
+              Fiber.scheduler.kernel_sleep(0)
+            else
+              Thread.pass
+            end
+          end
+        end
+        private_class_method :with_cells
+
+        # This entry coordinates index and cell locks rather than a single storage field.
+        def initialize(source, working, _kind, baseline) # rubocop:disable Lint/MissingSuper
+          @source, @working, @baseline = source, working, baseline
+          @dirty = @applied = false
+          @index = source.instance_variable_get(:@index)
+          @index_lock = @index.instance_variable_get(:@lock)
+        end
+
+        def prepare
+          capture_cells
+          replacement = @working.instance_variable_get(:@index)
+          @replacement = FIELDS.map { replacement.instance_variable_get(it) }
+        end
+
+        def valid?
+          return false if @dirty && @source.frozen?
+          return false if @index_lock.instance_variable_get(:@reserved)
+          current = @index.instance_variable_get(:@entries).compact
+          return false unless current.size == @cells.size &&
+            current.each_index.all? { PortableTransaction.same?(current[it], @cells[it]) }
+          return false unless @cells.size == @baseline.size
+          return false unless @cells.all? do |cell|
+            next false if cell.instance_variable_get(:@reserved) || cell.instance_variable_get(:@retired)
+            next false unless cell.instance_variable_get(:@present)
+            alive, key = cell.instance_variable_get(:@key).read
+            alive && @baseline.key?(key) &&
+              PortableTransaction.same?(@baseline[key], cell.instance_variable_get(:@value))
+          end
+          @original = FIELDS.map { @index.instance_variable_get(it) }
+          @original_cells = @cells.map { |cell| CELL_FIELDS.map { cell.instance_variable_get(it) } }
+          @replacement[-1] = @original[-1] + 1
+          true
+        end
+
+        def apply
+          return unless @dirty
+          @applied = true
+          FIELDS.each_with_index { |field, index| @index.instance_variable_set(field, @replacement[index]) }
+          @cells.each do |cell|
+            cell.instance_variable_set(:@retired, true)
+            cell.instance_variable_set(:@present, false)
+            cell.instance_variable_set(:@key, nil)
+            cell.instance_variable_set(:@value, nil)
+          end
+        end
+
+        def restore
+          return unless @applied
+          FIELDS.each_with_index { |field, index| @index.instance_variable_set(field, @original[index]) }
+          @cells.each_with_index do |cell, index|
+            CELL_FIELDS.each_with_index do |field, offset|
+              cell.instance_variable_set(field, @original_cells[index][offset])
+            end
+          end
+        end
+
+        def notify
+          return unless @dirty
+          @index.change_signal.broadcast
+          @cells.each do |cell|
+            cell.instance_variable_get(:@changes)&.broadcast
+            cell.instance_variable_get(:@signal)&.broadcast
+          end
+        end
+
+        private
+
+        def capture_cells
+          @cells = @index.snapshot
+          @locks = [@index_lock.instance_variable_get(:@mutex), @index.instance_variable_get(:@registry_mutex)]
+          @locks.concat(@cells.map { it.instance_variable_get(:@mutex) })
+        end
+      end
+    end
+  end
+end