Memcached Cache Store

A cache store implementation which stores data in Memcached: memcached.org

This is currently the most popular cache store for production websites.

Special features:

  • Clustering and load balancing. One can specify multiple memcached servers, and MemCacheStore will load balance between all available servers. If a server goes down, then MemCacheStore will ignore it until it comes back up.

MemCacheStore implements the Strategy::LocalCache strategy which implements an in-memory cache inside of a block.

Namespace

Module

Methods

Constants

ESCAPE_KEY_CHARS = /[\x00-\x20%\x7F-\xFF]/n
KEY_MAX_SIZE = 250
OVERRIDDEN_OPTIONS = UNIVERSAL_OPTIONS
 

These options represent behavior overridden by this implementation and should not be allowed to get down to the Dalli client

Class Public methods

new(*addresses)

Creates a new MemCacheStore object, with the given memcached server addresses. Each address is either a host name, or a host-with-port string in the form of “host_name:port”. For example:

ActiveSupport::Cache::MemCacheStore.new("localhost", "server-downstairs.localnetwork:8229")

If no addresses are provided, but ENV['MEMCACHE_SERVERS'] is defined, it will be used instead. Otherwise, MemCacheStore will connect to localhost:11211 (the default memcached port). Passing a Dalli::Client instance is deprecated and will be removed. Please pass an address instead.

📝 Source code 
# File activesupport/lib/active_support/cache/mem_cache_store.rb, line 118
      def initialize(*addresses)
        addresses = addresses.flatten
        options = addresses.extract_options!
        if options.key?(:cache_nils)
          options[:skip_nil] = !options.delete(:cache_nils)
        end
        super(options)

        unless [String, Dalli::Client, NilClass].include?(addresses.first.class)
          raise ArgumentError, "First argument must be an empty array, address, or array of addresses."
        end
        if addresses.first.is_a?(Dalli::Client)
          ActiveSupport.deprecator.warn(<<~MSG)
            Initializing MemCacheStore with a Dalli::Client is deprecated and will be removed in Rails 7.2.
            Use memcached server addresses instead.
          MSG
          @data = addresses.first
        else
          @mem_cache_options = options.dup
          # The value "compress: false" prevents duplicate compression within Dalli.
          @mem_cache_options[:compress] = false
          (OVERRIDDEN_OPTIONS - %i(compress)).each { |name| @mem_cache_options.delete(name) }
          @data = self.class.build_mem_cache(*(addresses + [@mem_cache_options]))
        end
      end
🔎 See on GitHub

supports_cache_versioning?()

Advertise cache versioning support.

📝 Source code 
# File activesupport/lib/active_support/cache/mem_cache_store.rb, line 38
      def self.supports_cache_versioning?
        true
      end
🔎 See on GitHub

Instance Public methods

clear(options = nil)

Clear the entire cache on all memcached servers. This method should be used with care when shared cache is being used.

📝 Source code 
# File activesupport/lib/active_support/cache/mem_cache_store.rb, line 215
      def clear(options = nil)
        rescue_error_with(nil) { @data.with { |c| c.flush_all } }
      end
🔎 See on GitHub

decrement(name, amount = 1, options = nil)

Decrement a cached integer value using the memcached decr atomic operator. Returns the updated value.

If the key is unset or has expired, it will be set to 0. Memcached does not support negative counters.

cache.decrement("foo") # => 0

To set a specific value, call write passing raw: true:

cache.write("baz", 5, raw: true)
cache.decrement("baz") # => 4

Decrementing a non-numeric value, or a value written without raw: true, will fail and return nil.

📝 Source code 
# File activesupport/lib/active_support/cache/mem_cache_store.rb, line 204
      def decrement(name, amount = 1, options = nil)
        options = merged_options(options)
        instrument(:decrement, name, amount: amount) do
          rescue_error_with nil do
            @data.with { |c| c.decr(normalize_key(name, options), amount, options[:expires_in], 0) }
          end
        end
      end
🔎 See on GitHub

increment(name, amount = 1, options = nil)

Increment a cached integer value using the memcached incr atomic operator. Returns the updated value.

If the key is unset or has expired, it will be set to amount:

cache.increment("foo") # => 1
cache.increment("bar", 100) # => 100

To set a specific value, call write passing raw: true:

cache.write("baz", 5, raw: true)
cache.increment("baz") # => 6

Incrementing a non-numeric value, or a value written without raw: true, will fail and return nil.

📝 Source code 
# File activesupport/lib/active_support/cache/mem_cache_store.rb, line 180
      def increment(name, amount = 1, options = nil)
        options = merged_options(options)
        instrument(:increment, name, amount: amount) do
          rescue_error_with nil do
            @data.with { |c| c.incr(normalize_key(name, options), amount, options[:expires_in], amount) }
          end
        end
      end
🔎 See on GitHub

inspect()

📝 Source code 
# File activesupport/lib/active_support/cache/mem_cache_store.rb, line 144
      def inspect
        instance = @data || @mem_cache_options
        "#<#{self.class} options=#{options.inspect} mem_cache=#{instance.inspect}>"
      end
🔎 See on GitHub

stats()

Get the statistics from the memcached servers.

📝 Source code 
# File activesupport/lib/active_support/cache/mem_cache_store.rb, line 220
      def stats
        @data.with { |c| c.stats }
      end
🔎 See on GitHub

write(name, value, options = nil)

Behaves the same as ActiveSupport::Cache::Store#write, but supports additional options specific to memcached.

Additional Options

  • raw: true - Sends the value directly to the server as raw bytes. The value must be a string or number. You can use memcached direct operations like increment and decrement only on raw values.

  • unless_exist: true - Prevents overwriting an existing cache entry.

🔎 See on GitHub