farce 0.0.1.alpha2-x86_64-linux-gnu

data/lib/farce/_yard/ractor.rb

@@ -0,0 +1,46 @@
+return if true
+
+# @!visibility private
+class Ractor
+end
+
+module Farce
+  module Ractor
+    # Either `Ractor::Port` or a shim for it. It is recommended to use {Farce::Port Farce::Port} instead,
+    # which will always be a subclass of this class, but has added safety and functionality.
+    class Port
+      # Closes the port. Sending to a closed port is prohibited. Receiving is also prohibited if there are no
+      # messages in its message queue. Only the Ractor which created the port is allowed to close it.
+      # @return [void]
+      def close = super
+  
+      # Checks it the port is closed.
+      # @return [Boolean] `true` if the port is closed, `false` otherwise.
+      # @see #close
+      def closed? = super
+  
+      # @overload receive
+      #   Receives a message from the port.
+      #   @return [BasicObject] The received message.
+      # @overload receive(timeout: nil)
+      #   Receives a message from the port. Blocks until a message is available or the timeout is reached.
+      #   @note
+      #     Use {Farce::Port Farce::Port} instead to guarantee a timeout argument on all Ruby implementations.
+      #   @ruby CRuby 4.1+, JRuby, TruffleRuby
+      #   @param timeout [Numeric, nil] The timeout in seconds, or `nil` for no timeout.
+      #   @return [BasicObject, nil] The received message, or `nil` if the timeout has been reached.
+      #
+      # @return [BasicObject]
+      # @raise [Farce::Ractor::ClosedError] if the port is closed and there are no messages in the queue.
+      def receive = super
+  
+      # Sends a message over the port.
+      # @param message [BasicObject] The message to send.
+      # @param move [Boolean] Whether to move the message to the Ractor if it isn't sharable.
+      # @return [self]
+      # @raise [Farce::Ractor::ClosedError] if the port is closed.
+      def send(message, move: false) = super
+      alias << send
+    end
+  end
+end

data/lib/farce/abstract/atom.rb

