farce 0.0.1.alpha2-x86-linux-gnu

data/lib/farce/internal/lease_map.rb

@@ -0,0 +1,441 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  # @!visibility private
+  module Internal # :nodoc: all
+    # Portable per-key ownership and lifecycle implementation for LeaseMap.
+    class LeaseMap
+      include Freeze::Unfreezable
+
+      AUTO_LEASE_CONTEXTS = Object.new.freeze
+      private_constant :AUTO_LEASE_CONTEXTS
+
+      def initialize(initial_mapping, lease_class:, registry_class:)
+        raise TypeError, "lease map initializer must return a Hash" unless initial_mapping.is_a?(Hash)
+
+        @lease_class    = lease_class
+        @registry_lock  = Lock.new
+        @creation_locks = KeyLockMap.new(registry_class:)
+
+        initial_mapping.each_key { validate_key!(it) }
+        initial_mapping.each_value { validate_resource!(it) }
+
+        entries   = initial_mapping.to_h { |key, resource| [key, new_lease(resource)] }
+        @registry = registry_class.new(entries, compare_values_by_identity: true)
+
+        return unless @registry.ractor_shareable?
+
+        Freeze.publish(self)
+      end
+
+      def checkout(key, receiver:, missing_key: key, timeout: nil, &block)
+        lease = fetch_lease(key, receiver:, missing_key:)
+        if block
+          entered = false
+          lease.checkout(timeout:) do |resource|
+            entered = true
+            block.call(resource)
+          end
+        else
+          context = auto_context
+          context ? acquire_for_context(lease, context, timeout:) : lease.checkout(timeout:)
+        end
+      rescue RetiredLeaseError
+        raise if entered
+        prune_binding(key, lease)
+        raise_missing_key(missing_key, receiver)
+      end
+
+      def try_checkout(key, receiver:, missing_key: key, &block)
+        lease = fetch_lease(key, receiver:, missing_key:)
+        if block
+          entered = false
+          lease.try_checkout do |resource|
+            entered = true
+            block.call(resource)
+          end
+        else
+          context = auto_context
+          context ? acquire_for_context(lease, context, try: true) : lease.try_checkout
+        end
+      rescue RetiredLeaseError
+        raise if entered
+        prune_binding(key, lease)
+        raise_missing_key(missing_key, receiver)
+      end
+
+      def checkin(key, resource, receiver:, missing_key: key)
+        lease = fetch_lease(key, receiver:, missing_key:)
+
+        if nil.equal?(resource)
+          unless explicitly_owned?(lease) && !scope_managed?(lease)
+            raise OwnershipError, "the current Fiber does not own an explicit checkout"
+          end
+
+          delete_entry(key, lease)
+          return self
+        end
+
+        lease.checkin(resource)
+        self
+      end
+
+      def read_entry(key)
+        lease = current_lease(key)
+        return [false, nil] unless lease
+
+        resource = if lease.owned?
+                     owned_resource(lease)
+                   elsif (context = auto_context)
+                     acquire_for_context(lease, context)
+                   else
+                     raise RetiredLeaseError, "lease has been retired" if lease.retired?
+                     raise OwnershipError, "the current Fiber does not own the key checkout"
+                   end
+
+        [true, resource]
+      rescue RetiredLeaseError
+        prune_binding(key, lease)
+        [false, nil]
+      end
+
+      def lease_for(key, receiver:, missing_key: key) = fetch_lease(key, receiver:, missing_key:)
+
+      def store(key, resource)
+        key = validate_key!(key)
+        return delete(key) if nil.equal?(resource)
+        validate_resource!(resource)
+
+        lease = nil
+        inserted = false
+        context = auto_context
+        @creation_locks.synchronize(key) do
+          Thread.handle_interrupt(INTERRUPT_MASK) do
+            @registry_lock.synchronize do
+              lease = @registry[key]
+              if lease&.retired?
+                @registry.delete(key)
+                lease = nil
+              end
+              unless lease
+                lease = new_lease(resource)
+                @registry[key] = lease
+                acquire_for_context(lease, context) if context
+                inserted = true
+              end
+            end
+          end
+        end
+        return resource if inserted
+
+        replace(key, lease, resource)
+      rescue RetiredLeaseError
+        prune_binding(key, lease)
+        retry
+      end
+
+      def store_if_absent(key, &)
+        raise LocalJumpError, "no block given" unless block_given?
+        key = validate_key!(key)
+
+        while true
+          present, resource = read_entry(key)
+          return resource if present
+
+          context = auto_context
+          raise OwnershipError, "resource construction requires an automatic lease scope" unless context
+
+          inserted = false
+          @creation_locks.synchronize(key) do
+            next if current_lease(key)
+
+            Thread.handle_interrupt(INTERRUPT_MASK) do
+              resource = Thread.handle_interrupt(Exception => :immediate, &)
+              validate_resource!(resource)
+              @registry_lock.synchronize do
+                lease          = new_lease(resource)
+                @registry[key] = lease
+                resource       = acquire_for_context(lease, context)
+                inserted       = true
+              end
+            end
+          end
+          return resource if inserted
+        end
+      end
+
+      def delete(key)
+        lease = current_lease(key)
+        return unless lease
+
+        delete_entry(key, lease)
+      rescue RetiredLeaseError
+        prune_binding(key, lease)
+        nil
+      end
+
+      def clear
+        entries_snapshot.each do |key, lease|
+          delete_entry(key, lease)
+        rescue RetiredLeaseError
+          prune_binding(key, lease)
+        end
+        self
+      end
+
+      def auto_lease
+        raise LocalJumpError, "no block given" unless block_given?
+
+        contexts = context = nil
+        pushed = false
+        Thread.handle_interrupt(INTERRUPT_MASK) do
+          contexts = auto_contexts
+          context = {}.compare_by_identity
+          (contexts[self] ||= []) << context
+          pushed = true
+        end
+        yield
+      ensure
+        if pushed
+          Thread.handle_interrupt(INTERRUPT_MASK) do
+            cleanup_context(context)
+          ensure
+            stack = contexts[self]
+            stack.pop
+            contexts.delete(self) if stack.empty?
+          end
+        end
+      end
+
+      def available?(key)             = current_lease(key)&.available? || false
+      def checked_out?(key)           = current_lease(key)&.checked_out? || false
+      def owned?(key)                 = current_lease(key)&.owned? || false
+      def key?(key)                   = !current_lease(key).nil?
+      def size                        = entries_snapshot.size
+      def keys                        = entries_snapshot.map(&:first)
+      def compare_keys_by_identity?   = @registry.compare_keys_by_identity?
+      def compare_values_by_identity? = true
+      def getkey(key)                 = current_lease(key) && @registry.getkey(key)
+
+      def each
+        return enum_for(__method__) { size } unless block_given?
+
+        entries_snapshot.each do |key, lease|
+          next unless current_binding?(key, lease)
+
+          if lease.owned?
+            yield key, owned_resource(lease)
+          else
+            entered = false
+            begin
+              lease.checkout do |resource|
+                entered = true
+                yield key, resource
+              end
+            rescue RetiredLeaseError
+              raise if entered
+
+              prune_binding(key, lease)
+            end
+          end
+        end
+        self
+      end
+
+      def each_key
+        return enum_for(__method__) { size } unless block_given?
+
+        keys.each { yield it }
+        self
+      end
+
+      def each_value
+        return enum_for(__method__) { size } unless block_given?
+
+        each { |_key, value| yield value }
+        self
+      end
+
+      def handles = entries_snapshot
+
+      private
+
+      def new_lease(resource) = @lease_class.new { resource }
+
+      def current_lease(key)
+        @registry_lock.synchronize do
+          lease = @registry[key]
+          if lease&.retired?
+            @registry.delete(key) if @registry[key].equal?(lease)
+            lease = nil
+          end
+          lease
+        end
+      end
+
+      def fetch_lease(key, receiver:, missing_key: key)
+        current_lease(key) || raise_missing_key(missing_key, receiver)
+      end
+
+      def raise_missing_key(key, receiver)
+        raise KeyError.new("key not found: #{key.inspect}", receiver:, key:)
+      end
+
+      def replace(key, lease, resource)
+        if lease.owned?
+          replace_owned_resource(lease, resource)
+          return resource
+        end
+
+        original  = nil
+        completed = false
+        begin
+          if (context = auto_context)
+            original = acquire_for_context(lease, context)
+            replace_owned_resource(lease, resource)
+          else
+            lease.__send__(:checkout_with_handoff) { |value| original = value }
+            lease.checkin(resource)
+          end
+          completed = true
+        ensure
+          if !completed && original && lease.owned? && !lease.retired?
+            if scope_managed?(lease)
+              lease.__send__(:checkin_scope, owned_resource(lease))
+            else
+              lease.checkin(original)
+            end
+          end
+        end
+        resource
+      rescue RetiredLeaseError
+        prune_binding(key, lease)
+        raise
+      end
+
+      def delete_entry(key, lease)
+        return unless current_binding?(key, lease)
+
+        acquired = false
+        resource = nil
+        begin
+          if lease.owned?
+            resource = owned_resource(lease)
+          else
+            lease.__send__(:checkout_with_handoff) do |value|
+              resource = value
+              acquired = true
+            end
+          end
+
+          removed = Thread.handle_interrupt(INTERRUPT_MASK) do
+            @registry_lock.synchronize do
+              next false unless @registry[key].equal?(lease)
+
+              @registry.delete(key)
+              remove_auto_resource(lease)
+              lease.retire
+              true
+            end
+          end
+          return resource if removed
+        ensure
+          lease.checkin(resource) if acquired && lease.owned? && !lease.retired?
+        end
+        nil
+      end
+
+      def entries_snapshot
+        @registry_lock.synchronize do
+          entries = @registry.each_pair.to_a
+          entries.reject! do |key, lease|
+            next false unless lease.retired?
+
+            @registry.delete(key) if @registry[key].equal?(lease)
+            true
+          end
+          entries
+        end
+      end
+
+      def current_binding?(key, lease)
+        @registry_lock.synchronize { @registry[key].equal?(lease) && !lease.retired? }
+      end
+
+      def prune_binding(key, lease)
+        return unless lease
+
+        @registry_lock.synchronize { @registry.delete(key) if @registry[key].equal?(lease) && lease.retired? }
+      end
+
+      def owned_resource(lease) = lease.__send__(:owned_resource)
+
+      def replace_owned_resource(lease, resource)
+        lease.__send__(:replace_owned_resource, resource)
+      end
+
+      def auto_contexts
+        Storage.fiber.store_if_absent(AUTO_LEASE_CONTEXTS, mode: :strong) { {}.compare_by_identity }
+      end
+
+      def auto_context
+        auto_contexts[self]&.last
+      end
+
+      def acquire_for_context(lease, context, timeout: nil, try: false)
+        method  = try ? :try_checkout_with_handoff : :checkout_with_handoff
+        options = try ? {} : { timeout: }
+        already_registered = context.key?(lease)
+        lease.__send__(method, **options) do
+          lease.__send__(:mark_scope_managed)
+          register_context_resource(context, lease)
+        end
+      rescue Exception # rubocop:disable Lint/RescueException
+        context.delete(lease) if !already_registered && context.key?(lease)
+        raise
+      end
+
+      def register_context_resource(context, lease)
+        context[lease] = true
+      end
+
+      def remove_auto_resource(lease)
+        auto_contexts[self]&.each { it.delete(lease) }
+      end
+
+      def cleanup_context(context)
+        Thread.handle_interrupt(INTERRUPT_MASK) do
+          failure = nil
+          context.each_key.to_a.reverse_each do |lease|
+            next if lease.retired? || !lease.owned? || !scope_managed?(lease)
+
+            begin
+              lease.__send__(:checkin_scope, owned_resource(lease))
+            rescue Exception => e # rubocop:disable Lint/RescueException
+              failure ||= e
+            end
+          end
+          raise failure if failure
+        end
+      end
+
+      def validate_resource!(resource)
+        return unless nil.equal?(resource) || true.equal?(resource) || false.equal?(resource)
+
+        raise ArgumentError, "lease resource cannot be nil or boolean"
+      end
+
+      def validate_key!(key)
+        key = String.instance_method(:-@).bind_call(key) if String === key && !key.frozen?
+        return key if Ractor.shareable?(key)
+
+        raise Ractor::IsolationError, "key must be Ractor-shareable"
+      end
+
+      def explicitly_owned?(lease) = lease.__send__(:explicitly_owned?)
+      def scope_managed?(lease) = lease.__send__(:scope_managed?)
+    end
+  end
+end

