MemoWise
is the wise choice for Ruby memoization, featuring:
- Fast performance of memoized reads (with benchmarks)
- Support for resetting and presetting memoized values
- Support for memoization on frozen objects
- Support for memoization of class and module methods
- Support for inheritance of memoized class and instance methods
- Documented and tested thread-safety guarantees
- Full documentation and test coverage!
Add this line to your application's Gemfile:
gem 'memo_wise'
And then execute:
$ bundle install
Or install it yourself as:
$ gem install memo_wise
When you prepend MemoWise
within a class or module, MemoWise
exposes three
methods:
class Example
prepend MemoWise
def slow_value(x)
sleep x
x
end
memo_wise :slow_value
private
# maintains privacy of the memoized method
def private_slow_method(x)
sleep x
x
end
memo_wise :private_slow_method
end
ex = Example.new
ex.slow_value(2) # => 2 # Sleeps for 2 seconds before returning
ex.slow_value(2) # => 2 # Returns immediately because the result is memoized
ex.reset_memo_wise(:slow_value) # Resets all memoized results for slow_value
ex.slow_value(2) # => 2 # Sleeps for 2 seconds before returning
ex.slow_value(2) # => 2 # Returns immediately because the result is memoized
# NOTE: Memoization can also be reset for all methods, or for just one argument.
ex.preset_memo_wise(:slow_value, 3) { 4 } # Store 4 as the result for slow_value(3)
ex.slow_value(3) # => 4 # Returns immediately because the result is memoized
ex.reset_memo_wise # Resets all memoized results for all methods on ex
The same three methods are exposed for class methods as well:
class Example
prepend MemoWise
def self.class_slow_value(x)
sleep x
x
end
memo_wise self: :class_slow_value
end
Example.class_slow_value(2) # => 2 # Sleeps for 2 seconds before returning
Example.class_slow_value(2) # => 2 # Returns immediately because the result is memoized
Example.reset_memo_wise(:class_slow_value) # Resets all memoized results for class_slow_value
Example.preset_memo_wise(:class_slow_value, 3) { 4 } # Store 4 as the result for slow_value(3)
Example.class_slow_value(3) # => 4 # Returns immediately because the result is memoized
Example.reset_memo_wise # Resets all memoized results for all methods on class
NOTE: Methods which take implicit or explicit block arguments cannot be memoized.
For more usage details, see our detailed documentation.
Benchmarks are run in GitHub Actions, and the tables below are updated with every code change. Values >1.00x represent how much slower each gem’s memoized value retrieval is than the latest commit of MemoWise
, according to benchmark-ips
(2.11.0).
Results using Ruby 3.3.2:
Method arguments | Dry::Core * (1.0.1) |
Memery (1.5.0) |
---|---|---|
() (none) |
0.60x | 3.17x |
(a) |
1.01x | 7.94x |
(a, b) |
0.85x | 6.38x |
(a:) |
1.00x | 11.78x |
(a:, b:) |
0.88x | 9.67x |
(a, b:) |
0.83x | 9.44x |
(a, *args) |
0.67x | 1.45x |
(a:, **kwargs) |
0.68x | 1.88x |
(a, *args, b:, **kwargs) |
0.64x | 1.29x |
* Dry::Core
may cause incorrect behavior caused by hash collisions.
Results using Ruby 2.7.8 (because these gems raise errors in Ruby 3.x):
Method arguments | DDMemoize (1.0.0) |
Memoist (0.16.2) |
Memoized (1.1.1) |
Memoizer (1.0.3) |
---|---|---|---|---|
() (none) |
22.57x | 2.27x | 23.46x | 2.63x |
(a) |
20.96x | 14.29x | 20.54x | 11.97x |
(a, b) |
18.22x | 13.21x | 17.76x | 11.34x |
(a:) |
30.66x | 23.52x | 25.37x | 21.61x |
(a:, b:) |
27.31x | 21.98x | 23.02x | 20.31x |
(a, b:) |
26.21x | 20.85x | 21.57x | 19.20x |
(a, *args) |
3.06x | 2.23x | 3.10x | 1.92x |
(a:, **kwargs) |
2.67x | 2.18x | 2.39x | 2.02x |
(a, *args, b:, **kwargs) |
2.14x | 1.80x | 1.89x | 1.70x |
You can run benchmarks yourself with:
$ cd benchmarks
$ bundle install
$ bundle exec ruby benchmarks.rb
If your results differ from what's posted here, let us know!
MemoWise makes the following thread safety guarantees on all supported Ruby versions:
-
Before a value has been memoized
- Contended calls from multiple threads...
- May each call the original method
- May return different valid results (when the method is nondeterministic,
like
rand
) - Will memoize exactly one valid return value
- Contended calls from multiple threads...
-
After a value has been memoized
- Contended calls from multiple threads...
- Always return the same memoized value
- Contended calls from multiple threads...
We maintain API documentation using YARD, which is published automatically at RubyDoc.info.
To generate documentation locally or run documentation tests,
first install the docs
dependencies (e.g. yard
) as follows:
BUNDLE_WITH=docs bundle install
To edit documentation locally and see it rendered in your browser using hot reloading, run:
bundle exec yard server --reload
You can then open your web browser to http://127.0.0.1:8808/
. As you
edit documentation locally, reload your browser to see it generated.
To statically generate documentation locally, run:
bundle exec yard
You can then open the generated documentation at docs/index.html
.
We use yard-doctest to test all
code examples in our YARD documentation. To run doctest
locally:
bundle exec yard doctest
We use dokaz to test all code examples in
this README.md file, and all other non-code documentation. To run dokaz
locally:
bundle exec dokaz
When testing memoized module methods, note that some testing setups will
reuse the same instance (which include
s/extend
s/prepend
s the module)
across tests, which can result in confusing test failures when this differs from
how you use the code in production.
For example, Rails view helpers are modules that are commonly tested with a
shared view
instance. Rails initializes a new view instance for each web request so any view helper
methods would only be memoized for the duration of that web request, but in
tests (such as when using
rspec-rails
's helper
),
the memoization may persist across tests. In this case, simply reset the
memoization between your tests with something like:
after(:each) { helper.reset_memo_wise }
We presented at RubyConf 2021:
- Achieving Fast Method Metaprogramming: Lessons from
MemoWise
(slides / benchmarks)
And we've written more about MemoWise
in a series of blog posts:
MemoWise
's logo was created by Luci Cooke. The
logo is licensed under a
Creative Commons Attribution-NonCommercial 4.0 International License.
Bug reports and pull requests are welcome on GitHub at https://github.com/panorama-ed/memo_wise. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.
To make a new release of MemoWise
to
RubyGems, first install the release
dependencies (e.g. rake
) as follows:
BUNDLE_WITH=release bundle install
Then carry out these steps:
-
Update
CHANGELOG.md
:- Add an entry for the upcoming version x.y.z
- Move content from Unreleased to the upcoming version x.y.z
- Update the diff links for this version and Unreleased in
CHANGELOG.md
- Change Unreleased section to say:
**Gem enhancements:** none _No breaking changes!_ **Project enhancements:** none
- Commit with title
Update CHANGELOG.md for x.y.z
-
Update
lib/memo_wise/version.rb
- Replace with upcoming version x.y.z
- Run
bundle install
to updateGemfile.lock
- Commit with title
Bump version to x.y.z
-
bundle exec rake release
The gem is available as open source under the terms of the MIT License.
Everyone interacting in the MemoWise
project's codebases, issue trackers, chat
rooms and mailing lists is expected to follow the
code of conduct.