ractor-cache 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c2fb8ce98adad688d2ff0e150265154ba963c62a4c7cd88e87bb09ab366db535
-  data.tar.gz: fda4eb8307bb638e87841f418895c4f57297c975349c9502026b3346ad570256
+  metadata.gz: 8ed3b5b4ab4307230b9dab1a21f269ac9d3bae8803f11bb209798df4de02e031
+  data.tar.gz: ed75a15f8035a23955d1e25ce9c88e32a540881a2322ba0267c0c98302d50010
 SHA512:
-  metadata.gz: 38ad35d50bf189e0dc9f0da88f91f484664811824f1310e2e4a040f49b19d3f9f079c826d9667956d5d3ec4949e440583f7f38d74c6f6841af40a9f65b672453
-  data.tar.gz: fa23e9e4cebd2891ba3bfdfe81e8d88fe693e2efd770e2f08cc1be576bb3a46ddae543562c95c760e917f39f895ba64bb5e039fff6a68ea9e4eccb690194a8db
+  metadata.gz: 63984280a9bc9d9530e86cc4d9c69987a4dbcc0128cf3525bf434006bbfc3b00515f5fb1e2aa65c85050cb37691dd666d7b39f1d9d05574078c29713501c8780
+  data.tar.gz: 4e9725ab3449785e3b87a594c13c4175a083cc5910bf72c5fece2bcdcd4da7ce3c4ac4aa222553c6efceb8525a9490173e0f32274fdee13e6c9dfaeb01a0f878

data/.github/workflows/ractor-cache.yml

@@ -5,13 +5,16 @@ on: [pull_request]
 jobs:
   tests:
     name: >-
-      Specs | ${{ matrix.ruby }}
+      Specs ${{ matrix.with_backports }} | ${{ matrix.ruby }}
     runs-on: ${{ matrix.os }}-latest
     strategy:
       fail-fast: false
       matrix:
         os: [ ubuntu ]
-        ruby: [ 2.4, 2.5, 2.6, 2.7, head ]
+        ruby: [ 2.4, 2.5, 2.6, 2.7, 3.0, head ]
+        with_backports: [ null ]
+        include:
+          - { os: ubuntu, ruby: 2.7, with_backports: '(with Backports)' }
     steps:
       - name: checkout
         uses: actions/checkout@v2
@@ -19,6 +22,9 @@ jobs:
         uses: ruby/setup-ruby@v1
         with:
           ruby-version: ${{ matrix.ruby }}
+      - name: setup Env
+        if: matrix.with_backports
+        run: echo "B=true" >> $GITHUB_ENV
       - name: install dependencies
         run: bundle install --jobs 3 --retry 3
       - name: spec

data/.rubocop.yml

@@ -3,6 +3,11 @@ AllCops:
   TargetRubyVersion: 2.4
   NewCops: enable
 
+# Export
+
+Lint/EmptyClass:
+  Enabled: false
+
 # For sure
 
 Layout/LineLength:
@@ -52,3 +57,16 @@ Style/AccessModifierDeclarations:
 
 Style/DocumentDynamicEvalDefinition:
   Enabled: false
+
+Layout/EmptyLineAfterMagicComment:
+  Enabled: false # https://github.com/rubocop-hq/rubocop/issues/9327
+
+Style/MutableConstant:
+  Enabled: false # https://github.com/rubocop-hq/rubocop/issues/9328
+
+Lint/UselessAssignment:
+  Enabled: false # https://github.com/rubocop-hq/rubocop/issues/9330
+
+Layout/HashAlignment:
+  Exclude:
+    - 'lib/ractor/cache/cached_method.rb'

data/Gemfile

@@ -5,8 +5,8 @@ source 'https://rubygems.org'
 # Specify your gem's dependencies in ractor-cache.gemspec
 gemspec
 
