attr_memoized 0.2.2 → 0.3.0

data/.rubocop_todo.yml

@@ -0,0 +1,110 @@
+# This configuration was generated by
+# `rubocop --auto-gen-config`
+# on 2020-04-30 18:01:43 -0700 using RuboCop version 0.82.0.
+# The point is for the user to remove these configuration records
+# one by one as the offenses are removed from the code base.
+# Note that changes in the inspected code, or installation of new
+# versions of RuboCop, may require this file to be generated again.
+
+# Offense count: 14
+# Cop supports --auto-correct.
+# Configuration parameters: AllowMultipleStyles, EnforcedHashRocketStyle, EnforcedColonStyle, EnforcedLastArgumentHashStyle.
+# SupportedHashRocketStyles: key, separator, table
+# SupportedColonStyles: key, separator, table
+# SupportedLastArgumentHashStyles: always_inspect, always_ignore, ignore_implicit, ignore_explicit
+Layout/HashAlignment:
+  Exclude:
+    - 'spec/attr_memoized_spec.rb'
+
+# Offense count: 1
+# Cop supports --auto-correct.
+Layout/MultilineBlockLayout:
+  Exclude:
+    - 'spec/support/shared_examples.rb'
+
+# Offense count: 1
+# Configuration parameters: IgnoredMethods.
+Metrics/AbcSize:
+  Max: 36
+
+# Offense count: 3
+# Configuration parameters: CountComments, ExcludedMethods.
+# ExcludedMethods: refine
+Metrics/BlockLength:
+  Max: 65
+
+# Offense count: 2
+# Configuration parameters: CountComments, ExcludedMethods.
+Metrics/MethodLength:
+  Max: 48
+
+# Offense count: 1
+Naming/AsciiIdentifiers:
+  Exclude:
+    - 'spec/multi_attribute_spec.rb'
+
+# Offense count: 1
+# Configuration parameters: EnforcedStyleForLeadingUnderscores.
+# SupportedStylesForLeadingUnderscores: disallowed, required, optional
+Naming/MemoizedInstanceVariableName:
+  Exclude:
+    - 'lib/attr_memoized.rb'
+
+# Offense count: 1
+# Configuration parameters: IgnoredPatterns.
+# SupportedStyles: snake_case, camelCase
+Naming/MethodName:
+  EnforcedStyle: snake_case
+
+# Offense count: 2
+# Configuration parameters: AllowedChars.
+Style/AsciiComments:
+  Exclude:
+    - 'lib/attr_memoized.rb'
+
+# Offense count: 1
+# Cop supports --auto-correct.
+# Configuration parameters: EnforcedStyle, ProceduralMethods, FunctionalMethods, IgnoredMethods, AllowBracesOnProceduralOneLiners, BracesRequiredMethods.
+# SupportedStyles: line_count_based, semantic, braces_for_chaining, always_braces
+# ProceduralMethods: benchmark, bm, bmbm, create, each_with_object, measure, new, realtime, tap, with_object
+# FunctionalMethods: let, let!, subject, watch
+# IgnoredMethods: lambda, proc, it
+Style/BlockDelimiters:
+  Exclude:
+    - 'lib/attr_memoized.rb'
+
+# Offense count: 1
+# Cop supports --auto-correct.
+Style/IfUnlessModifier:
+  Exclude:
+    - 'lib/attr_memoized.rb'
+
+# Offense count: 1
+# Cop supports --auto-correct.
+# Configuration parameters: PreferredDelimiters.
+Style/PercentLiteralDelimiters:
+  Exclude:
+    - 'spec/support/pet_store.rb'
+
+# Offense count: 8
+# Cop supports --auto-correct.
+# Configuration parameters: EnforcedStyle, ConsistentQuotesInMultiline.
+# SupportedStyles: single_quotes, double_quotes
+Style/StringLiterals:
+  Exclude:
+    - 'Gemfile'
+    - 'Rakefile'
+    - 'bin/console'
+    - 'spec/multi_attribute_spec.rb'
+
+# Offense count: 1
+Style/StructInheritance:
+  Exclude:
+    - 'spec/support/pet_store.rb'
+
+# Offense count: 24
+# Cop supports --auto-correct.
+# Configuration parameters: AutoCorrect, AllowHeredoc, AllowURI, URISchemes, IgnoreCopDirectives, IgnoredPatterns.
+# URISchemes: http, https
+Layout/LineLength:
+  Max: 271

