farce 0.0.1.alpha2-x86_64-linux-gnu

data/lib/farce/weak_atom.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  # A Ractor-shareable atomic reference that retains its value weakly.
+  # Values support :raise (the default), :make_shareable, and :dedup.
+  # The value becomes nil after collection when no strong references remain.
+  # With :dedup, retain the canonical result returned by store or update.
+  # Keeping only the input alive may not keep the stored result alive.
+  # Assignment evaluates to the input rather than the canonical result.
+  # Comparisons observe the stored object without preparing their operands.
+  #
+  # @example Publishing the original object without keeping it alive
+  #   value = []
+  #   atom = Farce::WeakAtom.new(value, mode: :make_shareable)
+  #   atom.value.equal?(value) # => true
+  #   value = nil
+  #   # After collection, atom.value returns nil.
+  class WeakAtom < Farce::Abstract::WeakAtom
+    include Shareable::Delegated
+
+    TIMED_OUT = Object.new.freeze
+    private_constant :TIMED_OUT
+
+    # @param value [BasicObject, nil] the initial value
+    # @param mode [Symbol] :raise, :make_shareable, or :dedup
+    # @param compare_by_identity [Boolean] whether comparisons use object identity
+    def initialize(value = nil, mode: :raise, compare_by_identity: false)
+      @manager = Internal::WeakModeManager.new(mode:)
+      super(@manager.wrap(value), compare_by_identity:)
+    end
+
+    # The default mode used to prepare replacement values.
+    # @return [Symbol]
+    def mode = @manager.mode
+
+    # (see Abstract::Atom#store)
+    # @param mode [Symbol, nil] the replacement's mode, or nil for the default
+    def store(new_value, mode: nil, timeout: nil, &)
+      check_frozen!
+      super(@manager.wrap(new_value, mode:), timeout:, &)
+    end
+
+    # (see Abstract::Atom#swap)
+    # @param mode [Symbol, nil] the replacement's mode, or nil for the default
+    def swap(new_value, mode: nil, timeout: nil, &)
+      check_frozen!
+      super(@manager.wrap(new_value, mode:), timeout:, &)
+    end
+
+    # (see Abstract::Atom#store_if_absent)
+    # @param mode [Symbol, nil] the result's mode, or nil for the default
+    def store_if_absent(mode: nil, timeout: nil)
+      raise LocalJumpError, "no block given" unless block_given?
+      @manager.validate_mode!(mode)
+      super(timeout:) do
+        value = yield
+        check_frozen!
+        @manager.wrap(value, mode:)
+      end
+    end
+
+    # (see Abstract::Atom#update)
+    # @param mode [Symbol, nil] the result's mode, or nil for the default
+    def update(mode: nil, timeout: nil)
+      raise LocalJumpError, "no block given" unless block_given?
+      @manager.validate_mode!(mode)
+      super(timeout:) do |current|
+        value = yield(current)
+        check_frozen!
+        @manager.wrap(value, mode:)
+      end
+    end
+
+    # (see Abstract::Atom#upsert)
+    # @param mode [Symbol, nil] the replacement's mode, or nil for the default
+    def upsert(initial, mode: nil, timeout: nil)
+      raise LocalJumpError, "no block given" unless block_given?
+      @manager.validate_mode!(mode)
+      @atom.update(timeout:) do |current|
+        value = nil.equal?(current) ? initial : yield(current)
+        check_frozen!
+        @manager.wrap(value, mode:)
+      end
+    end
+
+    # (see Abstract::Atom#compare_and_set)
+    # @param mode [Symbol, nil] the replacement's mode, or nil for the default
+    def compare_and_set(expected, replacement, mode: nil, timeout: nil)
+      @manager.validate_mode!(mode)
+      matched = false
+      @atom.update(timeout:) do |current|
+        next current unless values_equal?(current, expected)
+        check_frozen!
+        prepared = @manager.wrap(replacement, mode:)
+        matched = true
+        prepared
+      end
+      matched
+    end
+
+    # (see Abstract::Atom#wait_until_changed)
+    def wait_until_changed(expected, timeout: nil, &fallback)
+      deadline = Internal.timeout_deadline(timeout)
+      while true
+        current = @atom.get(timeout: Internal.remaining_timeout(deadline)) { TIMED_OUT }
+        return fallback&.call if TIMED_OUT.equal?(current)
+        return current unless values_equal?(current, expected)
+        result = @atom.wait_until_changed(current, timeout: Internal.remaining_timeout(deadline)) { TIMED_OUT }
+        return fallback&.call if TIMED_OUT.equal?(result)
+      end
+    end
+
+    private
+
+    def internal_atom_class = Internal::WeakAtom
+    def freeze_backend      = @atom
+    def values_equal?(left, right) = @manager.same_value?(left, right, identity: compare_by_identity?)
+  end
+end

