farce 0 → 0.1.0

data/lib/farce/abstract/duplicable_map.rb

@@ -0,0 +1,229 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Abstract
+    # Map operations that return independent maps of the same kind.
+    # Include this in subclasses of {Map} that support copying.
+    # Operations work on an independent copy, not an atomic snapshot of the source.
+    # Local copies transform the current scope and retain constructor defaults for other scopes.
+    module DuplicableMap
+      # Return an independent map containing only the requested keys that exist.
+      # @param keys [Array<BasicObject>] keys to retain, using the map's lookup rules
+      # @return [Map] A map of the same class with the same settings.
+      def slice(*keys)
+        with_map_copy do |_, map|
+          retained = {}.compare_by_identity
+          keys.each do |key|
+            key = normalize_copied_key(key)
+            retained[map.getkey(key)] = true if map.key?(key)
+          end
+          # Tree backends expose each, but not each_key.
+          map.each { |key, _| map.delete(key) unless retained.key?(key) } # rubocop:disable Style/HashEachMethods
+        end
+      end
+
+      # Return an independent map without the requested keys.
+      # @param keys [Array<BasicObject>] keys to omit, using the map's lookup rules
+      # @return [Map] A map of the same class with the same settings.
+      def except(*keys)
+        with_map_copy do |_, map|
+          keys.each { map.delete(normalize_copied_key(it)) }
+        end
+      end
+
+      # Return an independent map without entries whose value is nil. False values are retained.
+      # @return [Map] A map of the same class with the same settings.
+      def compact
+        with_map_copy do |copy, map|
+          nil_value = copy.wrap_value(nil)
+          map.each { |key, value| map.delete(key) if nil_value.equal?(value) }
+        end
+      end
+
+      # Return an independent map containing entries accepted by the block.
+      # The block receives public values from the copy. Stored values and map settings are preserved.
+      # @yieldparam key [BasicObject] an existing key
+      # @yieldparam value [BasicObject] the public value
+      # @return [Map, Enumerator] A map of the same class, or an Enumerator without a block.
+      def select
+        return enum_for(__method__) { size } unless block_given?
+        with_map_copy do |copy, map|
+          map.each { |key, value| map.delete(key) unless yield(key, copy.unwrap_value(value)) }
+        end
+      end
+      alias filter select
+
+      # Return an independent map excluding entries accepted by the block.
+      # The block receives public values from the copy. Stored values and map settings are preserved.
+      # @yieldparam key [BasicObject] an existing key
+      # @yieldparam value [BasicObject] the public value
+      # @return [Map, Enumerator] A map of the same class, or an Enumerator without a block.
+      def reject
+        return enum_for(__method__) { size } unless block_given?
+        with_map_copy do |copy, map|
+          map.each { |key, value| map.delete(key) if yield(key, copy.unwrap_value(value)) }
+        end
+      end
+
+      # Return an independent map with transformed keys and unchanged stored values.
+      # Mapping entries take precedence over the block. Unmapped keys are retained when no block is given.
+      # Transformed keys pass through this map's normalizer. On collisions, the last visited entry wins.
+      # Bounded copies rebuild eviction history as transformed entries are inserted.
+      # @param mapping [Hash, #to_hash] optional replacements for existing keys
+      # @yieldparam key [BasicObject] an existing key
+      # @yieldreturn [BasicObject] the replacement key
+      # @return [Map, Enumerator] A map of the same class, or an Enumerator without a mapping or block.
+      def transform_keys(mapping = UNDEFINED)
+        if UNDEFINED.equal?(mapping)
+          return enum_for(__method__, mapping) { size } unless block_given?
+          mapping = nil
+        else
+          mapping = Hash.try_convert(mapping) || raise(TypeError, "mapping must be a Hash or respond to #to_hash")
+        end
+
+        with_map_copy(empty: true) do |_, map|
+          internal_map.each do |key, value|
+            if mapping&.key?(key)
+              key = normalize_copied_key(mapping.fetch(key))
+            elsif block_given?
+              key = normalize_copied_key(yield(key))
+            end
+            map[key] = value
+          end
+        end
+      end
+
+      # Return an independent map with transformed values and unchanged keys.
+      # Results follow the map's transfer mode. Move-mode results are copied before transfer to preserve the source.
+      # Bounded copies count replacements as writes. The source's eviction history is unchanged.
+      # @yieldparam value [BasicObject] the current value
+      # @yieldreturn [BasicObject] the replacement value
+      # @return [Map, Enumerator] A map of the same class, or an Enumerator without a block.
+      def transform_values
+        return enum_for(__method__) { size } unless block_given?
+        copier = ModeManager.new(mode: :copy) if respond_to?(:mode) && mode == :move
+        with_map_copy do |copy, map|
+          map.each do |key, value|
+            value = yield copy.unwrap_value(value)
+            value = copier.unwrap(copier.wrap(value)) if copier
+            map[key] = copy.wrap_value(value)
+          end
+        end
+      end
+
+      # Return an independent map with keys and values exchanged.
+      # New keys follow the map's normal key normalization and shareability rules.
+      # On collisions, the last visited entry wins. Bounded copies rebuild eviction history.
+      # @return [Map] A map of the same class with the same settings.
+      # @raise [Ractor::IsolationError] if a new key violates the map's shareability rules
+      def invert
+        copier = ModeManager.new(mode: :copy) if respond_to?(:mode) && mode == :move
+        empty_copy.tap do |copy|
+          each_pair do |key, value|
+            key = copier.unwrap(copier.wrap(key)) if copier
+            copy[value] = key
+          end
+        end
+      end
+
+      # Return an independent map with entries from each input applied in order.
+      # Incoming keys pass through the normalizer. A block resolves collisions using the canonical key.
+      # Move-mode values are copied before transfer to preserve the source and inputs.
+      # Bounded copies retain eviction history and apply their usual capacity limits to new writes.
+      # @param others [Array<Map, Hash, #to_hash>] maps to merge, with later entries taking precedence
+      # @yieldparam key [BasicObject] the canonical key shared by both maps
+      # @yieldparam old_value [BasicObject] the current value in the result
+      # @yieldparam new_value [BasicObject] the incoming value
+      # @yieldreturn [BasicObject] the replacement value
+      # @return [Map] A map of the same class with the same settings.
+      def merge(*others)
+        copier = ModeManager.new(mode: :copy) if respond_to?(:mode) && mode == :move
+        with_map_copy do |copy, map|
+          others.each do |other|
+            unless Map === other
+              other = Hash.try_convert(other) || raise(TypeError, "input must be a Map, Hash, or respond to #to_hash")
+            end
+            other.each_pair do |key, value|
+              key = normalize_copied_key(key)
+              value = yield(key, copy.unwrap_value(map[key]), value) if block_given? && map.key?(key)
+              value = copier.unwrap(copier.wrap(value)) if copier
+              map[key] = copy.wrap_value(value)
+            end
+          end
+        end
+      end
+
+      # Return a lambda that looks up a key using this map's current contents and lookup rules.
+      # The lambda is Ractor-shareable when this map is Ractor-shareable.
+      # @return [Proc] A one-argument lookup lambda.
+      def to_proc
+        lookup = ->(key) { self[key] }
+        Ractor.shareable?(self) ? Ractor.shareable_lambda(self: self, &lookup) : lookup
+      end
+
+      # Return keys and values in a flattened Array.
+      # The default depth flattens entry pairs. Zero preserves pairs, and negative depths flatten all levels.
+      # @param level [Integer, #to_int] the number of Array levels to flatten
+      # @return [Array] The flattened entries.
+      def flatten(level = 1)
+        level = Integer.try_convert(level) || raise(TypeError, "level must be an Integer or respond to #to_int")
+        to_a.flatten(level)
+      end
+
+      protected
+
+      # The backing map used by copying and transformation operations.
+      # Scoped maps override this to resolve storage for the current scope.
+      # @api private
+      def internal_map = @map
+
+      private
+
+      def initialize_dup(other)
+        super
+        publish_shareable_copy(other, operation: :dup) if is_a?(Shareable)
+      end
+
+      def initialize_clone(other, freeze: nil)
+        super
+        publish_shareable_copy(other, operation: :clone, freeze:) if is_a?(Shareable)
+      end
+
+      def initialize_copy(other, empty: false)
+        super(other)
+        normalizer = other.instance_variable_get(:@key_normalizer)
+        if normalizer && !is_a?(ConcurrentMap)
+          operations = Internal::KeyNormalizer.operations_for(self)
+          Internal::KeyNormalizer.install(self, normalizer, operations) unless is_a?(operations)
+        end
+        install_copied_map(copy_map_backend(other.internal_map, empty:))
+      end
+
+      def install_copied_map(map) = @map = map
+
+      def empty_copy
+        # Preserve wrapper settings without copying entries or rerunning the public constructor.
+        copy = self.class.allocate
+        instance_variables.each { |name| copy.instance_variable_set(name, instance_variable_get(name)) }
+        copy.__send__(:initialize_copy, self, empty: true)
+        copy.__send__(:publish_shareable) if is_a?(Shareable)
+        copy
+      end
+
+      def with_map_copy(empty: false)
+        copy = empty ? empty_copy : dup
+        map  = copy.internal_map
+        map  = map.instance_variable_get(:@map) if map.is_a?(Internal::KeyNormalizer::ConcurrentMap)
+        yield copy, map
+        copy
+      end
+
+      def normalize_copied_key(key)
+        normalizer = instance_variable_get(:@key_normalizer)
+        normalizer ? normalizer.call(key) : key
+      end
+    end
+  end
+end

