attr_memoized 0.2.2

data/.travis.yml

@@ -0,0 +1,10 @@
+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
+after_success:
+- bundle exec codeclimate-test-reporter

data/Gemfile

@@ -0,0 +1,4 @@
+source "https://rubygems.org"
+
+# Specify your gem's dependencies in attr_memoized.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2017 Konstantin Gredeskoul
+
+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,170 @@
+[![Build Status](https://travis-ci.org/kigster/attr_memoized.svg?branch=master)](https://travis-ci.org/kigster/attr_memoized)
+[![Code Climate](https://codeclimate.com/github/kigster/attr_memoized/badges/gpa.svg)](https://codeclimate.com/github/kigster/attr_memoized)
+[![Test Coverage](https://codeclimate.com/github/kigster/attr_memoized/badges/coverage.svg)](https://codeclimate.com/github/kigster/attr_memoized/coverage)
+[![Issue Count](https://codeclimate.com/github/kigster/attr_memoized/badges/issue_count.svg)](https://codeclimate.com/github/kigster/attr_memoized)
+
+# AttrMemoized
+
+This is a simple, and yet rather useful **memoization** library, with a specific goal of being **thread-safe** during lazy-loading of 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 passing `writer: false` option to `attr_memoized` method.
+
+Any `attr_memoized` attribute may depend on any number of regular attributes or other `attr_memoized` attributes.
+
+This gems provides a shorthand syntax for defining lazy-initialized variables as "one-liners", while additionally providing thread-safety guarantees around lazy-initilization of attributes, or attribute assignments.
+
+#### Caveat
+
+Note, that 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.
+
+```ruby
+require 'redis'
+# Save config to Redis
+r = Redis.new
+#=> #<Redis:0x007fbd8d3a4308>
+r.set('config_file', '{ "host": "127.0.0.1" }')
+#=> OK
+r.set('another_file', '{ "host": "google.com" }')
+#=> OK
+r.get('config_file') #=> { "host": "127.0.0.1" }
+
+require 'attr_memoized'
+module Concurrent
+  class RedisConfig
+    include AttrMemoized
+    # Now there is an instance and a class methods +#mutex+ are defined.
+    # We also have an instance method +with_lock+, and a class method 
+    # +attr_memoized+
+    attr_memoized :contents, -> { redis.get(redis_key) } 
+    attr_memoized :redis,  -> { Redis.new }   
+    attr_memoized :redis_key, -> { 'config_file' }
+  
+    def reload_config!(new_key)
+      # +with_lock+ method if offered in place of +synchronize+
+      # to avoid double-locking within the same thread.
+      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 [_race condition_](https://stackoverflow.com/questions/34510/what-is-a-race-condition).
+
+Consider the following example:
+
+```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)
+```
+
+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.
+
+
+## Usage
+
+`AttrMemoized` — the gem's primary module, when included, decorates the receiver with several useful
+methods:
+
+  * Pre-initialized class method `#mutex`. Each class that includes `AttrMemoized` gets their own mutex.
+   
+  * Pre-initialized instance method `#mutex`. Each instance of the class gets it's own dedicated mutex.
+
+  * Convenience method `#with_lock` is provided in place of `#mutex.synhronize` 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:
+
+```ruby
+attr_memoized :attribute, [ :attribute, ...], -> { block returning a value } # Proc
+attr_memoized :attribute, [ :attribute, ...], :instance_method               # symbol
+attr_memoized :attribute, [ :attribute, ...], SomeClass.method(:method_name) # Method instance
+```
+
+  * 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 takes no arguments.
+ 
+    * 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:
+
+```ruby
+srand
+require 'attr_memoized'
+class RandomNumberGenerator
+  include AttrMemoized
+  attr_memoized :random1,
+                :random2,
+                :random3, -> { rand(2**64) }
+end
+
+rng = RandomNumberGenerator.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
+```    
+
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```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 [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at [https://github.com/kigster/attr_memoized](https://github.com/kigster/attr_memoized).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).

data/Rakefile

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

data/attr_memoized.gemspec

@@ -0,0 +1,32 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'attr_memoized/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'attr_memoized'
+  spec.version       = AttrMemoized::VERSION
+  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.homepage      = 'https://github.com/kigster/attr_memoized'
+  spec.license       = 'MIT'
+
+  spec.files         = `git ls-files -z`.split("\x0").reject do |f|
+    f.match(%r{^(test|spec|features)/})
+  end
+  spec.bindir        = 'exe'
+  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 'rspec-its'
+  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

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "attr_memoized"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/attr_memoized.rb

@@ -0,0 +1,224 @@
+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.
+#
+# * new class method #attr_memoized is added, the syntax is as follows:
+#
+#        attr_memoized :attribute_name, ..., -> { block returning a value }
+#
+# * the block in the definition above is called via #instance_exec on the
+#   object (instance of a class) and therefore has access to all private
+#   methods. If the value is a symbol, it is expected to be a method.
+#
+# * multiple attribute names are allowed in the #attr_memoized, but they
+#   will all be assigned the result of the block (last argument) when called.
+#   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
+# =======
+#
+#      class RandomNumbers
+#         include AttrMemoized
+#
+#         attr_memoized :random, -> { rand(10) },            writer: false
+#         attr_memoized :seed,   -> { Time.now.to_i % 57 }
+#
+#         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
+#
+#       @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
+#
+#       # 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>
+#
+#
+module AttrMemoized
+
+  # We are being a bit paranoid here, so yes we are creating
+  # a central lock used to initialize other class-specific mutexes.
+  # 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]
+
+  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
+        end
+
+        class << self
+          attr_reader :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 }
+          #
+          #        end
+          #
+          #        LazyConnection.new.database_connection
+          #        #=> <ActiveRecord::Connection::PgSQL::Driver:0xff23234f....>
+          #
+          def attr_memoized(*attributes, **opts)
+            attributes    = Array[*attributes]
+            block_or_proc = attributes.pop if SUPPORTED_INIT_TYPES.include?(attributes.last.class)
+            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)
+            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)
+            end
+          end
+
+          def define_attribute_writer(attribute)
+            at_attribute = at(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) }
+              value
+            end
+          end
+
+          private
+
+          # Convert an attribute name into an @variable syntax
+          def at(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
+          }
+        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+.
+  def with_lock(&block)
+    already_locked? ?
+      block[] :
+      with_thread_local_lock { mutex.synchronize(&block) }
+  end
+
+  private
+
+  # 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
+  # @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)
+  end
+
+  # This private method resolves the initializer argument and returns it's result.
+  def assign_value(attribute, at_attribute, block_or_proc, **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))
+
+    # 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}"
+    end.tap do |result|
+      self.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
+  end
+
+  # just a key into Thread.local
+  def object_locked_key
+    @key ||= "this.#{object_id}".to_sym
+  end
+
+  def already_locked?
+    Thread.current[object_locked_key]
+  end
+
+  def with_thread_local_lock
+    raise ArgumentError, 'Already locked!' if already_locked?
+    Thread.current[object_locked_key] = true
+    yield if block_given?
+    Thread.current[object_locked_key] = nil
+  end
+end