memorb 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 9724352c954ae84fd4004bc0cdc534fd71c847fdd5ceeb241a1b92855cd3374f
+  data.tar.gz: 3d1b910ae44c6680eb4ae5a997800630da89bffed0f851849b32beedfbbeb257
+SHA512:
+  metadata.gz: 62d3610c4f5591da319e16bef054ad79acc32329c4ea95e2a9fe793b1124e3059fdf6743a19130e1c6fd5a380bd387c3b0ea8b67b39e3fc13c01c4880b1b23ce
+  data.tar.gz: ece13fcec090a805cd010217e85d6ff3b42868156c47856f58781dc79faa1edb30eb88b06da0039869aac93cc59229c86c98c3c2d308376c39cf970538622983

data/.circleci/config.yml

@@ -0,0 +1,52 @@
+_: &steps
+  - checkout
+  - run:
+      name: Bundle
+      command: |
+        gem install bundler
+        bundle install
+  - run:
+      name: RSpec
+      command: bundle exec rspec
+
+version: 2
+jobs:
+  ruby-2.6:
+    docker:
+      - image: circleci/ruby:2.6
+    steps: *steps
+  ruby-2.5:
+    docker:
+      - image: circleci/ruby:2.5
+    steps: *steps
+  ruby-2.4:
+    docker:
+      - image: circleci/ruby:2.4
+    steps: *steps
+  ruby-2.3:
+    docker:
+      - image: circleci/ruby:2.3
+    steps: *steps
+  jruby-9.2:
+    docker:
+      - image: circleci/jruby:9.2
+    steps: *steps
+  jruby-9.1:
+    docker:
+      - image: circleci/jruby:9.1
+    steps: *steps
+  jruby-9.0:
+    docker:
+      - image: circleci/jruby:9
+    steps: *steps
+workflows:
+  version: 2
+  rubies:
+    jobs:
+      - ruby-2.6
+      - ruby-2.5
+      - ruby-2.4
+      - ruby-2.3
+      - jruby-9.2
+      - jruby-9.1
+      - jruby-9.0

data/.gitignore

@@ -0,0 +1,4 @@
+/pkg
+*.gem
+/.bundle
+/Gemfile.lock

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--order random
+--require spec_helper

data/Gemfile

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+source :rubygems
+gemspec

data/LICENSE.txt

