farce 0.0.1.alpha2-x86_64-linux-gnu

data/lib/farce/abstract/sorted_set.rb

@@ -0,0 +1,172 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Abstract
+    # @abstract A set maintained in ascending comparator order.
+    # Membership, insertion, and deletion use `<=>`. Two elements occupy the
+    # same slot when their comparison returns zero. Elements must be mutually
+    # comparable and must not change their ordering while stored. Incompatible
+    # elements raise during insertion or lookup.
+    class SortedSet < Set
+      # Construct a set in ascending comparator order.
+      # @overload initialize(enumerable = nil, normalize: nil, compare_by_identity: false, mode: :copy, **options)
+      #   @param enumerable [#each, nil] The initial elements, or nil for an empty set.
+      #   @param normalize [Symbol, Proc, Hash, Farce::Abstract::Map, nil] The element normalizer.
+      #   @param compare_by_identity [Boolean] Must be false. Membership uses <=>.
+      #   @param mode [Symbol] The default transfer mode. Only Farce::SortedSet accepts
+      #     this option, which defaults to :copy.
+      #   @param options [Hash] Additional options for the selected variant.
+      #   @option options [Symbol] scope (:ractor) The scope used by Farce::Local::SortedSet.
+      #   @yield [element] Optionally transform each initial element before normalization.
+      #   @yieldparam element [BasicObject] An element from enumerable.
+      #   @yieldreturn [BasicObject] The comparable element to normalize and store.
+      #   @return [Farce::Abstract::SortedSet] The new sorted set.
+      #   @raise [ArgumentError] If compare_by_identity is true.
+      #   @see Farce::Abstract::Set#initialize Additional options for Local variants.
+      def initialize(
+        enumerable = nil, normalize: nil, compare_by_identity: false, mode: UNDEFINED, **, &transform
+      )
+        raise ArgumentError, "sorted sets do not support identity comparison" if compare_by_identity
+        super(enumerable, normalize:, compare_by_identity: false, mode:, **, &transform)
+      end
+
+      # @api private
+      def transaction_wrapper(transaction) = Transaction::SortedSet.new(transaction, self, @map)
+
+      # Return whether this set has comparator-equivalent members in the same order.
+      # @param other [BasicObject] The object to compare against.
+      # @return [Boolean] Whether other is a Farce sorted set with comparator-equivalent members.
+      def ==(other)
+        return true if equal?(other)
+        return false unless other.is_a?(Abstract::SortedSet) && size == other.size
+        ordered_keys.zip(other.ordered_keys).all? { comparator_equal?(_1, _2) }
+      end
+
+      # Compare canonical ordered members using eql?.
+      # @param other [BasicObject] The object to compare against.
+      # @return [Boolean] Whether other is a Farce sorted set with eql? ordered members.
+      def eql?(other)
+        return true if equal?(other)
+        other.is_a?(Abstract::SortedSet) && ordered_keys.eql?(other.ordered_keys)
+      end
+
+      # Return a hash derived from the canonical ordered members.
+      # @return [Integer] The hash code.
+      def hash = ordered_keys.hash
+
+      # Remove every comparator-equivalent member yielded by enumerable.
+      # @param enumerable [#each] The elements to normalize and remove by comparison.
+      # @return [self] The set.
+      def subtract(enumerable)
+        check_frozen!
+        if ordered_compatible?(enumerable)
+          enumerable.each_stored { |key, _| @map.delete(key) }
+        else
+          each_input(enumerable) do |element|
+            key = lookup_key(normalize_element(element))
+            @map.delete(key) unless MISSING_KEY.equal?(key)
+          end
+        end
+        self
+      end
+
+      # Return a same-kind set containing members present by comparator in every input.
+      # @param enumerables [Array<#each>] The collections whose comparator-equivalent members must be present.
+      # @return [Farce::Abstract::SortedSet] A new sorted set of the same class with the same settings.
+      def intersection(*enumerables)
+        indexes = enumerables.map { ordered_index(it) }
+        dup.filter_stored! { |key, _| indexes.all? { it.key?(key) } }
+      end
+      alias & intersection
+
+      # Return whether every member has a comparator-equivalent member in other.
+      # @param other [Farce::Abstract::Set, ::Set] The set to compare against.
+      # @return [Boolean] Whether the comparator-based relation holds.
+      # @raise [ArgumentError] If other is not a Farce or Ruby set.
+      def subset?(other)
+        validate_set_like(other)
+        index = ordered_index(other)
+        size <= index.size && ordered_keys.all? { index.key?(it) }
+      end
+      alias <= subset?
+
+      # Return whether this is a proper comparator subset of other.
+      # @param other [Farce::Abstract::Set, ::Set] The set to compare against.
+      # @return [Boolean] Whether the comparator-based relation holds.
+      # @raise [ArgumentError] If other is not a Farce or Ruby set.
+      def proper_subset?(other)
+        validate_set_like(other)
+        index = ordered_index(other)
+        size < index.size && ordered_keys.all? { index.key?(it) }
+      end
+      alias < proper_subset?
+
+      # Return whether every member of other has a comparator-equivalent member here.
+      # @param other [Farce::Abstract::Set, ::Set] The set to compare against.
+      # @return [Boolean] Whether the comparator-based relation holds.
+      # @raise [ArgumentError] If other is not a Farce or Ruby set.
+      def superset?(other)
+        validate_set_like(other)
+        index = ordered_index(other)
+        size >= index.size && index.keys.all? { @map.key?(it) }
+      end
+      alias >= superset?
+
+      # Return whether this is a proper comparator superset of other.
+      # @param other [Farce::Abstract::Set, ::Set] The set to compare against.
+      # @return [Boolean] Whether the comparator-based relation holds.
+      # @raise [ArgumentError] If other is not a Farce or Ruby set.
+      def proper_superset?(other)
+        validate_set_like(other)
+        index = ordered_index(other)
+        size > index.size && index.keys.all? { @map.key?(it) }
+      end
+      alias > proper_superset?
+
+      # Return whether another set has a comparator-equivalent member.
+      # @param other [Farce::Abstract::Set, ::Set] The set to compare against.
+      # @return [Boolean] Whether the comparator-based relation holds.
+      # @raise [ArgumentError] If other is not a Farce or Ruby set.
+      def intersect?(other)
+        validate_set_like(other)
+        index = ordered_index(other)
+        left, right = size <= index.size ? [ordered_keys, index] : [index.keys, @map]
+        left.any? { right.key?(it) }
+      end
+
+      protected
+
+      def ordered_keys = @map.keys
+      def ordered?     = true
+
+      private
+
+      def ordered_compatible?(other)
+        canonical_compatible?(other) && other.is_a?(Abstract::SortedSet)
+      end
+
+      def ordered_index(enumerable)
+        index = new_map(nil, compare_keys_by_identity: false, **copy_map_options(self))
+        if ordered_compatible?(enumerable)
+          enumerable.each_stored { |key, _| index[key] = true }
+        else
+          each_input(enumerable) do |element|
+            key        = lookup_key(normalize_element(element))
+            index[key] = true unless MISSING_KEY.equal?(key)
+          end
+        end
+        index
+      end
+
+      def comparator_equal?(left, right)
+        comparison = left <=> right
+        return comparison.zero? if comparison
+        raise ArgumentError, "comparison of #{left.class} with #{right.class} failed"
+      end
+
+      def identity_membership?(_element) = false
+    end
+  end
+end