data/lib/farce/abstract/exchanger.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Abstract
+    # A rendezvous where callers pair up and receive each other's offered value.
+    # Each call participates in one exchange. The exchanger can be reused by any number of callers.
+    class Exchanger
+      include Internal::Noncopyable
+      include Internal::Inspect
+
+      # Wait for a partner and return the partner's value.
+      # Offering nil allows a caller to receive a value without sending a payload.
+      # A timeout of zero only exchanges with a partner that is already waiting.
+      # A successful exchange of nil does not invoke the fallback.
+      #
+      # @param offered [BasicObject, nil] the value to give to the partner
+      # @param timeout [Numeric, nil] the maximum seconds to wait, or nil to wait indefinitely
+      # @yield called without arguments when the timeout expires
+      # @return [BasicObject, nil] the partner's value, or the fallback result or nil on timeout
+      # @raise [ArgumentError] if the timeout is negative or not finite
+      def exchange(offered, timeout: nil, &) = @exchanger.exchange(offered, timeout:, &)
+    end
+  end
+end

data/lib/farce/abstract/flag.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Abstract
+    # @abstract Common boolean interface and serialization for atomic flags.
+    # @note This is a module rather than a class so {Farce::Flag} can inherit
+    #   directly from the native flag and avoid delegation overhead.
+    #
+    # @!method value
+    #   @return [Boolean] the current value
+    #
+    # @!method set
+    #   Set the flag to true.
+    #   @return [true]
+    #
+    # @!method unset
+    #   Set the flag to false.
+    #   @return [false]
+    #
+    # @!method store(value)
+    #   Set the flag to the given value.
+    #   @param value [Boolean] the new value
+    #   @return [Boolean] the new value
+    #   @raise [ArgumentError] if the value is not true or false
+    #
+    # @!method value=(value)
+    #   Alias for {#store}
+    #
+    # @!method swap(value)
+    #   Replace the value and return its previous state.
+    #   @param value [Boolean] the new value
+    #   @return [Boolean] the previous value
+    #   @raise [ArgumentError] if the value is not true or false
+    #
+    # @!method compare_and_set(expected_value, replacement_value)
+    #   Replace the value only if it matches the expected value.
+    #   @param expected_value [Boolean] the expected current value
+    #   @param replacement_value [Boolean] the new value
+    #   @return [Boolean] whether the replacement succeeded
+    #   @raise [ArgumentError] if either argument is not true or false
+    #
+    # @!method toggle
+    #   Atomically invert the value.
+    #   @return [Boolean] the new value
+    module Flag
+      include Internal::MarshalSupport::Flag
+      include Internal::Copyable
+      include Value
+      include Internal::ValueSerialization
+      include Internal::Inspect
+
+      # @api private
+      def inspect_with(inspector)
+        begin
+          current = value
+        rescue StandardError
+          # FrozenError may inspect an allocated flag before it is initialized.
+          return inspector.object_with_address(self)
+        end
+
+        super do
+          yield if block_given?
+          inspector.breakable
+          inspector.object(current)
+        end
+      end
+    end
+  end
+end