@@ -0,0 +1,7 @@
+Copyright 2019 Patrick Rebsch
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,258 @@
+# Memorb
+
+Memoize instance methods with ease.
+
+[![CircleCI](https://circleci.com/gh/pjrebsch/memorb/tree/master.svg?style=svg)](https://circleci.com/gh/pjrebsch/memorb/tree/master)
+
+## Overview
+
+Below is a contrived example class that could benefit from memoization.
+
+```ruby
+class WeekForecast
+
+  def initialize(date:)
+    @date = date
+  end
+
+  def data
+    API.get '/weather/week', { date: @date.iso8601 }
+  end
+
+  def week_days
+    Date::ABBR_DAYNAMES.rotate(@date.wday)
+  end
+
+  def rain_on?(day)
+    percent_chance = data.dig('days', day.to_s, 'rain')
+    percent_chance > 75 if percent_chance
+  end
+
+  def will_rain?
+    week_days.any? { |wd| rain_on? wd }
+  end
+
+end
+```
+
+All of its instance methods could be memoized to save them from unnecessary recomputation or I/O.
+
+A common way of accomplishing memoization is to save the result in an instance variable:
+
+```ruby
+@will_rain ||= ...
+```
+
+But that approach is problematic for expressions that return a falsey value as the instance variable will be overlooked on subsequent evaluations. Often, the solution for this case is to instead check whether or not the instance variable has been previously defined:
+
+```ruby
+defined?(@will_rain) ? @will_rain : @will_rain = ...
+```
+
+While this does address the issue of falsey values, this is significantly more verbose. And neither of these approaches take into consideration the arguments to the method, which a method like `rain_on?` in the above example class would need to function properly.
+
+Memorb exists to make memoization in these cases much easier to implement. Simply register the methods with Memorb on the class and you're done:
+
+```ruby
+class WeekForecast
+  extend Memorb
+
+  memorb! def data
+    ...
+  end
+
+  memorb! def week_days
+    ...
+  end
+
+  memorb! def rain_on?(day)
+    ...
+  end
+
+  memorb! def will_rain?
+    ...
+  end
+end
+```
+
+These methods' return values will now be memoized for each instance of `WeekForecast`. The `rain_on?` method will memoize its return values based on the arguments supplied to it (in this case one argument since that's all it accepts), and the other methods will each memoize their single, independent return value.
+
+## Usage
+
+First, integrate Memorb into a class with `extend Memorb`. Then, use the `memorb!` class method to register instance methods for memoization.
+
+### Integrating Class Methods
+
+These methods are available as class methods on the integrating class.
+
+#### `memorb!`
+
+Use this method to register instance methods for memoization. When a method is both registered and defined, Memorb will override it. Once the method is overridden, it's considered "enabled" for memoization. On initial invocation with a given set of arguments, the method's return value is cached based on the given arguments and returned. Then, subsequent invocations of that method with the same arguments return the cached value.
+
+Internally, calls to the overriding method implementation are serialized with a read-write lock to guarantee that the initial method call is not subject to a race condition between threads, while also optimizing the performance of concurrent reads of the cached result.
+
+##### Prefix form
+
+Conveniently, methods defined using the `def` keyword return the method name, so the method definition can just be prefixed with a registration directive. This approach helps make apparent the fact that the method is being memoized when reading the method.
+
+```ruby
+memorb! def data
+  ...
+end
+```
+
+If you prefer `def` and `end` to align, you can move `memorb!` up to a new line and escape the line break. The Memorb registration methods require arguments, so if you forget to escape the line break, you'll be made aware with an exception when the class is loaded.
+
+```ruby
+memorb! \
+def data
+  ...
+end
+```
+
+##### List form
+
+If you wish to enumerate the methods to register all at once, or don't have access to a method's implementation source to use the Prefix form, you can supply a list of method names instead.
+
+```ruby
+memorb! :data, :week_days, :rain_on?, :will_rain?
+```
+
+Typos are a potential problem. Memorb can't know when a registered method's definition is going to occur, so if you mistype the name of a method you intend to define later, Memorb will anticipate that method's definition indefinitely and the method that you intended to register won't end up being memoized. The Prefix form is recommended for this reason.
+
+If you do use this form, you can check that all registered methods were enabled by validating that `memorb.disabled_methods` is empty, which might be a valuable addition in a test suite.
+
+##### Block form
+
+Instead of listing out method names or decorating their definitions, you can just define them within a block.
+
+```ruby
+memorb! do
+  def data
+    ...
+  end
+  def week_days
+    ...
+  end
+  def rain_on?(day)
+    ...
+  end
+  def will_rain?
+    ...
+  end
+end
+```
+
+Just be careful not to accidentally include any other methods that must always execute!
+
+It is also important to note that all instance methods that are defined while the block is executing will be registered, not necessarily just the ones that can be seen using the `def` keyword. This is also not thread-safe, so if you are defining methods concurrently (which you shouldn't be), you may risk registering methods you didn't intend to register.
+
+#### `memorb`
+
+Returns the `Memorb::Integration` instance for the integrating class.
+
+### Integration Methods
+
+These methods are available on the `Memorb::Integration` instance for an integrating class.
+
+#### `register`
+
+Alias of `memorb!`.
+
+#### `registered_methods`
+
+Returns the names of methods that have been registered for the integrating class.
+
+#### `registered?(method_name)`
+
+Returns whether or not the specified method is registered.
+
+#### `enable(method_name)` / `disable(method_name)`
+
+Enable/Disable a registered method.
+
+#### `enabled?(method_name)`
+
+Returns whether or not the specified method is enabled.
+
+#### `enabled_methods` / `disabled_methods`
+
+Returns which methods are registered and enabled/disabled for the integrating class.
+
+### Instance Methods
+
+These methods are available to instances of the integrating class.
+
+#### `memorb`
+
+Returns the `Memorb::Agent` for the object instance.
+
+## Advisories
+
+### Cache Explosion
+
+No, sorry, not [the show](https://www.cashexplosionshow.com/).
+
+Because memoization trades computation for memory, there is potential for memory explosion with a method that accepts arguments. All distinct sets of arguments to a method will map to a return value, and this mapping will be stored, so the potential for explosion increases exponentially as more arguments are supported. As long as the method is guaranteed to be called with a small, finite set of arguments, this needn't be much of a concern. But if the method is expected to handle arbitrary arguments or a large range of values, you may want to handle caching at a lower level within the method or even abandon the memoization/caching approach altogether.
+
+The `rain_on?` method in the example class represents a method that is subject to this. It can also be used as an example of how to handle caching at a lower level. The only valid arguments to it are a representation of the seven days of the week, so there need only ever be up to seven cache entries. The day might not always be passed as a string—it could be anything that responds to `to_s`. The logic of the method doesn't care because it always transforms the argument to a string, but Memorb can't know what values for that argument the method's logic would consider to be the same thing, so it would cache them as distinct values. A solution is to perform "argument normalization" and use the results of that to implement caching within the method:
+
+```ruby
+def rain_on?(day)
+  day = day.to_s
+  return unless week_days.include?(day)
+  memorb.fetch([__method__, day]) do
+    ...
+  end
+end
+```
+
+Obviously, this method doesn't benefit much from a caching approach in the first place: computation already needs to be done to achieve argument normalization and the actual logic for the method is quite lightweight. Methods that take arguments may not be good candidates for memoization because the explosion problem may represent too big a risk for the benefits that caching would provide, but this is a judgment call to be made per case.
+
+### Blocks are not considered distinguishing arguments
+
+Memorb ignores block arguments when determining whether or not a method has been called with the same arguments. It doesn't matter if a block is provided explicitly (using `&block` as a parameter), provided implicitly (using `yield` in the method body), or not provided at all. Therefore, blocks should not be used to distinguish otherwise equivalent method calls for the sake of memoization.
+
+However, a `Proc` can be passed as a normal argument and it _will_ be used in distinguishing method calls.
+
+### Redefining an enabled method
+
+Redefining a method that Memorb has already overridden can be done. Since Memorb's override of the method is of greater precedence, Memorb will continue to work for the method. But if you are doing this, you'll want to read this section to understand what behavior to expect.
+
+Any return values from previous executions of the method will remain in Memorb's cache even after the method has been redefined. If the method was redefined in a way that return values from the old definition no longer make sense for the application, then you can clear the cache after redefining the method.
+
+If redefinining the method changes its class visibility, see the next section.
+
+### Changing the visibility of an enabled method
+
+If you change the visibility of an enabled method, Memorb won't automatically know that it needs to change the visibility of its corresponding override, so the visibility change will appear to have not worked because Memorb's override takes precedence. Memorb is unable to reliably override the visibility modifier for a class to detect such changes on its own (see [this Ruby not-a-bug report](https://bugs.ruby-lang.org/issues/16100)). You're advised to avoid doing this.
+
+### Aliasing overridden methods
+
+Using `alias_method` in Ruby will create a copy of the method implementation found at that time. This means that the aliased method will have different behavior relative to when the method was overridden by Memorb. If the method was aliased before override by Memorb, then its calls will not reference the cache of the original method, but if aliased after the override, then such calls will reference the cache.
+
+### Alias method chaining on overridden methods
+
+If you or another library uses alias method chaining on a method that Memorb has overridden, you will experience infinite recursion upon calling that method. See [this article](https://blog.newrelic.com/engineering/ruby-agent-module-prepend-alias-method-chains/) for an explanation of the incompatibility between using `Module#prepend` (which Memorb uses internally) with the alias method chaining technique. Refactoring such alias method chaining in the integrating class to instead use `Module#prepend` will prevent this issue.
+
+### Potential for initial method invocation race
+
+If you are relying on Memorb's serialization for method invocation to prevent multiple executions of a method body across threads, then you should read this section.
+
+Memorb overrides a registered method only once that method has been defined. To prevent `respond_to?` from returning true for an instance prematurely or allowing the method to be called prematurely, Memorb must wait until after the method is officially defined. There is no way to hook into Ruby's method definition process (in pure Ruby), so Memorb can only know of a method definition event after it has occurred using Ruby's provided notification methods.
+
+This means that there is a small window of time between when a registered method is originally defined and when Memorb overrides it with memoization support. For methods that are registered and defined within the initial class definition, this shouldn't be a problem because there should be no instantiations of the class before its initial definition is closed. But methods that are defined dynamically may be able to be called by another thread before Memorb has had a chance to override them.
+
+## Potential Enhancements
+
+### Ability to configure Memorb
+
+It could be beneficial to configure Memorb, though the options for configuration are unclear.
+
+### Ability to log cache accesses
+
+Caching introduces the possibility of bugs when things are cached too much. It would be helpful for debugging to be able to configure a `Logger` for cache accesses.
+
+### Alternative to instance variables
+
+Expanding Memorb to more than just memoization could include providing enhanced features for local instance state, such as capturing parameters during `initialize`.

data/Rakefile

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require 'bundler'
+Bundler::GemHelper.install_tasks

data/lib/memorb.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require_relative 'memorb/version'
+require_relative 'memorb/ruby_compatibility'
+require_relative 'memorb/errors'
+require_relative 'memorb/method_identifier'
+require_relative 'memorb/key_value_store'
+require_relative 'memorb/integrator_class_methods'
+require_relative 'memorb/integration'
+require_relative 'memorb/agent'
+
+module Memorb
+  class << self
+
+    def extended(target)
+      Integration.integrate_with!(target)
+    end
+
+    def included(*)
+      _raise_invalid_integration_error!
+    end
+
+    def prepended(*)
+      _raise_invalid_integration_error!
+    end
+
+    private
+
+    def _raise_invalid_integration_error!
+      raise InvalidIntegrationError, 'Memorb must be integrated using `extend`'
+    end
+
+  end
+end

data/lib/memorb/agent.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Memorb
+  class Agent
+
+    def initialize(id)
+      @id = id
+      @store = KeyValueStore.new
+    end
+
+    attr_reader :id
+
+    def method_store
+      store.fetch(:methods) { KeyValueStore.new }
+    end
+
+    def value_store
+      store.fetch(:value) { KeyValueStore.new }
+    end
+
+    def fetch(key, &block)
+      value_store.fetch(key.hash, &block)
+    end
+
+    private
+
+    attr_reader :store
+
+  end
+end

data/lib/memorb/errors.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Memorb
+
+  class InvalidIntegrationError < ::StandardError
+  end
+
+  class MismatchedTargetError < ::StandardError
+  end
+
+end

data/lib/memorb/integration.rb

@@ -0,0 +1,277 @@
+# frozen_string_literal: true
+
+require 'concurrent'
+
+module Memorb
+  module Integration
+    class << self
+
+      def integrate_with!(target)
+        unless target.is_a?(::Class)
+          raise InvalidIntegrationError, 'integration target must be a class'
+        end
+        INTEGRATIONS.fetch(target) do
+          new(target).tap do |integration|
+            target.singleton_class.prepend(IntegratorClassMethods)
+            target.prepend(integration)
+          end
+        end
+      end
+
+      def integrated?(target)
+        INTEGRATIONS.has?(target)
+      end
+
+      def [](integrator)
+        INTEGRATIONS.read(integrator)
+      end
+
+      private
+
+      INTEGRATIONS = KeyValueStore.new
+
+      def new(integrator)
+        mixin = ::Module.new do
+          def initialize(*)
+            agent = Integration[self.class].create_agent(self)
+            define_singleton_method(:memorb) { agent }
+            super
+          end
+
+          class << self
+
+            def register(*names, &block)
+              names_present = !names.empty?
+              block_present = !block.nil?
+
+              if names_present && block_present
+                raise ::ArgumentError,
+                  'register may not be called with both a method name and a block'
+              elsif names_present
+                names.flatten.each { |n| _register_from_name(_identifier(n)) }
+              elsif block_present
+                _register_from_block(&block)
+              else
+                raise ::ArgumentError,
+                  'register must be called with either a method name or a block'
+              end
+
+              nil
+            end
+
+            def registered_methods
+              _identifiers_to_symbols(_registrations.keys)
+            end
+
+            def registered?(name)
+              _registered?(_identifier(name))
+            end
+
+            def enable(name)
+              _enable(_identifier(name))
+            end
+
+            def disable(name)
+              _disable(_identifier(name))
+            end
+
+            def enabled_methods
+              _identifiers_to_symbols(_overrides.keys)
+            end
+
+            def disabled_methods
+              registered_methods - enabled_methods
+            end
+
+            def enabled?(name)
+              _enabled?(_identifier(name))
+            end
+
+            def purge(name)
+              _purge(_identifier(name))
+            end
+
+            def auto_register?
+              _auto_registration.value > 0
+            end
+
+            def auto_register!(&block)
+              raise ::ArgumentError, 'a block must be provided' if block.nil?
+              _auto_registration.update { |v| [0, v].max + 1 }
+              begin
+                block.call
+              ensure
+                _auto_registration.update { |v| [0, v - 1].max }
+              end
+            end
+
+            def prepended(target)
+              _check_target!(target)
+              super
+            end
+
+            def included(*)
+              raise InvalidIntegrationError,
+                'an integration must be applied with `prepend`, not `include`'
+            end
+
+            def name
+              [:name, :inspect, :object_id].each do |m|
+                next unless integrator.respond_to?(m)
+                base_name = integrator.public_send(m)
+                return "Memorb:#{ base_name }" if base_name
+              end
+            end
+
+            alias_method :inspect, :name
+
+            # Never save reference to the integrator instance or it may
+            # never be garbage collected!
+            def create_agent(integrator_instance)
+              Agent.new(integrator_instance.object_id).tap do |agent|
+                _agents.write(agent.id, agent)
+
+                # The proc must not be made here because it would save a
+                # reference to `integrator_instance`.
+                finalizer = _agent_finalizer(agent.id)
+                ::ObjectSpace.define_finalizer(integrator_instance, finalizer)
+              end
+            end
+
+            private
+
+            def _check_target!(target)
+              unless target.equal?(integrator)
+                raise MismatchedTargetError
+              end
+            end
+
+            def _identifier(name)
+              MethodIdentifier.new(name)
+            end
+
+            def _identifiers_to_symbols(method_ids)
+              method_ids.map(&:to_sym)
+            end
+
+            def _register_from_name(method_id)
+              _registrations.write(method_id, nil)
+              _enable(method_id)
+            end
+
+            def _register_from_block(&block)
+              auto_register! do
+                integrator.class_eval(&block)
+              end
+            end
+
+            def _registered?(method_id)
+              _registrations.keys.include?(method_id)
+            end
+
+            def _enable(method_id)
+              return unless _registered?(method_id)
+
+              visibility = _integrator_instance_method_visibility(method_id)
+              return if visibility.nil?
+
+              _overrides.fetch(method_id) do
+                _define_override(method_id)
+                _set_visibility(visibility, method_id.to_sym)
+              end
+            end
+
+            def _disable(method_id)
+              _overrides.forget(method_id)
+              _remove_override(method_id)
+            end
+
+            def _enabled?(method_id)
+              _overrides.keys.include?(method_id)
+            end
+
+            def _purge(method_id)
+              _agents.keys.each do |id|
+                agent = _agents.read(id)
+                store = agent&.method_store&.read(method_id)
+                store&.reset!
+              end
+            end
+
+            def _remove_override(method_id)
+              # Ruby will raise an exception if the method doesn't exist.
+              # Catching it is the safest thing to do for thread-safety.
+              # The alternative would be to check the list if it were
+              # present or not, but the read could be outdated by the time
+              # that we tried to remove the method and this exception
+              # wouldn't be caught.
+              remove_method(method_id.to_sym)
+            rescue ::NameError => e
+              # If this exception was for something else, it should be re-raised.
+              unless RubyCompatibility.name_error_matches(e, method_id, self)
+                raise e
+              end
+            end
+
+            def _define_override(method_id)
+              define_method(method_id.to_sym) do |*args, &block|
+                memorb.method_store
+                  .fetch(method_id) { KeyValueStore.new }
+                  .fetch(args.hash) { super(*args, &block) }
+              end
+            end
+
+            def _integrator_instance_method_visibility(method_id)
+              [:public, :protected, :private].find do |visibility|
+                methods = integrator.send(:"#{ visibility }_instance_methods")
+                methods.include?(method_id.to_sym)
+              end
+            end
+
+            def _set_visibility(visibility, name)
+              send(visibility, name)
+              visibility
+            end
+
+            def _agent_finalizer(agent_id)
+              # This must not be a lambda proc, otherwise GC hangs!
+              ::Proc.new { _agents.forget(agent_id) }
+            end
+
+            def _registrations
+              RubyCompatibility.module_constant(self, :registrations)
+            end
+
+            def _overrides
+              RubyCompatibility.module_constant(self, :overrides)
+            end
+
+            def _agents
+              RubyCompatibility.module_constant(self, :agents)
+            end
+
+            def _auto_registration
+              RubyCompatibility.module_constant(self, :auto_registration)
+            end
+
+          end
+        end
+
+        RubyCompatibility.module_constant_set(mixin, :registrations, KeyValueStore.new)
+        RubyCompatibility.module_constant_set(mixin, :overrides, KeyValueStore.new)
+        RubyCompatibility.module_constant_set(mixin, :agents, KeyValueStore.new)
+        RubyCompatibility.module_constant_set(mixin,
+          :auto_registration,
+          ::Concurrent::AtomicFixnum.new,
+        )
+
+        RubyCompatibility.define_method(mixin.singleton_class, :integrator) do
+          integrator
+        end
+
+        mixin
+      end
+
+    end
+  end
+end