data/lib/farce/abstract/timer_queue.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Abstract
+    # @abstract Shared timer scheduling and blocking behavior.
+    class TimerQueue < Queue
+      include Internal::BlockingPriorityQueue
+
+      # @param capacity [Integer, nil] the maximum number of values, or nil for an unbounded queue
+      def initialize(capacity: nil, track_age: false)
+        super
+      end
+
+      # Add a value to become available at the given time.
+      # @param value [BasicObject] the value to add
+      # @param non_block [Boolean] whether to raise an exception when the queue is at capacity
+      # @param timeout [Numeric, nil] maximum number of seconds to wait for capacity
+      # @param time_options [Hash{Symbol => Object}] a scheduling option accepted by {Clock.parse}:
+      #   `at:`, `time:`, `timeout_at:`, `delay:`, `in:`, `offset:`, `wait:`, or `clock:`.
+      #   With no scheduling option, the value is available immediately. Since `timeout:` controls the capacity wait,
+      #   use `delay:` or `wait:` to schedule a relative offset.
+      # @raise [ThreadError] when the queue is at capacity and non_block is true
+      # @return [Boolean] whether the value was added
+      def push(value, non_block = false, timeout: nil, **time_options) # rubocop:disable Style/OptionalBooleanParameter
+        at = Clock.parse(time_options)
+        push_to_storage(at, non_block, value, timeout:)
+      end
+
+      # Remove the earliest value, waiting until its timestamp is reached.
+      # @param timeout [Numeric, nil] maximum number of seconds to wait
+      # @yield called when the timeout expires first
+      # @return [BasicObject, nil] the value or the fallback result
+      def pop(non_block = false, timeout: nil) # rubocop:disable Style/OptionalBooleanParameter
+        return try_pop { raise ThreadError, "queue empty" } if non_block
+        deadline = timeout_at(timeout) unless timeout.nil?
+
+        while true
+          empty = false
+          value = internal_queue.pop_before(Clock.now) { empty = true }
+          return value unless empty
+          return block_given? ? yield : nil if UNDEFINED.equal?(wait_for_timestamp(deadline))
+        end
+      end
+
+      # Try to add a value without waiting for capacity.
+      # @param value [BasicObject] the value to add
+      # @param time_options [Hash{Symbol => Object}] a scheduling option accepted by {Clock.parse}:
+      #   `at:`, `time:`, `timeout_at:`, `delay:`, `in:`, `offset:`, `timeout:`, `wait:`, or `clock:`.
+      #   With no scheduling option, the value is available immediately.
+      # @yield called when the queue is at capacity
+      # @return [Boolean, BasicObject] true, or the fallback result when full
+      def try_push(value, **time_options)
+        at = Clock.parse(time_options)
+        return true if internal_queue.push(at, value)
+        block_given? ? yield : false
+      end
+
+      # Try to remove the earliest value only if its timestamp has been reached.
+      # @yield called when no value is ready
+      # @return [BasicObject, nil] the value or the fallback result
+      def try_pop(&) = internal_queue.pop_before(Clock.now, &)
+
+      # Return the earliest value without removing it, whether or not it is due.
+      # @yield called when the queue is empty
+      # @return [BasicObject, nil] the value or the fallback result
+      def peek(&) = internal_queue.peek(&)
+
+      # Return the earliest timestamp without removing it.
+      # @yield called when the queue is empty
+      # @return [Float, nil] the timestamp or the fallback result
+      def first_timestamp(&) = internal_queue.peek_priority(&)
+
+      # Return the latest timestamp without removing it.
+      # @yield called when the queue is empty
+      # @return [Float, nil] the timestamp or the fallback result
+      def last_timestamp(&) = internal_queue.peek_last_priority(&)
+
+      # Checks whether the earliest timestamp has been reached.
+      # @param leeway [Numeric] how much leeway to allow for clock drift and scheduling delays
+      def overdue?(leeway: 0)
+        return false unless timestamp = first_timestamp
+        timestamp <= Clock.in(leeway)
+      end
+
+      # Returns how long the earliest timestamp has been overdue, or nil if it is not yet due.
+      # @param leeway [Numeric] how much leeway to allow for clock drift and scheduling delays
+      # @return [Float, nil] the number of seconds overdue, or nil if the earliest timestamp is not yet due
+      def overdue_by(leeway: 0)
+        return unless timestamp = first_timestamp
+        delay = Clock.now - timestamp
+        delay > leeway ? delay : nil
+      end
+
+      # Wait until the earliest timestamp is reached without removing its value.
+      # @param timeout [Numeric, nil] maximum number of seconds to wait
+      # @return [Boolean] whether a value is ready
+      def wait_pop(timeout: nil) # rubocop:disable Naming/PredicateMethod
+        !UNDEFINED.equal?(wait_for_timestamp(timeout_at(timeout)))
+      end
+
+      # Delete the oldest matching value at the exact time.
+      # @param value [BasicObject] the value to delete
+      # @param at [Numeric, Time] the exact time to search
+      # @param compare_by_identity [Boolean] compare values by identity instead of equality
+      # @return [Boolean] whether a value was deleted
+      def delete(value, at:, compare_by_identity: false)
+        delete_from_storage(Clock.at(at), value, compare_by_identity:)
+      end
+
+      private
+
+      def wait_for_timestamp(deadline)
+        while true
+          generation = internal_signal.generation
+          timestamp = internal_queue.peek_priority
+          wake_after = nil
+          if timestamp
+            delay = timestamp - Clock.now
+            return timestamp unless delay.positive?
+            wake_after = delay if delay.finite?
+          end
+
+          remaining = remaining_timeout(deadline)
+
+          wait_for = wake_after && remaining ?
+            (wake_after < remaining ? wake_after : remaining) :
+            wake_after || remaining
+          changed = internal_signal.wait(generation, timeout: wait_for)
+          return UNDEFINED if !changed && deadline && remaining_timeout(deadline).zero?
+        end
+      end
+    end
+  end
+end

