memo_wise 0.4.0 → 1.3.0

data/benchmarks/benchmarks.rb

@@ -2,17 +2,21 @@
 
 require "benchmark/ips"
 
+require "tempfile"
 require "memo_wise"
 
 # Some gems do not yet work in Ruby 3 so we only require them if they're loaded
 # in the Gemfile.
-%w[memery memoist memoized memoizer].
+%w[memery memoist memoized memoizer ddmemoize dry-core].
   each { |gem| require gem if Gem.loaded_specs.key?(gem) }
 
 # The VERSION constant does not get loaded above for these gems.
 %w[memoized memoizer].
   each { |gem| require "#{gem}/version" if Gem.loaded_specs.key?(gem) }
 
+# The Memoizable module from dry-core needs to be required manually
+require "dry/core/memoizable" if Gem.loaded_specs.key?("dry-core")
+
 class BenchmarkSuiteWithoutGC
   def warming(*)
     run_gc
@@ -36,7 +40,7 @@ class BenchmarkSuiteWithoutGC
 end
 suite = BenchmarkSuiteWithoutGC.new
 
-BenchmarkGem = Struct.new(:klass, :inheritance_method, :memoization_method) do
+BenchmarkGem = Struct.new(:klass, :activation_code, :memoization_method) do
   def benchmark_name
     "#{klass} (#{klass::VERSION})"
   end
@@ -47,160 +51,171 @@ end
 # NOTE: Some gems do not yet work in Ruby 3 so we only test with them if they've
 # been `require`d.
 BENCHMARK_GEMS = [
-  BenchmarkGem.new(MemoWise, :prepend, :memo_wise),
-  (BenchmarkGem.new(Memery, :include, :memoize) if defined?(Memery)),
-  (BenchmarkGem.new(Memoist, :extend, :memoize) if defined?(Memoist)),
-  (BenchmarkGem.new(Memoized, :include, :memoize) if defined?(Memoized)),
-  (BenchmarkGem.new(Memoizer, :include, :memoize) if defined?(Memoizer))
+  BenchmarkGem.new(MemoWise, "prepend MemoWise", :memo_wise),
+  (BenchmarkGem.new(DDMemoize, "DDMemoize.activate(self)", :memoize) if defined?(DDMemoize)),
+  (BenchmarkGem.new(Dry::Core, "include Dry::Core::Memoizable", :memoize) if defined?(Dry::Core)),
+  (BenchmarkGem.new(Memery, "include Memery", :memoize) if defined?(Memery)),
+  (BenchmarkGem.new(Memoist, "extend Memoist", :memoize) if defined?(Memoist)),
+  (BenchmarkGem.new(Memoized, "include Memoized", :memoize) if defined?(Memoized)),
+  (BenchmarkGem.new(Memoizer, "include Memoizer", :memoize) if defined?(Memoizer))
 ].compact.shuffle
 
 # Use metaprogramming to ensure that each class is created in exactly the
 # the same way.
 BENCHMARK_GEMS.each do |benchmark_gem|
-  # rubocop:disable Security/Eval
-  # rubocop:disable Style/DocumentDynamicEvalDefinition
-  eval <<-CLASS, binding, __FILE__, __LINE__ + 1
+  eval <<~HEREDOC, binding, __FILE__, __LINE__ + 1 # rubocop:disable Security/Eval
+    # For these methods, we alternately return truthy and falsey values in
+    # order to benchmark memoization when the result of a method is falsey.
+    #
+    # We do this by checking if the first argument to a method is even.
     class #{benchmark_gem.klass}Example
-      #{benchmark_gem.inheritance_method} #{benchmark_gem.klass}
+      #{benchmark_gem.activation_code}
 
       def no_args
         100
       end
       #{benchmark_gem.memoization_method} :no_args
 
+      # For the no_args case, we can't depend on arguments to alternate between
+      # returning truthy and falsey values, so instead make two separate
+      # no_args methods
+      def no_args_falsey
+        nil
+      end
+      #{benchmark_gem.memoization_method} :no_args_falsey
+
+      def one_positional_arg(a)
+        100 if a.positive?
+      end
+      #{benchmark_gem.memoization_method} :one_positional_arg
+
       def positional_args(a, b)
