farce 0.0.1.alpha2-java

data/lib/farce/abstract/lease_map.rb

@@ -0,0 +1,261 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Abstract
+    # @abstract Shared per-key checkout, mutation, and automatic cleanup behavior for lease maps.
+    class LeaseMap < Map
+      include Internal::MarshalSupport::Reject
+
+      # Construct a lease map from a block returning key/value entries.
+      # @!macro key_normalization
+      # @yield builds the initial key and resource mapping
+      # @yieldreturn [Hash, Farce::Abstract::Map, #each] the initial mapping
+      def initialize(normalize_keys: nil)
+        raise ArgumentError, "a resource constructor block is required" unless block_given?
+
+        normalizer = Internal::KeyNormalizer.build(
+          normalize_keys,
+          shareable: Internal::KeyNormalizer.shareable_target?(self),
+        )
+        Internal::KeyNormalizer.install(self, normalizer, Internal::KeyNormalizer::LeaseOperations)
+        mapping = prepare_initial_resources(yield, normalizer)
+        @lease_map = new_internal_lease_map(mapping)
+        super()
+      end
+
+      # @api private
+      def initialize_copy(_other)
+        raise TypeError, "lease maps cannot be copied"
+      end
+
+      # Acquire one key's resource, waiting until it is available.
+      # @param key [BasicObject] the key to acquire
+      # @param timeout [Numeric, nil] maximum seconds to wait
+      # @yieldparam resource [BasicObject] the acquired resource
+      # @return [BasicObject] the resource without a block, or the block result
+      # @raise [KeyError] if the key is absent or its entry is deleted while waiting
+      # @raise [Farce::TimeoutError] if the timeout expires
+      def checkout(key, timeout: nil, &) = checkout_canonical(key, missing_key: key, timeout:, &)
+
+      # Acquire one key's resource immediately if it is available.
+      # @param key [BasicObject] the key to acquire
+      # @yieldparam resource [BasicObject] the acquired resource
+      # @return [BasicObject, nil] the resource or block result, or nil when unavailable
+      # @raise [KeyError] if the key is absent
+      def try_checkout(key, &) = try_checkout_canonical(key, missing_key: key, &)
+
+      # Return an explicitly checked-out resource, replace it, or delete it with nil.
+      # @param key [BasicObject] the checked-out key
+      # @param resource [BasicObject, nil] the replacement, or nil to delete the entry
+      # @return [self]
+      # @raise [Farce::OwnershipError] unless the current Fiber owns an explicit checkout
+      # @raise [ArgumentError] if the replacement is boolean
+      def checkin(key, resource) = checkin_canonical(key, resource, missing_key: key)
+
+      # Return the Lease attached to a key's current entry.
+      # A retained handle becomes retired when its entry is deleted.
+      # @param key [BasicObject] the key to look up
+      # @return [Farce::Abstract::Lease] the current entry's Lease
+      # @raise [KeyError] if the key is absent
+      def lease_for(key) = lease_for_canonical(key, missing_key: key)
+
+      # Keep resources acquired by reads checked out until the block exits.
+      # Checkouts already owned before the scope remain owned afterward.
+      # Nested scopes return only the resources they acquire, including on exceptions and early returns.
+      #
+      # @example Nesting automatic checkout scopes
+      #   map = Farce::LeaseMap.new { { a: [], b: [] } }
+      #   map.auto_lease do
+      #     map[:a]       # Held by the outer scope
+      #
+      #     map.auto_lease do
+      #       map[:a]     # Reuses the outer checkout
+      #       map[:b]     # Held by the inner scope
+      #     end           # Checks in b only
+      #
+      #     map[:b]       # Acquires b again for the outer scope
+      #   end             # Checks in a and b
+      #
+      # @yield the automatic checkout scope
+      # @return [BasicObject] the block result
+      def auto_lease(&) = internal_lease_map.auto_lease(&)
+
+      # Read an owned resource or acquire it through the active automatic scope.
+      def [](key) = internal_lease_map.read_entry(key).last
+
+      # (see Map#fetch)
+      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
+        present, value = internal_lease_map.read_entry(key)
+        return value if present
+        return yield(key) if block_given?
+        return default if arguments.length == 2
+
+        raise KeyError.new("key not found: #{key.inspect}", receiver: self, key:)
+      end
+
+      # Insert or replace a resource. Assigning nil deletes the entry.
+      # Assignment waits for another owner. An assignment to an explicitly owned
+      # entry replaces its held resource without ending the checkout. Assignment
+      # is invalid during a checkout block or an iteration yield.
+      # @return [BasicObject, nil] the supplied resource, or the deleted resource
+      # @raise [ArgumentError] if the resource is boolean
+      def []=(key, resource)
+        internal_lease_map.store(key, resource)
+      end
+
+      # Read an owned resource or construct an absent resource in an automatic scope.
+      # Constructors for the same key run one at a time, outside the map lock.
+      # Missing-key assignments wait for construction. Deletion and clear only
+      # affect published entries and do not cancel a pending constructor.
+      # @param key [BasicObject] the key to read or initialize
+      # @yield builds the missing resource without arguments
+      # @yieldreturn [BasicObject] a resource other than nil or a boolean
+      # @return [BasicObject] the existing or newly constructed resource
+      # @raise [LocalJumpError] if no block is given
+      # @raise [Farce::OwnershipError] if reading requires ownership or creation lacks an automatic scope
+      # @raise [ArgumentError] if the constructor returns nil or a boolean
+      def store_if_absent(key, &) = internal_lease_map.store_if_absent(key, &)
+
+      # Delete a key after acquiring and retiring its Lease.
+      # @return [BasicObject, nil] the removed resource, or nil if absent
+      def delete(key) = internal_lease_map.delete(key)
+
+      # Delete each entry captured when clearing begins.
+      # Entries concurrently reinserted under the same key are preserved.
+      # @return [self]
+      def clear
+        internal_lease_map.clear
+        self
+      end
+
+      # @return [Boolean] whether the key's resource is available
+      def available?(key) = internal_lease_map.available?(key)
+
+      # @return [Boolean] whether the key's resource is checked out
+      def checked_out?(key) = internal_lease_map.checked_out?(key)
+
+      # @return [Boolean] whether the current Fiber owns the key's checkout
+      def owned?(key) = internal_lease_map.owned?(key)
+
+      # (see Map#key?)
+      def key?(key) = internal_lease_map.key?(key)
+
+      # (see Map#getkey)
+      def getkey(key) = internal_lease_map.getkey(key)
+
+      # (see Map#size)
+      def size = internal_lease_map.size
+
+      # (see Map#keys)
+      def keys = internal_lease_map.keys
+
+      # LeaseMap keys use equality and values use Lease identity.
+      def compare_keys_by_identity? = internal_lease_map.compare_keys_by_identity?
+      def compare_values_by_identity? = internal_lease_map.compare_values_by_identity?
+
+      # Top-level keys must be shareable. Managed resources may be unshareable.
+      def shareable_keys? = true
+      def shareable_values? = false
+
+      # Iterate while leasing only the entry currently being yielded.
+      def each(&block)
+        return enum_for(__callee__) { size } unless block
+
+        internal_lease_map.each(&block)
+        self
+      end
+      alias each_pair each
+
+      # Iterate over a snapshot of current keys without leasing their resources.
+      def each_key(&block)
+        return enum_for(__callee__) { size } unless block
+
+        internal_lease_map.each_key(&block)
+        self
+      end
+
+      # Iterate while leasing only the value currently being yielded.
+      def each_value(&block)
+        return enum_for(__callee__) { size } unless block
+
+        internal_lease_map.each_value(&block)
+        self
+      end
+
+      # Return key and Lease handle pairs.
+      # Unlike iteration, this method never checks resources out.
+      # @return [Array<Array(BasicObject, Farce::Abstract::Lease)>]
+      def to_a = internal_lease_map.handles
+
+      # Return a key to Lease handle mapping.
+      # Unlike iteration, this method never checks resources out.
+      # A block receives each key and Lease handle and returns a pair for the new Hash.
+      # @return [Hash{BasicObject => Farce::Abstract::Lease}]
+      def to_h(&) = entries_to_hash(to_a, &)
+
+      # Return the current Lease handles.
+      # @return [Array<Farce::Abstract::Lease>]
+      def values = to_h.values
+
+      private
+
+      def prepare_initial_resources(entries, normalizer)
+        entries = convert_entries(entries)
+        raise TypeError, "lease map initializer must yield key/value pairs" unless entries
+        return entries if entries.is_a?(Hash) && !normalizer
+
+        mapping = {}
+        entries.each do |key, resource|
+          if resource.nil? || resource.equal?(true) || resource.equal?(false)
+            raise ArgumentError, "resource must not be nil or a boolean"
+          end
+          key = normalizer.call(key) if normalizer
+          mapping[key] = resource
+        end
+        mapping
+      end
+
+      def checkout_canonical(key, missing_key:, timeout: nil, &)
+        internal_lease_map.checkout(key, timeout:, receiver: self, missing_key:, &)
+      end
+
+      def try_checkout_canonical(key, missing_key:, &)
+        internal_lease_map.try_checkout(key, receiver: self, missing_key:, &)
+      end
+
+      def checkin_canonical(key, resource, missing_key:)
+        internal_lease_map.checkin(key, resource, receiver: self, missing_key:)
+        self
+      end
+
+      def lease_for_canonical(key, missing_key:)
+        internal_lease_map.lease_for(key, receiver: self, missing_key:)
+      end
+
+      def each_for_inspect
+        return enum_for(__method__) { size } unless block_given?
+        to_a.each { |key, lease| yield key, lease_state(lease) }
+        self
+      end
+
+      def internal_lease_map                 = @lease_map
+      def new_internal_lease_map(_)          = raise(NoMethodError, "abstract lease map storage")
+      def inspect_value(inspector, lease, *) = inspector.text(lease.to_s)
+
+      def lease_state(lease)
+        return :retired if lease.retired?
+        return :available if lease.available?
+        return :owned if lease.owned?
+        :checked_out
+      end
+    end
+  end
+end