data/lib/farce/abstract/lazy.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Abstract
+    # @abstract Shared factory, caching, and delegation behavior for lazy values.
+    class Lazy
+      include Internal::MarshalSupport::Initialize
+      include Internal::Copyable
+      include Internal::Inspect
+      include Value
+
+      # @overload initialize(factory)
+      #   @param [Class, Proc, #call] factory The factory to use for creating the value. Must be ractor-shareable.
+      #
+      # @overload initialize(self: nil)
+      #   @yield The block to use for creating the value. Must be ractor-shareable.
+      #   @yieldreceiver [BasicObject] The `self` parameter provided, or `nil` if not provided.
+      #   @yieldreturn [BasicObject] The value to be returned by the lazy instance.
+      #   @param [BasicObject] self The `self` parameter to be provided to the block. Must be ractor-shareable.
+      def initialize(factory = nil, **, &)
+        @factory = prepare_factory(factory, **, &)
+        @atom    = new_internal_atom
+        super()
+      end
+
+      # The first time this method is called, the value will be computed based on the factory provided.
+      # Subsequent calls will return the same value.
+      #
+      # Concurrent access computes the value once.
+      # Shareable variants support calls from any Ractor.
+      # @return [BasicObject] The value computed by the factory.
+      def value
+        atom  = internal_atom
+        value = atom.value
+        if value.nil?
+          value = atom.store_if_absent do
+            value = compute_value
+            value.nil? ? UNDEFINED : value
+          end
+        end
+        value unless UNDEFINED.equal?(value)
+      end
+
+      # @api private
+      def marshal_dump
+        current           = marshal_current_value
+        resolved          = !current.nil?
+        stored            = UNDEFINED.equal?(current) ? nil : current
+        manager           = @manager if defined?(@manager)
+        options           = {}
+        options[:mode]    = manager.mode if manager
+        options[:manager] = manager if manager
+        options[:scope]   = scope if is_a?(Local::Lazy)
+
+        # Other scopes still need their factory even when this scope is resolved.
+        factory = @factory if !resolved || is_a?(Local::Lazy)
+
+        [1, resolved, factory, Internal::MarshalSupport.value(stored), options, frozen?]
+      end
+
+      # @api private
+      def marshal_load(data)
+        resolved, factory, stored, options, frozen = Internal::MarshalSupport.payload(data, 5)
+        @manager = options.delete(:manager) if options.key?(:manager)
+        initialize(factory, **options)
+        if resolved
+          value = Internal::MarshalSupport.restore_value(stored)
+          internal_atom.store(value.nil? ? UNDEFINED : value)
+        end
+        Internal::MarshalSupport.freeze(self, frozen)
+      end
+
+      # @api private
+      def inspect_with(inspector)
+        super do
+          inspector.breakable
+          display_value(inspector)
+        end
+      end
+
+      private
+
+      # @api private
+      def marshal_current_value = internal_atom.value
+
+      def internal_atom     = @atom
+      def new_internal_atom = Internal::StrictAtom.new
+      def compute_value     = @factory.is_a?(Class) ? @factory.new : @factory.call
+      def prepare_proc(factory, **) = Ractor.shareable_proc(**, &factory)
+
+      def prepare_factory(factory, **options, &block)
+        Internal.self_option(options.dup)
+        if block
+          raise ArgumentError, "factory and block cannot be both given" unless factory.nil?
+          factory = block
+        end
+        factory.is_a?(Proc) ? prepare_proc(factory, **options) : factory
+      end
+
+      def display_value(inspector, ...)
+        case value = internal_atom.value
+        when nil       then inspector.object(@factory, ...)
+        when UNDEFINED then inspector.object(nil)
+        else inspector.object(value, ...)
+        end
+      end
+
+      # Delegates all method calls to {#value}.
+      def method_missing(...) = value.public_send(...)
+      def respond_to_missing?(...) = value.respond_to?(...)
+    end
+  end
+end