data/lib/farce/weak_key_map.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  # A concurrent map with weak shareable keys and strongly retained values.
+  # Transfer modes apply only to values. Keys are stored directly.
+  # Entries disappear after their keys are collected. A value that references
+  # its key, including through an envelope, can keep that key alive.
+  #
+  # @example Associating mutable metadata with a shareable object
+  #   owner      = Object.new.freeze
+  #   map        = Farce::WeakKeyMap.new
+  #   map[owner] = { visits: 1 }
+  #   map.update(owner) { |metadata| { visits: metadata[:visits] + 1 } }
+  #   map[owner] # => { visits: 2 }
+  #
+  #   # The entry can disappear once its key is collected.
+  #   owner = nil
+  class WeakKeyMap < Farce::Abstract::WeakKeyMap
+    include Internal::MapValueModes
+    include Shareable::Delegated
+
+    private
+
+    def new_map(**)    = Internal::StrictWeakKeyMap.new(**)
+    def freeze_backend = @map
+  end
+
+  Internal::KeyNormalizer.prepare_concurrent_class(Internal::StrictWeakKeyMap)
+end

data/lib/farce/weak_map.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  # A Ractor-shareable concurrent map with weak shareable keys and weak values.
+  # Entries disappear after a weakly held object is collected.
+  #
+  # Supported modes are `:raise` (the default), `:make_shareable`, and `:dedup`.
+  # Modes apply only to values. Keys must already be shareable.
+  #
+  # With `:dedup`, retain the canonical result returned by store or update,
+  # as it might differ from the input and could be immediately collected.
+  # Assignment evaluates to the input rather than the canonical result.
+  #
+  # @example Publishing a value without retaining it strongly
+  #   key      = Object.new.freeze
+  #   value    = []
+  #   map      = Farce::WeakMap.new(mode: :make_shareable)
+  #   map[key] = value
+  #   map[key].equal?(value) # => true
+  class WeakMap < Farce::Abstract::WeakMap
+    include Internal::WeakMapValueModes
+    include Shareable::Delegated
+
+    private
+
+    def new_map(**)    = Internal::StrictWeakMap.new(**)
+    def freeze_backend = @map
+  end
+
+  Internal::KeyNormalizer.prepare_concurrent_class(Internal::StrictWeakMap)
+end

data/lib/farce/weak_ref.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+require "delegate"
+
+module Farce
+  # Drop-in replacement for Ruby's WeakRef class that is Ractor-friendly.
+  #
+  # @example
+  #   foo = Object.new               # create a new object instance
+  #   p foo.to_s                     # original's class
+  #   foo = Farce::WeakRef.new(foo)  # reassign foo with WeakRef instance
+  #   p foo.to_s                     # should be same class
+  #   GC.start                       # start the garbage collector
+  #   p foo.to_s                     # should raise exception (recycled)
+  class WeakRef < Delegator
+    include Internal::MarshalSupport::WeakRef
+
+    recycled = allocate
+    recycled.instance_variable_set(:@value, WeakValue::RECYCLED)
+
+    class << recycled
+      undef marshal_dump
+
+      # @api private
+      def _dump(_) = "recycled"
+    end
+
+    # @api private
+    RECYCLED = Kernel.instance_method(:freeze).bind_call(recycled)
+
+    # Alias for {WeakRefError} to mimic `::WeakRef::RefError`
+    RefError = WeakRefError
+
+    # @api private
+    def self._load(state)
+      raise TypeError, "invalid weak reference state" unless state == "recycled"
+      RECYCLED
+    end
+
+    def initialize(value)
+      @value = WeakValue.new(value)
+      super
+      Kernel.instance_method(:freeze).bind_call(self)
+    end
+
+    # @api private
+    def __getobj__ = @value.value # :nodoc:
+
+    # @api private
+    def __setobj__(_) = nil # :nodoc:
+
+    # @return [Boolean] true if the referenced object is still alive and reachable
+    def weakref_alive? = @value.alive?
+
+    private
+
+    def respond_to_missing?(name, include_private = false)
+      return false if Internal.marshal_protocol_method?(name)
+      super
+    end
+
+    def initialize_dup(other)       = initialize_copy(other)
+    def initialize_clone(other, **) = initialize_copy(other)
+  end
+end