data/lib/farce/abstract/lease_pool.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Abstract
+    # @abstract Shared checkout, return, ownership, and capacity behavior for resource pools.
+    class LeasePool
+      include Internal::Noncopyable
+      include Internal::Inspect
+
+      # Construct an empty pool whose resources are created on demand.
+      # @param max_size [Integer] the maximum number of managed resources
+      # @yield builds one resource after capacity has been reserved
+      # @yieldreturn [BasicObject] a new resource
+      # @raise [ArgumentError] if no block is given or max_size is not a positive Integer
+      def initialize(max_size:, &factory)
+        validate_configuration!(max_size, factory)
+        @max_size = Integer(max_size)
+        @factory  = prepare_factory(factory)
+        @pool     = new_internal_pool(max_size)
+        super()
+      end
+
+      # Acquire a resource, waiting for availability or creation capacity.
+      # @param timeout [Numeric, nil] maximum seconds to wait before reserving a resource
+      # @yieldparam resource [BasicObject] the acquired resource
+      # @return [BasicObject] the resource without a block, or the block result
+      # @raise [Farce::TimeoutError] if the timeout expires
+      def checkout(timeout: nil, &block)
+        pool = internal_pool
+        block ? pool.checkout(@factory, timeout:, &block) : pool.checkout(@factory, timeout:)
+      end
+
+      # Acquire an available resource or create one without waiting for capacity.
+      # @yieldparam resource [BasicObject] the acquired resource
+      # @return [BasicObject, nil] the resource or block result, or nil at capacity
+      def try_checkout(&block)
+        pool = internal_pool
+        block ? pool.try_checkout(@factory, &block) : pool.try_checkout(@factory)
+      end
+
+      # Return an explicitly checked-out resource, a replacement, or nil to delete its slot.
+      # @param resource [BasicObject, nil] the resource to store, or nil to release capacity
+      # @return [self]
+      # @raise [Farce::OwnershipError] unless the current Fiber owns an explicit checkout
+      # @raise [ArgumentError] if resource is true or false
+      def checkin(resource)
+        internal_pool.checkin(resource)
+        self
+      end
+
+      # @return [Integer] the configured capacity
+      attr_reader :max_size
+
+      # @return [Integer] managed resources, excluding in-progress factory calls
+      def size = internal_pool.size
+
+      # @return [Integer] resources ready for checkout
+      def available_count = internal_pool.available_count
+
+      # @return [Integer] resources currently checked out
+      def checked_out_count = internal_pool.checked_out_count
+
+      # @return [Integer] capacity reserved by in-progress factory calls
+      def creating_count = internal_pool.creating_count
+
+      # @api private
+      def inspect_with(inspector)
+        super do
+          yield if block_given?
+          inspector.attribute(:size,     size)
+          inspector.attribute(:max_size, max_size)
+        end
+      end
+
+      private
+
+      def validate_configuration!(max_size, factory)
+        raise ArgumentError, "a resource factory block is required" unless factory
+        return if max_size.is_a?(Integer) && max_size.positive?
+
+        raise ArgumentError, "max_size must be a positive Integer"
+      end
+
+      def prepare_factory(factory) = factory
+      def internal_pool = @pool
+      def new_internal_pool(_) = raise(NoMethodError, "abstract lease pool storage")
+    end
+  end
+end

data/lib/farce/abstract/lfu_map.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Abstract
+    # @abstract A bounded map that evicts the least frequently accessed entry.
+    # Ties are resolved by least recent access.
+    class LFUMap < BoundedMap
+      private
+
+      # simplecov:disable
+      def new_bounded_map(...)
+        raise "subclass failed to implement #new_bounded_map" unless instance_of?(LFUMap)
+        raise NoMethodError, "Farce::Abstract::LFUMap should not be instantiated directly. Use a subclass instead."
+      end
+      # simplecov:enable
+    end
+  end
+end

data/lib/farce/abstract/lru_map.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Abstract
+    # @abstract A bounded map that evicts the least recently accessed entry.
+    class LRUMap < BoundedMap
+      private
+
+      # @api private
+      def marshal_entries
+        map = marshal_map.dup
+        Array.new(map.size) { map.shift }
+      end
+
+      # simplecov:disable
+      def new_bounded_map(...)
+        raise "subclass failed to implement #new_bounded_map" unless instance_of?(LRUMap)
+        raise NoMethodError, "Farce::Abstract::LRUMap should not be instantiated directly. Use a subclass instead."
+      end
+      # simplecov:enable
+    end
+  end
+end