memo_wise 1.0.0 → 1.4.0

data/lib/memo_wise/internal_api.rb

@@ -10,114 +10,138 @@ module MemoWise
     #
     # @return [Object] the passed-in obj
     def self.create_memo_wise_state!(obj)
-      unless obj.instance_variables.include?(:@_memo_wise)
-        obj.instance_variable_set(:@_memo_wise, {})
+      # `@_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
 
-    # Determine whether `method` takes any *positional* args.
-    #
-    # These are the types of positional args:
-    #
-    #   * *Required* -- ex: `def foo(a)`
-    #   * *Optional* -- ex: `def foo(b=1)`
-    #   * *Splatted* -- ex: `def foo(*c)`
-    #
-    # @param method [Method, UnboundMethod]
-    #   Arguments of this method will be checked
-    #
-    # @return [Boolean]
-    #   Return `true` if `method` accepts one or more positional arguments
-    #
-    # @example
-    #   class Example
-    #     def no_args
-    #     end
-    #
-    #     def position_arg(a)
-    #     end
-    #   end
-    #
-    #   MemoWise::InternalAPI.
-    #     has_arg?(Example.instance_method(:no_args)) #=> false
-    #
-    #   MemoWise::InternalAPI.
-    #     has_arg?(Example.instance_method(:position_arg)) #=> true
-    #
-    def self.has_arg?(method) # rubocop:disable Naming/PredicateName
-      method.parameters.any? do |param, _|
-        param == :req || param == :opt || param == :rest # rubocop:disable Style/MultipleComparison
+    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
 
-    # Determine whether `method` takes any *keyword* args.
-    #
-    # These are the types of keyword args:
-    #
-    #   * *Keyword Required* -- ex: `def foo(a:)`
-    #   * *Keyword Optional* -- ex: `def foo(b: 1)`
-    #   * *Keyword Splatted* -- ex: `def foo(**c)`
-    #
-    # @param method [Method, UnboundMethod]
-    #   Arguments of this method will be checked
-    #
-    # @return [Boolean]
-    #   Return `true` if `method` accepts one or more keyword arguments
-    #
-    # @example
-    #   class Example
-    #     def position_args(a, b=1)
-    #     end
-    #
-    #     def keyword_args(a:, b: 1)
-    #     end
-    #   end
-    #
-    #   MemoWise::InternalAPI.
-    #     has_kwarg?(Example.instance_method(:position_args)) #=> false
-    #
-    #   MemoWise::InternalAPI.
-    #     has_kwarg?(Example.instance_method(:keyword_args)) #=> true
-    #
-    def self.has_kwarg?(method) # rubocop:disable Naming/PredicateName
-      method.parameters.any? do |param, _|
-        param == :keyreq || param == :key || param == :keyrest # rubocop:disable Style/MultipleComparison
+    # @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
 
-    # Determine whether `method` takes only *required* args.
-    #
-    # These are the types of required args:
-    #
-    #   * *Required* -- ex: `def foo(a)`
-    #   * *Keyword Required* -- ex: `def foo(a:)`
-    #
-    # @param method [Method, UnboundMethod]
-    #   Arguments of this method will be checked
-    #
-    # @return [Boolean]
-    #   Return `true` if `method` accepts only required arguments
-    #
-    # @example
-    #   class Ex
-    #     def optional_args(a=1, b: 1)
-    #     end
-    #
-    #     def required_args(a, b:)
-    #     end
-    #   end
-    #
-    #   MemoWise::InternalAPI.
-    #     has_only_required_args?(Ex.instance_method(:optional_args))
-    #     #=> false
-    #
-    #   MemoWise::InternalAPI.
-    #     has_only_required_args?(Ex.instance_method(:required_args))
-    #     #=> true
-    def self.has_only_required_args?(method) # rubocop:disable Naming/PredicateName
-      method.parameters.all? { |type, _| type == :req || type == :keyreq } # rubocop:disable Style/MultipleComparison
+    # @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
@@ -135,15 +159,20 @@ module MemoWise
     #   Raises if `klass` is not a singleton class.
     #
     def self.original_class_from_singleton(klass)