-        100
+        100 if a.positive?
       end
       #{benchmark_gem.memoization_method} :positional_args
 
+      def one_keyword_arg(a:)
+        100 if a.positive?
+      end
+      #{benchmark_gem.memoization_method} :one_keyword_arg
+
       def keyword_args(a:, b:)
-        100
+        100 if a.positive?
       end
       #{benchmark_gem.memoization_method} :keyword_args
 
       def positional_and_keyword_args(a, b:)
-        100
+        100 if a.positive?
       end
       #{benchmark_gem.memoization_method} :positional_and_keyword_args
 
       def positional_and_splat_args(a, *args)
-        100
+        100 if a.positive?
       end
       #{benchmark_gem.memoization_method} :positional_and_splat_args
 
       def keyword_and_double_splat_args(a:, **kwargs)
-        100
+        100 if a.positive?
       end
       #{benchmark_gem.memoization_method} :keyword_and_double_splat_args
 
       def positional_splat_keyword_and_double_splat_args(a, *args, b:, **kwargs)
-        100
+        100 if a.positive?
       end
       #{benchmark_gem.memoization_method} :positional_splat_keyword_and_double_splat_args
     end
-  CLASS
-  # rubocop:enable Style/DocumentDynamicEvalDefinition
-  # rubocop:enable Security/Eval
+  HEREDOC
 end
 
 # We pre-create argument lists for our memoized methods with arguments, so that
 # our benchmarks are running the exact same inputs for each case.
-N_UNIQUE_ARGUMENTS = 100
+#
+# NOTE: The proportion of falsey results is 1/N_UNIQUE_ARGUMENTS (because for
+# the methods with arguments we are truthy for all but the first unique argument
+# set, and for zero-arity methods we manually execute `no_args` N_TRUTHY_RESULTS
+# times per each execution of `no_args_falsey`). This number was selected as the
+# lowest number such that this logic:
+#
+#   output = hash[key]
+#   if output || hash.key?(key)
+#     output
+#   else
+#     hash[key] = _original_method(...)
+#   end
+#
+# is consistently faster for cached lookups than:
+#
+#   hash.fetch(key) do
+#     hash[key] = _original_method(...)
+#   end
+#
+# as a result of `Hash#[]` having less overhead than `Hash#fetch`.
+#
+# We believe this is a reasonable choice because we believe most memoized method
+# results will be truthy, and so that is the case we should most optimize for.
+# However, we do not want to completely remove falsey method results from these
+# benchmarks because we do want to catch performance regressions for that case,
+# since it has its own "hot path."
+N_UNIQUE_ARGUMENTS = 30
 ARGUMENTS = Array.new(N_UNIQUE_ARGUMENTS) { |i| [i, i + 1] }
