Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Write documentation for the cache stores.

  • Loading branch information...
commit 295195b707d556610156349185bf9b5bf435abb1 1 parent 094a910
@FooBarWidget FooBarWidget authored
View
104 activesupport/lib/active_support/cache.rb
@@ -1,7 +1,33 @@
require 'benchmark'
module ActiveSupport
+ # See ActiveSupport::Cache::Store for documentation.
module Cache
+ # Creates a new CacheStore object according to the given options.
+ #
+ # If no arguments are passed to this method, then a new
+ # ActiveSupport::Cache::MemoryStore object will be returned.
+ #
+ # If you pass a Symbol as the first argument, then a corresponding cache
+ # store class under the ActiveSupport::Cache namespace will be created.
+ # For example:
+ #
+ # ActiveSupport::Cache.lookup_store(:memory_store)
+ # # => returns a new ActiveSupport::Cache::MemoryStore object
+ #
+ # ActiveSupport::Cache.lookup_store(:drb_store)
+ # # => returns a new ActiveSupport::Cache::DRbStore object
+ #
+ # Any additional arguments will be passed to the corresponding cache store
+ # class's constructor:
+ #
+ # ActiveSupport::Cache.lookup_store(:file_store, "/tmp/cache")
+ # # => same as: ActiveSupport::Cache::FileStore.new("/tmp/cache")
+ #
+ # If the first argument is not a Symbol, then it will simply be returned:
+ #
+ # ActiveSupport::Cache.lookup_store(MyOwnCacheStore.new)
+ # # => returns MyOwnCacheStore.new
def self.lookup_store(*store_option)
store, *parameters = *([ store_option ].flatten)
@@ -36,6 +62,21 @@ def self.expand_cache_key(key, namespace = nil)
expanded_cache_key
end
+ # An abstract cache store class. There are multiple cache store
+ # implementations, each having its own additional features. See the classes
+ # under the ActiveSupport::Cache module, e.g.
+ # ActiveSupport::Cache::MemCacheStore. MemCacheStore is currently the most
+ # popular cache store for large production websites.
+ #
+ # ActiveSupport::Cache::Store is meant for caching strings. Some cache
+ # store implementations, like MemoryStore, are able to cache arbitrary
+ # Ruby objects, but don't count on every cache store to be able to do that.
+ #
+ # cache = ActiveSupport::Cache::MemoryStore.new
+ #
+ # cache.read("city") # => nil
+ # cache.write("city", "Duckburgh")
+ # cache.read("city") # => "Duckburgh"
class Store
cattr_accessor :logger
@@ -44,7 +85,46 @@ def silence!
self
end
- # Pass <tt>:force => true</tt> to force a cache miss.
+ # Fetches data from the cache, using the given key. If there is data in
+ # the cache with the given key, then that data is returned.
+ #
+ # If there is no such data in the cache (a cache miss occurred), then
+ # then nil will be returned. However, if a block has been passed, then
+ # that block will be run in the event of a cache miss. The return value
+ # of the block will be written to the cache under the given cache key,
+ # and that return value will be returned.
+ #
+ # cache.write("today", "Monday")
+ # cache.fetch("today") # => "Monday"
+ #
+ # cache.fetch("city") # => nil
+ # cache.fetch("city") do
+ # "Duckburgh"
+ # end
+ # cache.fetch("city") # => "Duckburgh"
+ #
+ # You may also specify additional options via the +options+ argument.
+ # Setting <tt>:force => true</tt> will force a cache miss:
+ #
+ # cache.write("today", "Monday")
+ # cache.fetch("today", :force => true) # => nil
+ #
+ # Other options will be handled by the specific cache store implementation.
+ # Internally, #fetch calls #read, and calls #write on a cache miss.
+ # +options+ will be passed to the #read and #write calls.
+ #
+ # For example, MemCacheStore's #write method supports the +:expires_in+
+ # option, which tells the memcached server to automatically expire the
+ # cache item after a certain period. We can use this option with #fetch
+ # too:
+ #
+ # cache = ActiveSupport::Cache::MemCacheStore.new
+ # cache.fetch("foo", :force => true, :expires_in => 5.seconds) do
+ # "bar"
+ # end
+ # cache.fetch("foo") # => "bar"
+ # sleep(6)
+ # cache.fetch("foo") # => nil
def fetch(key, options = {})
@logger_off = true
if !options[:force] && value = read(key, options)
@@ -68,10 +148,32 @@ def fetch(key, options = {})
end
end
+ # Fetches data from the cache, using the given key. If there is data in
+ # the cache with the given key, then that data is returned. Otherwise,
+ # nil is returned.
+ #
+ # You may also specify additional options via the +options+ argument.
+ # The specific cache store implementation will decide what to do with
+ # +options+.
def read(key, options = nil)
log("read", key, options)
end
+ # Writes the given value to the cache, with the given key.
+ #
+ # You may also specify additional options via the +options+ argument.
+ # The specific cache store implementation will decide what to do with
+ # +options+.
+ #
+ # For example, MemCacheStore supports the +:expires_in+ option, which
+ # tells the memcached server to automatically expire the cache item after
+ # a certain period:
+ #
+ # cache = ActiveSupport::Cache::MemCacheStore.new
+ # cache.write("foo", "bar", :expires_in => 5.seconds)
+ # cache.read("foo") # => "bar"
+ # sleep(6)
+ # cache.read("foo") # => nil
def write(key, value, options = nil)
log("write", key, options)
end
View
1  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
View
42 activesupport/lib/active_support/cache/mem_cache_store.rb
@@ -2,8 +2,19 @@
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 Response
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 @@ def initialize(*addresses)
@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 @@ def read(key, options = nil)
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 @@ def write(key, value, options = nil)
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 @@ def delete(key, options = nil)
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 @@ def increment(key, amount = 1)
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 @@ def decrement(key, amount = 1)
nil
end
- def delete_matched(matcher, options = nil)
+ def delete_matched(matcher, options = nil) # :nodoc:
super
raise "Not supported by Memcache"
end
View
14 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 = {}
View
1  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
Please sign in to comment.
Something went wrong with that request. Please try again.