ttl_memoizeable 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e905652905199d704403098c3e9ac0ff4c6e405cd1a888a949134a434a030856
+  data.tar.gz: b21c2af2bddddbcb19e83887c3d0f20e482d80e53835b92ea406d3e0f5ae54e6
+SHA512:
+  metadata.gz: 37c2e2d28b4c4b3f5ffaa8143228db8f5063353dbcdb65c0265ef856bc6b473661069b10e183965db23dd8e1cc92dca978b8517e1f99bdb5f34c4809d228fcc2
+  data.tar.gz: c73e41dee8ac3a01a8ede3c8783dc7424739fa489abfa4a661c9a72b126b70cb92e52f93fee7de773525aeede26460cd287198e22ace5b269b148ed77744873e

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.standard.yml

@@ -0,0 +1,3 @@
+# For available configuration options, see:
+#   https://github.com/testdouble/standard
+ruby_version: 2.6

data/CHANGELOG.md

@@ -0,0 +1,7 @@
+## [Unreleased]
+## [0.2.0] - 2023-11-27
+- Publish to rubygems
+
+## [0.1.0] - 2023-11-26
+
+- Initial release

data/Gemfile

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+# Specify your gem's dependencies in ttl_memoizeable.gemspec
+gemspec
+
+gem "rake"
+gem "rspec"
+gem "standard"

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2023 Huntress Labs
+
+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,191 @@
+# TTLMemoizeable
+
+Cross-thread memoization with eventual consistency.
+
+## Okay... what?
+
+Memoization is popular pattern to reduce expensive computation; you don't need a library for this, despite some [existing to provide better developer ergonomics](https://github.com/matthewrudy/memoist). What is hard, however, is supporting higher-level memoization which can be leveraged across threads and periodically reloads/refreshes. This library is, conceptually, a mix of memoization and in-memory caching with time-to-live expiration/refresh which is thread-safe. It works best for computations or data fetching which:
+
+1. Can be eventually correct; where inconsistent data across processes is acceptable.
+  - Given two or more processes, one may have "stale" data while the other may have "less-stale" data. There are no cross-process data consistency guarantees.
+2. Happens in any given thread in a given process.
+  - Since this library memoizes data in-memory it may result in poorly allocated memory consumption if only the occasional thread needs the data.
+
+This library is a sharp knife with a specific use-case. Do not use it without fully understanding the implications of its application.
+
+## Impetus
+
+Extracted from the scaling pains we experienced over at [Huntress Labs](https://www.huntress.com) (the scale of many billions of ruby background jobs per month, millions of HTTP requests per minute), this pattern has allowed us to reduce the execution time of hot code paths where every computation, database query, and HTTP request matters. We discovered these code paths were accessing infrequently changing data sets in each execution and began investigating ways to reduce the overhead of their access. Since it's inception, this library has been used widely across our code bases.
+
+## Benchmark
+
+```ruby
+require "benchmark"
+require "ttl_memoizeable"
+
+class ApplicationConfig
+  class << self
+    def config_without_ttl_memoization
+      # JSON.parse($redis.get("some_big_json_string")) => 0.05ms of execution time
+      sleep 0.05
+    end
+
+    def config_with_ttl_memoization
+      # JSON.parse($redis.get("some_big_json_string")) => 0.05ms of execution time
+      sleep 0.05
+    end
+
+    extend TTLMemoizeable
+    ttl_memoized_method :config_with_ttl_memoization, ttl: 1000
+  end
+end
+
+iterations_per_thread = 1000
+thread_count = 4
+
+Benchmark.bm do |x|
+  x.report("baseline:") do
+    thread_count.times.collect do
+      Thread.new do
+        iterations_per_thread.times do
+          ApplicationConfig.config_without_ttl_memoization
+        end
+      end
+    end.each(&:join)
+  end
+
+  x.report("ttl_memoized:") do
+    thread_count.times.collect do
+      Thread.new do
+        iterations_per_thread.times do
+          ApplicationConfig.config_with_ttl_memoization
+        end
+      end
+    end.each(&:join)
+  end
+end
+```
+
+```
+       user     system      total        real
+baseline:  0.112220   0.101602   0.213822 ( 52.803622)
+ttl_memoized:  0.008847   0.000755   0.009602 (  0.221783)
+```
+
+## Usage
+
+  1. Define your method as you normally would. Test it. Benchmark it to know that it is "expensive"
+  2. Extend the methods defined in this file by calling `extend TTLMemoizeable` in your class (if not already extended)
+  3. Call `ttl_memoized_method :your_method_name, ttl: 5.minutes` where `:your_method_name` is the method you just defined, and the `ttl` is the duration (in time or accessor counts) of acceptable data inconsistency
+  4. 🎉
+
+### TTL Types:
+  Two methods of TTL expiration are available
+    1. Time Duration (i.e `5.minutes`). This will ensure the process will cache your method
+       for that given amount of time. This option is likely best when you can quantify the
+       acceptable threshold for stale data. Every time the memoized method is called, the date
+       the current memoized value was fetched + your ttl value will be compared to the current time.
+
+    2. Accessor count (i.e. 10_000). This will ensure the process will cache your method
+       for that number of attempts to access the data. This option is likely best when you
+       want to TTL to expire based of volume. Every time the memoized method is called, the counter
+       will decrement by 1.
+
+
+### Dont's
+
+1. Use this library on methods that have logic involving state
+2. Use this library on methods that accept parameters, as that introduces state; see above
+
+
+Using this library is most effective on class methods.
+
+```ruby
+require "ttl_memoizeable"
+
+class ApplicationConfig
+  class << self
+    extend TTLMemoizeable
+
+    def config
+      JSON.parse($redis.get("some_big_json_string"))
+    end
+
+    ttl_memoized_method :config, ttl: 1.minute # Redis/JSON.parse will only be hit once per minute from this process
+  end
+end
+
+ApplicationConfig.config # => {...} Redis/JSON.parse will be called
+ApplicationConfig.config # => {...} Redis/JSON.parse will NOT be called
+#... at least 1 minute later ...
+ApplicationConfig.config # => {...} Redis/JSON.parse will be called
+```
+
+
+It will work on instance methods as well, however, this is less useful as it does not share state across threads without the use of a global
+```ruby
+require "ttl_memoizeable"
+
+class ApplicationConfig
+  extend TTLMemoizeable
+
+  def config
+    JSON.parse($redis.get("some_big_json_string"))
+  end
+
+  ttl_memoized_method :config, ttl: 1.minute
+end
+
+ApplicationConfig.new.config # => {...} Redis/JSON.parse will be called
+ApplicationConfig.new.config # => {...} Redis/JSON.parse will be called
+
+application_config = ApplicationConfig.new
+application_config.config # => {...} Redis/JSON.parse will be called
+application_config.config # => {...} Redis/JSON.parse will NOT be called
+#... at least 1 minute later ...
+application_config.config # => {...} Redis/JSON.parse will be called
+```
+
+## Testing a TTLMemoized Method
+
+You likely don't want to test the implementation of this library, but the logic of your memoized method. In that case you probably want "fresh" data on every invocation of the method. There are two approaches, depending on your preference of flavor.
+
+1. Use the reset method provided for you. It follows the pattern of `reset_memoized_value_for_#{method_name}`. Note that this will only reset the value for the current thread, and shouldn't be used to try and create consistent data state across processes.
+```ruby
+def test_config
+  ApplicationConfig.reset_memoized_value_for_config # or in a setup method or before block if available
+
+  assert_equal {...}, ApplicationConfig.config
+end
+```
+
+2. Conditionally TTL memoize the method based on test environment or some other condition.
+```ruby
+def config
+  JSON.parse($redis.get("some_big_json_string"))
+end
+
+ttl_memoized_method :config, ttl: 1.minute unless test_env?
+```
+
+## 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 the created tag, 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/huntresslabs/ttl_memoizeable.
+
+### Publish a new version
+
+`bundle exec bump ${major / minor / patch / pre} --tag --edit-changelog`
+`git push`
+`git push --tags`
+`gem build`
+`gem push`
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "standard/rake"
+
+task default: %i[spec standard]

data/lib/ttl_memoizeable/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module TTLMemoizeable
+  VERSION = "0.2.0"
+end

data/lib/ttl_memoizeable.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require "active_support"
+require "active_support/core_ext/integer/time"
+
+require_relative "ttl_memoizeable/version"
+
+module TTLMemoizeable
+  TTLMemoizationError = Class.new(StandardError)
+
+  def ttl_memoized_method(method_name, ttl: 1000)
+    raise TTLMemoizationError, "Method not defined: #{method_name}" unless method_defined?(method_name) || private_method_defined?(method_name)
+
+    ivar_name = method_name.to_s.gsub(/\??/, "") # remove trailing question marks
+    time_based_ttl = ttl.is_a?(ActiveSupport::Duration)
+    expired_ttl = time_based_ttl ? 1.year.ago : 1
+
+    ttl_variable_name = "@_ttl_for_#{ivar_name}".to_sym
+    mutex_variable_name = "@_mutex_for_#{ivar_name}".to_sym
+    value_variable_name = "@_value_for_#{ivar_name}".to_sym
+
+    reset_memoized_value_method_name = "reset_memoized_value_for_#{method_name}".to_sym
+    setup_memoization_method_name = "_setup_memoization_for_#{method_name}".to_sym
+    decrement_ttl_method_name = "_decrement_ttl_for_#{method_name}".to_sym
+    ttl_exceeded_method_name = "_ttl_exceeded_for_#{method_name}".to_sym
+    extend_ttl_method_name = "_extend_ttl_for_#{method_name}".to_sym
+
+    [
+      reset_memoized_value_method_name, setup_memoization_method_name,
+      decrement_ttl_method_name, ttl_exceeded_method_name, extend_ttl_method_name
+    ].each do |potential_method_name|
+      raise TTLMemoizationError, "Method name conflict: #{potential_method_name}" if method_defined?(potential_method_name)
+    end
+
+    memoized_module = Module.new do
+      define_method reset_memoized_value_method_name do
+        send setup_memoization_method_name if instance_variable_get(mutex_variable_name).nil?
+
+        instance_variable_get(mutex_variable_name).synchronize do
+          instance_variable_set(ttl_variable_name, expired_ttl)
+        end
+
+        nil
+      end
+
+      define_method setup_memoization_method_name do
+        instance_variable_set(ttl_variable_name, expired_ttl) unless instance_variable_defined?(ttl_variable_name)
+        instance_variable_set(mutex_variable_name, Mutex.new) unless instance_variable_defined?(mutex_variable_name)
+        instance_variable_set(value_variable_name, nil) unless instance_variable_defined?(value_variable_name)
+      end
+
+      define_method decrement_ttl_method_name do
+        return if time_based_ttl
+
+        instance_variable_set(ttl_variable_name, instance_variable_get(ttl_variable_name) - 1)
+      end
+
+      define_method ttl_exceeded_method_name do
+        instance_variable_get(ttl_variable_name) <= if time_based_ttl
+          ttl.ago
+        else
+          0
+        end
+      end
+
+      define_method extend_ttl_method_name do
+        if time_based_ttl
+          instance_variable_set(ttl_variable_name, Time.current)
+        else
+          instance_variable_set(ttl_variable_name, ttl)
+        end
+      end
+
+      define_method method_name do |*args|
+        raise ArgumentError, "Cannot cache method which requires arguments" if args.size.positive?
+
+        send setup_memoization_method_name
+
+        instance_variable_get(mutex_variable_name).synchronize do
+          send(decrement_ttl_method_name)
+
+          if send(ttl_exceeded_method_name)
+            send(extend_ttl_method_name)
+
+            # Refresh value from the original method
+            instance_variable_set(value_variable_name, super())
+          end
+        end
+
+        instance_variable_get(value_variable_name)
+      end
+    end
+
+    prepend memoized_module
+  end
+end

data/sig/ttl_memoizeable.rbs

@@ -0,0 +1,4 @@
+module TTLMemoizeable
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,83 @@
+--- !ruby/object:Gem::Specification
+name: ttl_memoizeable
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+platform: ruby
+authors:
+- Daniel Westendorf
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2023-11-28 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: bump
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: A sharp knife for cross-thread memoization providing eventual consistency.
+email:
+- daniel@prowestech.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- ".standard.yml"
+- CHANGELOG.md
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/ttl_memoizeable.rb
+- lib/ttl_memoizeable/version.rb
+- sig/ttl_memoizeable.rbs
+homepage: https://github.com/huntresslabs/ttl_memoizeable
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/huntresslabs/ttl_memoizeable
+  source_code_uri: https://github.com/huntresslabs/ttl_memoizeable
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.1
+signing_key:
+specification_version: 4
+summary: Cross-thread memoization in ruby with eventual consistency.
+test_files: []