@@ -0,0 +1,186 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Abstract
+    # @abstract Common interface and behavior for atomic references.
+    #
+    # Concrete implementations decide how values are retained and transferred.
+    # A value may become `nil` without an explicit update when an implementation
+    # retains it weakly.
+    class Atom
+      include Internal::MarshalSupport::Atom
+      include Internal::Copyable
+      include Internal::Inspect
+      include Value
+      include Internal::ValueSerialization
+
+      # @api private
+      def transaction_wrapper(transaction) = Transaction::Atom.new(transaction, self, internal_atom)
+
+      # Whether comparisons use object identity instead of equality.
+      # @return [Boolean]
+      def compare_by_identity? = internal_atom.compare_by_identity?
+
+      # Return the current value without waiting for an update in progress.
+      # @return [BasicObject, nil] the current value
+      def value = internal_atom.value
+
+      # Store a new value.
+      # @param new_value [BasicObject, nil] the new value
+      # @return [BasicObject, nil] the new value
+      def value=(new_value)
+        store(new_value)
+      end
+
+      # Return the current value, waiting for any update in progress.
+      # @param timeout [Numeric, nil] the maximum number of seconds to wait
+      # @yield called when the timeout expires
+      # @return [BasicObject, nil] the current value or the fallback result
+      def get(timeout: nil, &) = internal_atom.get(timeout:, &)
+
+      # Store a new value, waiting for any update in progress.
+      # @param new_value [BasicObject, nil] the new value
+      # @param timeout [Numeric, nil] the maximum number of seconds to wait
+      # @yield called when the timeout expires
+      # @return [BasicObject, nil] the stored value or the fallback result
+      def store(new_value, timeout: nil, &) = internal_atom.store(new_value, timeout:, &)
+
+      # Replace the current value and return the previous value.
+      # @param new_value [BasicObject, nil] the new value
+      # @param timeout [Numeric, nil] the maximum number of seconds to wait
+      # @yield called when the timeout expires
+      # @return [BasicObject, nil] the previous value or the fallback result
+      def swap(new_value, timeout: nil, &) = internal_atom.swap(new_value, timeout:, &)
+
+      # Compute and store a value if the current value is nil.
+      # @param timeout [Numeric, nil] the maximum number of seconds to wait
+      # @yield computes the value to store when the current value is nil
+      # @yieldreturn [BasicObject, nil] the value to store
+      # @return [BasicObject, nil] the current or newly stored value, or nil when the timeout expires
+      def store_if_absent(timeout: nil, &) = internal_atom.store_if_absent(timeout:, &)
+
+      # Atomically replace the current value if it matches the expected value.
+      # @param expected [BasicObject, nil] the value to compare with the current value
+      # @param new_value [BasicObject, nil] the replacement value
+      # @param timeout [Numeric, nil] the maximum number of seconds to wait
+      # @return [Boolean] whether the value was replaced
+      def compare_and_set(expected, new_value, timeout: nil)
+        internal_atom.compare_and_set(expected, new_value, timeout:)
+      end
+
+      # Atomically replace the current value with the result of a block.
+      # @param timeout [Numeric, nil] the maximum number of seconds to wait
+      # @yield receives the current value and computes its replacement
+      # @yieldparam current [BasicObject, nil] the current value
+      # @yieldreturn [BasicObject, nil] the replacement value
+      # @return [BasicObject, nil] the replacement value, or nil when the timeout expires
+      def update(timeout: nil, &) = internal_atom.update(timeout:, &)
+
+      # Store an initial value if the current value is nil, otherwise replace it with the result of a block.
+      # @param initial_value [BasicObject, nil] the value to store when the current value is nil
+      # @param timeout [Numeric, nil] the maximum number of seconds to wait
+      # @yield receives a non-nil current value and computes its replacement
+      # @yieldparam current [BasicObject] the current value
+      # @yieldreturn [BasicObject, nil] the replacement value
+      # @return [BasicObject, nil] the replacement or initial value, or nil when the timeout expires
+      def upsert(initial_value, timeout: nil, &) = internal_atom.upsert(initial_value, timeout:, &)
+
+      # Wait until a block condition matches the current value.
+      # One timeout budget covers all checks and waits. The block is not interrupted.
+      # @yieldparam value [BasicObject, nil] the current value
+      # @yieldreturn [Boolean] whether the value matches
+      # @param timeout [Numeric, nil] the total seconds available
+      # @return [BasicObject, nil] the matching value, or nil on timeout
+      # @raise [LocalJumpError] if no block is given
+      def wait_until(timeout: nil, &) = Internal.wait_until(self, timeout:, &)
+
+      # Wait while the block returns a truthy value.
+      # @yieldparam value [BasicObject, nil] the current value
+      # @yieldreturn [BasicObject] a truthy value to keep waiting, or nil or false to stop
+      # @param timeout [Numeric, nil] the total seconds available
+      # @return [BasicObject, nil] the value when the condition becomes false, or nil on timeout
+      # @raise [LocalJumpError] if no block is given
+      def wait_while(timeout: nil)
+        raise LocalJumpError, "no block given" unless block_given?
+        wait_until(timeout:) { |value| !yield(value) }
+      end
+
+      # Wait while `object === value` is true.
+      # @param object [#===] the pattern to stop matching
+      # @param timeout [Numeric, nil] the total seconds available
+      # @return [BasicObject, nil] the first nonmatching value, or nil on timeout
+      def wait_while_match(object, timeout: nil)
+        wait_while(timeout:) { |value| object === value } # rubocop:disable Style/CaseEquality
+      end
+
+      # (see #wait_until_changed)
+      def wait_while_value(...) = wait_until_changed(...)
+
+      # Wait until the current value equals an object using the configured comparison mode.
+      # @param object [BasicObject, nil] the value to compare with the current value
+      # @param timeout [Numeric, nil] the total seconds available
+      # @return [BasicObject, nil] the matching value, or nil on timeout
+      def wait_until_value(object, timeout: nil)
+        wait_until(timeout:) { |value| compare_by_identity? ? object.equal?(value) : object == value }
+      end
+
+      # Wait until `object === value` is true.
+      # @param object [#===] the pattern to match
+      # @param timeout [Numeric, nil] the total seconds available
+      # @return [BasicObject, nil] the matching value, or nil on timeout
+      def wait_until_match(object, timeout: nil)
+        wait_until(timeout:) { |value| object === value } # rubocop:disable Style/CaseEquality
+      end
+
+      # Wait until the current value no longer matches an expected value.
+      # @param expected [BasicObject, nil] the value to compare with the current value
+      # @param timeout [Numeric, nil] the maximum number of seconds to wait
+      # @yield called when the timeout expires
+      # @return [BasicObject, nil] the changed value or the fallback result
+      def wait_until_changed(expected, timeout: nil, &)
+        internal_atom.wait_until_changed(expected, timeout:, &)
+      end
+
+      # Wait until the current value is not nil.
+      # @param timeout [Numeric, nil] the maximum number of seconds to wait
+      # @yield called when the timeout expires
+      # @return [BasicObject, nil] the non-nil value or the fallback result
+      def wait_until_non_nil(timeout: nil, &) = internal_atom.wait_until_non_nil(timeout:, &)
+
+      # @api private
+      def inspect_with(inspector)
+        super do
+          yield if block_given?
+          inspect_value(inspector)
+        end
+      end
+
+      protected
+
+      def internal_atom = @atom
+
+      private
+
+      def inspect_value(inspector, prefix = "value=")
+        if prefix
+          inspector.breakable
+          inspector.text(prefix)
+        end
+        inspector.object(value)
+      end
+
+      def initialize_copy(other)
+        super
+        source = other.internal_atom
+        copy   = source.class.new(source.value, compare_by_identity: source.compare_by_identity?)
+        if is_a?(Local::Scoped)
+          Internal::Storage.scope(scope)[self] = copy
+        else
+          @atom = copy
+        end
+      end
+    end
+  end
+end