data/lib/farce/internal/lease_pool_state.rb

@@ -0,0 +1,228 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  # @!visibility private
+  module Internal # :nodoc: all
+    # Coordinates capacity, ownership, waiting, and cleanup for a resource pool.
+    class LeasePoolState
+      OWNERSHIP = Object.new.freeze
+      private_constant :OWNERSHIP
+
+      attr_reader :max_size
+
+      def initialize(max_size)
+        @max_size    = max_size
+        @slots       = ::Farce::Counter.new
+        @managed     = Counter.new
+        @creating    = Counter.new
+        @checked_out = Counter.new
+        @available   = Queue.new(capacity: max_size)
+        @signal      = Signal.new
+        initialize_storage
+        finalize_initialization
+      end
+
+      def size              = @managed.value
+      def available_count   = @available.size
+      def checked_out_count = @checked_out.value
+      def creating_count    = @creating.value
+
+      def checkout(factory, timeout: nil, &block)
+        return checkout_block(factory, timeout, block) if block
+
+        checkout_explicit(factory, timeout:, wait: true)
+      end
+
+      def try_checkout(factory, &block)
+        return checkout_block(factory, nil, block, wait: false) if block
+
+        checkout_explicit(factory, wait: false)
+      end
+
+      def checkin(resource)
+        tokens = explicit_tokens(create: false)
+        raise OwnershipError, "the current Fiber does not own an explicit pool checkout" unless tokens&.any?
+        validate_resource!(resource) unless nil.equal?(resource)
+
+        Thread.handle_interrupt(INTERRUPT_MASK) do
+          token = tokens.last
+          if nil.equal?(resource)
+            @checked_out.decrement
+            @managed.decrement
+            @slots.decrement
+          else
+            return_resource(token, resource)
+            @available.push(token)
+            @checked_out.decrement
+          end
+          tokens.pop
+          clear_explicit_tokens if tokens.empty?
+          @signal.broadcast
+        end
+        self
+      end
+
+      private
+
+      def checkout_explicit(factory, wait:, timeout: nil)
+        acquisition = nil
+        owned       = false
+        begin
+          Thread.handle_interrupt(INTERRUPT_MASK) do
+            acquisition = acquire(factory, timeout:, wait:)
+            return unless acquisition
+
+            explicit_tokens << acquisition.first
+            owned = true
+          end
+          acquisition.last
+        rescue Exception # rubocop:disable Lint/RescueException
+          rollback_explicit(acquisition) if owned
+          raise
+        end
+      end
+
+      def checkout_block(factory, timeout, block, wait: true)
+        acquisition = nil
+        Thread.handle_interrupt(INTERRUPT_MASK) do
+          acquisition = acquire(factory, timeout:, wait:)
+          return unless acquisition
+
+          begin
+            Thread.handle_interrupt(Exception => :immediate) { return block.call(acquisition.last) }
+          ensure
+            checkin_block(acquisition)
+          end
+        end
+      end
+
+      def acquire(factory, timeout:, wait:)
+        deadline = timeout_deadline(timeout)
+
+        loop do
+          observed = @signal.generation
+          token    = @available.try_pop
+          return take_available(token) if token
+          return create_resource(factory) if reserve_creation
+          return unless wait
+
+          remaining = deadline - Clock.now if deadline
+          raise TimeoutError, "lease pool checkout timed out" if remaining && !remaining.positive?
+          interval = LeaseWaiting.wait_interval(remaining)
+          changed  = Thread.handle_interrupt(Exception => :immediate) do
+            @signal.wait(observed, timeout: interval)
+          end
+          next if changed || interval != remaining
+
+          raise TimeoutError, "lease pool checkout timed out"
+        end
+      end
+
+      def take_available(token)
+        resource = take_resource(token)
+        @checked_out.increment
+        [token, resource]
+      rescue Exception # rubocop:disable Lint/RescueException
+        @available.push(token)
+        @signal.broadcast
+        raise
+      end
+
+      def reserve_creation # rubocop:disable Naming/PredicateMethod
+        return false unless @slots.increment_if_below(max_size)
+
+        @creating.increment
+        true
+      end
+
+      def create_resource(factory)
+        committed = false
+        stored    = false
+        token     = nil
+        begin
+          resource = Thread.handle_interrupt(Exception => :immediate) { factory.call }
+          validate_resource!(resource)
+          token = next_token
+          store_resource(token, resource)
+          stored   = true
+          resource = take_resource(token)
+          stored   = false
+          @managed.increment
+          @creating.decrement
+          @checked_out.increment
+          committed = true
+          [token, resource]
+        ensure
+          unless committed
+            discard_resource(token) if stored
+            @creating.decrement
+            @slots.decrement
+            @signal.broadcast
+          end
+        end
+      end
+
+      def checkin_block(acquisition)
+        token, resource = acquisition
+        return_resource(token, resource)
+        @available.push(token)
+        @checked_out.decrement
+        @signal.broadcast
+      end
+
+      def rollback_explicit(acquisition)
+        Thread.handle_interrupt(INTERRUPT_MASK) do
+          token, resource = acquisition
+          return_resource(token, resource)
+          @available.push(token)
+          @checked_out.decrement
+          tokens = explicit_tokens
+          tokens.pop
+          clear_explicit_tokens if tokens.empty?
+          @signal.broadcast
+        end
+      end
+
+      def explicit_tokens(create: true)
+        ownership = Storage.fiber[OWNERSHIP, :strong]
+        if create
+          ownership ||= Storage.fiber.store_if_absent(OWNERSHIP, mode: :strong) { {}.compare_by_identity }
+          ownership[self] ||= []
+        else
+          ownership&.[](self)
+        end
+      end
+
+      def clear_explicit_tokens
+        Storage.fiber[OWNERSHIP, :strong]&.delete(self)
+      end
+
+      def timeout_deadline(timeout)
+        return if timeout.nil?
+
+        timeout = Float(timeout)
+        unless timeout.finite? && !timeout.negative?
+          raise ArgumentError, "timeout must be a finite, non-negative number or nil"
+        end
+        Clock.now + timeout
+      end
+
+      def next_token = Object.new.freeze
+
+      def validate_resource!(resource)
+        return unless nil.equal?(resource) || true.equal?(resource) || false.equal?(resource)
+
+        raise ArgumentError, "lease pool resource cannot be nil or boolean"
+      end
+
+      def initialize_storage      = nil
+      def finalize_initialization = nil
+      def store_resource(*)       = raise(NoMethodError, "abstract lease pool storage")
+      def take_resource(*)        = raise(NoMethodError, "abstract lease pool storage")
+      def return_resource(*)      = raise(NoMethodError, "abstract lease pool storage")
+      def discard_resource(*)     = raise(NoMethodError, "abstract lease pool storage")
+    end
+  end
+end