-gem 'backports', git: 'https://github.com/marcandre/backports.git', branch: 'ractor'
-gem 'pry-byebug', require: false
-gem 'rake', require: false
-gem 'rspec', require: false
-gem 'rubocop', require: false
+gem 'backports'
+gem 'pry-byebug'
+gem 'rake'
+gem 'rspec'
+gem 'rubocop'

data/README.md

@@ -23,9 +23,11 @@ end
 ## Why?
 
 0) It's pretty
-1) It makes your class `Ractor`-compatible
+1) Handles `nil` / `false` results
+2) Works even for frozen instances
+3) Works even for deeply frozen instances (`Ractor`-shareable).
 
-## `Ractor`-compatible?
+## `Ractor`-shareable?
 
 Ractor is new in Ruby 3.0 and is awesome.
 
@@ -69,14 +71,9 @@ foo.long_calc # => `FrozenError`, @cache is frozen
 
 ## How to resolve this
 
-This gem will:
-1) Use a mutable data structure like above, which means no issue for shallow freezing an instance
-2) If an instance is deeply frozen, the gem will either insure things will keep working by applying any of the following strategies:
-- prebuild the cache,
-- not write to the cache,
-- (or maybe use a separate Ractor / `SharedHash`)
+This gem will use associate a mutable data structure to the instance. Even if deeply-frozen it can still mutate the data structure. The data is Ractor-local, so it won't be shared and won't cause issues. Internally a `WeakMap` is used to make sure objects are still garbage collected as they should.
 
-Implementation details pexplained here](hacker_guide.md)
+Implementation details [explained here](hacker_guide.md)
 
 ## Contributing
 

data/hacker_guide.md

@@ -1,5 +1,7 @@
 ### Structure
 
+(Code simplified: handling of `nil` / `false` not shown for simplicity)
+
 ```ruby
 using Ractor::Cache
 
@@ -17,7 +19,7 @@ class Mammal < Animal
 end
 
 class Ape < Mammal
-  cache def something_else # Supported if same strategy and signature
+  cache def something_else
     return super unless a_predicate?
 
     # specialized calculation
@@ -26,7 +28,7 @@ class Ape < Mammal
   def complex(arg)
     # ... calculation
   def
-  cache :complex, strategy: :disable
+  cache :complex
 end
 ```
 
@@ -34,42 +36,25 @@ Equivalent code:
 ```
 class Animal
   module RactorCacheLayer
-    CACHED = ... # private information of how things are cached
-
     # Where caching info is stored for `Animal`
     class Store
-      def initialize(owner)
-        @owner = owner
+      def cached_something_or_init
+        @something ||= yield
       end
 
-      attr_accessor :something, :something_else
-
-      def freeze # only called in case of deep-freezing
-        @owner.class::RactorCacheLayer.deep_freeze_callback(@owner)
-        super
-      end
+      # same for something_else
     end
 
     def something
-      ractor_cache.something ||= super
-    end
-
-    def freeze
-      ractor_cache # make sure cache store is built
-      super
-    end
-
-    def self.deep_freeze_callback(instance)
-      # strategy for `something` is prebuild:
-      instance.something
-      # same for `something_else`:
-      instance.something_else
+      ractor_cache.cached_something_or_init { super }
     end
 
     private
 
     def ractor_cache
+      # similar to:
       @ractor_cache ||= self.class::Store.new
+      # but actually using a ractor-local WeakMap instead of an instance variable
     end
   end
   prepend CacheLayer
@@ -85,38 +70,23 @@ end
 
 class Ape < Mammal
   module RactorCacheLayer
-    CACHED = ... # private array of Strategy
-
     # Where caching info is stored for `Ape`
     class Store < Animal::CacheLayer::Store
-      attr_reader :complex
-
-      def initialize(owner)
-        @complex = {}
-        super
+      def initilialize
+        @complex_fetch = {}
       end
-    end
 
-    def something_else
-      ractor_cache.something_else ||= super
+      def cached_complex_or_init(owner)
+        @complex_fetch[owner] ||= yield
+      end
     end
 
     def complex(arg)
-      hash = ractor_cache.complex
-      hash.fetch(arg) do
-        result = super
-        # strategy is disable:
-        hash[arg] = result unless frozen?
-        result
-      end
+      ractor_cache.cached_complex_or_init(arg) { super }
     end
 
-    def self.deep_freeze_callback(instance)
-      # strategy for `complex` is disable
-      # nothing to do
-      # process any other cached data
-      # and then
-      super
+    def something_else # refine again
+      ractor_cache.cached_something_else_or_init { super }
     end
   end
   prepend CacheLayer
@@ -134,10 +104,13 @@ Ape.ancestors # =>
   Animal,
   Object, #...
 ]
-```
-
-### Class ancestors
 