data/lib/farce/abstract/tree_map.rb

@@ -0,0 +1,269 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Abstract
+    # @abstract Superclass for all tree map implementations.
+    #
+    # You can think of a tree map as a sorted hash (sorted by key).
+    # Under the hood, tree maps are implemented as a balanced binary search tree.
+    #
+    # This means lookups, insertions, and deletions are O(log n) operations (vs O(1) for a hash map).
+    # This is much slower than a hash map, but much faster than ad hoc sorting of the map.
+    class TreeMap < Map
+      include DuplicableMap
+
+      # @note Subclasses may accept additional, optional arguments (usually keyword arguments) to configure the map.
+      # @param entries [Hash, Array<Array(BasicObject, BasicObject)>, Map, #each, nil]
+      #   Optional initial entries for the map. Needs to implement #each and yield key-value pairs.
+      #   If nil, the map will be empty.
+      # @!macro key_normalization
+      def initialize(entries = nil, normalize_keys: nil, **keyword_entries)
+        unless keyword_entries.empty?
+          raise ArgumentError, "entries given as both positional and keyword arguments" unless entries.nil?
+          entries = keyword_entries
+        end
+        entries = convert_entries(entries)
+        @map       = new_tree_map
+        @key_locks = new_key_locks
+        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::TreeOperations) unless restoring
+        entries&.each { self[_1] = _2 }
+        Internal::KeyNormalizer.install(self, normalizer, Internal::KeyNormalizer::TreeOperations) if restoring
+        super()
+      end
+
+      # @api private
+      def transaction_wrapper(transaction)
+        transaction.enlist(transaction_key_locks)
+        manager = @manager if defined?(@manager)
+        Transaction::TreeMap.new(transaction, self, internal_map, manager:)
+      end
+
+      # (see Map#[])
+      def [](key) = unwrap_value(internal_map[prepare_key(key)])
+
+      # (see Map#[]=)
+      def []=(key, value)
+        key = internal_map.prepare_key(prepare_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.
+      # Concurrent callers for equally ordered keys share one initialization.
+      # The block runs without holding the map's structural lock. Other keys
+      # remain accessible. Assigning the same key waits for initialization.
+      # Deletion or clearing can precede a pending initialization's insertion.
+      # Unsafe maps require callers to provide their own synchronization.
+      # @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 initialization recursively accesses its own gate.
+      def store_if_absent(key)
+        raise LocalJumpError, "no block given" unless block_given?
+
+        map      = internal_map
+        key      = map.prepare_key(prepare_key(key))
+        found    = true
+        existing = map.fetch(key) { found = false }
+        return unwrap_value(existing) if found
+
+        with_key_lock(key) do
+          stored     = map.fetch(key) do
+            value    = yield
+            wrapped  = wrap_value(value)
+            map[key] = wrapped
+            return unwrap_value(wrapped)
+          end
+          unwrap_value(stored)
+        end
+      end
+
+      # (see Map#delete)
+      def delete(key) = unwrap_value(internal_map.delete(prepare_key(key)))
+
+      # (see Map#empty?)
+      def empty? = internal_map.empty?
+
+      # (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
+        key = prepare_key(key)
+        warn "block supersedes default value argument", uplevel: 1 if block_given? && arguments.length == 2
+        value = internal_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
+
+      # Return the smallest key according to the map's ordering.
+      # @return [BasicObject, nil] The first key, or nil if the map is empty.
+      def first_key = internal_map.first_key
+
+      # (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 largest key according to the map's ordering.
+      # @return [BasicObject, nil] The last key, or nil if the map is empty.
+      def last_key = internal_map.last_key
+
+      # (see Map#size)
+      def length = internal_map.length
+
+      # Remove and return the entry with the largest key according to the map's ordering.
+      # @return [Array(BasicObject, BasicObject), nil] The last key-value pair, or nil if the map is empty.
+      def pop
+        pair = internal_map.pop
+        [pair.first, unwrap_value(pair.last)] if pair
+      end
+
+      # Remove and return the entry with the smallest key according to the map's ordering.
+      # @return [Array(BasicObject, BasicObject), nil] The first key-value pair, or nil if the map is empty.
+      def shift
+        pair = internal_map.shift
+        [pair.first, unwrap_value(pair.last)] if pair
+      end
+
+      # (see Map#size)
+      def size = internal_map.size
+
+      # Remove all entries from the map.
+      # @return [self]
+      def clear
+        internal_map.clear
+        self
+      end
+
+      # Iterate over the map's key-value pairs.
+      # Order is guaranteed to be from smallest to largest key according.
+      #
+      # @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] An enumerator over two-element `[key, value]` pairs.
+      def each
+        return enum_for(__method__) unless block_given?
+        internal_map.each { |key, value| yield [key, unwrap_value(value)] }
+        self
+      end
+
+      # Iterate incrementally in key order without allocating a full snapshot.
+      # Deletion and value replacement between yields are permitted. Insertion
+      # or clearing can invalidate traversal and raise RuntimeError. No tree
+      # lock is held while the block runs.
+      # @api private
+      def each_live
+        return enum_for(__method__) { size } unless block_given?
+        internal_map.each_live { |key, value| yield [key, unwrap_value(value)] }
+        self
+      end
+
+      alias each_pair each
+
+      # Iterate over the keys currently stored in the map.
+      # Keys are yielded from smallest to largest.
+      #
+      # @overload each_key
+      #   @yield [key] Called once for each stored key.
+      #   @yieldparam key [BasicObject] A stored key.
+      #   @return [self]
+      # @overload each_key
+      #   @return [Enumerator] An enumerator over the stored keys.
+      def each_key
+        return enum_for(__method__) unless block_given?
+        each { |key, _| yield key }
+        self
+      end
+
+      # Iterate over the values currently stored in the map.
+      # Values are yielded in the order of their corresponding keys (from smallest to largest).
+      #
+      # @overload each_value
+      #   @yield [value] Called once for each stored value.
+      #   @yieldparam value [BasicObject] A stored value.
+      #   @return [self]
+      # @overload each_value
+      #   @return [Enumerator] An enumerator over the stored values.
+      def each_value
+        return enum_for(__method__) unless block_given?
+        each { |_, value| yield value }
+        self
+      end
+
+      # Return the keys currently stored in the map.
+      # The result is frozen and ordered from smallest to largest key.
+      # @return [Array<BasicObject>] The keys currently stored in the map, in order from smallest to largest.
+      def keys = each_key.to_a.freeze
+
+      # Return the values currently stored in the map.
+      # The result is frozen and ordered according to the order of their corresponding keys (from smallest to largest).
+      # @return [Array<BasicObject>] The values currently stored in the map.
+      def values = each_value.to_a.freeze
+
+      # TreeMap keys always have to be Ractor-shareable.
+      # Mutable strings are accepted however and will be converted to an immutable string.
+      # @return [true]
+      def shareable_keys? = true
+
+      # TreeMap keys are compared by their ordering, never by identity.
+      # @return [false]
+      def compare_keys_by_identity? = false
+
+      # TreeMap values are compared by equality, never by identity.
+      # @return [false]
+      def compare_values_by_identity? = false
+
+      protected
+
+      def transaction_key_locks = @key_locks
+
+      private
+
+      def copy_map_backend(source, empty: false)
+        copied = source.class.new
+        source.each { |key, value| copied[key] = value } unless empty
+        copied
+      end
+
+      def install_copied_map(map)
+        super
+        @key_locks = new_key_locks
+      end
+
+      def each_for_inspect(&) = each(&)
+
+      def prepare_key(key)
+        return key if String === key || Ractor.shareable?(key)
+        raise Ractor::IsolationError, "key must be Ractor-shareable"
+      end
+
+      def new_key_locks         = Internal::OrderedKeyLockMap.new
+      def with_key_lock(key, &) = @key_locks.synchronize(key, &)
+
+      # simplecov:disable
+      def new_tree_map(...)
+        raise "subclass failed to implement #new_tree_map" unless instance_of?(TreeMap)
+        raise NoMethodError, "Farce::Abstract::TreeMap should not be instantiated directly. Use a subclass instead."
+      end
+      # simplecov:enable
+    end
+  end
+end

data/lib/farce/abstract/value.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  module Abstract
+    # Mixin to indicate {#value} can safely be called on an object.
+    #
+    # @!method value
+    #   @abstract
+    #   Can be called multiple times without argument.
+    #   Some subclasses may allow optional arguments, especially a `timeout` keyword argument.
+    #   This method may block.
+    #   @return [BasicObject] The underlying value of the object.
+    #
+    # @abstract
+    module Value
+      Internal::Atom.include(self)
+
+      # Unwraps nested {Value} objects to get the underlying value.
+      #
+      # @example Nested unwrapping
+      #   MyValue = Data.define(:value) { include Farce::Abstract::Value }
+      #   inner   = MyValue.new(42)
+      #   outer   = MyValue.new(inner)
+      #   outer.unwrap # => 42
+      #
+      # @example Cycle detection
+      #   MyValue = Struct.new(:name, :value) { include Farce::Abstract::Value }
+      #
+      #   a = MyValue.new("A")
+      #   b = MyValue.new("B", a)
+      #   c = MyValue.new("C", a)
+      #   a.value = b
+      #
+      #   c.unwrap # => nil
+      #   c.unwrap("default") # => "default"
+      #
+      #   # RuntimeError: cycle detected starting at A
+      #   c.unwrap { raise "cycle detected starting at #{value.name}" }
+      #
+      # @overload unwrap(default = nil)
+      #   @param [BasicObject] default The value to return if a cycle is detected.
+      #
+      # @overload unwrap
+      #   @yield [value] Block to call if a cycle is detected.
+      #   @yieldparam [Value] value The value that has been determined to be the start of the cycle.
+      #   @yieldreturn [BasicObject] The value to return if a cycle is detected
+      #
+      # @return [BasicObject] The underlying value of the object, or a default value based on the argument or block.
+      def unwrap(default = nil)
+        value = value()
+        return value unless value.is_a?(Value)
+
+        seen = ::Set.new.compare_by_identity
+        seen << self
+
+        while value.is_a?(Value)
+          return block_given? ? yield(value) : default if seen.include?(value)
+          seen << value
+          value = value.value
+        end
+
+        value
+      end
+    end
+  end
+end