From 295195b707d556610156349185bf9b5bf435abb1 Mon Sep 17 00:00:00 2001 From: "Hongli Lai (Phusion)" Date: Sun, 26 Oct 2008 22:25:52 +0100 Subject: Write documentation for the cache stores. --- .../lib/active_support/cache/file_store.rb | 1 + .../lib/active_support/cache/mem_cache_store.rb | 42 +++++++++++++++++----- .../lib/active_support/cache/memory_store.rb | 14 ++++++++ .../cache/synchronized_memory_store.rb | 1 + 4 files changed, 49 insertions(+), 9 deletions(-) (limited to 'activesupport/lib/active_support/cache') diff --git a/activesupport/lib/active_support/cache/file_store.rb b/activesupport/lib/active_support/cache/file_store.rb index ffe0baba99..7f34cb52a1 100644 --- a/activesupport/lib/active_support/cache/file_store.rb +++ b/activesupport/lib/active_support/cache/file_store.rb @@ -1,5 +1,6 @@ module ActiveSupport module Cache + # A cache store implementation which stores everything on the filesystem. class FileStore < Store attr_reader :cache_path diff --git a/activesupport/lib/active_support/cache/mem_cache_store.rb b/activesupport/lib/active_support/cache/mem_cache_store.rb index 5531c30b7f..f9a7fb1440 100644 --- a/activesupport/lib/active_support/cache/mem_cache_store.rb +++ b/activesupport/lib/active_support/cache/mem_cache_store.rb @@ -2,8 +2,19 @@ require 'memcache' module ActiveSupport module Cache + # A cache store implementation which stores data in Memcached: + # http://www.danga.com/memcached/ + # + # 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 goes back + # online. + # - Time-based expiry support. See #write and the +:expires_in+ option. class MemCacheStore < Store - module Response + module Response # :nodoc: STORED = "STORED\r\n" NOT_STORED = "NOT_STORED\r\n" EXISTS = "EXISTS\r\n" @@ -13,6 +24,14 @@ module ActiveSupport attr_reader :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 specified, then MemCacheStore will connect to + # localhost port 11211 (the default memcached port). def initialize(*addresses) addresses = addresses.flatten options = addresses.extract_options! @@ -21,7 +40,7 @@ module ActiveSupport @data = MemCache.new(addresses, options) end - def read(key, options = nil) + def read(key, options = nil) # :nodoc: super @data.get(key, raw?(options)) rescue MemCache::MemCacheError => e @@ -29,8 +48,13 @@ module ActiveSupport nil end - # Set key = value. Pass :unless_exist => true if you don't - # want to update the cache if the key is already set. + # Writes a value to the cache. + # + # Possible options: + # - +:unless_exist+ - set to true if you don't want to update the cache + # if the key is already set. + # - +:expires_in+ - the number of seconds that this value may stay in + # the cache. See ActiveSupport::Cache::Store#write for an example. def write(key, value, options = nil) super method = options && options[:unless_exist] ? :add : :set @@ -44,7 +68,7 @@ module ActiveSupport false end - def delete(key, options = nil) + def delete(key, options = nil) # :nodoc: super response = @data.delete(key, expires_in(options)) response == Response::DELETED @@ -53,13 +77,13 @@ module ActiveSupport false end - def exist?(key, options = nil) + def exist?(key, options = nil) # :nodoc: # Doesn't call super, cause exist? in memcache is in fact a read # But who cares? Reading is very fast anyway !read(key, options).nil? end - def increment(key, amount = 1) + def increment(key, amount = 1) # :nodoc: log("incrementing", key, amount) response = @data.incr(key, amount) @@ -68,7 +92,7 @@ module ActiveSupport nil end - def decrement(key, amount = 1) + def decrement(key, amount = 1) # :nodoc: log("decrement", key, amount) response = @data.decr(key, amount) @@ -77,7 +101,7 @@ module ActiveSupport nil end - def delete_matched(matcher, options = nil) + def delete_matched(matcher, options = nil) # :nodoc: super raise "Not supported by Memcache" end diff --git a/activesupport/lib/active_support/cache/memory_store.rb b/activesupport/lib/active_support/cache/memory_store.rb index c1a713b4c5..1b30d49155 100644 --- a/activesupport/lib/active_support/cache/memory_store.rb +++ b/activesupport/lib/active_support/cache/memory_store.rb @@ -1,5 +1,19 @@ module ActiveSupport module Cache + # A cache store implementation which stores everything into memory in the + # same process. If you're running multiple Ruby on Rails server processes + # (which is the case if you're using mongrel_cluster or Phusion Passenger), + # then this means that your Rails server process instances won't be able + # to share cache data with each other. If your application never performs + # manual cache item expiry (e.g. when you're using generational cache keys), + # then using MemoryStore is ok. Otherwise, consider carefully whether you + # should be using this cache store. + # + # MemoryStore is not only able to store strings, but also arbitrary Ruby + # objects. + # + # MemoryStore is not thread-safe. Use SynchronizedMemoryStore instead + # if you need thread-safety. class MemoryStore < Store def initialize @data = {} diff --git a/activesupport/lib/active_support/cache/synchronized_memory_store.rb b/activesupport/lib/active_support/cache/synchronized_memory_store.rb index d2ff28768f..ea03a119c6 100644 --- a/activesupport/lib/active_support/cache/synchronized_memory_store.rb +++ b/activesupport/lib/active_support/cache/synchronized_memory_store.rb @@ -1,5 +1,6 @@ module ActiveSupport module Cache + # Like MemoryStore, but thread-safe. class SynchronizedMemoryStore < MemoryStore def initialize super -- cgit v1.2.3