diff options
author | Aditya Chadha <aditya@sublucid.com> | 2009-02-23 00:43:38 -0500 |
---|---|---|
committer | Aditya Chadha <aditya@sublucid.com> | 2009-02-23 00:43:38 -0500 |
commit | 7cf3822c5624cca530afa8481956142dfff6cca3 (patch) | |
tree | a8a919666ff7289881949885ad4dc6da7986aa7a | |
parent | b9e87f46791d81083c8d44890cd50a03c1c0b7fa (diff) | |
download | rails-7cf3822c5624cca530afa8481956142dfff6cca3.tar.gz rails-7cf3822c5624cca530afa8481956142dfff6cca3.tar.bz2 rails-7cf3822c5624cca530afa8481956142dfff6cca3.zip |
Updated with all the new cache_store stuff
-rw-r--r-- | railties/guides/source/caching_with_rails.textile | 113 |
1 files changed, 92 insertions, 21 deletions
diff --git a/railties/guides/source/caching_with_rails.textile b/railties/guides/source/caching_with_rails.textile index d77f48929d..b7082e8092 100644 --- a/railties/guides/source/caching_with_rails.textile +++ b/railties/guides/source/caching_with_rails.textile @@ -304,51 +304,110 @@ that action and thus persist only for the duration of the action. h4. Cache stores -Rails provides different stores for the cached data for action and fragment -caches. Page caches are always stored on disk. +Rails (as of 2.1) provides different stores for the cached data for action and +fragment caches. Page caches are always stored on disk. -The cache stores provided include: +Rails 2.1 and above provide ActiveSupport::Cache::Store which can be used to +cache 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. -1) Memory store: Cached data is stored in the memory allocated to the Rails - process, which is fine for WEBrick and for FCGI (if you - don't care that each FCGI process holds its own fragment - store). It's not suitable for CGI as the process is thrown - away at the end of each request. It can potentially also - take up a lot of memory since each process keeps all the - caches in memory. +The default cache stores provided include: + +1) ActiveSupport::Cache::MemoryStore: 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. + <ruby> ActionController::Base.cache_store = :memory_store </ruby> -2) File store: Cached data is stored on the disk, this is the default store - and the default path for this store is: /tmp/cache. Works - well for all types of environments and allows all processes - running from the same application directory to access the - cached content. +2) ActiveSupport::Cache::FileStore: Cached data is stored on the disk, this is +the default store and the default path for this store is: /tmp/cache. Works +well for all types of environments and allows all processes running from the +same application directory to access the cached content. If /tmp/cache does not +exist, the default store becomes MemoryStore. <ruby> ActionController::Base.cache_store = :file_store, "/path/to/cache/directory" </ruby> -3) DRb store: Cached data is stored in a separate shared DRb process that all - servers communicate with. This works for all environments and - only keeps one cache around for all processes, but requires - that you run and manage a separate DRb process. +3) ActiveSupport::Cache::DRbStore: Cached data is stored in a separate shared +DRb process that all servers communicate with. This works for all environments +and only keeps one cache around for all processes, but requires that you run +and manage a separate DRb process. + <ruby> ActionController::Base.cache_store = :drb_store, "druby://localhost:9192" </ruby> 4) MemCached store: Works like DRbStore, but uses Danga's MemCache instead. - Rails uses the bundled memcached-client gem by default. +Rails uses the bundled memcached-client gem by default. 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. + * Per-request in memory cache for all communication with the MemCache server(s). + +It also accepts a hash of additional options: + + * :namespace - specifies a string that will automatically be prepended to keys when accessing the memcached store. + * :readonly - a boolean value that when set to true will make the store read-only, with an error raised on any attempt to write. + * :multithread - a boolean value that adds thread safety to read/write operations - it is unlikely you’ll need to use this option as the Rails threadsafe! method offers the same functionality. + +The read and write methods of the MemCacheStore accept an options hash too. +When reading you can specify :raw => true to prevent the object being marshaled +(by default this is false which means the raw value in the cache is passed to +Marshal.load before being returned to you.) + +When writing to the cache it is also possible to specify :raw => true means the +value is not passed to Marshal.dump before being stored in the cache (by +default this is false). + +The write method also accepts an :unless_exist flag which determines whether +the memcached add (when true) or set (when false) method is used to store the +item in the cache and an :expires_in option that specifies the time-to-live for +the cached item in seconds. + <ruby> ActionController::Base.cache_store = :mem_cache_store, "localhost" </ruby> -5) Custom store: You can define your own cache store (new in Rails 2.1) +5) ActiveSupport::Cache::SynchronizedMemoryStore: Like ActiveSupport::Cache::MemoryStore but thread-safe. + + +<ruby> +ActionController::Base.cache_store = :synchronized_memory_store +</ruby> + +6) ActiveSupport::Cache::CompressedMemCacheStore: Works just like the regular +MemCacheStore but uses GZip to decompress/compress on read/write. + + +<ruby> +ActionController::Base.cache_store = :compressed_mem_cache_store, "localhost" +</ruby> + +7) Custom store: You can define your own cache store (new in Rails 2.1) + <ruby> ActionController::Base.cache_store = MyOwnStore.new("parameter") @@ -358,6 +417,18 @@ ActionController::Base.cache_store = MyOwnStore.new("parameter") ActionController::Base.cache_store in your Rails::Initializer.run block in environment.rb+ +In addition to all of this, Rails also adds the ActiveRecord::Base#cache_key +method that generates a key using the class name, id and updated_at timestamp +(if available). + +An example: + +<ruby> +Rails.cache.read("city") # => nil +Rails.cache.write("city", "Duckburgh") +Rails.cache.read("city") # => "Duckburgh" +</ruby> + h3. Conditional GET support Conditional GETs are a facility of the HTTP spec that provide a way for web |