-
-# We benchmark different cases separately, to ensure that slow performance in
-# one method or code path isn't hidden by fast performance in another.
-
-Benchmark.ips do |x|
-  x.config(suite: suite)
-  BENCHMARK_GEMS.each do |benchmark_gem|
-    instance = Object.const_get("#{benchmark_gem.klass}Example").new
-
-    # Run once to memoize the result value, so our benchmark only tests memoized
-    # retrieval time.
+N_TRUTHY_RESULTS = N_UNIQUE_ARGUMENTS - 1
+N_RESULT_DECIMAL_DIGITS = 2
+
+# Each method within these benchmarks is initially run once to memoize the
+# result value, so our benchmark only tests memoized retrieval time.
+benchmark_lambdas = [
+  lambda do |x, instance, benchmark_gem|
+    instance.no_args_falsey
     instance.no_args
 
-    x.report("#{benchmark_gem.benchmark_name}: ()") { instance.no_args }
-  end
-
-  x.compare!
-end
-
-Benchmark.ips do |x|
-  x.config(suite: suite)
-  BENCHMARK_GEMS.each do |benchmark_gem|
-    instance = Object.const_get("#{benchmark_gem.klass}Example").new
+    x.report("#{benchmark_gem.benchmark_name}: ()") do
+      instance.no_args_falsey
+      N_TRUTHY_RESULTS.times { instance.no_args }
+    end
+  end,
+  lambda do |x, instance, benchmark_gem|
+    ARGUMENTS.each { |a, _| instance.one_positional_arg(a) }
 
-    # Run once with each set of arguments to memoize the result values, so our
-    # benchmark only tests memoized retrieval time.
+    x.report("#{benchmark_gem.benchmark_name}: (a)") do
+      ARGUMENTS.each { |a, _| instance.one_positional_arg(a) }
+    end
+  end,
+  lambda do |x, instance, benchmark_gem|
     ARGUMENTS.each { |a, b| instance.positional_args(a, b) }
 
     x.report("#{benchmark_gem.benchmark_name}: (a, b)") do
       ARGUMENTS.each { |a, b| instance.positional_args(a, b) }
     end
-  end
-
-  x.compare!
-end
+  end,
+  lambda do |x, instance, benchmark_gem|
+    ARGUMENTS.each { |a, _| instance.one_keyword_arg(a: a) }
 
-Benchmark.ips do |x|
-  x.config(suite: suite)
-  BENCHMARK_GEMS.each do |benchmark_gem|
-    instance = Object.const_get("#{benchmark_gem.klass}Example").new
-
-    # Run once with each set of arguments to memoize the result values, so our
-    # benchmark only tests memoized retrieval time.
+    x.report("#{benchmark_gem.benchmark_name}: (a:)") do
+      ARGUMENTS.each { |a, _| instance.one_keyword_arg(a: a) }
+    end
+  end,
+  lambda do |x, instance, benchmark_gem|
     ARGUMENTS.each { |a, b| instance.keyword_args(a: a, b: b) }
 
     x.report("#{benchmark_gem.benchmark_name}: (a:, b:)") do
       ARGUMENTS.each { |a, b| instance.keyword_args(a: a, b: b) }
     end
-  end
-
-  x.compare!
-end
-
-Benchmark.ips do |x|
-  x.config(suite: suite)
-  BENCHMARK_GEMS.each do |benchmark_gem|
-    instance = Object.const_get("#{benchmark_gem.klass}Example").new
-
-    # Run once with each set of arguments to memoize the result values, so our
-    # benchmark only tests memoized retrieval time.
+  end,
+  lambda do |x, instance, benchmark_gem|
     ARGUMENTS.each { |a, b| instance.positional_and_keyword_args(a, b: b) }
 
     x.report("#{benchmark_gem.benchmark_name}: (a, b:)") do
       ARGUMENTS.each { |a, b| instance.positional_and_keyword_args(a, b: b) }
     end
-  end
-
-  x.compare!
-end
-
-Benchmark.ips do |x|
-  x.config(suite: suite)
-  BENCHMARK_GEMS.each do |benchmark_gem|
-    instance = Object.const_get("#{benchmark_gem.klass}Example").new
-
-    # Run once with each set of arguments to memoize the result values, so our
-    # benchmark only tests memoized retrieval time.
+  end,
+  lambda do |x, instance, benchmark_gem|
     ARGUMENTS.each { |a, b| instance.positional_and_splat_args(a, b) }
 
     x.report("#{benchmark_gem.benchmark_name}: (a, *args)") do
       ARGUMENTS.each { |a, b| instance.positional_and_splat_args(a, b) }
     end
-  end
-
-  x.compare!
-end
-
-Benchmark.ips do |x|
-  x.config(suite: suite)
-  BENCHMARK_GEMS.each do |benchmark_gem|
-    instance = Object.const_get("#{benchmark_gem.klass}Example").new
-
-    # Run once with each set of arguments to memoize the result values, so our
-    # benchmark only tests memoized retrieval time.
+  end,
+  lambda do |x, instance, benchmark_gem|
     ARGUMENTS.each { |a, b| instance.keyword_and_double_splat_args(a: a, b: b) }
 
     x.report(
@@ -210,18 +225,8 @@ Benchmark.ips do |x|
         instance.keyword_and_double_splat_args(a: a, b: b)
       end
     end
-  end
-
-  x.compare!
-end
-
-Benchmark.ips do |x|
-  x.config(suite: suite)
-  BENCHMARK_GEMS.each do |benchmark_gem|
-    instance = Object.const_get("#{benchmark_gem.klass}Example").new
-
-    # Run once with each set of arguments to memoize the result values, so our
-    # benchmark only tests memoized retrieval time.
+  end,
+  lambda do |x, instance, benchmark_gem|
     ARGUMENTS.each do |a, b|
       instance.positional_splat_keyword_and_double_splat_args(a, b, b: b, a: a)
     end
@@ -235,6 +240,62 @@ Benchmark.ips do |x|
       end
     end
   end
+]
+
+# We benchmark different cases separately, to ensure that slow performance in
+# one method or code path isn't hidden by fast performance in another.
+benchmark_lambdas.map do |benchmark|
+  json_file = Tempfile.new
+
+  Benchmark.ips do |x|
+    x.config(suite: suite)
+    BENCHMARK_GEMS.each do |benchmark_gem|
+      instance = Object.const_get("#{benchmark_gem.klass}Example").new
+
+      benchmark.call(x, instance, benchmark_gem)
+    end
+
+    x.compare!
+    x.json! json_file.path
+  end
+
+  JSON.parse(json_file.read)
+end.each_with_index do |benchmark_json, i|
+  # We print a comparison table after we run each benchmark to copy into our
+  # README.md
+
+  # MemoWise will not appear in the comparison table, but we will use it to
+  # compare against other gems' benchmarks
+  memo_wise = benchmark_json.find { _1["name"].include?("MemoWise") }
+  benchmark_json.delete(memo_wise)
+
+  # Sort benchmarks by gem name to alphabetize our final output table.
+  benchmark_json.sort_by! { _1["name"] }
+
+  # Print headers based on the first benchmark_json
+  if i.zero?
+    benchmark_headers = benchmark_json.map do |benchmark_gem|
+      # Gem name is of the form:
+      # "MemoWise (1.1.0): ()"
+      # We use this mapping to get a header of the form
+      # "`MemoWise` (1.1.0)
+      gem_name_parts = benchmark_gem["name"].split
+      "`#{gem_name_parts[0]}` #{gem_name_parts[1][...-1]}"
+    end.join("|")
+    puts "|Method arguments|#{benchmark_headers}|"
+    puts "#{'|--' * (benchmark_json.size + 1)}|"
+  end
 
-  x.compare!
+  output_str = benchmark_json.map do |bgem|
+    # "%.2f" % 12.345 => "12.34" (instead of "12.35")
+    #   See: https://bugs.ruby-lang.org/issues/12548
+    # 1.00.round(2).to_s => "1.0" (instead of "1.00")
+    #
+    # So to round and format correctly, we first use Float#round and then %
+    "%.#{N_RESULT_DECIMAL_DIGITS}fx" %
+      (memo_wise["central_tendency"] / bgem["central_tendency"]).round(N_RESULT_DECIMAL_DIGITS)
+  end.join("|")
+
+  name = memo_wise["name"].partition(": ").last
+  puts "|`#{name}`#{' (none)' if name == '()'}|#{output_str}|"
 end

data/lib/memo_wise/internal_api.rb

@@ -0,0 +1,309 @@
+# frozen_string_literal: true
+
+module MemoWise
+  class InternalAPI
+    # Create initial mutable state to store memoized values if it doesn't
+    # already exist
+    #
+    # @param [Object] obj
+    #   Object in which to create mutable state to store future memoized values
+    #
+    # @return [Object] the passed-in obj
+    def self.create_memo_wise_state!(obj)
+      # `@_memo_wise` stores memoized results of method calls. The structure is
+      # slightly different for different types of methods. It looks like:
+      #   [
+      #     :memoized_result, # For method 0 (which takes no arguments)
+      #     { arg1 => :memoized_result, ... }, # For method 1 (which takes an argument)
+      #     { [arg1, arg2] => :memoized_result, ... } # For method 2 (which takes multiple arguments)
+      #   ]
+      # This is a faster alternative to:
+      #   {
+      #     zero_arg_method_name: :memoized_result,
+      #     single_arg_method_name: { arg1 => :memoized_result, ... },
+      #
+      #     # Surprisingly, this is faster than a single top-level hash key of: [:multi_arg_method_name, arg1, arg2]
+      #     multi_arg_method_name: { [arg1, arg2] => :memoized_result, ... }
+      #   }
+      # because we can give each method its own array index at load time and
+      # perform that array lookup more quickly than a hash lookup by method
+      # name.
+      obj.instance_variable_set(:@_memo_wise, []) unless obj.instance_variable_defined?(:@_memo_wise)
+
+      # For zero-arity methods, memoized values are stored in the `@_memo_wise`
+      # array. Arrays do not differentiate between "unset" and "set to nil" and
+      # so to handle this case we need another array to store sentinels and
+      # store `true` at indexes for which a zero-arity method has been memoized.
+      # `@_memo_wise_sentinels` looks like:
+      #   [
+      #     true, # A zero-arity method's result has been memoized
+      #     nil, # A zero-arity method's result has not been memoized
+      #     nil, # A one-arity method will always correspond to `nil` here
+      #     ...
+      #   ]
+      # NOTE: Because `@_memo_wise` stores memoized values for more than just
+      # zero-arity methods, the `@_memo_wise_sentinels` array can end up being
+      # sparse (see above), even when all methods' memoized values have been
+      # stored. If this becomes an issue we could store a separate index for
+      # zero-arity methods to make every element in `@_memo_wise_sentinels`
+      # correspond to a zero-arity method.
+      # NOTE: Surprisingly, lookups on an array of `true` and `nil` values
+      # appear to outperform even bitwise operators on integers (as of Ruby
+      # 3.0.2), allowing us to avoid more complex sentinel structures.
+      unless obj.instance_variable_defined?(:@_memo_wise_sentinels)
+        obj.instance_variable_set(:@_memo_wise_sentinels, [])
+      end
+
+      obj
+    end
+
+    NONE = :none
+    ONE_REQUIRED_POSITIONAL = :one_required_positional
+    ONE_REQUIRED_KEYWORD = :one_required_keyword
+    MULTIPLE_REQUIRED = :multiple_required
+    SPLAT = :splat
+    DOUBLE_SPLAT = :double_splat
+    SPLAT_AND_DOUBLE_SPLAT = :splat_and_double_splat
+
+    # @param method [UnboundMethod] a method to categorize based on the types of
+    #   arguments it has
+    # @return [Symbol] one of:
+    #   - :none (example: `def foo`)
+    #   - :one_required_positional (example: `def foo(a)`)
+    #   - :one_required_keyword (example: `def foo(a:)`)
+    #   - :multiple_required (examples: `def foo(a, b)`, `def foo(a:, b:)`, `def foo(a, b:)`)
+    #   - :splat (examples: `def foo(a=1)`, `def foo(a, *b)`)
+    #   - :double_splat (examples: `def foo(a: 1)`, `def foo(a:, **b)`)
+    #   - :splat_and_double_splat (examples: `def foo(a=1, b: 2)`, `def foo(a=1, **b)`, `def foo(*a, **b)`)
+    def self.method_arguments(method)
+      return NONE if method.arity.zero?
+
+      parameters = method.parameters.map(&:first)
+
+      if parameters == [:req]
+        ONE_REQUIRED_POSITIONAL
+      elsif parameters == [:keyreq]
+        ONE_REQUIRED_KEYWORD
+      elsif parameters.all? { |type| type == :req || type == :keyreq }
+        MULTIPLE_REQUIRED
+      elsif parameters & %i[req opt rest] == parameters.uniq
+        SPLAT
+      elsif parameters & %i[keyreq key keyrest] == parameters.uniq
+        DOUBLE_SPLAT
+      else
+        SPLAT_AND_DOUBLE_SPLAT
+      end
+    end
+
+    # @param method [UnboundMethod] a method being memoized
+    # @return [String] the arguments string to use when defining our new
+    #   memoized version of the method
+    def self.args_str(method)
+      case method_arguments(method)
+      when SPLAT then "*args"
+      when DOUBLE_SPLAT then "**kwargs"
+      when SPLAT_AND_DOUBLE_SPLAT then "*args, **kwargs"
+      when ONE_REQUIRED_POSITIONAL, ONE_REQUIRED_KEYWORD, MULTIPLE_REQUIRED
+        method.parameters.map do |type, name|
+          "#{name}#{':' if type == :keyreq}"
+        end.join(", ")
+      else
+        raise ArgumentError, "Unexpected arguments for #{method.name}"
+      end
+    end
+
+    # @param method [UnboundMethod] a method being memoized
+    # @return [String] the arguments string to use when calling the original
+    #   method in our new memoized version of the method, i.e. when setting a
+    #   memoized value
+    def self.call_str(method)
+      case method_arguments(method)
+      when SPLAT then "*args"
+      when DOUBLE_SPLAT then "**kwargs"
+      when SPLAT_AND_DOUBLE_SPLAT then "*args, **kwargs"
+      when ONE_REQUIRED_POSITIONAL, ONE_REQUIRED_KEYWORD, MULTIPLE_REQUIRED
+        method.parameters.map do |type, name|
+          type == :req ? name : "#{name}: #{name}"
+        end.join(", ")
+      else
+        raise ArgumentError, "Unexpected arguments for #{method.name}"
+      end
+    end
+
+    # @param method [UnboundMethod] a method being memoized
+    # @return [String] the string to use as a hash key when looking up a
+    #   memoized value, based on the method's arguments
+    def self.key_str(method)
+      case method_arguments(method)
+      when SPLAT then "args"
+      when DOUBLE_SPLAT then "kwargs"
+      when SPLAT_AND_DOUBLE_SPLAT then "[args, kwargs]"
+      when MULTIPLE_REQUIRED then "[#{method.parameters.map(&:last).join(', ')}]"
+      else
+        raise ArgumentError, "Unexpected arguments for #{method.name}"
+      end
+    end
+
+    # Find the original class for which the given class is the corresponding
+    # "singleton class".
+    #
+    # See https://stackoverflow.com/questions/54531270/retrieve-a-ruby-object-from-its-singleton-class
+    #
+    # @param klass [Class]
+    #   Singleton class to find the original class of
+    #
+    # @return Class
+    #   Original class for which `klass` is the singleton class.
+    #
+    # @raise ArgumentError
+    #   Raises if `klass` is not a singleton class.
+    #
+    def self.original_class_from_singleton(klass)
+      raise ArgumentError, "Must be a singleton class: #{klass.inspect}" unless klass.singleton_class?
+
+      # Since we call this method a lot, we memoize the results. This can have a
+      # huge impact; for example, in our test suite this drops our test times
+      # from over five minutes to just a few seconds.
+      @original_class_from_singleton ||= {}
+
+      # Search ObjectSpace
+      #   * 1:1 relationship of singleton class to original class is documented
+      #   * Performance concern: searches all Class objects
+      #     But, only runs at load time and results are memoized
+      @original_class_from_singleton[klass] ||= ObjectSpace.each_object(Module).find do |cls|
+        cls.singleton_class == klass
+      end
+    end
+
+    # Increment the class's method index counter, and return an index to use for
+    # the given method name.
+    #
+    # @param klass [Class]
+    #   Original class on which a method is being memoized
+    #
+    # @param method_name [Symbol]
+    #   The name of the method being memoized
+    #
+    # @return [Integer]
+    #   The index within `@_memo_wise` to store the method's memoized results
+    def self.next_index!(klass, method_name)
+      # `@_memo_wise_indices` stores the `@_memo_wise` indices of different
+      # method names. We only use this data structure when resetting or
+      # presetting memoization. It looks like:
+      #   {
+      #     single_arg_method_name: 0,
+      #     other_single_arg_method_name: 1
+      #   }
+      memo_wise_indices = klass.instance_variable_get(:@_memo_wise_indices)
+      memo_wise_indices ||= klass.instance_variable_set(:@_memo_wise_indices, {})
+
+      # When a parent and child class both use `class << self` to define
+      # memoized class methods, the child class' singleton is not considered a
+      # descendent of the parent class' singleton. Because we store the index
+      # counter as a class variable that can be shared up the inheritance chain,
+      # we want to detect this case and store it on the original class instead
+      # of the singleton to make the counter shared correctly.
+      counter_class = klass.singleton_class? ? original_class_from_singleton(klass) : klass
+
+      # We use a class variable for tracking the index to make this work with
+      # inheritance structures. When a parent and child class both use
+      # MemoWise, we want the child class's index to not "reset" back to 0 and
+      # overwrite the behavior of a memoized parent method. Using a class
+      # variable will share the index data between parent and child classes.
+      #
+      # However, we don't use a class variable for `@_memo_wise_indices`
+      # because we want to allow instance and class methods with the same name
+      # to both be memoized, and using a class variable would share that index
+      # data between them.
+      index = if counter_class.class_variable_defined?(:@@_memo_wise_index_counter)
+                counter_class.class_variable_get(:@@_memo_wise_index_counter)
+              else
+                0
+              end
+
+      memo_wise_indices[method_name] = index
+      counter_class.class_variable_set(:@@_memo_wise_index_counter, index + 1) # rubocop:disable Style/ClassVars
+
+      index
+    end
+
+    # Convention we use for renaming the original method when we replace with
+    # the memoized version in {MemoWise.memo_wise}.
+    #
+    # @param method_name [Symbol]
+    #   Name for which to return the renaming for the original method
+    #
+    # @return [Symbol]
+    #   Renamed method to use for the original method with name `method_name`
+    #
+    def self.original_memo_wised_name(method_name)
+      :"_memo_wise_original_#{method_name}"
+    end
+
+    # @param target [Class, Module]
+    #   The class to which we are prepending MemoWise to provide memoization;
+    #   the `InternalAPI` *instance* methods will refer to this `target` class.
+    def initialize(target)
+      @target = target
+    end
+
+    # @return [Class, Module]
+    attr_reader :target
+
+    # @param method_name [Symbol] the name of the memoized method
+    # @return [Integer] the array index in `@_memo_wise_indices` to use to find
+    #   the memoization data for the given method
+    def index(method_name)
+      target_class.instance_variable_get(:@_memo_wise_indices)[method_name]
+    end
+
+    # Returns visibility of an instance method defined on class `target`.
+    #
+    # @param method_name [Symbol]
+    #   Name of existing *instance* method find the visibility of.
+    #
+    # @return [:private, :protected, :public]
+    #   Visibility of existing instance method of the class.
+    #
+    # @raise ArgumentError
+    #   Raises `ArgumentError` unless `method_name` is a `Symbol` corresponding
+    #   to an existing **instance** method defined on `klass`.
+    #
+    def method_visibility(method_name)
+      if target.private_method_defined?(method_name)
+        :private
+      elsif target.protected_method_defined?(method_name)
+        :protected
+      elsif target.public_method_defined?(method_name)
+        :public
+      else
+        raise ArgumentError, "#{method_name.inspect} must be a method on #{target}"
+      end
+    end
+
+    # Validates that {.memo_wise} has already been called on `method_name`.
+    #
+    # @param method_name [Symbol]
+    #   Name of method to validate has already been setup with {.memo_wise}
+    def validate_memo_wised!(method_name)
+      original_name = self.class.original_memo_wised_name(method_name)
+
+      unless target_class.private_method_defined?(original_name)
+        raise ArgumentError, "#{method_name} is not a memo_wised method"
+      end
+    end
+
+    private
+
+    # @return [Class] where we look for method definitions
+    def target_class
+      if target.instance_of?(Class)
+        # A class's methods are defined in its singleton class
+        target.singleton_class
+      else
+        # An object's methods are defined in its class
+        target.class
+      end
+    end
+  end
+end

data/lib/memo_wise/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module MemoWise
-  VERSION = "0.4.0"
+  VERSION = "1.3.0"
 end