weak 0.1.0

data/lib/weak/set/strong_keys.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+# Copyright (c) Holger Just
+#
+# This software may be modified and distributed under the terms
+# of the MIT license. See the LICENSE.txt file for details.
+
+##
+module Weak
+  class Set
+    # This {Weak::Set} strategy targets JRuby >= 9.4.6.0 and TruffleRuby >= 22.
+    # Older versions require additional indirections implemented in
+    # {Weak::Set::StrongSecondaryKeys}:
+    #
+    # - https://github.com/jruby/jruby/issues/7862
+    # - https://github.com/oracle/truffleruby/issues/2267
+    #
+    # The `ObjectSpace::WeakMap` on JRuby and TruffleRuby has strong keys and
+    # weak values. Thus, only the value object can be garbage collected to
+    # remove the entry while the key defines a strong object reference which
+    # prevents the key object from being garbage collected.
+    #
+    # As a workaround, we use the element's object_id as a key. Being an
+    # `Integer`, the object_id is generally is not garbage collected anyway but
+    # allows to uniquely identity the object.
+    #
+    # The `ObjectSpace::WeakMap` class does not allow to explicitly delete
+    # entries. We emulate this by setting the garbage-collectible value of a
+    # deleted entry to a simple new object. This value will be garbage collected
+    # on the next GC run which will then remove the entry. When accessing
+    # elements, we delete and filter out these recently deleted entries.
+    module StrongKeys
+      class DeletedEntry; end
+      private_constant :DeletedEntry
+
+      # Checks if this strategy is usable for the current Ruby version.
+      #
+      # @return [Bool] truethy for Ruby, TruffleRuby and modern JRuby, falsey
+      #   otherwise
+      def self.usable?
+        case RUBY_ENGINE
+        when "ruby", "truffleruby"
+          true
+        when "jruby"
+          Gem::Version.new(RUBY_ENGINE_VERSION) >= Gem::Version.new("9.4.6.0")
+        end
+      end
+
+      # @!macro weak_set_method_add
+      def add(obj)
+        @map[obj.__id__] = obj
+        self
+      end
+
+      # @!macro weak_set_method_clear
+      def clear
+        @map = ObjectSpace::WeakMap.new
+        self
+      end
+
+      # @!macro weak_set_method_delete_question
+      def delete?(obj)
+        key = obj.__id__
+        return unless @map.key?(key) && @map[key].equal?(obj)
+
+        # If there is a valid value in the `ObjectSpace::WeakMap` (with a strong
+        # object_id key), we replace the value of the strong key with a
+        # temporary DeletedEntry object. As we do not keep any strong reference
+        # to this object, this will cause the key/value entry to vanish from the
+        # `Objectpace::WeakMap when the DeletedEntry object is eventually
+        # garbage collected.
+        @map[key] = DeletedEntry.new
+        self
+      end
+
+      # @!macro weak_set_method_each
+      def each
+        return enum_for(__method__) { size } unless block_given?
+
+        @map.values.each do |obj|
+          yield(obj) unless DeletedEntry === obj
+        end
+        self
+      end
+
+      # @!macro weak_set_method_include_question
+      def include?(obj)
+        key = obj.__id__
+        !!(@map.key?(key) && @map[key].equal?(obj))
+      end
+
+      # @!macro weak_set_method_prune
+      def prune
+        self
+      end
+
+      # @!macro weak_set_method_replace
+      def replace(enum)
+        map = ObjectSpace::WeakMap.new
+        do_with_enum(enum) do |obj|
+          map[obj.__id__] = obj
+        end
+        @map = map
+
+        self
+      end
+
+      # @!macro weak_set_method_size
+      def size
+        # Compared to using `ObjectSpace::WeakMap#each_value` like we do in
+        # `Weak::Set::WeakKeys`, this version is
+        #   * ~12% faster on JRuby >= 9.4.6.0
+        #   * sam-ish on TruffleRuby 24 with a slight advantage to this version
+        @map.values.delete_if { |obj| DeletedEntry === obj }.size
+      end
+
+      # @!macro weak_set_method_to_a
+      def to_a
+        @map.values.delete_if { |obj| DeletedEntry === obj }
+      end
+    end
+  end
+end

