memorb 0.1.0

data/lib/memorb/integrator_class_methods.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Memorb
+  module IntegratorClassMethods
+
+    def memorb
+      Integration[self]
+    end
+
+    def memorb!(*args, &block)
+      memorb.register(*args, &block)
+    end
+
+    private
+
+    def inherited(child)
+      super.tap do
+        Integration.integrate_with!(child)
+      end
+    end
+
+    def method_added(name)
+      super.tap do
+        memorb.register(name) if memorb.auto_register?
+        memorb.enable(name)
+      end
+    end
+
+    def method_removed(name)
+      super.tap do
+        memorb.disable(name)
+        memorb.purge(name)
+      end
+    end
+
+    def method_undefined(name)
+      super.tap do
+        memorb.disable(name)
+        memorb.purge(name)
+      end
+    end
+
+  end
+end

data/lib/memorb/key_value_store.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require 'concurrent'
+
+module Memorb
+  class KeyValueStore
+
+    def initialize
+      @data = ::Hash.new
+      @lock = ::Concurrent::ReentrantReadWriteLock.new
+    end
+
+    attr_reader :lock
+
+    def write(key, value)
+      @lock.with_write_lock { _write(key, value) }
+    end
+
+    def read(key)
+      @lock.with_read_lock { _read(key) }
+    end
+
+    def has?(key)
+      @lock.with_read_lock { _has?(key) }
+    end
+
+    def fetch(key, &fallback)
+      @lock.with_read_lock do
+        return _read(key) if _has?(key)
+      end
+      # Concurrent readers could all see no entry if none were able to
+      # write before the others checked for the key, so they need to be
+      # synchronized below to ensure that only one of them actually
+      # executes the fallback block and writes the resulting value.
+      @lock.with_write_lock do
+        # The first thread to acquire the write lock will write the value
+        # for the key causing the other aforementioned threads that may
+        # also want to write to now see the key and return it.
+        _has?(key) ? _read(key) : _write(key, fallback.call)
+      end
+    end
+
+    def forget(key)
+      @lock.with_write_lock { _forget(key) }
+    end
+
+    def reset!
+      @lock.with_write_lock { _reset! }
+    end
+
+    def keys
+      @lock.with_read_lock { _keys }
+    end
+
+    def inspect
+      "#<#{ self.class.name } keys=#{ keys.inspect }>"
+    end
+
+    private
+
+    def _write(key, value)
+      @data[key] = value
+    end
+
+    def _read(key)
+      @data[key]
+    end
+
+    def _has?(key)
+      @data.include?(key)
+    end
+
+    def _forget(key)
+      @data.delete(key)
+      nil
+    end
+
+    def _reset!
+      @data.clear
+      nil
+    end
+
+    def _keys
+      @data.keys
+    end
+
+  end
+end

data/lib/memorb/method_identifier.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Memorb
+  class MethodIdentifier
+
+    def initialize(method_name)
+      @method_name = method_name.to_sym
+    end
+
+    def hash
+      self.class.hash ^ method_name.hash
+    end
+
+    def ==(other)
+      hash === other.hash
+    end
+
+    alias_method :eql?, :==
+
+    def to_s
+      method_name.to_s
+    end
+
+    def to_sym
+      method_name
+    end
+
+    protected
+
+    attr_reader :method_name
+
+  end
+end

data/lib/memorb/ruby_compatibility.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Memorb
+  # When Memorb code needs to be changed to accomodate older Ruby versions,
+  # that code should live here. This has a few advantages:
+  #   - it will be clear that there was a need to change the code for Ruby
+  #     compatibility reasons
+  #   - when the Ruby versions that required the altered code will no longer
+  #     be supported, locating the places to refactor is easy
+  #   - the specific approach needed to accommodate older version of Ruby
+  #     and any explanatory comments need only be defined in one place
+  module RubyCompatibility
+    class << self
+
+      # MRI < 2.5
+      # These methods are `private` and require the use of `send`.
+      %i[ define_method remove_method undef_method ].each do |m|
+        eval(<<~RUBY, binding, __FILE__, __LINE__ + 1)
+          def #{ m }(receiver, *args, &block)
+            receiver.send(__method__, *args, &block)
+          end
+        RUBY
+      end
+
+      # JRuby *
+      # JRuby doesn't work well with module singleton constants, so an
+      # instance variable is used instead.
+      def module_constant(receiver, key)
+        receiver.instance_variable_get(ivar_name(key))
+      end
+      def module_constant_set(receiver, key, value)
+        n = ivar_name(key)
+        if receiver.instance_variable_defined?(n)
+          raise "Memorb internal error! Reassignment of constant at #{ n }"
+        end
+        receiver.instance_variable_set(n, value)
+      end
+
+      # JRuby *
+      # JRuby does not yet support `receiver` on `NameError`.
+      # https://github.com/jruby/jruby/issues/5576
+      def name_error_matches(error, expected_name, expected_receiver)
+        return false unless error.name.to_s == expected_name.to_s
+        ::RUBY_ENGINE == 'jruby' || error.receiver.equal?(expected_receiver)
+      end
+
+      private
+
+      def ivar_name(key)
+        :"@#{ key }"
+      end
+
+    end
+  end
+end

