farce 0 → 0.1.0

data/lib/farce/internal/lease_state.rb

@@ -0,0 +1,342 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  # @!visibility private
+  module Internal # :nodoc: all
+    # Coordinates ownership and lifecycle for one leased resource.
+    class LeaseState
+      OWNED_RESOURCES         = Object.new.freeze
+      SCOPE_MANAGED_RESOURCES = Object.new.freeze
+      AVAILABLE               = :available
+      EXPLICIT                = :explicit
+      BLOCK                   = :block
+      RETIRED                 = :retired
+      private_constant :OWNED_RESOURCES, :SCOPE_MANAGED_RESOURCES,
+        :AVAILABLE, :EXPLICIT, :BLOCK, :RETIRED
+
+      def initialize(resource)
+        validate_resource!(resource)
+        initialize_state
+        initialize_resource(resource)
+      end
+
+      def available?        = state == AVAILABLE && !@lock.locked?
+      def checked_out?      = !retired? && @lock.locked?
+      def owned?            = !retired? && @lock.owned?
+      def retired?          = state == RETIRED
+      def explicitly_owned? = owned? && state == EXPLICIT
+
+      # Return the resource held by the current Fiber.
+      # @raise [Farce::OwnershipError] unless the current Fiber owns the checkout
+      def owned_resource
+        raise OwnershipError, "the current Fiber does not own the checkout" unless @lock.owned?
+
+        owned_resources.fetch(self)
+      end
+
+      # Replace the resource held by an explicit checkout without ending it.
+      # @raise [Farce::OwnershipError] unless the current Fiber owns an explicit checkout
+      def replace_owned_resource(resource)
+        unless @lock.owned? && state == EXPLICIT
+          raise OwnershipError, "the current Fiber does not own an explicit checkout"
+        end
+
+        validate_resource!(resource)
+        owned_resources[self] = resource
+        self
+      end
+
+      # Acquire explicitly and complete a caller-provided ownership handoff before interrupts resume.
+      def checkout_with_handoff(timeout: nil)
+        resource = nil
+        begin
+          Thread.handle_interrupt(INTERRUPT_MASK) do
+            resource = wait_for_resource(timeout, EXPLICIT)
+            yield resource
+          end
+        rescue Exception # rubocop:disable Lint/RescueException
+          rollback_acquisition(resource) if resource && @lock.owned? && state == EXPLICIT
+          raise
+        end
+        resource
+      end
+
+      # Attempt an explicit checkout and complete an ownership handoff before interrupts resume.
+      def try_checkout_with_handoff
+        resource = nil
+        begin
+          Thread.handle_interrupt(INTERRUPT_MASK) do
+            resource = try_acquire(EXPLICIT)
+            yield resource if resource
+          end
+        rescue Exception # rubocop:disable Lint/RescueException
+          rollback_acquisition(resource) if resource && @lock.owned? && state == EXPLICIT
+          raise
+        end
+        resource
+      end
+
+      # Mark an explicit checkout as owned by an automatic cleanup scope.
+      def mark_scope_managed
+        unless @lock.owned? && state == EXPLICIT
+          raise OwnershipError, "the current Fiber does not own an explicit checkout"
+        end
+
+        scope_managed_resources[self] = true
+        self
+      end
+
+      def scope_managed? = Storage.fiber[SCOPE_MANAGED_RESOURCES, :strong]&.key?(self) || false
+
+      # Return a checkout through its automatic cleanup scope.
+      def checkin_scope(resource)
+        checkin_resource(resource, scope: true)
+      end
+
+      def checkout(timeout: nil, &block)
+        return wait_for_block(timeout, block) if block
+
+        explicit_checkout { wait_for_resource(timeout, EXPLICIT) }
+      end
+
+      def try_checkout(&block)
+        if block
+          outcome = try_acquire_block(block)
+          return outcome.first if outcome
+          return
+        end
+
+        explicit_checkout { try_acquire(EXPLICIT) }
+      end
+
+      def checkin(resource)
+        checkin_resource(resource, scope: false)
+      end
+
+      def checkin_resource(resource, scope:)
+        raise RetiredLeaseError, "lease has been retired" if retired?
+        unless @lock.owned? && state == EXPLICIT
+          raise OwnershipError, "the current Fiber does not own an explicit checkout"
+        end
+        raise OwnershipError, "the checkout belongs to an automatic lease scope" if scope_managed? && !scope
+
+        validate_resource!(resource)
+        Thread.handle_interrupt(INTERRUPT_MASK) do
+          return_resource(resource)
+          unregister_owned_resource
+          release
+        end
+        self
+      end
+
+      def retire
+        return self if retired?
+        raise OwnershipError, "the current Fiber does not own the checkout" unless @lock.owned?
+
+        Thread.handle_interrupt(INTERRUPT_MASK) do
+          @state.store(RETIRED)
+          unregister_owned_resource
+          @owner_thread_id.store(0)
+          @lock.unlock
+          @signal.broadcast
+        end
+        self
+      end
+
+      private
+
+      def wait_for_resource(timeout, kind)
+        deadline = timeout_deadline(timeout)
+        resource = nil
+
+        loop do
+          observed = @signal.generation
+          resource = try_acquire(kind)
+          return resource if resource
+
+          remaining = deadline - Clock.now if deadline
+          raise TimeoutError, "lease checkout timed out" if remaining && !remaining.positive?
+          reject_unscheduled_fiber_wait!
+          interval = wait_interval(remaining)
+          changed  = Thread.handle_interrupt(Exception => :immediate) do
+            @signal.wait(observed, timeout: interval)
+          end
+          next if changed || interval != remaining
+
+          raise TimeoutError, "lease checkout timed out"
+        end
+      rescue Exception # rubocop:disable Lint/RescueException
+        rollback_acquisition(resource) if resource && @lock.owned? && state == kind
+        raise
+      end
+
+      def wait_for_block(timeout, block)
+        deadline = timeout_deadline(timeout)
+
+        loop do
+          observed = @signal.generation
+          outcome  = try_acquire_block(block)
+          return outcome.first if outcome
+
+          remaining = deadline - Clock.now if deadline
+          raise TimeoutError, "lease checkout timed out" if remaining && !remaining.positive?
+          reject_unscheduled_fiber_wait!
+          interval = wait_interval(remaining)
+          changed  = Thread.handle_interrupt(Exception => :immediate) do
+            @signal.wait(observed, timeout: interval)
+          end
+          next if changed || interval != remaining
+
+          raise TimeoutError, "lease checkout timed out"
+        end
+      end
+
+      def checkin_block(resource)
+        return if retired?
+        raise OwnershipError, "the current Fiber does not own this block checkout" unless
+          @lock.owned? && state == BLOCK
+
+        Thread.handle_interrupt(INTERRUPT_MASK) do
+          return_resource(resource)
+          unregister_owned_resource
+          release
+        end
+      end
+
+      def initialize_state
+        @lock            = Lock.new
+        @state           = Atom.new(AVAILABLE)
+        @signal          = Signal.new
+        @owner_thread_id = Atom.new(0)
+      end
+
+      def state = @state.value
+
+      def try_acquire_block(block)
+        raise RetiredLeaseError, "lease has been retired" if retired?
+        raise ThreadError, "deadlock; recursive lease checkout" if @lock.owned?
+
+        acquired = false
+        resource = nil
+        Thread.handle_interrupt(INTERRUPT_MASK) do
+          acquired = @lock.try_lock
+          return unless acquired
+
+          begin
+            raise RetiredLeaseError, "lease has been retired" if retired?
+            @owner_thread_id.store(Thread.current.object_id)
+            @state.store(BLOCK)
+            resource = take_resource
+            register_owned_resource(resource)
+            [Thread.handle_interrupt(Exception => :immediate) { block.call(resource) }]
+          ensure
+            if resource
+              checkin_block(resource) if @lock.owned? && state == BLOCK
+            elsif acquired
+              rollback_acquisition(resource)
+            end
+          end
+        end
+      end
+
+      def explicit_checkout
+        resource = nil
+        begin
+          Thread.handle_interrupt(INTERRUPT_MASK) { resource = yield }
+        rescue Exception # rubocop:disable Lint/RescueException
+          rollback_acquisition(resource) if resource && @lock.owned? && state == EXPLICIT
+          raise
+        end
+        resource
+      end
+
+      def try_acquire(kind)
+        raise RetiredLeaseError, "lease has been retired" if retired?
+        raise ThreadError, "deadlock; recursive lease checkout" if @lock.owned?
+
+        acquired = false
+        resource = nil
+        begin
+          Thread.handle_interrupt(INTERRUPT_MASK) do
+            acquired = @lock.try_lock
+            return unless acquired
+
+            raise RetiredLeaseError, "lease has been retired" if retired?
+            @owner_thread_id.store(Thread.current.object_id)
+            @state.store(kind)
+            resource = take_resource
+            register_owned_resource(resource)
+          end
+        rescue Exception # rubocop:disable Lint/RescueException
+          rollback_acquisition(resource) if acquired
+          raise
+        end
+        resource
+      end
+
+      def release
+        @state.store(AVAILABLE)
+        @owner_thread_id.store(0)
+        @lock.unlock
+        @signal.broadcast
+      end
+
+      def rollback_acquisition(resource)
+        Thread.handle_interrupt(INTERRUPT_MASK) do
+          return_resource(resource) if resource
+          unregister_owned_resource
+          @state.store(AVAILABLE) unless retired?
+          @owner_thread_id.store(0)
+          @lock.unlock if @lock.owned?
+          @signal.broadcast
+        end
+      end
+
+      def reject_unscheduled_fiber_wait!
+        return unless @lock.locked? && @owner_thread_id.value == Thread.current.object_id
+        return if Fiber.respond_to?(:scheduler) && Fiber.scheduler
+
+        raise ThreadError, "deadlock; lease is owned by another unscheduled Fiber on the same thread"
+      end
+
+      def wait_interval(remaining)
+        LeaseWaiting.wait_interval(remaining)
+      end
+
+      def owned_resources
+        Storage.fiber.store_if_absent(OWNED_RESOURCES, mode: :strong) { {}.compare_by_identity }
+      end
+
+      def register_owned_resource(resource)
+        owned_resources[self] = resource
+      end
+
+      def unregister_owned_resource
+        Storage.fiber[OWNED_RESOURCES, :strong]&.delete(self)
+        Storage.fiber[SCOPE_MANAGED_RESOURCES, :strong]&.delete(self)
+      end
+
+      def scope_managed_resources
+        Storage.fiber.store_if_absent(SCOPE_MANAGED_RESOURCES, mode: :strong) { {}.compare_by_identity }
+      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 validate_resource!(resource)
+        return unless nil.equal?(resource) || true.equal?(resource) || false.equal?(resource)
+
+        raise ArgumentError, "lease resource cannot be nil or boolean"
+      end
+    end
+  end
+end