data/.travis.yml

@@ -2,9 +2,13 @@ sudo: false
 language: ruby
 cache: bundler
 rvm:
- - jruby-9.1.9.0
- - 2.3.4
- - 2.4.1
-before_install: gem install bundler -v 1.15.1
+ - 2.4.10
+ - 2.5.8
+ - 2.6.6
+ - 2.7.1
+ - jruby-9.2.11.1
+before_install: 
+- gem update --system
+- gem install bundler -v 2.1.4
 after_success:
 - bundle exec codeclimate-test-reporter

data/.vscode/settings.json

@@ -0,0 +1,7 @@
+{
+  "cSpell.words": [
+    "Memoized",
+    "memoization",
+    "mutex"
+  ]
+}

data/Gemfile

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 source "https://rubygems.org"
 
 # Specify your gem's dependencies in attr_memoized.gemspec

data/README.adoc

@@ -0,0 +1,199 @@
+:doctype: book
+:toc:
+
+image:https://travis-ci.org/kigster/attr_memoized.svg?branch=master[Build Status,link=https://travis-ci.org/kigster/attr_memoized]
+image:https://codeclimate.com/github/kigster/attr_memoized/badges/gpa.svg[Code Climate,link=https://codeclimate.com/github/kigster/attr_memoized]
+image:https://codeclimate.com/github/kigster/attr_memoized/badges/coverage.svg[Test Coverage,link=https://codeclimate.com/github/kigster/attr_memoized/coverage]
+image:https://codeclimate.com/github/kigster/attr_memoized/badges/issue_count.svg[Issue Count,link=https://codeclimate.com/github/kigster/attr_memoized]
+
+= AttrMemoized
+
+This is a simple, and yet powerful *memoization* library, with a specific goal of being *thread-safe* during lazy-loading of expensive to create
+attributes.
+Class method
+`attr_memoized` automatically generates attribute reader and attribute writer methods. The reader performs a thread-safe lazy-initialization of
+each attribute. The writer performs a thread-safe assignment. You can disable writer method generation by using `attr_memoized_reader` class
+method instead of the `attr_memoized`.
+
+This gems provides a shorthand syntax for defining lazy-initialized variables as "one-liners", while additionally providing thread-safety
+guarantees around lazy-initialization of attributes, or attribute assignments.
+
+[discrete]
+WARNING: **Caveat**:
+If the initialization or assignment returns a "falsey" result (ie, `false` or `nil`), then the attribute will attempt to be re-initialized every
+time its "reader" method is called. This is not a bug. We treat falsey value as uninitialized by design.
+
+== Complete Example
+
+Below we have a `Configuration` class that has several attributes that are all lazy loaded.
+
+[source,ruby]
+----
+require 'redis'
+require 'attr_memoized'
+
+module Concurrent
+  class RedisConfig
+
+    include AttrMemoized
+
+    CONTENT_KEY = 'site-content'.freeze
+
+    # This imports instance method #with_lock+, and class methods
+    # #attr_memoized, and #attr_memoized_reader.
+
+    attr_memoized_reader :redis_key,    -> { CONTENT_KEY }
+    attr_memoized_reader :redis_config, -> { { host: 'localhost', port: 6379 } }
+    attr_memoized_reader :redis,        -> { Redis.new(redis_config) }
+    attr_memoized_reader :contents,     -> { redis.get(redis_key) }
+
+
+    # #with_lock method if offered in place of the #synchronize
+    # to avoid double-locking within the same thread.
+    def reload_config!(new_key)
+      with_lock do
+        self.redis_key = new_key
+        contents(reload: true)
+      end
+    end
+  end
+end
+
+@config = Concurrent::RedisConfig.new
+@config.contents
+#=> { "host": "127.0.0.1" }
+@config.reload_config!('another_file')
+#=> { "host": "google.com" }
+@config.contents
+#=> { "host": "google.com" }
+----
+
+=== The Problem
+
+One of the issues with memoization in multi-threaded environment is that it may lead to unexpected or undefined behavior, due to the situation known as a https://stackoverflow.com/questions/34510/what-is-a-race-condition[_race condition_].
+
+Consider the following example:
+
+[source,ruby]
+----
+class Account
+  def self.owner
+    # Slow expensive query
+    @owner ||= ActiveRecord::Base.execute('select ...').first
+  end
+end
+
+# Let's be dangerous:
+[ Thread.new { Account.owner },
+  Thread.new { Account.owner } ].map(&:join)
+----
+
+==== Deeper into the `||=`
+
+Ruby evaluates `a||=b` as `a || a=b`, which means that the assignment above won't happen if `a` is "falsey", ie. `false` or `nil`. If the method `self.owner` is not synchronized, then both threads will execute the expensive query, and only the result of the query executed by the second thread will be saved in `@owner`, even though by that time it will already have a value assigned by the first thread, that by that time had already completed.
+
+Most memoization gems out there, among those that the author had reviewed, did not seem to be concerned with thread safety, which is actually OK under wide ranging situations, particularly if the objects are not meant to be shared across threads.
+
+But in multi-threaded applications it's important to protect initializers of expensive resources, which is exactly what this library attempts to accomplish.
+
+== Using `attr_memoized`
+
+`AttrMemoized` -- the gem's primary module, when included, decorates the receiver with several useful
+methods:
+
+* Pre-initialized class method `#attr_memoized_mutex`. Each class that includes `AttrMemoized` gets their own mutex.
+
+* Pre-initialized instance method `#attr_memoized_mutex`. Each instance of the class gets it's own dedicated mutex.
+
+* Convenience method `#with_lock` is provided in place of `#attr_memoized_mutex.synchronize` and should be used to wrap any state changes to the class in order to guard against concurrent modification by other threads. It will only use `mutex.synchronize` once per thread, to avoid self-deadlocking.
+
+* New class method `#attr_memoized` is added, with the following syntax:
+
+[source,ruby]
+----
+attr_memoized :attr, [ :aliases, ], -> { block returning a value }     # A proc
+attr_memoized :attr, [ :aliases, ], :instance_method, arg1: value, ... # A symbol
+attr_memoized :attr, [ :aliases, ], SomeClass.method(:method_name)     # A method
+----
+
+* In the above definitions:
+ ** If a `Proc` is provided as an initializer, it will be called via `#instance_exec` method on the instance and, therefore, can access any public or private method of the instance without the need for `self.` receiver.
+
+ ** If the initializer is a `Symbol`, it is expected to be an instance method name, of a method that accepts keyword arguments - in other words the methods should always have `**opts` as the last argument, even if you are not using them.
+ +
+ *** The reason for this is that you can supply arguments to methods when defining lazy initializations, for instance — take a look at the definition of `pi25` in the provided example `NumericHelper` below.
+
+ ** Finally, any `Method` instance can also be used.
+
+ ** Note, that multiple attribute names can be passed to `#attr_memoized`, and they will be lazy-loaded in the order of access and independently of each other. If the block always returns the same exactly value, then the list may be viewed as aliases. But if the block returns a new value each time its called, then each attribute will be initialized with a different value, eg:
+
+[source,ruby]
+----
+Kernel.srand # init random numbers
+require 'attr_memoized'
+require 'bigdecimal/math'
+
+class NumericHelper
+  include AttrMemoized
+  attr_memoized :random1,
+                :random2,
+                :random3, -> { rand(2**64) }
+
+  attr_memoized :pi, :π  # call a class method when accessed
+
+  # Returns PI as a string with digits.
+  def self.π(digits: 25)
+    precision = digits
+    result = BigMath.PI(precision)
+    result = result.truncate(precision).to_s
+    result = result[2..-1]                # Remove '0.'
+    result = result.split('e').first      # Remove 'e1'
+    result.insert(1, '.')
+  end
+end
+
+rng = NumericHelper.new
+# each is initialized as it's called, and so they
+# are all different:
+rng.random1 #=> 1304594275874777789
+rng.random2 #=> 12671375021040220422
+rng.random3 #=> 16656281832060271071
+
+# second time, they are all already memoized:
+rng.random1 #=> 1304594275874777789
+rng.random2 #=> 12671375021040220422
+rng.random3 #=> 16656281832060271071
+
+rng.pi      #=>
+----
+
+== Installation
+
+Add this line to your application's Gemfile:
+
+[source,ruby]
+----
+gem 'attr_memoized'
+----
+
+And then execute:
+
+ $ bundle
+
+Or install it yourself as:
+
+ $ gem install attr_memoized
+
+== Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to https://rubygems.org[rubygems.org].
+
+== Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/kigster/attr_memoized.
+
+== License
+
+The gem is available as open source under the terms of the http://opensource.org/licenses/MIT[MIT License].