data/lib/farce/weak_set.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  # A Ractor-shareable concurrent set that retains prepared elements weakly.
+  # Elements support :raise (the default), :make_shareable, and :dedup.
+  # Membership refers to the prepared element itself. Lookup and deletion do
+  # not freeze or deduplicate their arguments. Already-shareable elements pass
+  # through unchanged, as with other mode-backed containers.
+  #
+  # With :dedup, the stored canonical element can differ from the input.
+  # Keeping only the input alive may not keep that element alive. Callers are
+  # responsible for retaining elements they need. Both add and add? retain
+  # their usual set return values rather than returning the stored element.
+  #
+  # @example Tracking an object without keeping it alive
+  #   resource = []
+  #   set = Farce::WeakSet.new(mode: :make_shareable)
+  #   set.add(resource)
+  #   set.first.equal?(resource) # => true
+  #   resource = nil
+  #   # After collection, the set can become empty.
+  class WeakSet < Farce::Abstract::WeakSet
+    include Shareable::Delegated
+
+    # The default mode used to prepare elements for insertion.
+    # @return [Symbol] :raise, :make_shareable, or :dedup
+    def mode = @manager.mode
+
+    # (see Abstract::Set#include?)
+    def include?(element)
+      key = lookup_key(normalize_element(element))
+      !MISSING_KEY.equal?(key) && @map.key?(key)
+    end
+    alias member? include?
+    alias === include?
+
+    # (see Abstract::Set#delete)
+    def delete(element)
+      check_frozen!
+      key = lookup_key(normalize_element(element))
+      @map.delete(key) unless MISSING_KEY.equal?(key)
+      self
+    end
+
+    # (see Abstract::Set#delete?)
+    def delete?(element) # rubocop:disable Naming/PredicateMethod
+      check_frozen!
+      key = lookup_key(normalize_element(element))
+      self unless MISSING_KEY.equal?(key) || !@map.delete(key)
+    end
+
+    protected
+
+    # Canonical imports bypass normalization, but still prepare external elements.
+    def add_stored(key, value) = super(@manager.wrap(key), value)
+
+    private
+
+    def initialize_value_mode(mode)
+      mode = :raise if UNDEFINED.equal?(mode)
+      @manager = Internal::WeakModeManager.new(mode:)
+    end
+
+    def add_normalized?(element, mode: UNDEFINED)
+      selected = UNDEFINED.equal?(mode) ? nil : mode
+      super(@manager.wrap(element, mode: selected))
+    end
+
+    def lookup_key(element)
+      return element if Ractor.shareable?(element)
+      return MISSING_KEY if identity_membership?(element)
+      structural_key(element)
+    end
+
+    def new_map(entries = nil, **)
+      entries = entries&.map { |element, value| [@manager.wrap(element), value] }
+      Strict::WeakMap.new(entries, **)
+    end
+  end
+end

data/lib/farce/weak_value.rb