data/lib/farce/abstract/bounded_map.rb

@@ -0,0 +1,232 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Abstract
+    # @abstract Superclass for maps that retain at most a configured number of entries.
+    #
+    # Successful individual value reads and writes update the map's eviction policy.
+    # Observational operations such as iteration, {#key?}, and {#getkey} do not.
+    # Copies preserve capacity and eviction history without counting copying as an access.
+    class BoundedMap < Map
+      include DuplicableMap
+
+      # @param entries [Hash, Array<Array(BasicObject, BasicObject)>, Map, #each, nil]
+      #   Optional initial entries. Entries are stored sequentially and may be evicted.
+      # @param max_size [Integer] Maximum number of retained entries.
+      # @!macro key_normalization
+      # @param compare_by_identity [Boolean] Whether keys and values are compared by identity.
+      # @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(
+        entries = nil,
+        max_size:,
+        normalize_keys: nil,
+        compare_by_identity: false,
+        compare_keys_by_identity: compare_by_identity,
+        compare_values_by_identity: compare_by_identity
+      )
+        entries = convert_entries(entries)
+        @map    = new_bounded_map(
+          max_size:,
+          compare_by_identity:,
+          compare_keys_by_identity:,
+          compare_values_by_identity:,
+        )
+        @key_locks = new_key_locks(compare_keys_by_identity:)
+        restoring  = Internal::KeyNormalizer.restoration?(normalize_keys)
+        normalizer = Internal::KeyNormalizer.build(
+          normalize_keys,
+          shareable: normalize_keys && Internal::KeyNormalizer.shareable_target?(self),
+        )
+        Internal::KeyNormalizer.install(self, normalizer, Internal::KeyNormalizer::BoundedOperations) unless restoring
+        entries&.each { self[_1] = _2 }
+        Internal::KeyNormalizer.install(self, normalizer, Internal::KeyNormalizer::BoundedOperations) if restoring
+        super()
+      end
+
+      # (see Map#[])
+      def [](key) = unwrap_value(internal_map[prepare_key(key)])
+
+      # (see Map#[]=)
+      def []=(key, value)
+        key = prepare_store_key(key)
+        with_key_lock(key) { internal_map[key] = wrap_value(value) }
+        value
+      end
+
+      # Return an existing value, or store the block result for an absent key.
+      # Coordinated implementations share one initialization among concurrent
+      # callers for equal keys. Unsafe implementations can run competing loaders.
+      # The block runs without holding the map's structural lock, so other keys
+      # remain accessible. Coordinated assignment waits for initialization.
+      # Deletion or clearing can precede a pending initialization's insertion.
+      # At zero capacity, coordinated implementations run equal-key loaders
+      # sequentially. Each loader validates and transfers its result, but the
+      # map retains no value.
+      # @param key [BasicObject] The key to retrieve or initialize.
+      # @yieldreturn [BasicObject] The value to store.
+      # @return [BasicObject] The existing or newly stored value.
+      # @raise [LocalJumpError] If no block is given, even when the key exists.
+      # @raise [ThreadError] If coordinated initialization recursively accesses its own gate.
+      def store_if_absent(key)
+        raise LocalJumpError, "no block given" unless block_given?
+
+        map    = internal_map
+        found  = true
+        stored = map.fetch(prepare_key(key)) { found = false }
+        return unwrap_value(stored) if found
+
+        key = prepare_store_key(key)
+        with_key_lock(key) do
+          stored     = map.fetch(key) do
+            wrapped  = wrap_value(yield)
+            map[key] = wrapped
+            return unwrap_value(wrapped)
+          end
+          unwrap_value(stored)
+        end
+      end
+
+      # (see Map#clear)
+      def clear
+        internal_map.clear
+        self
+      end
+
+      # (see Map#compare_keys_by_identity?)
+      def compare_keys_by_identity? = internal_map.compare_keys_by_identity?
+
+      # (see Map#compare_values_by_identity?)
+      def compare_values_by_identity? = internal_map.compare_values_by_identity?
+
+      # (see Map#delete)
+      def delete(key) = unwrap_value(internal_map.delete(prepare_key(key)))
+
+      # (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
+        prepared_key = prepare_key(key)
+        warn "block supersedes default value argument", uplevel: 1 if block_given? && arguments.length == 2
+        value = internal_map.fetch(prepared_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
+
+      # (see Map#getkey)
+      def getkey(key) = internal_map.getkey(prepare_key(key))
+
+      # (see Map#key?)
+      def key?(key) = internal_map.key?(prepare_key(key))
+
+      # Return the maximum number of entries retained by the current backing map.
+      # @return [Integer]
+      def max_size = internal_map.max_size
+
+      # Change the maximum number of retained entries and immediately evict any excess.
+      # @param limit [Integer] The new non-negative capacity.
+      # @return [Integer] `limit`
+      def max_size=(limit)
+        internal_map.max_size = limit
+      end
+
+      # Remove entries selected by the eviction policy until at most `to` remain.
+      # This does not change {#max_size}.
+      # @param to [Integer] The non-negative target size.
+      # @return [Integer] Number of entries removed.
+      def prune(to:) = internal_map.prune(to:)
+
+      # Remove and return the next entry selected by the eviction policy.
+      # @return [Array(BasicObject, BasicObject), nil]
+      def shift
+        pair = internal_map.shift
+        [pair.first, unwrap_value(pair.last)] if pair
+      end
+
+      # (see Map#size)
+      def size = internal_map.size
+      alias length size
+
+      # Iterate over a snapshot without updating eviction history.
+      # @overload each
+      #   @yield [pair] Called once for each entry.
+      #   @yieldparam pair [Array<BasicObject>] A two-element `[key, value]` pair.
+      #   @return [self]
+      # @overload each
+      #   @return [Enumerator]
+      def each
+        return enum_for(__method__) unless block_given?
+        internal_map.each { |key, value| yield [key, unwrap_value(value)] }
+        self
+      end
+      alias each_pair each
+
+      # Iterate over a snapshot of stored keys without updating eviction history.
+      # @return [self, Enumerator]
+      def each_key
+        return enum_for(__method__) unless block_given?
+        internal_map.each_key { yield it }
+        self
+      end
+
+      # Iterate over a snapshot of stored values without updating eviction history.
+      # @return [self, Enumerator]
+      def each_value
+        return enum_for(__method__) unless block_given?
+        internal_map.each_value { yield unwrap_value(it) }
+        self
+      end
+
+      # Return a frozen snapshot of stored keys.
+      # @return [Array<BasicObject>]
+      def keys = each_key.to_a.freeze
+
+      # Return a frozen snapshot of stored values.
+      # @return [Array<BasicObject>]
+      def values = each_value.to_a.freeze
+
+      private
+
+      def copy_map_backend(source, empty: false)
+        return source.dup unless empty
+        source.class.new(
+          max_size:                   source.max_size,
+          compare_keys_by_identity:   source.compare_keys_by_identity?,
+          compare_values_by_identity: source.compare_values_by_identity?,
+        )
+      end
+
+      def install_copied_map(map)
+        super
+        @key_locks = new_key_locks(compare_keys_by_identity: map.compare_keys_by_identity?)
+      end
+
+      def each_for_inspect(&)    = each(&)
+      def prepare_key(key)       = key
+      def prepare_store_key(key) = internal_map.prepare_key(prepare_key(key))
+      def with_key_lock(key, &)  = @key_locks.synchronize(key, &)
+
+      # simplecov:disable
+      def new_key_locks(...)
+        raise "subclass failed to implement #new_key_locks" unless instance_of?(BoundedMap)
+        raise NoMethodError, "Farce::Abstract::BoundedMap should not be instantiated directly. Use a subclass instead."
+      end
+      # simplecov:enable
+
+      # simplecov:disable
+      def new_bounded_map(...)
+        raise "subclass failed to implement #new_bounded_map" unless instance_of?(BoundedMap)
+        raise NoMethodError, "Farce::Abstract::BoundedMap should not be instantiated directly. Use a subclass instead."
+      end
+      # simplecov:enable
+    end
+  end
+end

data/lib/farce/abstract/collection.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Abstract
+    # @abstract Superclass for a collection of elements.
+    #
+    # Subclasses define traversal, comparison, and insertion rules.
+    # They may accept additional optional parameters for the methods below.
+    #
+    # Notable subclasses include {Vector}, {Set}, and {SortedSet}.
+    #
+    # @!method each
+    #   Iterate over the elements currently present.
+    #   @yield [element] Visit each element. Returns an Enumerator without a block.
+    #   @yieldparam element [BasicObject] The current element.
+    #   @yieldreturn [void] The result is ignored.
+    #   @return [self, Enumerator] Self, or a sized Enumerator without a block.
+    #   @abstract
+    #
+    # @!method size
+    #   Return the number of elements currently present.
+    #   @return [Integer] The number of elements.
+    #   @abstract
+    #
+    # @!method to_a
+    #   Return the observed elements in a new Array.
+    #   @return [Array<BasicObject>] The observed elements.
+    #   @abstract
+    #
+    # @!method clear
+    #   Remove all elements and return self.
+    #   @return [self] The collection.
+    #   @abstract
+    #
+    # @!method include?(element)
+    #   Return whether an element is present using the collection's membership rules.
+    #   @param element [BasicObject] The element to look up.
+    #   @return [Boolean] Whether the element is present.
+    #   @abstract
+    #
+    # @!method member?(element)
+    #   Return whether an element is present, as with {#include?}.
+    #   @param element [BasicObject] The element to look up.
+    #   @return [Boolean] Whether the element is present.
+    #   @see #include?
+    #   @abstract
+    #
+    # @!method compare_by_identity?
+    #   Return whether elements are compared by object identity.
+    #   @return [Boolean] Whether identity comparison is enabled.
+    #   @abstract
+    #
+    # @!method select
+    #   Return a collection of the same kind containing elements accepted by the block.
+    #   @yield [element] Test each element. Returns an Enumerator without a block.
+    #   @yieldparam element [BasicObject] The current element.
+    #   @yieldreturn [BasicObject] A truthy value to retain the element.
+    #   @return [Farce::Abstract::Collection, Enumerator] A new collection, or an Enumerator without a block.
+    #   @abstract
+    #
+    # @!method filter
+    #   Return elements accepted by the block, as with {#select}.
+    #   @yield [element] Test each element. Returns an Enumerator without a block.
+    #   @yieldparam element [BasicObject] The current element.
+    #   @yieldreturn [BasicObject] A truthy value to retain the element.
+    #   @return [Farce::Abstract::Collection, Enumerator] A new collection of the same kind, or an Enumerator.
+    #   @see #select
+    #   @abstract
+    #
+    # @!method reject
+    #   Return a collection of the same kind excluding elements accepted by the block.
+    #   @yield [element] Test each element. Returns an Enumerator without a block.
+    #   @yieldparam element [BasicObject] The current element.
+    #   @yieldreturn [BasicObject] A truthy value to exclude the element.
+    #   @return [Farce::Abstract::Collection, Enumerator] A new collection, or an Enumerator without a block.
+    #   @abstract
+    #
+    # @!method <<(element)
+    #   Add an element using the collection's insertion rules and return self.
+    #   @param element [BasicObject] The element to add.
+    #   @return [self] The collection.
+    #   @abstract
+    class Collection
+      include Enumerable
+      include Internal::Copyable
+      include Internal::Inspect
+
+      # @overload [](*elements, **options)
+      #   Construct a collection from the arguments.
+      #   @param elements [Array<BasicObject>] The initial elements.
+      #   @param **options [Hash] Additional options passed to the constructor.
+      #   @return [Farce::Abstract::Collection] A new instance of the receiving class.
+      def self.[](*elements, **) = new(elements, **)
+
+      # Return the number of elements currently present.
+      # @return [Integer] The collection's size.
+      def length = size
+
+      # Return whether no elements are present.
+      # @return [Boolean] Whether the collection is empty.
+      def empty? = size.zero?
+
+      # Count all elements, matching elements, or elements accepted by a block.
+      # Without an argument or block, read the size without traversing elements.
+      # @param item [BasicObject] The value to count. Omit to count all elements or use the block.
+      # @yield [element] Select elements to count when item is omitted.
+      # @yieldparam element [BasicObject] The current element.
+      # @yieldreturn [BasicObject] A truthy value to count the element.
+      # @return [Integer] The number of matching elements.
+      def count(item = UNDEFINED)
+        return size if item.equal?(UNDEFINED) && !block_given?
+
+        if item.equal?(UNDEFINED)
+          super() { yield it }
+        else
+          warn("given block not used") if block_given?
+          super(item, &nil)
+        end
+      end
+
+      # Join the elements through Array#join.
+      # @param separator [String, nil] The separator. Nil uses Array's default separator.
+      # @return [String] The joined elements.
+      def join(separator = nil) = to_a.join(separator)
+
+      # @return [String] The class name and observed elements, suitable for debugging.
+      def to_s = inspect
+
+      # @api private
+      def inspect_with(inspector)
+        super do
+          yield if block_given?
+          inspector.breakable
+          inspector.group("[", "]") do
+            inspector.breakable ""
+            inspector.seplist(self, nil, :each_for_inspect) do |value|
+              inspector.group { inspect_value(inspector, value) }
+            end
+          end
+        end
+      end
+
+      private
+
+      def each_for_inspect(&)           = each(&)
+      def inspect_value(inspector, ...) = inspector.object(...)
+    end
+  end
+end