data/lib/farce/abstract/lease.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Abstract
+    # @abstract Shared checkout, return, ownership, and retirement behavior for leases.
+    class Lease
+      include Internal::Noncopyable
+      include Internal::Inspect
+
+      # Construct a lease from one resource-building block.
+      # @yield builds the resource managed by the lease
+      # @yieldreturn [BasicObject] the initial resource
+      # @raise [ArgumentError] if no block is given or the resource is nil or boolean
+      def initialize
+        raise ArgumentError, "a resource constructor block is required" unless block_given?
+
+        @lease = new_internal_lease(yield)
+        super
+      end
+
+      # Acquire the resource, waiting until it is available.
+      # @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 [Farce::TimeoutError] if the timeout expires
+      # @raise [Farce::RetiredLeaseError] if the lease is retired
+      def checkout(timeout: nil, &block)
+        lease = internal_lease
+        block ? lease.checkout(timeout:, &block) : lease.checkout(timeout:)
+      end
+
+      # Acquire the resource immediately if it is available.
+      # @yieldparam resource [BasicObject] the acquired resource
+      # @return [BasicObject, nil] the resource or block result, or nil when unavailable
+      # @raise [Farce::RetiredLeaseError] if the lease is retired
+      def try_checkout(&block)
+        lease = internal_lease
+        block ? lease.try_checkout(&block) : lease.try_checkout
+      end
+
+      # Return an explicitly checked-out resource or a replacement.
+      # @param resource [BasicObject] the resource to store
+      # @return [self]
+      # @raise [Farce::OwnershipError] unless the current Fiber owns an explicit checkout
+      # @raise [Farce::RetiredLeaseError] if the lease is retired
+      # @raise [ArgumentError] if the resource is nil or boolean
+      def checkin(resource)
+        internal_lease.checkin(resource)
+        self
+      end
+
+      # Permanently retire this lease and wake its waiters.
+      #
+      # The current Fiber must own the checkout. Retirement ends that checkout,
+      # so automatic block cleanup does not return the resource. The resource is
+      # not closed or otherwise disposed. Calling this again after retirement is safe.
+      # @return [self]
+      # @raise [Farce::OwnershipError] unless the current Fiber owns the checkout
+      def retire
+        internal_lease.retire
+        self
+      end
+
+      # @return [Boolean] whether the resource is available for checkout
+      def available? = internal_lease.available?
+
+      # @return [Boolean] whether the resource is checked out
+      def checked_out? = internal_lease.checked_out?
+
+      # @return [Boolean] whether the current Fiber owns the checkout
+      def owned? = internal_lease.owned?
+
+      # @return [Boolean] whether the lease has been permanently retired
+      def retired? = internal_lease.retired?
+
+      # @api private
+      def inspect_with(inspector)
+        super do
+          yield if block_given?
+          inspector.breakable
+          next inspector.text("checked_out") if checked_out?
+          next inspector.text("available")   if available?
+          next inspector.text("retired")     if retired?
+          inspector.text("unknown")
+        end
+      end
+
+      private
+
+      def checkout_with_handoff(...)       = internal_lease.checkout_with_handoff(...)
+      def try_checkout_with_handoff(...)   = internal_lease.try_checkout_with_handoff(...)
+      def checkin_scope(resource)          = internal_lease.checkin_scope(resource)
+      def explicitly_owned?                = internal_lease.explicitly_owned?
+      def mark_scope_managed               = internal_lease.mark_scope_managed
+      def scope_managed?                   = internal_lease.scope_managed?
+      def owned_resource                   = internal_lease.owned_resource
+      def replace_owned_resource(resource) = internal_lease.replace_owned_resource(resource)
+      def internal_lease                   = @lease
+      def new_internal_lease(_)            = raise(NoMethodError, "abstract lease storage")
+    end
+  end
+end