0.0
No commit activity in last 3 years
No release in over 3 years
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.
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
 Dependencies
 Project Readme
Table of Contents
  • AttrMemoized
    • Complete Example
      • The Problem
    • Using attr_memoized
    • Installation
    • Development
    • Contributing
    • License

Build Status Code Climate Test Coverage Issue Count

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.

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.

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 race condition.

Consider the following example:

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:

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:

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:

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.

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 MIT License.