data/lib/memorb/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Memorb
+  VERSION = '0.1.0'
+end

data/memorb.gemspec

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require File.expand_path('../lib/memorb/version', __FILE__)
+
+Gem::Specification.new do |s|
+  s.name        = 'memorb'
+  s.version     = Memorb::VERSION
+  s.platform    = Gem::Platform::RUBY
+  s.license     = 'MIT'
+  s.authors     = ['Patrick Rebsch']
+  s.email       = ['pjrebsch@gmail.com']
+  s.homepage    = 'https://github.com/pjrebsch/memorb'
+  s.summary     = 'Memoization made easy'
+  s.description = <<~TXT
+    Memorb makes instance method memoization easy to set up and use.
+  TXT
+
+  s.required_ruby_version     = '~> 2.3'
+  s.required_rubygems_version = '>= 2.6'
+
+  s.add_development_dependency 'bundler', '~> 2.0'
+  s.add_development_dependency 'rspec', '~> 3.9'
+  s.add_dependency 'concurrent-ruby', '~> 1.1'
+
+  s.require_paths = ['lib']
+  s.files         = `git ls-files`.split("\n")
+end

data/spec/memorb/agent_spec.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+describe ::Memorb::Agent do
+  let(:target) { ::SpecHelper.basic_target_class }
+  let(:integrator) { ::Class.new(target) { extend ::Memorb } }
+  let(:integrator_instance) { integrator.new }
+  subject { described_class.new(integrator_instance.object_id) }
+
+  describe '#id' do
+    it 'returns the value provided upon initialization' do
+      expect(subject.id).to equal(integrator_instance.object_id)
+    end
+  end
+  describe '#method_store' do
+    it 'returns a key-values store' do
+      expect(subject.method_store).to be_an_instance_of(::Memorb::KeyValueStore)
+    end
+    context 'when called more than once' do
+      it 'returns the same store each time' do
+        store_1 = subject.method_store
+        store_2 = subject.method_store
+        expect(store_1).to be(store_2)
+      end
+    end
+  end
+  describe '#value_store' do
+    it 'returns a key-values store' do
+      expect(subject.value_store).to be_an_instance_of(::Memorb::KeyValueStore)
+    end
+    context 'when called more than once' do
+      it 'returns the same store each time' do
+        store_1 = subject.value_store
+        store_2 = subject.value_store
+        expect(store_1).to be(store_2)
+      end
+    end
+  end
+  describe '#fetch' do
+    it 'delegates to the value store' do
+      subject.fetch([:a, :b]) { :c }
+      value = subject.value_store.read([:a, :b].hash)
+      expect(value).to eq(:c)
+    end
+  end
+end

data/spec/memorb/integration_spec.rb

