Interlock
A Rails plugin for maintainable and high-efficiency caching.
== License
Copyright 2007 Cloudburst, LLC. Licensed under the AFL 3; see the included LICENSE file. Portions copyright 2006 Chris Wanstrath and used with permission.
The public certificate for the gem is at http://rubyforge.org/frs/download.php/25331/evan_weaver-original-public_cert.pem.
== Requirements
* memcached (http://www.danga.com/memcached)
* memcache-client gem
* Rails 1.2.6
Note that Rails 2.0.2 is required for caching content_for or nesting view_cache blocks.
== What it does
Interlock makes your view fragments and associated controller blocks march along together. If a fragment is fresh, the controller behavior won't run. This eliminates duplicate effort from your request cycle. Your controller blocks run so infrequently that you can use regular ActiveRecord finders and not worry about object caching at all.
Interlock automatically tracks invalidation dependencies based on the model lifecyle, and supports arbitrary levels of scoping per-block. It also caches content_for calls, unlike regular Rails.
== Installation
First, compile and install memcached itself. Get a memcached server running.
You also need the memcache-client gem:
sudo gem install memcache-client
Then, install the plugin:
script/plugin install -x svn://rubyforge.org/var/svn/fauna/interlock/trunk
Lastly, configure your Rails app for memcached by creating a config/memcached.yml file. The format is compatible with Cache_fu:
defaults:
namespace: myapp
sessions: false
development:
servers:
- localhost:11211 # Default port
production:
servers
- 10.12.128.1
- 10.12.128.2
Now you're ready to go.
== Usage
Interlock provides two similar caching methods: behavior_cache for controllers and view_cache for views. They both accept an optional list or hash of model dependencies, and an optional :tag keypair. view_cache also accepts a :ttl keypair.
The simplest usage doesn't require any parameters. In the controller:
class ItemsController < ActionController::Base
def slow_action
behavior_cache do
@items = Item.find(:all, :conditions => "be slow")
end
end
end
Now, in the view, wrap the largest section of ERB you can find that uses data from @items in a view_cache block. No other part of the view can refer to @items, because @items won't get set unless the cache is stale.
<% @title = "My Sweet Items" %>
<% view_cache do %>
<% @items.each do |item| %>
<%= item.name %>
<% end %>
<% end %>
You have to do them both.
This automatically registers a caching dependency on Item for slow_action. The controller block won't run if the slow_action view fragment is fresh, and the view fragment will only get invalidated when an Item is changed.
You can use multiple instance variables in one block, of course. Just make sure the behavior_cache provides whatever the view_cache uses.
See ActionController::Base and ActionView::Helpers::CacheHelper for more details.
== Notes
You will not see any actual cache reuse in development mode unless you set config.action_controller.perform_caching = true in config/environments/development.rb.
If you have custom render calls in the controller, they must be outside the behavior_cache blocks. No exceptions. For example:
def profile
behavior_cache do
@items = Item.find(:all, :conditions => "be slow")
end
render :action => 'home'
end
You can write custom invalidation rules if you really want to, but try hard to avoid it; it has a significant cost in long-term maintainability.
Also, Interlock obeys the ENV['RAILS_ASSET_ID'] setting, so if you need to blanket-invalidate all your caches, just change RAILS_ASSET_ID (for example, you could have it increment on every deploy).
== Further resources
* http://blog.evanweaver.com/articles/2007/12/13/better-rails-caching/
* http://www.socialtext.net/memcached/index.cgi?faq
== Reporting problems
* http://rubyforge.org/forum/forum.php?forum_id=19835
Patches and contributions are very welcome. Please note that contributors are required to assign copyright for their additions to Cloudburst, LLC.