data/lib/farce/internal/lease_waiting.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  # @!visibility private
+  module Internal # :nodoc: all
+    # Selects how long a Lease waits for one signal notification.
+    module LeaseWaiting
+      def self.wait_interval(remaining) = remaining
+    end
+  end
+end

data/lib/farce/internal/managed_queue.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Internal # :nodoc: all
+    # Shared mode metadata and deletion probes. Reads and writes are specialized
+    # in each public class to avoid forwarding overhead on the hot path.
+    module ManagedQueue
+      DeleteProbe = Data.define(:value, :compare_by_identity, :manager) do
+        def ===(stored) = manager.same_value?(stored, value, identity: compare_by_identity)
+      end
+      private_constant :DeleteProbe
+
+      def mode = @manager.mode
+
+      private
+
+      def delete_from_storage(priority, value, compare_by_identity:)
+        comparison_mode = compare_by_identity ? :local : :copy
+        value = @manager.wrap(value, mode: comparison_mode)
+        @queue.delete_match(priority, DeleteProbe.new(value, compare_by_identity, @manager))
+      end
+    end
+  end
+end

data/lib/farce/internal/map_value_modes.rb

@@ -0,0 +1,227 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  # @!visibility private
+  module Internal # :nodoc: all
+    module MapValueModes
+      NIL_VALUE = Object.new.freeze
+      TIMED_OUT = Object.new.freeze
+      CANCEL_UPDATE = Object.new.freeze
+      private_constant :NIL_VALUE, :TIMED_OUT, :CANCEL_UPDATE
+
+      # @!macro modes
+      # @param initial_mapping [Hash, Farce::Abstract::Map, #each, nil] initial entries with shareable keys
+      # @param mode [Symbol] the default value transfer mode
+      # @!macro key_normalization
+      # @param compare_by_identity [Boolean] the default comparison mode for keys and values
+      # @param compare_keys_by_identity [Boolean] whether keys are compared by identity
+      # @param compare_values_by_identity [Boolean] whether values are compared by identity
+      def initialize(initial_mapping = nil, mode: :copy, normalize_keys: nil, compare_by_identity: false,
+                     compare_keys_by_identity: compare_by_identity, compare_values_by_identity: compare_by_identity)
+        initial_mapping = convert_entries(initial_mapping)
+
+        identity         = BasicObject.instance_method(:equal?)
+        valid_comparison = identity.bind_call(compare_values_by_identity, true) ||
+          identity.bind_call(compare_values_by_identity, false)
+
+        raise ArgumentError, "compare_values_by_identity must be a boolean" unless valid_comparison
+        @compare_values_by_identity = compare_values_by_identity
+
+        @manager = new_mode_manager(mode:)
+        @map     = new_map(compare_by_identity:, compare_keys_by_identity:, compare_values_by_identity: true)
+        KeyNormalizer.prepare_concurrent(@map)
+
+        restoring  = KeyNormalizer.restoration?(normalize_keys)
+        normalizer = KeyNormalizer.build(normalize_keys, shareable: true)
+        KeyNormalizer.install_concurrent(self, normalizer) unless restoring
+
+        initial_mapping&.each { |key, value| self[key] = value }
+        KeyNormalizer.install_concurrent(self, normalizer) if restoring
+        super()
+      end
+
+      # Build a wrapper that preserves this object's value modes.
+      def transaction_wrapper(transaction)
+        Transaction::Map.new(transaction, self, @map, manager: @manager, nil_value: NIL_VALUE)
+      end
+
+      # The default transfer mode for values.
+      # @return [Symbol]
+      def mode                        = @manager.mode
+      def compare_values_by_identity? = @compare_values_by_identity
+      def shareable_keys?             = true
+      def shareable_values?           = true
+      def [](key)                     = unwrap_value(@map[key])
+
+      def []=(key, value)
+        key = @map.prepare_mutation_key(key)
+        @map.store_prepared(key, wrap_value(value))
+        value
+      end
+
+      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
+        warn "block supersedes default value argument", uplevel: 1 if block_given? && arguments.length == 2
+        value = @map.fetch(key) do
+          return yield(key) if block_given?
+          return default if arguments.length == 2
+          raise KeyError.new("key not found: #{key.inspect}", receiver: self, key: key)
+        end
+        unwrap_value(value)
+      end
+
+      def get(key, timeout: nil, &) = unwrap_result(@map.get(key, timeout:) { TIMED_OUT }, &)
+
+      # (see Abstract::ConcurrentMap#store)
+      # @param mode [Symbol, nil] the value transfer mode, or nil to use the default
+      def store(key, value, mode: nil, timeout: nil, &)
+        key = @map.prepare_mutation_key(key)
+        unwrap_result(@map.store_prepared(key, wrap_value(value, mode:), timeout:) { TIMED_OUT }, &)
+      end
+
+      # (see Abstract::ConcurrentMap#swap)
+      # @param mode [Symbol, nil] the replacement's transfer mode, or nil to use the default
+      def swap(key, replacement, mode: nil, timeout: nil, &)
+        key = @map.prepare_mutation_key(key)
+        unwrap_result(@map.swap_prepared(key, wrap_value(replacement, mode:), timeout:) { TIMED_OUT }, &)
+      end
+
+      # (see Abstract::ConcurrentMap#store_if_absent)
+      # @param mode [Symbol, nil] the result's transfer mode, or nil to use the default
+      def store_if_absent(key, mode: nil, timeout: nil)
+        raise LocalJumpError, "no block given" unless block_given?
+        @map.check_mutation
+        unwrap_value(@map.store_if_absent(key, timeout:) do
+          value = yield
+          @map.check_mutation
+          wrap_value(value, mode:)
+        end)
+      end
+
+      # (see Abstract::ConcurrentMap#update)
+      # @param mode [Symbol, nil] the result's transfer mode, or nil to use the default
+      def update(key, mode: nil, timeout: nil)
+        raise LocalJumpError, "no block given" unless block_given?
+        @map.check_mutation
+        unwrap_value(@map.update(key, timeout:) do |current|
+          value = yield(unwrap_value(current))
+          @map.check_mutation
+          wrap_value(value, mode:)
+        end)
+      end
+
+      # (see Abstract::ConcurrentMap#upsert)
+      # @param mode [Symbol, nil] the value transfer mode, or nil to use the default
+      def upsert(key, initial, mode: nil, timeout: nil)
+        raise LocalJumpError, "no block given" unless block_given?
+        @map.check_mutation
+        unwrap_value(@map.update(key, timeout:) do |current|
+          value = nil.equal?(current) ? initial : yield(unwrap_value(current))
+          @map.check_mutation
+          wrap_value(value, mode:)
+        end)
+      end
+
+      # (see Abstract::ConcurrentMap#compare_and_set)
+      # @param mode [Symbol, nil] the replacement's transfer mode, or nil to use the default
+      def compare_and_set(key, expected, replacement, mode: nil, timeout: nil)
+        key = @map.prepare_mutation_key(key)
+        expected = wrap_comparison(expected)
+        catch(CANCEL_UPDATE) do
+          result = @map.update_prepared(key, timeout:) do |current|
+            # Abort the update instead of inserting a value for a missing key.
+            throw CANCEL_UPDATE, false if nil.equal?(current) || !values_equal?(current, expected)
+            @map.check_mutation
+            wrap_value(replacement, mode:)
+          end
+          !nil.equal?(result)
+        end
+      end
+
+      def wait_until_changed(key, expected, timeout: nil, &)
+        prepared_key = @map.normalize_external_key(key)
+        expected = wrap_comparison(expected)
+        deadline = Internal.timeout_deadline(timeout)
+        loop do
+          current = @map.get_prepared(prepared_key, timeout: Internal.remaining_timeout(deadline)) { TIMED_OUT }
+          return unwrap_result(current, &) if TIMED_OUT.equal?(current)
+          return unwrap_value(current) unless values_equal?(nil.equal?(current) ? NIL_VALUE : current, expected)
+          result = @map.wait_until_changed_prepared(
+            prepared_key,
+            current,
+            timeout: Internal.remaining_timeout(deadline),
+          ) { TIMED_OUT }
+          return unwrap_result(result, &) if TIMED_OUT.equal?(result)
+        end
+      end
+
+      def wait_until_non_nil(key, timeout: nil, &) = wait_until_changed(key, nil, timeout:, &)
+      def delete(key) = unwrap_value(@map.delete(key))
+
+      def each
+        return enum_for(__method__) { size } unless block_given?
+        @map.each { |key, value| yield [key, unwrap_value(value)] }
+        self
+      end
+      alias each_pair each
+
+      def each_live
+        return enum_for(__method__) { size } unless block_given?
+        @map.each_live { |key, value| yield [key, unwrap_value(value)] }
+        self
+      end
+
+      def each_value
+        return enum_for(__method__) { size } unless block_given?
+        @map.each_value { |value| yield unwrap_value(value) }
+        self
+      end
+
+      protected
+
+      def wrap_value(value, mode: nil) = nil.equal?(value) ? NIL_VALUE : @manager.wrap(value, mode:)
+      def unwrap_value(value)          = NIL_VALUE.equal?(value) ? nil : @manager.unwrap(value)
+
+      private
+
+      def marshal_map_value(value) = super(NIL_VALUE.equal?(value) ? nil : value)
+
+      def marshal_restore_map_value(data)
+        value = super
+        nil.equal?(value) ? NIL_VALUE : value
+      end
+
+      def each_for_inspect(&) = @map.each(&)
+
+      def inspect_pair(inspector, key, value)
+        inspector.hash_pair(key, value, @manager) { inspect_value(inspector, value) }
+      end
+
+      def inspect_value(inspector, value)
+        value = nil if NIL_VALUE.equal?(value)
+        super(inspector, value, @manager)
+      end
+
+      def new_mode_manager(mode:) = marshal_mode_manager(mode)
+
+      def check_key(key)
+        return if Ractor.shareable?(key)
+        raise Ractor::IsolationError, "key must be Ractor-shareable"
+      end
+
+      def wrap_comparison(value) = wrap_value(value, mode: compare_values_by_identity? ? :local : :copy)
+
+      def unwrap_result(result)
+        return unwrap_value(result) unless TIMED_OUT.equal?(result)
+        yield if block_given?
+      end
+
+      def values_equal?(left, right) = @manager.same_value?(left, right, identity: compare_values_by_identity?)
+    end
+  end
+end