@@ -0,0 +1,529 @@
+# frozen_string_literal: true
+
+describe ::Memorb::Integration do
+  let(:target) { ::SpecHelper.basic_target_class }
+
+  describe '::integrate_with!' do
+    it 'returns the integration for the given class' do
+      result = described_class.integrate_with!(target)
+      expect(result).not_to be(nil)
+    end
+    context 'when called more than once for a given class' do
+      it 'returns the same integration every time' do
+        result1 = described_class.integrate_with!(target)
+        result2 = described_class.integrate_with!(target)
+        expect(result1).to be(result2)
+      end
+      it 'includes the integration with the integrator only once' do
+        described_class.integrate_with!(target)
+        integration = described_class.integrate_with!(target)
+        ancestors = target.ancestors
+        integrations = ancestors.select { |a| a.equal? integration }
+        expect(integrations).to contain_exactly(integration)
+      end
+    end
+    context 'when given a regular object' do
+      it 'raises an error' do
+        obj = ::Object.new
+        error = ::Memorb::InvalidIntegrationError
+        error_message = 'integration target must be a class'
+        expect { obj.extend(::Memorb) }.to raise_error(error, error_message)
+      end
+    end
+  end
+  describe '::integrated?' do
+    context 'when a given class has not integrated Memorb' do
+      it 'returns false' do
+        result = described_class.integrated?(target)
+        expect(result).to be(false)
+      end
+    end
+    context 'when a given class has integrated with Memorb' do
+      it 'returns true' do
+        described_class.integrate_with!(target)
+        result = described_class.integrated?(target)
+        expect(result).to be(true)
+      end
+    end
+  end
+  describe '::[]' do
+    it 'returns the integration for the given class' do
+      integration = described_class.integrate_with!(target)
+      result = described_class[target]
+      expect(result).to be(integration)
+    end
+    context 'when given a class that has not been called with integrate!' do
+      it 'returns nil' do
+        result = described_class[target]
+        expect(result).to be(nil)
+      end
+    end
+  end
+
+  describe 'an integration' do
+    let(:integrator) { target.tap { |x| x.extend(::Memorb) } }
+    let(:integrator_singleton) { integrator.singleton_class }
+    let(:instance) { integrator.new }
+    let(:agent_registry) { subject.send(:_agents) }
+    subject { described_class[integrator] }
+
+    describe 'integrator instance methods' do
+      describe '#initialize' do
+        it 'retains the behavior of the instance' do
+          expect(instance.counter).to be(0)
+        end
+        it 'initializes the agent with the object ID of the instance' do
+          agent = instance.memorb
+          expect(agent.id).to equal(instance.object_id)
+        end
+        it 'adds the agent to the global registry' do
+          agent = instance.memorb
+          expect(agent_registry.keys).to contain_exactly(agent.id)
+        end
+      end
+      describe '#memorb' do
+        it 'returns the agent for the instance' do
+          agent = instance.memorb
+          expect(agent).to be_an_instance_of(::Memorb::Agent)
+        end
+        it 'does not share the agent across instances' do
+          agent_1 = integrator.new.memorb
+          agent_2 = integrator.new.memorb
+          expect(agent_1).not_to equal(agent_2)
+        end
+      end
+    end
+    describe '::integrator' do
+      it 'returns its integrating class' do
+        expect(subject.integrator).to be(integrator)
+      end
+    end
+    describe '::register' do
+      let(:method_name) { :increment }
+
+      context 'when called with method names as arguments' do
+        it 'caches the registered method' do
+          subject.register(method_name)
+          result1 = instance.send(method_name)
+          result2 = instance.send(method_name)
+          expect(result1).to eq(result2)
+        end
+        it 'records the registration of the method' do
+          subject.register(method_name)
+          expect(subject.registered_methods).to include(method_name)
+        end
+        context 'when providing a method name as a string' do
+          it 'registers the given method' do
+            subject.register('a')
+            expect(subject.registered_methods).to include(:a)
+          end
+        end
+        context 'when providing multiple method names' do
+          it 'registers each method' do
+            subject.register(:a, :b)
+            expect(subject.registered_methods).to include(:a, :b)
+          end
+        end
+        context 'when providing arrays of method names' do
+          it 'registers all methods in those arrays' do
+            subject.register([:a, :b], [:c])
+            expect(subject.registered_methods).to include(:a, :b, :c)
+          end
+        end
+        context 'when registering a method multiple times' do
+          before(:each) { 2.times { subject.register(method_name) } }
+
+          it 'still caches the registered method' do
+            result1 = instance.send(method_name)
+            result2 = instance.send(method_name)
+            expect(result1).to eq(result2)
+          end
+          it 'records registration of the method once' do
+            expect(subject.registered_methods).to contain_exactly(method_name)
+          end
+        end
+        context 'when registering a method that does not exist' do
+          let(:target) { ::Class.new }
+
+          it 'still allows the method to be registered' do
+            subject.register(method_name)
+            expect(subject.registered_methods).to include(method_name)
+          end
+          it 'does not enable the method' do
+            subject.register(method_name)
+            expect(subject.enabled_methods).not_to include(method_name)
+          end
+          it 'an integrator instance does not respond to the method' do
+            subject.register(method_name)
+            expect(instance).not_to respond_to(method_name)
+          end
+          it 'raises an error when trying to call it' do
+            subject.register(method_name)
+            expect { instance.send(method_name) }.to raise_error(::NoMethodError)
+          end
+          context 'once the method is defined' do
+            it 'responds to the the method' do
+              subject.register(method_name)
+              ::Memorb::RubyCompatibility
+                .define_method(integrator, method_name) { nil }
+              expect(instance).to respond_to(method_name)
+            end
+          end
+        end
+      end
+      context 'when called with only a block' do
+        it 'adds the methods defined in the block to the integrator' do
+          subject.register do
+            def method_1; end
+            def method_2; end
+          end
+          methods = integrator.public_instance_methods(false)
+          expect(methods).to include(:method_1, :method_2)
+        end
+        it 'registers and enables the methods defined in that block' do
+          subject.register do
+            def method_1; end
+            def method_2; end
+          end
+          expect(subject.registered_methods).to include(:method_1, :method_2)
+          expect(subject.enabled_methods).to include(:method_1, :method_2)
+        end
+        context 'when an error is raised in the provided block' do
+          it 'still disables automatic registration' do
+            begin
+              subject.register { raise }
+            rescue ::RuntimeError
+            end
+            expect(subject.auto_register?).to be(false)
+          end
+        end
+      end
+      context 'when called with arguments and a block' do
+        it 'raises an error' do
+          expect {
+            subject.register(:method_1) { nil }
+          }.to raise_error(::ArgumentError)
+        end
+      end
+      context 'when called without arguments or a block' do
+        it 'raises an error' do
+          expect { subject.register }.to raise_error(::ArgumentError)
+        end
+      end
+    end
+    describe '::registered?' do
+      it 'preserves the visibility of the method that it overrides' do
+        visibilities = [:public, :protected, :private]
+        method_names = visibilities.map { |vis| :"#{ vis }_method" }
+
+        integrator = ::Class.new.tap do |target|
+          eval_string = visibilities.map.with_index do |vis, i|
+            "#{ vis }; def #{ method_names[i] }; end;"
+          end.join("\n")
+          target.class_eval(eval_string)
+          target.extend(::Memorb)
+        end
+
+        subject = described_class[integrator]
+
+        method_names.each do |m|
+          subject.register(m)
+        end
+
+        visibilities.each.with_index do |vis, i|
+          overrides = subject.send(:"#{ vis }_instance_methods", false)
+          expect(overrides).to include(method_names[i])
+          other_methods = method_names.reject { |m| m === method_names[i] }
+          expect(overrides).not_to include(*other_methods)
+        end
+      end
+      ::SpecHelper.test_method_name(:increment) do |method_name, provided_name|
+        context 'when the named method is registered' do
+          it 'returns true' do
+            subject.register(method_name)
+            result = subject.registered?(provided_name)
+            expect(result).to be(true)
+          end
+        end
+        context 'when the named method is not registered' do
+          it 'returns false' do
+            result = subject.registered?(provided_name)
+            expect(result).to be(false)
+          end
+        end
+      end
+    end
+    describe '::enable' do
+      ::SpecHelper.test_method_name(:increment) do |method_name, provided_name|
+        it 'records the cache key correctly' do
+          method_id = ::Memorb::MethodIdentifier.new(provided_name)
+          subject.register(method_name)
+          instance.send(method_name)
+          store = instance.memorb.method_store
+          expect(store.keys).to contain_exactly(method_id)
+        end
+        context 'when the method is registered' do
+          it 'overrides the method' do
+            subject.register(method_name)
+            subject.disable(method_name)
+            subject.enable(provided_name)
+            expect(subject.enabled_methods).to include(method_name)
+          end
+          it 'returns the visibility of the method' do
+            subject.register(method_name)
+            result = subject.enable(provided_name)
+            expect(result).to be(:public)
+          end
+          context 'when the method is not defined' do
+            let(:target) { ::Class.new }
+
+            it 'does not override the method' do
+              subject.register(method_name)
+              subject.enable(provided_name)
+              expect(subject.enabled_methods).not_to include(method_name)
+            end
+            it 'returns nil' do
+              subject.register(method_name)
+              result = subject.enable(provided_name)
+              expect(result).to be(nil)
+            end
+          end
+        end
+        context 'when the method is not registered' do
+          it 'does not override the method' do
+            subject.enable(provided_name)
+            expect(subject.enabled_methods).not_to include(method_name)
+          end
+          it 'returns nil' do
+            result = subject.enable(provided_name)
+            expect(result).to be(nil)
+          end
+        end
+      end
+    end
+    describe '::disable' do
+      ::SpecHelper.test_method_name(:increment) do |method_name, provided_name|
+        it 'removes the override method for the given method' do
+          subject.register(method_name)
+          subject.disable(provided_name)
+          expect(subject.enabled_methods).not_to include(method_name)
+        end
+        context 'when there is no override method defined' do
+          let(:target) { ::Class.new }
+
+          it 'does not raise an error' do
+            expect { subject.disable(provided_name) }.not_to raise_error
+          end
+        end
+      end
+    end
+    describe '::registered_methods' do
+      it 'returns an array of registered methods' do
+        methods = [:increment, :decrement]
+        methods.each { |m| subject.register(m) }
+        expect(subject.registered_methods).to match_array(methods)
+      end
+    end
+    describe '::enabled_methods' do
+      it 'returns an array of enabled methods' do
+        methods = [:increment, :double]
+        methods.each { |m| subject.register(m) }
+        expect(subject.enabled_methods).to match_array(methods)
+      end
+    end
+    describe '::disabled_methods' do
+      it 'returns an array of methods that are not enabled' do
+        methods = [:a, :increment, :b, :double, :c]
+        methods.each { |m| subject.register(m) }
+        expect(subject.disabled_methods).to contain_exactly(:a, :b, :c)
+      end
+    end
+    describe '::enabled?' do
+      ::SpecHelper.test_method_name(:increment) do |method_name, provided_name|
+        context 'when the named method is enabled' do
+          it 'returns true' do
+            subject.register(method_name)
+            result = subject.enabled?(provided_name)
+            expect(result).to be(true)
+          end
+        end
+        context 'when the named method is not enabled' do
+          it 'returns false' do
+            result = subject.enabled?(provided_name)
+            expect(result).to be(false)
+          end
+        end
+      end
+    end
+    describe '::purge' do
+      let(:method_name) { :increment }
+      let(:method_id) { ::Memorb::MethodIdentifier.new(method_name) }
+
+      it 'clears cached data for the given method in all instances' do
+        subject.register(method_name)
+        instance.send(method_name)
+        store = instance.memorb.method_store.read(method_id)
+        expect(store.keys).not_to be_empty
+        subject.purge(method_name)
+        expect(store.keys).to be_empty
+      end
+      context 'when the given method has no cache record' do
+        it 'does not raise an error' do
+          subject.register(method_name)
+          store = instance.memorb.method_store.read(method_id)
+          expect(store).to be(nil)
+          expect { subject.purge(method_name) }.not_to raise_error
+        end
+      end
+    end
+    describe '::auto_register?' do
+      context 'by default' do
+        it 'returns false' do
+          expect(subject.auto_register?).to be(false)
+        end
+      end
+      context 'when turned on' do
+        it 'returns true' do
+          subject.send(:_auto_registration).increment
+          expect(subject.auto_register?).to be(true)
+        end
+      end
+    end
+    describe '::auto_register!' do
+      context 'when not given a block' do
+        it 'raises an error' do
+          expect {
+            subject.auto_register!
+          }.to raise_error(::ArgumentError, 'a block must be provided')
+        end
+      end
+      it 'enables automatic registration of methods defined in the block' do
+        subject.auto_register! do
+          ::Memorb::RubyCompatibility.define_method(integrator, :a) { nil }
+        end
+        expect(subject.registered_methods).to include(:a)
+      end
+      it 'returns the return value of the given block' do
+        result = subject.auto_register! { 1 }
+        expect(result).to be(1)
+      end
+      context 'when an error is raised in the given block' do
+        it 'still disables automatic registration' do
+          begin
+            subject.auto_register! { raise }
+          rescue ::RuntimeError
+          end
+          expect(subject.auto_register?).to be(false)
+        end
+        it 'returns nil' do
+          begin
+            result = subject.auto_register! { raise }
+          rescue ::RuntimeError
+          end
+          expect(result).to be(nil)
+        end
+      end
+      context 'when nested' do
+        it 'preserves the setting until the outer block ends' do
+          subject.auto_register! do
+            subject.auto_register! do
+              nil
+            end
+            expect(subject.auto_register?).to be(true)
+          end
+        end
+      end
+      context 'if the internal counter goes below zero' do
+        it 'be corrected on subsequent calls' do
+          subject.send(:_auto_registration).decrement
+          subject.auto_register! do
+            expect(subject.auto_register?).to be(true)
+          end
+        end
+      end
+    end
+    describe '::name' do
+      it 'includes the name of the integrating class' do
+        name = 'IntegratingKlass'
+        expectation = "Memorb:#{ name }"
+        ::Memorb::RubyCompatibility
+          .define_method(integrator_singleton, :name) { name }
+        expect(subject.name).to eq(expectation)
+      end
+      context 'when integrating class does not have a name' do
+        it 'uses the inspection of the integrating class' do
+          expectation = "Memorb:#{ integrator.inspect }"
+          ::Memorb::RubyCompatibility
+            .define_method(integrator_singleton, :name) { nil }
+          expect(subject.name).to eq(expectation)
+          ::Memorb::RubyCompatibility.undef_method(integrator_singleton, :name)
+          expect(subject.name).to eq(expectation)
+        end
+      end
+      context 'when integrating class does not have an inspection' do
+        it 'uses the object ID of the integrating class' do
+          expectation = "Memorb:#{ integrator.object_id }"
+          ::Memorb::RubyCompatibility
+            .define_method(integrator_singleton, :inspect) { nil }
+          expect(subject.name).to eq(expectation)
+          ::Memorb::RubyCompatibility.undef_method(integrator_singleton, :inspect)
+          expect(subject.name).to eq(expectation)
+        end
+      end
+    end
+    describe '::create_agent' do
+      it 'returns a agent object' do
+        agent = subject.create_agent(instance)
+        expect(agent).to be_an_instance_of(::Memorb::Agent)
+      end
+      it 'writes the agent to the global agent registry' do
+        agent = subject.create_agent(instance)
+        registry = subject.send(:_agents)
+        expect(registry.keys).to contain_exactly(agent.id)
+      end
+    end
+    it 'supports regularly invalid method names' do
+      invalid_starting_chars = [0x00..0x40, 0x5b..0x60, 0x7b..0xff]
+      method_name = invalid_starting_chars
+        .map(&:to_a)
+        .flatten
+        .map(&:chr)
+        .shuffle(random: ::SpecHelper.prng)
+        .join
+        .to_sym
+      subject.register(method_name)
+      ::Memorb::RubyCompatibility
+        .define_method(integrator, method_name) { nil }
+      expect(subject.registered_methods).to include(method_name)
+      expect(subject.enabled_methods).to include(method_name)
+      expect { instance.send(method_name) }.not_to raise_error
+    end
+    context 'when prepending on another class' do
+      it 'raises an error' do
+        klass = ::Class.new.singleton_class
+        error = ::Memorb::MismatchedTargetError
+        expect { klass.prepend(subject) }.to raise_error(error)
+      end
+    end
+    context 'when including with any class' do
+      it 'raises an error' do
+        klass = subject.integrator
+        error = ::Memorb::InvalidIntegrationError
+        error_message = 'an integration must be applied with `prepend`, not `include`'
+        expect { klass.include(subject) }.to raise_error(error, error_message)
+      end
+    end
+    ::SpecHelper.for_testing_garbage_collection do
+      context 'when freed by the garbage collector' do
+        it 'removes its agent from the global registry' do
+          ref = ::WeakRef.new(integrator.new)
+          agent = ref.__getobj__.memorb
+          expect(agent_registry.keys).to include(agent.id)
+          ::SpecHelper.force_garbage_collection
+          expect(ref.weakref_alive?).to be_falsey
+          expect(agent_registry.keys).to be_empty
+        end
+      end
+    end
+  end
+end