data/lib/weak/set/strong_secondary_keys.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+# Copyright (c) Holger Just
+#
+# This software may be modified and distributed under the terms
+# of the MIT license. See the LICENSE.txt file for details.
+
+##
+module Weak
+  class Set
+    # This {Weak::Set} strategy targets JRuby < 9.4.6.0.
+    #
+    # These JRuby versions have a similar `ObjectSpace::WeakMap` as newer
+    # JRubies with strong keys and weak values. Thus, only the value object can
+    # be garbage collected to remove the entry while the key defines a strong
+    # object reference which prevents the key object from being garbage
+    # collected.
+    #
+    # Additionally, `Integer` values (including object_ids) can have multiple
+    # different object representations in JRuby, making them not strictly equal.
+    # Thus, we can not use the object_id as a key in an `ObjectSpace::WeakMap`
+    # as we do in {Weak::Set::StrongKeys} for newer JRuby versions.
+    #
+    # As a workaround we use a more indirect implementation with a secondary
+    # lookup table for the keys which is inspired by
+    # [Google::Protobuf::Internal::LegacyObjectCache](https://github.com/protocolbuffers/protobuf/blob/afe2de261861717026c3b57ec83678590d5de838/ruby/lib/google/protobuf/internal/object_cache.rb#L42-L96)
+    #
+    # This secondary key map is a regular Hash which stores a mapping from an
+    # element's object_id to a separate Object which in turn is used as the key
+    # in the `ObjectSpace::WeakMap`.
+    #
+    # Being a regular Hash, the keys and values of the secondary key map are not
+    # automatically garbage collected as elements in the `ObjectSpace::WeakMap`
+    # are removed. However, its entries are rather cheap with Integer keys and
+    # "empty" objects as values. We perform manual garbage collection of this
+    # secondary key map during {StrongSecondaryKeys#include?} if required.
+    #
+    # As this strategy is the most conservative with the fewest requirements to
+    # the `ObjectSpace::WeakMap`, we use it as a default or fallback if there is
+    # no better strategy.
+    module StrongSecondaryKeys
+      class DeletedEntry; end
+      private_constant :DeletedEntry
+
+      # Checks if this strategy is usable for the current Ruby version.
+      #
+      # @return [Bool] always `true` to indicate that this stragegy should be
+      #   usable with any Ruby implementation which provides an
+      #   `ObjectSpace::WeakMap`.
+      def self.usable?
+        true
+      end
+
+      # @!macro weak_set_method_add
+      def add(obj)
+        key = @key_map[obj.__id__] ||= Object.new.freeze
+        @map[key] = obj
+        self
+      end
+
+      # @!macro weak_set_method_clear
+      def clear
+        @map = ObjectSpace::WeakMap.new
+        @key_map = {}
+        self
+      end
+
+      # @!macro weak_set_method_delete_question
+      def delete?(obj)
+        # When deleting, we still retain the key to avoid having to re-create it
+        # when `obj` is re-added to the {Weak::Set} again before the next GC.
+        #
+        # If `obj` is not added again, the key is eventually removed with our next
+        # GC of the `@key_map`.
+        key = @key_map[obj.__id__]
+        if key && @map.key?(key) && @map[key].equal?(obj)
+          # If there is a valid value in the `ObjectSpace::WeakMap` (with a
+          # strong object_id key), we replace the value of the strong key with a
+          # DeletedEntry marker object. This will cause the key/value entry to
+          # vanish from the `ObjectSpace::WeakMap` when the DeletedEntry object
+          # is eventually garbage collected.
+          @map[key] = DeletedEntry.new
+          self
+        end
+      end
+
+      # @!macro weak_set_method_each
+      def each
+        return enum_for(__method__) { size } unless block_given?
+
+        @map.values.each do |obj|
+          yield(obj) unless DeletedEntry === obj
+        end
+        self
+      end
+
+      # @!macro weak_set_method_include_question
+      def include?(obj)
+        key = @key_map[obj.__id__]
+        value = !!(key && @map.key?(key) && @map[key].equal?(obj))
+
+        auto_prune
+        value
+      end
+
+      # @!macro weak_set_method_prune
+      def prune
+        @key_map.each do |id, key|
+          @key_map.delete(id) unless @map.key?(key)
+        end
+        self
+      end
+
+      # @!macro weak_set_method_replace
+      def replace(enum)
+        map = ObjectSpace::WeakMap.new
+        key_map = {}
+        do_with_enum(enum) do |obj|
+          key = key_map[obj.__id__] ||= Object.new.freeze
+          map[key] = obj
+        end
+        @map = map
+        @key_map = key_map
+
+        self
+      end
+
+      # @!macro weak_set_method_size
+      def size
+        # Compared to using `ObjectSpace::WeakMap#each_value` like we do in
+        # {WeakKeys}, this version is ~12% faster on JRuby < 9.4.6.0
+        @map.values.delete_if { |obj| DeletedEntry === obj }.size
+      end
+
+      # @!macro weak_set_method_to_a
+      def to_a
+        @map.values.delete_if { |obj| DeletedEntry === obj }
+      end
+
+      private
+
+      # Prune unneeded entries from the `@key_map` Hash if we could remove at
+      # least 2000 entries or 20% of the table size (whichever is greater).
+      # Since the cost of the GC pass is O(N), we want to make sure that we
+      # condition this on overall table size, to avoid O(N^2) CPU costs.
+      def auto_prune
+        key_map_size = @key_map.size
+        cutoff = [2000, (key_map_size * 0.2).ceil].max
+
+        prune if key_map_size - @map.size > cutoff
+      end
+    end
+  end
+end