@@ -0,0 +1,195 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  # A weak value is similar to a {WeakRef}, but does not delegate method calls to the referenced object.
+  # If a weak value is created for a shareable object, it will also be shareable.
+  # If {#freeze} is called, the referenced object will be made shareable (unless it has been garbage collected).
+  #
+  # @example
+  #   object = Object.new
+  #   weak   = Farce::WeakValue.new(object)
+  #   weak.value == object # => true
+  #   weak.alive?          # => true
+  #
+  #   # Shareability traversal
+  #   Ractor.shareable?(object) # => false
+  #   Ractor.shareable?(weak)   # => false
+  #
+  #   Ractor.make_shareable(weak)
+  #   Ractor.shareable?(weak)   # => true
+  #   Ractor.shareable?(object) # => true
+  #
+  #   # lets assume that the object has been garbage collected
+  #   object = nil
+  #   GC.start
+  #
+  #   weak.alive? # => false
+  #   weak.value # WeakRefError: Invalid Reference - probably recycled
+  class WeakValue
+    include Internal::MarshalSupport::WeakValue
+    include Abstract::Value
+    include Internal::Inspect
+
+    MOVED = Object.new.freeze
+    private_constant :MOVED
+
+    nil_value = new
+
+    class << nil_value
+      undef marshal_dump
+
+      # @api private
+      def _dump(_) = "nil"
+
+      def dup               = self
+      def clone(**)         = self
+      def value             = nil
+      def alive?            = true
+      def moved?            = false
+      def ractor_shareable? = true
+
+      private
+
+      def _value          = nil
+      def state_and_value = [:alive, nil]
+    end
+
+    nil_value.instance_variable_set(:@mutex, nil)
+
+    NIL_VALUE = nil_value.freeze
+    private_constant :NIL_VALUE
+
+    recycled = new
+    class << recycled
+      undef marshal_dump
+
+      # @api private
+      def _dump(_) = "recycled"
+
+      def dup               = self
+      def clone(**)         = self
+      def alive?            = false
+      def moved?            = false
+      def ractor_shareable? = true
+
+      private
+
+      def _value          = nil
+      def state_and_value = [:recycled, nil]
+    end
+
+    # @api private
+    RECYCLED = recycled.freeze
+
+    # @param (see #initialize)
+    # @return [WeakValue] a new weak value wrapping the given object
+    # @see #initialize
+    def self.new(value) = value.nil? ? NIL_VALUE : super
+
+    # @api private
+    def self._load(state)
+      case state
+      when "nil" then NIL_VALUE
+      when "recycled" then RECYCLED
+      else raise TypeError, "invalid weak value state"
+      end
+    end
+
+    # @param value [Object] the object to be weakly referenced
+    def initialize(value)
+      if Ractor.shareable?(value)
+        @atom  = Strict::WeakAtom.new(value)
+        @mutex = nil
+      else
+        @atom  = Unshared::WeakAtom.new(value)
+        @mutex = Mutex.new
+      end
+    end
+
+    # Checks whether the referenced object has avoided garbage collection and has not been moved.
+    # @return [Boolean] true if the weak value is still alive, false otherwise
+    def alive?
+      !_value.nil?
+    rescue Ractor::MovedError
+      false
+    end
+
+    # Freezes the weak value, making the referenced object shareable if it is still alive.
+    # Can be called after the value has been garbage collected or moved.
+    # Will raise however if the referenced object is still alive and cannot be made shareable.
+    # @return [self] the frozen weak value
+    def freeze
+      @mutex&.synchronize do
+        return self if frozen?
+        value = begin
+          Ractor.make_shareable(_value)
+        rescue Ractor::MovedError
+          MOVED
+        end
+        @atom  = Strict::WeakAtom.new(value)
+        @mutex = nil
+      end
+      super
+    end
+
+    # Checks if the referenced object has been moved to another Ractor.
+    # @return [Boolean] true if the referenced object has been moved, false otherwise
+    def moved?
+      Ractor::MovedObject === _value
+    rescue Ractor::MovedError
+      true
+    end
+
+    # @return [Boolean] true if the referenced object is shareable by Ractor, false otherwise
+    def ractor_shareable?
+      return false unless Ractor.shareable?(_value)
+      freeze && true
+    rescue Ractor::MovedError
+      freeze && true
+    end
+
+    # Retrieves the referenced object if it is still alive and has not been moved.
+    # Raises if it is no longer reachable.
+    # @return [BasicObject] the referenced object if it is still alive and has not been moved
+    # @raise [WeakRefError] if the referenced object is no longer reachable or has been moved
+    def value
+      value = _value
+      raise WeakRefError, "Invalid Reference - probably recycled" if value.nil?
+      value
+    rescue Ractor::MovedError
+      raise WeakRefError, "Invalid Reference - referenced object has been moved"
+    end
+
+    # @api private
+    def inspect_with(inspector)
+      state, value = state_and_value
+      super do
+        inspector.attribute(:state, state)
+        inspector.attribute(:value, value) if state == :alive
+      end
+    end
+
+    private
+
+    def initialize_clone(other, freeze: nil)
+      super
+      self.freeze if freeze == true
+    end
+
+    def _value
+      value = @atom.value
+      raise Ractor::MovedError, "referenced object has been moved" if MOVED.equal?(value)
+      value
+    end
+
+    def state_and_value
+      value = _value
+      return :recycled if value.nil?
+      [:alive, value]
+    rescue Ractor::MovedError
+      :moved
+    end
+  end
+end

data/lib/farce/weak_value_map.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+# warn_indent: true
+
+module Farce
+  # A Ractor-shareable concurrent map with strong shareable keys and weak values.
+  #
+  # Supported modes are `:raise` (the default), `:make_shareable`, and `:dedup`.
+  # Modes apply only to values. Keys must already be shareable.
+  # Entries disappear after a weakly held object is collected.
+  #
+  # With `:dedup`, retain the canonical result returned by store or update,
+  # as it might differ from the input and could be immediately collected.
+  # Assignment evaluates to the input rather than the canonical result.
+  #
+  # @example Publishing a value without retaining it strongly
+  #   value        = []
+  #   map          = Farce::WeakValueMap.new(mode: :make_shareable)
+  #   map[:result] = value
+  #   map[:result].equal?(value) # => true
+  class WeakValueMap < Farce::Abstract::WeakValueMap
+    include Internal::WeakMapValueModes
+    include Shareable::Delegated
+
+    private
+
+    def new_map(**)    = Internal::StrictWeakValueMap.new(**)
+    def freeze_backend = @map
+  end
+
+  Internal::KeyNormalizer.prepare_concurrent_class(Internal::StrictWeakValueMap)
+end