-      unless klass.singleton_class?
-        raise ArgumentError, "Must be a singleton class: #{klass.inspect}"
-      end
+      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
-      ObjectSpace.each_object(Class).find { |cls| cls.singleton_class == klass }
+      #     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
 
     # Convention we use for renaming the original method when we replace with
@@ -159,56 +188,20 @@ module MemoWise
       :"_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
-
-    # Returns the "fetch key" for the given `method_name` and parameters, to be
-    # used to lookup the memoized results specifically for this method and these
-    # parameters.
-    #
-    # @param method_name [Symbol]
-    #   Name of method to derive the "fetch key" for, with given parameters.
-    # @param args [Array]
-    #   Zero or more positional parameters
-    # @param kwargs [Hash]
-    #   Zero or more keyword parameters
-    #
-    # @return [Array, Hash, Object]
-    #   Returns one of:
-    #     - An `Array` if only positional parameters.
-    #     - A nested `Array<Array, Hash>` if *both* positional and keyword.
-    #     - A `Hash` if only keyword parameters.
-    #     - A single object if there is only a single parameter.
-    def fetch_key(method_name, *args, **kwargs)
-      method = target_class.instance_method(method_name)
-
-      if MemoWise::InternalAPI.has_only_required_args?(method)
-        key = method.parameters.map.with_index do |(type, name), index|
-          type == :req ? args[index] : kwargs[name]
-        end
-        key.size == 1 ? key.first : key
-      else
-        has_arg = MemoWise::InternalAPI.has_arg?(method)
-
-        if has_arg && MemoWise::InternalAPI.has_kwarg?(method)
-          [args, kwargs].freeze
-        elsif has_arg
-          args
-        else
-          kwargs
-        end
-      end
+    # @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 self.index(target, method_name)
+      klass = target_class(target)
+      indices = klass.instance_variable_get(:@_memo_wise_indices)
+      indices&.[](method_name) || next_index!(klass, method_name)
     end
 
     # Returns visibility of an instance method defined on class `target`.
     #
+    # @param target [Class, Module]
+    #   The class to which we are prepending MemoWise to provide memoization.
+    #
     # @param method_name [Symbol]
     #   Name of existing *instance* method find the visibility of.
     #
@@ -219,7 +212,7 @@ module MemoWise
     #   Raises `ArgumentError` unless `method_name` is a `Symbol` corresponding
     #   to an existing **instance** method defined on `klass`.
     #
-    def method_visibility(method_name)
+    def self.method_visibility(target, method_name)
       if target.private_method_defined?(method_name)
         :private
       elsif target.protected_method_defined?(method_name)
@@ -227,25 +220,29 @@ module MemoWise
       elsif target.public_method_defined?(method_name)
         :public
       else
-        raise ArgumentError,
-              "#{method_name.inspect} must be a method on #{target}"
+        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 target [Class, Module]
+    #   The class to which we are prepending MemoWise to provide memoization.
+    #
     # @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)
+    def self.validate_memo_wised!(target, method_name)
+      original_name = original_memo_wised_name(method_name)
 
-      unless target_class.private_method_defined?(original_name)
+      unless target_class(target).private_method_defined?(original_name)
         raise ArgumentError, "#{method_name} is not a memo_wised method"
       end
     end
 
+    # @param target [Class, Module]
+    #   The class to which we are prepending MemoWise to provide memoization.
     # @return [Class] where we look for method definitions
-    def target_class
+    def self.target_class(target)
       if target.instance_of?(Class)
         # A class's methods are defined in its singleton class
         target.singleton_class
@@ -254,5 +251,36 @@ module MemoWise
         target.class
       end
     end
+    private_class_method :target_class
+
+    # 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, {})
+
+      index = klass.instance_variable_get(:@_memo_wise_index_counter) || 0
+      memo_wise_indices[method_name] = index
+      klass.instance_variable_set(:@_memo_wise_index_counter, index + 1)
+
+      index
+    end
+    private_class_method :next_index!
   end
 end

data/lib/memo_wise/version.rb

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