data/lib/weak/set/weak_keys.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+# Copyright (c) Holger Just
+#
+# This software may be modified and distributed under the terms
+# of the MIT license. See the LICENSE.txt file for details.
+
+##
+module Weak
+  class Set
+    # This {Weak::Set} strategy targets Ruby < 3.3.0.
+    #
+    # Its `ObjectSpace::WeakMap` uses weak keys and weak values so that either
+    # the key or the value can be independently garbage collected. If either of
+    # them vanishes, the entry is removed.
+    #
+    # The `ObjectSpace::WeakMap` does not allow to explicitly delete entries. We
+    # emulate this by setting the garbage-collectible value of a deleted entry
+    # to a simple new object. This value will be garbage collected on the next
+    # GC run which will then remove the entry. When accessing elements, we
+    # delete and filter out these recently deleted entries.
+    module WeakKeys
+      class DeletedEntry; end
+      private_constant :DeletedEntry
+
+      # Checks if this strategy is usable for the current Ruby version.
+      #
+      # @return [Bool] truethy for Ruby (aka. MRI, aka. YARV), falsey otherwise
+      def self.usable?
+        RUBY_ENGINE == "ruby"
+      end
+
+      # @!macro weak_set_method_add
+      def add(obj)
+        @map[obj] = obj
+        self
+      end
+
+      # @!macro weak_set_method_clear
+      def clear
+        @map = ObjectSpace::WeakMap.new
+        self
+      end
+
+      # @!macro weak_set_method_delete_question
+      def delete?(obj)
+        return unless include?(obj)
+
+        # If there is a valid entry in the `ObjectSpace::WeakMap`, we replace
+        # the value for the `obj` with a temporary DeletedEntry object. As we do
+        # not keep any strong reference to this object, this will cause the
+        # key/value entry to vanish from the `ObjectSpace::WeakMap` when the
+        # `DeletedEntry` object is eventually garbage collected.
+        #
+        # This ensures that we don't retain unnecessary entries in the map which
+        # we would have to skip over.
+        @map[obj] = DeletedEntry.new
+        self
+      end
+
+      # @!macro weak_set_method_each
+      def each
+        return enum_for(__method__) { size } unless block_given?
+
+        @map.values.each do |obj|
+          yield(obj) unless DeletedEntry === obj
+        end
+        self
+      end
+
+      # @!macro weak_set_method_include_question
+      def include?(obj)
+        !!(@map.key?(obj) && @map[obj].equal?(obj))
+      end
+
+      # @!macro weak_set_method_prune
+      def prune
+        self
+      end
+
+      # @!macro weak_set_method_replace
+      def replace(enum)
+        map = ObjectSpace::WeakMap.new
+        do_with_enum(enum) do |obj|
+          map[obj] = obj
+        end
+        @map = map
+
+        self
+      end
+
+      # @!macro weak_set_method_size
+      def size
+        count = 0
+        @map.each_value do |obj|
+          count = count.succ unless DeletedEntry === obj
+        end
+        count
+      end
+
+      # @!macro weak_set_method_to_a
+      def to_a
+        @map.values.delete_if { |obj| DeletedEntry === obj }
+      end
+    end
+  end
+end