-In the "equivalent" code above, `Animal::CacheLayer` is actually an instance of `Ractor::Cache::CacheLayer`.
-
-`Animal::CacheLayer::Store` is a subclass of `Ractor::Cache::Store`
+m = Ape.instance_method(:something_else)
+# => #<UnboundMethod: Ape::CacheLayer#something_else()>
+m = m.super_method
+# => #<UnboundMethod: Ape#something_else()>
+m = m.super_method
+# => #<UnboundMethod: Animal::CacheLayer#something_else()>
+m = m.super_method
+# => #<UnboundMethod: Animal#something_else()>
+```

data/lib/ractor/cache.rb

@@ -7,8 +7,8 @@ class Ractor
   module Cache
     require_relative_dir
 
-    private def cache(method_name, strategy: nil)
-      CachingLayer[self].cache(method_name, strategy: strategy)
+    private def cache(method_name)
+      CachingLayer[self].cache(method_name)
     end
 
     refine Module do

data/lib/ractor/cache/cached_method.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+# shareable_constant_values: literal
+
+class Ractor
+  module Cache
+    module CachedMethod
+      Base = Struct.new(:method_name, :argument_kind)
+      class Base
+        def compile_method
+          <<~RUBY
+            def #{method_name}#{args}
+              ractor_cache.cached_#{method_name}_or_init#{args} { super }
+            end
+          RUBY
+        end
+
+        SIGNATURES = {
+          none:       [''],
+          positional: ['(*args)',        'args'],
+          keyword:    ['(**opt)',        'opt'],
+          both:       ['(*args, **opt)', '[args, opt]'],
+        }
+        private_constant :SIGNATURES
+
+        private def args
+          SIGNATURES.fetch(argument_kind).first
+        end
+
+        private def key
+          SIGNATURES.fetch(argument_kind).fetch(1)
+        end
+      end
+
+      class WithoutArgument < Base
+        def compile_initializer
+          ''
+        end
+
+        def compile_accessor
+          <<~RUBY
+            def cached_#{method_name}_or_init
+              return @#{method_name} if defined?(@#{method_name})
+
+              @#{method_name} = yield
+            end
+          RUBY
+        end
+      end
+
+      class WithArguments < Base
+        def compile_initializer
+          "@#{method_name} = {}"
+        end
+
+        def compile_accessor
+          <<~RUBY
+            def cached_#{method_name}_or_init#{args}
+              @#{method_name}.fetch(#{key}) do
+                @#{method_name}[#{key}] = yield
+              end
+            end
+          RUBY
+        end
+      end
+
+      class << self
+        def new(instance_method)
+          kind = argument_kind(instance_method.parameters)
+          klass = kind == :none ? WithoutArgument : WithArguments
+          klass.new(instance_method.name, kind)
+        end
+
+        private def argument_kind(parameters) # rubocop:disable Metrics/CyclomaticComplexity, Metrics/MethodLength
+          kind = :none
+          parameters.each do |type, name|
+            case type
+            when :req, :opt, :rest
+              return :both if type == :rest && name == :*
+
+              kind = :positional
+            when :key, :keyrest
+              return kind == :positional ? :both : :keyword
+            when :nokey, :block
+              # ignore
+            end
+          end
+          kind
+        end
+      end
+    end
+  end
+end

data/lib/ractor/cache/caching_layer.rb

@@ -3,18 +3,57 @@
 class Ractor
   module Cache
     module CachingLayer
-      def freeze
-        ractor_cache # Make sure the instance variable is created beforehand
-        super
-      end
+      use_ractor_storage = defined?(Ractor.current) && # check we are not running Backports on a Ruby that is compatible:
+                           begin
+                             (::ObjectSpace::WeakMap.new[Object.new.freeze] = []) # Ruby 2.6- didn't work with frozen keys
+                           rescue FrozenError
+                             false
+                           end
 
-      private def ractor_cache
-        @ractor_cache ||= self.class::Store.new(self)
+      if use_ractor_storage
+        private def ractor_cache
+          CachingLayer.ractor_storage[self] ||= self.class::Store.new
+        end
+      else
+        def freeze
+          ractor_cache
+          super
+        end
+
+        private def ractor_cache
+          @ractor_cache ||= self.class::Store.new
+        end
       end
 
       class << self
+        def ractor_storage
+          Ractor.current[:RactorCacheLocalStore] ||= ::ObjectSpace::WeakMap.new
+        end
+
         attr_reader :sublayer, :cached, :parent
 
+        def cache(method_name)
+          cm = cached_method(method_name)
+
+          file, line = cm.method(:compile_method).source_location
+          module_eval(cm.compile_method, file, line + 2)
+          @cached << cm
+          update_store_methods(self::Store)
+        end
+
+        private def update_store_methods(store)
+          init = @cached.map(&:compile_initializer).join("\n")
+
+          store.class_eval <<~RUBY, __FILE__, __LINE__ + 1
+            def initialize
+              #{init}
+            end
+
+            #{@cached.last.compile_accessor}
+          RUBY
+        end
+
+        # @api private
         def attach(mod, sublayer)
           @sublayer = sublayer
           @cached = []
@@ -26,29 +65,14 @@ class Ractor
           self
         end
 
-        def cache(method, strategy:)
-          strat = build_stragegy(method, strategy)
-          file, line = strat.method(:compile_accessor).source_location
-          module_eval(strat.compile_accessor, file, line + 2)
-          @cached << strat
-          self::Store.update(@cached)
-        end
-
-        def deep_freeze_callback(instance)
-          @cached.each do |strategy|
-            strategy.deep_freeze_callback(instance)
-          end
-          sublayer&.deep_freeze_callback(instance)
-        end
-
-        # @returns [Strategy]
-        private def build_stragegy(method, strategy)
+        # @returns [CachedMethod]
+        private def cached_method(method_name)
           im = begin
-            @parent.instance_method(method)
+            @parent.instance_method(method_name)
           rescue ::NameError => e
             raise e, "#{e.message}. Method must be defined before calling `cache`", e.backtrace
           end
-          Strategy.new(strategy, to_cache: im)
+          CachedMethod.new(im)
         end
 
         # Return `CachingLayer` in `mod`, creating it if need be.

data/lib/ractor/cache/store.rb

@@ -3,35 +3,7 @@
 class Ractor
   module Cache
     class Store
-      def initialize(owner) # Possibly redefined by `update`
-        @owner = owner
-      end
-
-      def freeze
-        @owner.class::RactorCacheLayer.deep_freeze_callback(@owner)
-        super
-      end
-
-      class << self
-        def update(cached)
-          update_accessors(cached)
-          update_init(cached)
-        end
-
-        private def update_accessors(cached)
-          attr_accessor(*cached.map(&:method_name))
-        end
-
-        private def update_init(cached)
-          body = cached.map(&:compile_store_init).join("\n")
-          class_eval <<~RUBY, __FILE__, __LINE__ + 1
-            def initialize(owner)
-              #{body}
-              super
-            end
-          RUBY
-        end
-      end
+      # No base methods. All actual methods defined by `CachingLayer`
     end
   end
 end

data/lib/ractor/cache/version.rb

@@ -2,6 +2,6 @@
 
 class Ractor
   module Cache
-    VERSION = '0.2.0'
+    VERSION = '0.3.0'
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ractor-cache
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Marc-Andre Lafortune
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2020-11-11 00:00:00.000000000 Z
+date: 2021-01-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: require_relative_dir
@@ -44,9 +44,9 @@ files:
 - bin/setup
 - hacker_guide.md
 - lib/ractor/cache.rb
+- lib/ractor/cache/cached_method.rb
 - lib/ractor/cache/caching_layer.rb
 - lib/ractor/cache/store.rb
-- lib/ractor/cache/strategy.rb
 - lib/ractor/cache/version.rb
 - ractor-cache.gemspec
 homepage: https://github.com/marcandre/ractor-cache

data/lib/ractor/cache/strategy.rb

@@ -1,121 +0,0 @@
-# frozen_string_literal: true
-
-class Ractor
-  module Cache
-    EMPTY_CACHE = Class.new.freeze # lazy way to get a name
-
-    module Strategy
-      class Base
-        attr_reader :parameters, :method_name
-
-        def initialize(instance_method)
-          @method_name = instance_method.name
-          analyse_parameters(instance_method.parameters)
-        end
-
-        def compile_store_init
-          init = @has_arguments ? "Hash.new { #{EMPTY_CACHE} }" : EMPTY_CACHE
-          "@#{method_name} = #{init}"
-        end
-
-        private def analyse_parameters(parameters) # rubocop:disable Metrics/CyclomaticComplexity, Metrics/MethodLength
-          @has_positional_arguments = @has_keywords_arguments = false
-          parameters.each do |type, name|
-            case type
-            when :req, :opt, :rest
-              @has_positional_arguments = true
-              @has_keywords_arguments = true if type == :rest && name == :*
-            when :key, :keyrest
-              @has_keywords_arguments = true
-            when :nokey, :block
-              # ignore
-            end
-            @has_arguments = @has_positional_arguments || @has_keywords_arguments
-          end
-        end
-
-        private def compile_lookup
-          args = [
-            *('args' if @has_positional_arguments),
-            *('opts' if @has_keywords_arguments),
-          ]
-
-          return if args.empty?
-
-          "[#{args.join(', ')}]"
-        end
-
-        private def signature
-          [
-            *('*args' if @has_positional_arguments),
-            *('**opts' if @has_keywords_arguments),
-          ].join(', ')
-        end
-      end
-
-      class Prebuild < Base
-        def initialize(*)
-          super
-          raise ArgumentError, "Can not cache method #{method_name} by prebuilding because it accepts arguments" if @has_arguments
-        end
-
-        def deep_freeze_callback(instance)
-          instance.__send__ method_name
-        end
-
-        def compile_accessor
-          <<~RUBY
-            def #{method_name}(#{signature})
-              r = ractor_cache.#{method_name}
-              return r unless r == EMPTY_CACHE
-
-              ractor_cache.#{method_name} = super
-            end
-          RUBY
-        end
-      end
-
-      class Disable < Base
-        def compile_accessor
-          <<~RUBY
-            def #{method_name}(#{signature})
-              r = ractor_cache.#{method_name}#{compile_lookup}
-              return r unless r == EMPTY_CACHE
-
-              r = super
-              ractor_cache.#{method_name}#{compile_lookup} = r unless ractor_cache.frozen?
-              r
-            end
-          RUBY
-        end
-
-        def deep_freeze_callback(instance)
-          # nothing to do
-        end
-      end
-
-      MAP = {
-        prebuild: Prebuild,
-        disable: Disable,
-      }.freeze
-      private_constant :MAP
-
-      class << self
-        def [](kind)
-          MAP.fetch(kind)
-        end
-
-        def new(
-          strategy = nil,    # => (:prebuild | :disable)?
-          to_cache:          # => UnboundMethod
-        )                    # => Strategy
-          self[strategy || :prebuild].new(to_cache)
-        rescue ArgumentError
-          return new(:disable, to_cache: to_cache) if strategy == nil
-
-          raise
-        end
-      end
-    end
-  end
-end