class ActiveSupport::Cache::Store
@last_mod_time = Time.now # Invalidate the entire cache by changing namespace
cache.namespace = -> { @last_mod_time } # Set the namespace to a variable
use application logic to invalidate keys.
is a Proc, it will be invoked when each key is evaluated so that you can
to every key. The namespace can be either a static value or a Proc. If it
for your cache entries. If a namespace is defined, it will be prefixed on
If your cache is on a shared infrastructure, you can define a namespace
Nil values can be cached.
cache.read(‘city’) == cache.read(:city) # => true
will be sorted by key so they are consistent.
elements will be delimited by slashes, and the elements within a Hash
method will be called. Hashes and Arrays can also be used as keys. The
method will be called to define the key. Otherwise, the to_param
object is specified as a key and has a cache_key
method defined, this
Keys are always translated into Strings and are case sensitive. When an
cache.write(‘not serializable’, Proc.new {}) # => TypeError
cache.read(‘city’) # => “Duckburgh”
cache.write(‘city’, “Duckburgh”)
cache.read(‘city’) # => nil
cache = ActiveSupport::Cache::MemoryStore.new
its coder
‘s dump
and load
methods.
ActiveSupport::Cache::Store can store any Ruby object that is supported by
methods of #fetch, #write, #read, #exist?, and #delete.
Some implementations may not support all methods beyond the basic cache
popular cache store for large production websites.
ActiveSupport::Cache::MemCacheStore. MemCacheStore is currently the most
under the ActiveSupport::Cache module, e.g.
implementations, each having its own additional features. See the classes
An abstract cache store class. There are multiple cache store
def cleanup(options = nil)
Options are passed to the underlying cache implementation.
Cleans up the cache by removing expired entries.
def cleanup(options = nil) raise NotImplementedError.new("#{self.class.name} does not support cleanup") end
def clear(options = nil)
The options hash is passed to the underlying cache implementation.
affect other processes if shared cache is being used.
Clears the entire cache. Be careful with this method since it could
def clear(options = nil) raise NotImplementedError.new("#{self.class.name} does not support clear") end
def decrement(name, amount = 1, options = nil)
Options are passed to the underlying cache implementation.
Decrements an integer value in the cache.
def decrement(name, amount = 1, options = nil) raise NotImplementedError.new("#{self.class.name} does not support decrement") end
def default_coder
def default_coder Coders[Cache.format_version] end
def delete(name, options = nil)
Deletes an entry in the cache. Returns +true+ if an entry is deleted.
def delete(name, options = nil) options = merged_options(options) instrument(:delete, name) do delete_entry(normalize_key(name, options), **options) end end
def delete_entry(key, **options)
Deletes an entry from the cache implementation. Subclasses must
def delete_entry(key, **options) raise NotImplementedError.new end
def delete_matched(matcher, options = nil)
Options are passed to the underlying cache implementation.
Deletes all entries with keys matching the pattern.
def delete_matched(matcher, options = nil) raise NotImplementedError.new("#{self.class.name} does not support delete_matched") end
def delete_multi(names, options = nil)
Deletes multiple entries in the cache.
def delete_multi(names, options = nil) options = merged_options(options) names.map! { |key| normalize_key(key, options) } instrument :delete_multi, names do delete_multi_entries(names, **options) end end
def delete_multi_entries(entries, **options)
Deletes multiples entries in the cache implementation. Subclasses MAY
def delete_multi_entries(entries, **options) entries.count { |key| delete_entry(key, **options) } end
def deserialize_entry(payload)
def deserialize_entry(payload) payload.nil? ? nil : @coder.load(payload) end
def ensure_connection_pool_added!
def ensure_connection_pool_added! require "connection_pool" rescue LoadError => e $stderr.puts "You don't have connection_pool installed in your application. Please add it to your Gemfile and run bundle install" raise e end
def exist?(name, options = nil)
Returns +true+ if the cache contains an entry for the given key.
def exist?(name, options = nil) options = merged_options(options) instrument(:exist?, name) do |payload| entry = read_entry(normalize_key(name, options), **options, event: payload) (entry && !entry.expired? && !entry.mismatched?(normalize_version(name, options))) || false end end
def expanded_key(key)
object responds to +cache_key+. Otherwise, +to_param+ method will be
Expands key to be a consistent string value. Invokes +cache_key+ if
def expanded_key(key) return key.cache_key.to_s if key.respond_to?(:cache_key) case key when Array if key.size > 1 key.collect { |element| expanded_key(element) } else expanded_key(key.first) end when Hash key.collect { |k, v| "#{k}=#{v}" }.sort! else key end.to_param end
def expanded_version(key)
def expanded_version(key) case when key.respond_to?(:cache_version) then key.cache_version.to_param when key.is_a?(Array) then key.map { |element| expanded_version(element) }.tap(&:compact!).to_param when key.respond_to?(:to_a) then expanded_version(key.to_a) end end
def fetch(name, options = nil, &block)
val_2 # => "original value"
val_1 # => "new value 1"
cache.fetch('foo') # => "new value 1"
sleep 10 # First thread extended the life of cache by another 10 seconds
cache.fetch('foo') # => "original value"
end
end
'new value 2'
val_2 = cache.fetch('foo', race_condition_ttl: 10.seconds) do
Thread.new do
end
end
'new value 1'
sleep 1
val_1 = cache.fetch('foo', race_condition_ttl: 10.seconds) do
Thread.new do
sleep 60
val_2 = nil
val_1 = nil
cache.write('foo', 'original value')
cache = ActiveSupport::Cache::MemoryStore.new(expires_in: 1.minute)
# Set all values to expire after one minute.
has elapsed.
process can try to generate a new value after the extended time window
If the first process errors out while generating a new value, another
process writes the new value, other processes will then use it.
other processes will continue to use the old value. After the first
this extended time window, while the process generates a new value,
+:race_condition_ttl+ seconds before generating a new value. During
+:race_condition_ttl+ seconds ago, it will bump the expiration time by
When a process encounters a cache entry that has expired less than
same entry (also known as the dog pile effect).
by preventing multiple processes from simultaneously regenerating the
This can be used to prevent race conditions when cache entries expire,
an expired value can be reused while a new value is being generated.
* +:race_condition_ttl+ - Specifies the number of seconds during which
cache.exist?('bar') # => false
cache.exist?('foo') # => true
cache.fetch('bar', skip_nil: true) { nil }
cache.fetch('foo') { nil }
* skip_nil: true - Prevents caching a nil result:
just call +write+.
ask whether you should force a cache write. Otherwise, it's clearer to
The +:force+ option is useful when you're calling some other method to
cache.fetch('today', force: true) # => ArgumentError
cache.fetch('today', force: true) { 'Tuesday' } # => 'Tuesday'
cache.write('today', 'Monday')
required when +force+ is true so this always results in a cache write.
cache value as missing even if it's present. Passing a block is
* force: true - Forces a cache "miss," meaning we treat the
Additionally, +fetch+ supports the following options:
miss. Thus, +fetch+ supports the same options as #read and #write.
Internally, +fetch+ calls #read_entry, and calls #write_entry on a cache
==== Options
cache.fetch('city') # => "Duckburgh"
end
'Duckburgh'
cache.fetch('city') do
cache.fetch('city') # => nil
cache.fetch('today') # => "Monday"
cache.write('today', 'Monday')
return value will be returned.
block will be written to the cache under the given cache key, and that
the key and executed in the event of a cache miss. The return value of the
returned. However, if a block has been passed, that block will be passed
If there is no such data in the cache (a cache miss), then +nil+ will be
the cache with the given key, then that data is returned.
Fetches data from the cache, using the given key. If there is data in
def fetch(name, options = nil, &block) if block_given? options = merged_options(options) key = normalize_key(name, options) entry = nil instrument(:read, name, options) do |payload| cached_entry = read_entry(key, **options, event: payload) unless options[:force] entry = handle_expired_entry(cached_entry, key, options) entry = nil if entry && entry.mismatched?(normalize_version(name, options)) payload[:super_operation] = :fetch if payload payload[:hit] = !!entry if payload end if entry get_entry_value(entry, name, options) else save_block_result_to_cache(name, options, &block) end elsif options && options[:force] raise ArgumentError, "Missing block: Calling `Cache#fetch` with `force: true` requires a block." else read(name, options) end end
def fetch_multi(*names)
cache.read("fizz")
sleep(6)
# => "buzz"
cache.read("fizz")
# => {"fizz"=>"buzz"}
end
"buzz"
cache.fetch_multi("fizz", expires_in: 5.seconds) do |key|
Options are passed to the underlying cache implementation. For example:
# "unknown_key" => "Fallback value for key: unknown_key" }
# => { "bim" => "bam",
end
"Fallback value for key: #{key}"
cache.fetch_multi("bim", "unknown_key") do |key|
cache.write("bim", "bam")
Returns a hash with the data for each of the names. For example:
not found, use #read_multi.
to the cache. If you do not want to write the cache when the cache is
Therefore, you need to pass a block that returns the data to be written
and the result will be written to the cache and returned.
the supplied block is called for each key for which there was no data,
the cache with the given keys, then that data is returned. Otherwise,
Fetches data from the cache, using the given keys. If there is data in
def fetch_multi(*names) raise ArgumentError, "Missing block: `Cache#fetch_multi` requires a block." unless block_given? options = names.extract_options! options = merged_options(options) instrument :read_multi, names, options do |payload| reads = read_multi_entries(names, **options) writes = {} ordered = names.index_with do |name| reads.fetch(name) { writes[name] = yield(name) } end payload[:hits] = reads.keys payload[:super_operation] = :fetch_multi write_multi(writes, options) ordered end end
def get_entry_value(entry, name, options)
def get_entry_value(entry, name, options) instrument(:fetch_hit, name, options) { } entry.value end
def handle_expired_entry(entry, key, options)
def handle_expired_entry(entry, key, options) if entry && entry.expired? race_ttl = options[:race_condition_ttl].to_i if (race_ttl > 0) && (Time.now.to_f - entry.expires_at <= race_ttl) # When an entry has a positive :race_condition_ttl defined, put the stale entry back into the cache # for a brief period while the entry is being recalculated. entry.expires_at = Time.now.to_f + race_ttl write_entry(key, entry, expires_in: race_ttl * 2) else delete_entry(key, **options) end entry = nil end entry end
def increment(name, amount = 1, options = nil)
Options are passed to the underlying cache implementation.
Increments an integer value in the cache.
def increment(name, amount = 1, options = nil) raise NotImplementedError.new("#{self.class.name} does not support increment") end
def initialize(options = nil)
Any other specified options are treated as default options for the
Using a custom coder disables automatic compression.
with a custom one. The +coder+ must respond to +dump+ and +load+.
* +:coder+ - Replaces the default cache entry serialization mechanism
applications.
especially useful if your application shares a cache with other
* +:namespace+ - Sets the namespace for the cache. This option is
==== Options
Creates a new cache.
def initialize(options = nil) @options = options ? normalize_options(options) : {} @options[:compress] = true unless @options.key?(:compress) @options[:compress_threshold] = DEFAULT_COMPRESS_LIMIT unless @options.key?(:compress_threshold) @coder = @options.delete(:coder) { default_coder } || NullCoder @coder_supports_compression = @coder.respond_to?(:dump_compressed) end
def instrument(operation, key, options = nil)
def instrument(operation, key, options = nil) if logger && logger.debug? && !silence? logger.debug "Cache #{operation}: #{normalize_key(key, options)}#{options.blank? ? "" : " (#{options.inspect})"}" end payload = { key: key, store: self.class.name } payload.merge!(options) if options.is_a?(Hash) ActiveSupport::Notifications.instrument("cache_#{operation}.active_support", payload) { yield(payload) } end
def key_matcher(pattern, options) # :doc:
matches namespaced keys.
this method to translate a pattern that matches names into one that
match keys. Implementations that support delete_matched should call
Adds the namespace defined in the options to a pattern designed to
def key_matcher(pattern, options) # :doc: prefix = options[:namespace].is_a?(Proc) ? options[:namespace].call : options[:namespace] if prefix source = pattern.source if source.start_with?("^") source = source[1, source.length] else source = ".*#{source[0, source.length]}" end Regexp.new("^#{Regexp.escape(prefix)}:#{source}", pattern.options) else pattern end end
def merged_options(call_options)
def merged_options(call_options) if call_options call_options = normalize_options(call_options) if options.empty? call_options else options.merge(call_options) end else options end end
def mute
def mute previous_silence, @silence = defined?(@silence) && @silence, true yield ensure @silence = previous_silence end
def namespace_key(key, options = nil)
namespace_key 'foo', namespace: -> { 'cache' }
With a namespace block:
# => 'cache:foo'
namespace_key 'foo', namespace: 'cache'
Prefix the key with a namespace string:
def namespace_key(key, options = nil) options = merged_options(options) namespace = options[:namespace] if namespace.respond_to?(:call) namespace = namespace.call end if key && key.encoding != Encoding::UTF_8 key = key.dup.force_encoding(Encoding::UTF_8) end if namespace "#{namespace}:#{key}" else key end end
def new_entry(value, options = nil) # :nodoc:
def new_entry(value, options = nil) # :nodoc: Entry.new(value, **merged_options(options)) end
def normalize_key(key, options = nil)
Expands and namespaces the cache key. May be overridden by
def normalize_key(key, options = nil) namespace_key expanded_key(key), options end
def normalize_options(options)
def normalize_options(options) options = options.dup OPTION_ALIASES.each do |canonical_name, aliases| alias_key = aliases.detect { |key| options.key?(key) } options[canonical_name] ||= options[alias_key] if alias_key options.except!(*aliases) end options end
def normalize_version(key, options = nil)
def normalize_version(key, options = nil) (options && options[:version].try(:to_param)) || expanded_version(key) end
def read(name, options = nil)
as a cache miss. This feature is used to support recyclable cache keys.
version does not match the requested version, the read will be treated
* +:version+ - Specifies a version for the cache entry. If the cached
==== Options
the data is returned.
:version options, both of these conditions are applied before
Note, if data was written with the :expires_in or
+nil+ is returned.
the cache with the given key, then that data is returned. Otherwise,
Reads data from the cache, using the given key. If there is data in
def read(name, options = nil) options = merged_options(options) key = normalize_key(name, options) version = normalize_version(name, options) instrument(:read, name, options) do |payload| entry = read_entry(key, **options, event: payload) if entry if entry.expired? delete_entry(key, **options) payload[:hit] = false if payload nil elsif entry.mismatched?(version) payload[:hit] = false if payload nil else payload[:hit] = true if payload entry.value end else payload[:hit] = false if payload nil end end end
def read_entry(key, **options)
Reads an entry from the cache implementation. Subclasses must implement
def read_entry(key, **options) raise NotImplementedError.new end
def read_multi(*names)
Some cache implementation may optimize this method.
in the last argument.
Reads multiple values at once from the cache. Options can be passed
def read_multi(*names) options = names.extract_options! options = merged_options(options) instrument :read_multi, names, options do |payload| read_multi_entries(names, **options, event: payload).tap do |results| payload[:hits] = results.keys end end end
def read_multi_entries(names, **options)
Reads multiple entries from the cache implementation. Subclasses MAY
def read_multi_entries(names, **options) names.each_with_object({}) do |name, results| key = normalize_key(name, options) entry = read_entry(key, **options) next unless entry version = normalize_version(name, options) if entry.expired? delete_entry(key, **options) elsif !entry.mismatched?(version) results[name] = entry.value end end end
def retrieve_pool_options(options)
def retrieve_pool_options(options) {}.tap do |pool_options| pool_options[:size] = options.delete(:pool_size) if options[:pool_size] pool_options[:timeout] = options.delete(:pool_timeout) if options[:pool_timeout] end end
def save_block_result_to_cache(name, options)
def save_block_result_to_cache(name, options) result = instrument(:generate, name, options) do yield(name) end write(name, result, options) unless result.nil? && options[:skip_nil] result end
def serialize_entry(entry, **options)
def serialize_entry(entry, **options) options = merged_options(options) if @coder_supports_compression && options[:compress] @coder.dump_compressed(entry, options[:compress_threshold] || DEFAULT_COMPRESS_LIMIT) else @coder.dump(entry) end end
def silence!
def silence! @silence = true self end
def write(name, value, options = nil)
used to support recyclable cache keys.
version, the read will be treated as a cache miss. This feature is
from the cache, if the cached version does not match the requested
* +:version+ - Specifies a version for the cache entry. When reading
cache.write(key, value, expires_at: Time.now.at_end_of_hour)
cache = ActiveSupport::Cache::MemoryStore.new
* +:expires_at+ - Sets an absolute expiration time for the cache entry.
cache.write(key, value, expires_in: 1.minute) # Set a lower value for one entry
cache = ActiveSupport::Cache::MemoryStore.new(expires_in: 5.minutes)
+:expires_in+.
specified in seconds. +:expire_in+ and +:expired_in+ are aliases for
* +:expires_in+ - Sets a relative expiration time for the cache entry,
to +1.kilobyte+.
\Cache entries larger than this threshold will be compressed. Defaults
* +:compress_threshold+ - The compression threshold, specified in bytes.
* compress: false - Disables compression of the cache entry.
==== Options
fewer cache evictions and higher hit rates.
allows more data to be stored in the same memory footprint, leading to
By default, cache entries larger than 1kB are compressed. Compression
by the +coder+'s +dump+ and +load+ methods.
Writes the value to the cache with the key. The value must be supported
def write(name, value, options = nil) options = merged_options(options) instrument(:write, name, options) do entry = Entry.new(value, **options.merge(version: normalize_version(name, options))) write_entry(normalize_key(name, options), entry, **options) end end
def write_entry(key, entry, **options)
Writes an entry to the cache implementation. Subclasses must implement
def write_entry(key, entry, **options) raise NotImplementedError.new end
def write_multi(hash, options = nil)
def write_multi(hash, options = nil) options = merged_options(options) instrument :write_multi, hash, options do |payload| entries = hash.each_with_object({}) do |(name, value), memo| memo[normalize_key(name, options)] = Entry.new(value, **options.merge(version: normalize_version(name, options))) end write_multi_entries entries, **options end end
def write_multi_entries(hash, **options)
Writes multiple entries to the cache implementation. Subclasses MAY
def write_multi_entries(hash, **options) hash.each do |key, entry| write_entry key, entry, **options end end