data/lib/weak/set/weak_keys_with_delete.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+# Copyright (c) Holger Just
+#
+# This software may be modified and distributed under the terms
+# of the MIT license. See the LICENSE.txt file for details.
+
+##
+module Weak
+  class Set
+    # This {Weak::Set} strategy targets Ruby >= 3.3.0.
+    # Older Ruby versions require additional indirections implemented in
+    # {Weak::Set::WeakKeys}:
+    #
+    # - https://bugs.ruby-lang.org/issues/19561
+    #
+    # Ruby's `ObjectSpace::WeakMap` uses weak keys and weak values so that
+    # either the key or the value can be independently garbage collected. If
+    # either of them vanishes, the entry is removed.
+    #
+    # The `ObjectSpace::WeakMap` also allows to delete entries. This allows us
+    # to directly use the `ObjectSpace::WeakMap` as a storage the same way a
+    # `::Set` uses a `Hash` object object as storage.
+    module WeakKeysWithDelete
+      # Checks if this strategy is usable for the current Ruby version.
+      #
+      # @return [Bool] truethy for Ruby (aka. MRI, aka. YARV) >= 3.3.0,
+      #   falsey otherwise
+      def self.usable?
+        RUBY_ENGINE == "ruby" &&
+          ObjectSpace::WeakMap.instance_methods.include?(:delete)
+      end
+
+      # @!macro weak_set_method_add
+      def add(obj)
+        @map[obj] = true
+        self
+      end
+
+      # @!macro weak_set_method_clear
+      def clear
+        @map = ObjectSpace::WeakMap.new
+        self
+      end
+
+      # @!macro weak_set_method_delete_question
+      def delete?(obj)
+        # `ObjectSpace::WeakMap#delete` returns the value if it was removed. As
+        # we set it to true, `ObjectSpace::WeakMap#delete` returns either true
+        # or nil here.
+        self if @map.delete(obj)
+      end
+
+      # @!macro weak_set_method_each
+      def each(&block)
+        return enum_for(__method__) { size } unless block_given?
+
+        @map.keys.each(&block)
+        self
+      end
+
+      # @!macro weak_set_method_include_question
+      def include?(obj)
+        @map.key?(obj)
+      end
+
+      # @!macro weak_set_method_prune
+      def prune
+        self
+      end
+
+      # @!macro weak_set_method_replace
+      def replace(enum)
+        map = ObjectSpace::WeakMap.new
+        do_with_enum(enum) do |obj|
+          map[obj] = true
+        end
+        @map = map
+
+        self
+      end
+
+      # @!macro weak_set_method_size
+      def size
+        @map.size
+      end
+
+      # @!macro weak_set_method_to_a
+      def to_a
+        @map.keys
+      end
+    end
+  end
+end