data/Rakefile

@@ -1,6 +1,8 @@
+# frozen_string_literal: true
+
 require "bundler/gem_tasks"
 require "rspec/core/rake_task"
 
 RSpec::Core::RakeTask.new(:spec)
 
-task :default => :spec
+task default: :spec

data/attr_memoized.gemspec

@@ -1,5 +1,6 @@
-# coding: utf-8
-lib = File.expand_path('../lib', __FILE__)
+# frozen_string_literal: true
+
+lib = File.expand_path('lib', __dir__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 require 'attr_memoized/version'
 
@@ -9,8 +10,8 @@ Gem::Specification.new do |spec|
   spec.authors       = ['Konstantin Gredeskoul']
   spec.email         = ['kig@reinvent.one']
 
-  spec.summary       = %q{Memoize attributes in a thread-safe way. This ruby gem adds a `#attr_memoized` class method, that provides a lazy-loading mechanism for initializing "heavy" attributes, but in a thread-safe way. Instances thus created can be shared among threads.}
-  spec.description   = %q{Memoize attributes in a thread-safe way. This ruby gem adds a `#attr_memoized` class method, that provides a lazy-loading mechanism for initializing "heavy" attributes, but in a thread-safe way. Instances thus created can be shared among threads.}
+  spec.summary       = 'Memoize attributes in a thread-safe way. This ruby gem adds a `#attr_memoized` class method, that provides a lazy-loading mechanism for initializing "heavy" attributes, but in a thread-safe way. Instances thus created can be shared among threads.'
+  spec.description   = 'Memoize attributes in a thread-safe way. This ruby gem adds a `#attr_memoized` class method, that provides a lazy-loading mechanism for initializing "heavy" attributes, but in a thread-safe way. Instances thus created can be shared among threads.'
   spec.homepage      = 'https://github.com/kigster/attr_memoized'
   spec.license       = 'MIT'
 
@@ -21,12 +22,14 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ['lib']
 
-  spec.add_development_dependency 'bundler', '~> 1'
-  spec.add_development_dependency 'rake', '~> 12'
-  spec.add_development_dependency 'rspec', '~> 3'
+  spec.add_development_dependency 'bundler'
+  spec.add_development_dependency 'codeclimate-test-reporter'
+  spec.add_development_dependency 'colored2'
+  spec.add_development_dependency 'irbtools'
+  spec.add_development_dependency 'rake'
+  spec.add_development_dependency 'relaxed-rubocop'
+  spec.add_development_dependency 'rspec'
   spec.add_development_dependency 'rspec-its'
+  spec.add_development_dependency 'rubocop'
   spec.add_development_dependency 'simplecov'
-  spec.add_development_dependency 'irbtools'
-  spec.add_development_dependency 'colored2'
-  spec.add_development_dependency 'codeclimate-test-reporter'
 end

data/bin/console

@@ -1,4 +1,5 @@
 #!/usr/bin/env ruby
+# frozen_string_literal: true
 
 require "bundler/setup"
 require "attr_memoized"

data/lib/attr_memoized.rb

@@ -1,11 +1,12 @@
+# frozen_string_literal: true
+
 require 'attr_memoized/version'
-require 'thread'
 # This module, when included, decorates the receiver with several useful
 # methods:
 #
 # * Both class and instance methods #mutex are added, that can be used
-#   to guard any shared resources. Each class gets their own class mutex,
-#   and each instance gets it's own separate mutex.
+#   to guard any shared resources. Each class gets their own class attr_memoized_mutex.
+#   and each instance gets it's own separate attr_memoized_mutex.
 #
 # * new class method #attr_memoized is added, the syntax is as follows:
 #
@@ -20,147 +21,155 @@ require 'thread'
 #   Therefore, typically you would use #attr_memoized with one attribute at
 #   a time, unless you want to have several version of the same variable:
 #
-# Example
-# =======
+# @example
 #
-#      class RandomNumbers
-#         include AttrMemoized
+#  class RandomNumbers
+#     include AttrMemoized
 #
-#         attr_memoized :random, -> { rand(10) },            writer: false
-#         attr_memoized :seed,   -> { Time.now.to_i % 57 }
+#     attr_memoized :random, -> { rand(10) },            writer: false
+#     attr_memoized :seed,   -> { Time.now.to_i % 57 }
 #
-#         attr_memoized :number1, :number2, -> { self.class.incr! && rand(10) }
+#     attr_memoized :number1, :number2, -> { self.class.incr! && rand(10) }
 #
-#         @calls = 0
-#         class << self
-#           attr_reader :calls
-#           def incr!; @calls = 0 unless defined(@calls); @calls += 1 ; end
-#         end
-#       end
+#     @calls = 0
+#     class << self
+#       attr_reader :calls
+#       def incr!; @calls = 0 unless defined(@calls); @calls += 1 ; end
+#     end
+#   end
 #
-#       @rn = RandomNumbers.new
+#   @rn = RandomNumbers.new
 #
-#       # first call executes the block, and caches it
-#       @rn.number1                          # => 3
-#       # and it's saved now, and the block is no longer called
-#       @rn.number1                          # => 3
-#       @rn.number2                          # => 9
-#       @rn.number2                          # => 9
-#       # only 2 times did we ever call incr! method
-#       @rn.class.calls                      # => 2
+#   # first call executes the block, and caches it
+#   @rn.number1                          # => 3
+#   # and it's saved now, and the block is no longer called
+#   @rn.number1                          # => 3
+#   @rn.number2                          # => 9
+#   @rn.number2                          # => 9
+#   # only 2 times did we ever call incr! method
+#   @rn.class.calls                      # => 2
 #
-#       # Now #seed is also lazy-loaded, and also cached
-#       @rn.seed                             # => 34
-#       # And, we can change it thread safely!
-#       @rn.seed = 64; @rn.seed              # => 64
+#   # Now #seed is also lazy-loaded, and also cached
+#   @rn.seed                             # => 34
+#   # And, we can change it thread safely!
+#   @rn.seed = 64; @rn.seed              # => 64
 #
-#       # Not so with :random, which was defined without the writer:
-#       @rn.random                           # => 8
-#       @rn.random = 34
-#       # => NoMethodError: undefined method `random=' for #<RandomNumbers:0x007ffb28105178>
+#   # Not so with :random, which was defined without the writer:
+#   @rn.random                           # => 8
+#   @rn.random = 34
+#   # => NoMethodError: undefined method `random=' for #<RandomNumbers:0x007ffb28105178>
 #
 #
 module AttrMemoized
-
   # We are being a bit paranoid here, so yes we are creating
-  # a central lock used to initialize other class-specific mutexes.
+  # a central lock used to initialize other class-specific attr_memoized_mutex.s.
   # This should only be a problem if you are constantly defining new
   # classes that include +AttrMemoized++
   LOCK = Mutex.new.freeze unless defined?(LOCK)
   #
   # The types of initializers we support.
-  SUPPORTED_INIT_TYPES = [Proc, Method, Symbol]
+  SUPPORTED_INIT_TYPES = [Proc, Method, Symbol].freeze
 
   class << self
-    # that's obviously a joke. The name, I mean. Duh.
-    attr_accessor :gil
-
-
     def included(base)
       base.class_eval do
         AttrMemoized::LOCK.synchronize do
-          @mutex ||= Mutex.new
+          @attr_memoized_mutex ||= Mutex.new
         end
 
+        # noinspection ALL
         class << self
-          attr_reader :mutex
-          #
+          attr_reader :attr_memoized_mutex
+
           # A class method which, for each attribute in the list,
           # creates a thread-safe memoized reader and writer (unless writer: false)
           #
           # Memoized reader accepts <tt>reload: true</tt> as an optional argument,
           # which, if provided, forces reinitialization of the variable.
           #
-          # Example:
-          # ==========
-          #
-          #        class LazyConnection
-          #          include AttrMemoized
-          #          attr_memoized :database_connection, -> { ActiveRecord::Base.connection }
+          # @example:
           #
-          #        end
+          #   class LazyConnection
+          #     include AttrMemoized
+          #     attr_memoized :database_connection, -> { ActiveRecord::Base.connection }
+          #     attr_memoized :redis_pool, -> { ConnectionPool.new { Redis.new } }
+          #   end
           #
-          #        LazyConnection.new.database_connection
-          #        #=> <ActiveRecord::Connection::PgSQL::Driver:0xff23234f....>
+          #   LazyConnection.new.database_connection
+          #   #=> <ActiveRecord::Connection::PgSQL::Driver:0xff23234f....>
           #
+          # @param [Symbol] name of the attribute
+          # @param [Symbol] another name of the attribute, etc...
+          # @param [Proc,Symbol,Method] callable — something to call for lazy initialization
+          # @param [Hash] options — you can define arguments here to be passed to a method or proc
           def attr_memoized(*attributes, **opts)
-            attributes    = Array[*attributes]
-            block_or_proc = attributes.pop if SUPPORTED_INIT_TYPES.include?(attributes.last.class)
+            attributes = Array[*attributes]
+            callable   = attributes.pop
+            unless SUPPORTED_INIT_TYPES.include?(callable.class)
+              raise ArgumentError, "Invalid argument #{callable} to attr_memoized. Expecting one of: #{SUPPORTED_INIT_TYPES.map(&:to_s)}"
+            end
+
+            writer = opts.delete(:writer)
             attributes.each do |attribute|
-              define_attribute_writer(attribute) unless opts && opts.has_key?(:writer) && opts[:writer].eql?(false)
-              define_attribute_reader(attribute, block_or_proc)
+              __define_attribute_writer(attribute, **opts) unless writer == false
+              __define_attribute_reader(attribute, callable, **opts)
             end
           end
 
-          def define_attribute_reader(attribute, block_or_proc)
-            at_attribute = at(attribute)
-            define_method(attribute) do |**opts|
-              read_memoize(attribute, at_attribute, block_or_proc, **opts)
+          # Memoized Reader only
+          def attr_memoized_reader(*attrs, **opts)
+            attr_memoized(*attrs, writer: false, **opts)
+          end
+
+          private
+
+          def __define_attribute_reader(attribute, callable, **opts)
+            at_attribute = __at_var(attribute)
+            define_method(attribute) do |*|
+              __read_memoize(attribute, at_attribute, callable, **opts)
             end
           end
 
-          def define_attribute_writer(attribute)
-            at_attribute = at(attribute)
+          def __define_attribute_writer(attribute, **_opts)
+            at_attribute = __at_var(attribute)
             define_method("#{attribute}=".to_sym) do |value|
-              block = -> { self.instance_variable_set(at_attribute, value) }
-              already_locked? ?
-                block.call :
-                with_thread_local_lock { mutex.synchronize(&block) }
+              with_lock { instance_variable_set(at_attribute, value) }
               value
             end
           end
 
-          private
-
           # Convert an attribute name into an @variable syntax
-          def at(attr)
-            attr        = attr.to_sym unless attr.is_a?(Symbol)
+          def __at_var(attr)
+            attr = attr.to_sym unless attr.is_a?(Symbol)
             @attr_cache ||= {}
             @attr_cache[attr] || (@attr_cache[attr] = "@#{attr}".to_sym)
           end
         end
 
-        # instance method: uses the class mutex to create an instance
-        # mutex, and then uses the instance mutex to wrap instance's
-        # state
-        def mutex
-          return @mutex if @mutex
-          self.class.mutex.synchronize {
-            @mutex ||= Mutex.new
+        # instance method: uses the class +attr_memoized_mutex+ to create an instance
+        # attr_memoized_mutex and then uses the instance attr_memoized_mutex to wrap instance's state
+        # @return [Mutex] mutex
+        def attr_memoized_mutex
+          return @attr_memoized_mutex if @attr_memoized_mutex
+
+          self.class.attr_memoized_mutex.synchronize {
+            @attr_memoized_mutex ||= Mutex.new
           }
         end
       end
     end
   end
 
-  # This public method is offered in place of a local +#mutex+'s
-  # #synchronize method to guard state changes to the object using
-  # object's mutex and a thread-local flag. The flag prevents
-  # duplicate #synchronize within the same thread on the same +mutex+.
+  # This method offers "thread-local locking": meaning that the synchronize
+  # block is never called twice from the same thread, thus avoiding deadlocks.
+  #
+  # @param [Proc] block block to wrap in a synchronize unless we are already under one
   def with_lock(&block)
-    already_locked? ?
-      block[] :
-      with_thread_local_lock { mutex.synchronize(&block) }
+    if __locked?
+      block.call
+    else
+      __with_thread_local_lock { attr_memoized_mutex.synchronize(&block) }
+    end
   end
 
   private
@@ -168,57 +177,59 @@ module AttrMemoized
   # This private method is executed in order to initialize a memoized
   # attribute.
   #
-  # @param [Symbol]   attribute - name of the attribute
-  # @param [Symbol]   at_attribute - symbol representing attribute instance variable
-  # @param [Proc, Method, Symbol] block_or_proc - what to call to get the uncached value
-  # @param [Hash]     opts - additional options
+  # @param [Symbol] attribute - name of the attribute
+  # @param [Symbol] at_attribute - symbol representing attribute instance variable
+  # @param [Proc, Method, Symbol] callable - what to call to get the uncached value
+  # @param [Hash] opts - additional options
   # @option opts [Boolean] :reload - forces re-initialization of the memoized attribute
-  def read_memoize(attribute, at_attribute, block_or_proc, **opts)
-    var = self.instance_variable_get(at_attribute)
-    return var if var && !reload?(opts)
-    with_lock { assign_value(attribute, at_attribute, block_or_proc, **opts) }
-    self.instance_variable_get(at_attribute)
+  def __read_memoize(attribute, at_attribute, callable, **opts)
+    var = instance_variable_get(at_attribute)
+    return var if var && !__reload?(opts)
+
+    with_lock { __assign_value(attribute, at_attribute, callable, **opts) }
+    instance_variable_get(at_attribute)
   end
 
   # This private method resolves the initializer argument and returns it's result.
-  def assign_value(attribute, at_attribute, block_or_proc, **opts)
+  def __assign_value(attribute, at_attribute, callable, **opts)
     # reload the value of +var+ because we are now inside a synchronize block
-    var = self.instance_variable_get(at_attribute)
-    return var if (var && !reload?(opts))
+    var = instance_variable_get(at_attribute)
+    return var if var && !__reload?(opts)
 
     # now call whatever `was defined on +attr_memoized+ to get the actual value
-    case block_or_proc
-      when Symbol
-        send(block_or_proc)
-      when Method
-        block_or_proc.call
-      when Proc
-        instance_exec(&block_or_proc)
-      else
-        raise ArgumentError, "expected one of #{AttrMemoized::SUPPORTED_INIT_TYPES.map(&:to_s).join(', ')} for attribute #{attribute}, got #{block_or_proc.class}"
+    case callable
+    when Symbol
+      send(callable, **opts)
+    when Method
+      callable.call(**opts)
+    when Proc
+      instance_exec(&callable)
+    else
+      raise ArgumentError, "expected one of #{AttrMemoized::SUPPORTED_INIT_TYPES.map(&:to_s).join(', ')} for attribute #{attribute}, got #{callable.class}"
     end.tap do |result|
-      self.instance_variable_set(at_attribute, result)
+      instance_variable_set(at_attribute, result)
     end
   end
 
   # Returns +true+ if +opts+ contains reload: +true+
-  def reload?(opts)
-    (opts && opts.has_key?(:reload)) ? opts[:reload] : nil
+  def __reload?(opts)
+    opts.delete(:reload)
   end
 
   # just a key into Thread.local
-  def object_locked_key
+  def __object_lock_key
     @key ||= "this.#{object_id}".to_sym
   end
 
-  def already_locked?
-    Thread.current[object_locked_key]
+  def __locked?
+    Thread.current[__object_lock_key]
   end
 
-  def with_thread_local_lock
-    raise ArgumentError, 'Already locked!' if already_locked?
-    Thread.current[object_locked_key] = true
+  def __with_thread_local_lock
+    raise ArgumentError, 'Already locked!' if __locked?
+
+    Thread.current[__object_lock_key] = true
     yield if block_given?
-    Thread.current[object_locked_key] = nil
+    Thread.current[__object_lock_key] = nil
   end
 end