kotovalexarian-likes-github/rails--rails
1
0
Fork 0
mirror of https://github.com/rails/rails.git synced 2022-11-09 12:12:34 -05:00
Code Releases Activity

update AC::Caching documentation [ci skip]

Browse source
This commit is contained in:
Francesco Rodriguez 2012-09-22 19:42:40 -05:00
parent a045731718
commit 191ddf2637
5 changed files with 103 additions and 87 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

10
actionpack/lib/action_controller/caching.rb
View file

@ -23,10 +23,10 @@ module ActionController #:nodoc:
# Configuration examples (MemoryStore is the default): # Configuration examples (MemoryStore is the default):
# #
# config.action_controller.cache_store = :memory_store # config.action_controller.cache_store = :memory_store
# config.action_controller.cache_store = :file_store, "/path/to/cache/directory" # config.action_controller.cache_store = :file_store, '/path/to/cache/directory'
# config.action_controller.cache_store = :mem_cache_store, "localhost" # config.action_controller.cache_store = :mem_cache_store, 'localhost'
# config.action_controller.cache_store = :mem_cache_store, Memcached::Rails.new("localhost:11211") # config.action_controller.cache_store = :mem_cache_store, Memcached::Rails.new('localhost:11211')
# config.action_controller.cache_store = MyOwnStore.new("parameter") # config.action_controller.cache_store = MyOwnStore.new('parameter')
module Caching module Caching
extend ActiveSupport::Concern extend ActiveSupport::Concern
extend ActiveSupport::Autoload extend ActiveSupport::Autoload
@ -73,7 +73,7 @@ module ActionController #:nodoc:
end end
protected protected
# Convenience accessor # Convenience accessor.
def cache(key, options = {}, &block) def cache(key, options = {}, &block)
if cache_configured? if cache_configured?
cache_store.fetch(ActiveSupport::Cache.expand_cache_key(key, :controller), options, &block) cache_store.fetch(ActiveSupport::Cache.expand_cache_key(key, :controller), options, &block)

26
actionpack/lib/action_controller/caching/actions.rb
View file

@ -1,16 +1,16 @@
require 'set' require 'set'
module ActionController #:nodoc: module ActionController
module Caching module Caching
# Action caching is similar to page caching by the fact that the entire # Action caching is similar to page caching by the fact that the entire
# output of the response is cached, but unlike page caching, every # output of the response is cached, but unlike page caching, every
# request still goes through Action Pack. The key benefit of this is # request still goes through Action Pack. The key benefit of this is
# that filters run before the cache is served, which allows for # that filters run before the cache is served, which allows for
# authentication and other restrictions on whether someone is allowed # authentication and other restrictions on whether someone is allowed
# to execute such action. Example: # to execute such action.
# #
# class ListsController < ApplicationController # class ListsController < ApplicationController
# before_filter :authenticate, :except => :public # before_filter :authenticate, except: :public
# #
# caches_page :public # caches_page :public
# caches_action :index, :show # caches_action :index, :show
@ -35,8 +35,8 @@ module ActionController #:nodoc:
# <tt>http://david.example.com/lists.xml</tt> # <tt>http://david.example.com/lists.xml</tt>
# are treated like separate requests and so are cached separately. # are treated like separate requests and so are cached separately.
# Keep in mind when expiring an action cache that # Keep in mind when expiring an action cache that
# <tt>:action => 'lists'</tt> is not the same as # <tt>action: 'lists'</tt> is not the same as
# <tt>:action => 'list', :format => :xml</tt>. # <tt>action: 'list', format: :xml</tt>.
# #
# You can modify the default action cache path by passing a # You can modify the default action cache path by passing a
# <tt>:cache_path</tt> option. This will be passed directly to # <tt>:cache_path</tt> option. This will be passed directly to
@ -53,18 +53,18 @@ module ActionController #:nodoc:
# The following example depicts some of the points made above: # The following example depicts some of the points made above:
# #
# class ListsController < ApplicationController # class ListsController < ApplicationController
# before_filter :authenticate, :except => :public # before_filter :authenticate, except: :public
# #
# caches_page :public # caches_page :public
# #
# caches_action :index, :if => Proc.new do # caches_action :index, if: Proc.new do
# !request.format.json? # cache if is not a JSON request # !request.format.json? # cache if is not a JSON request
# end # end
# #
# caches_action :show, :cache_path => { :project => 1 }, # caches_action :show, cache_path: { project: 1 },
# :expires_in => 1.hour # expires_in: 1.hour
# #
# caches_action :feed, :cache_path => Proc.new do # caches_action :feed, cache_path: Proc.new do
# if params[:user_id] # if params[:user_id]
# user_list_url(params[:user_id, params[:id]) # user_list_url(params[:user_id, params[:id])
# else # else
@ -73,7 +73,7 @@ module ActionController #:nodoc:
# end # end
# end # end
# #
# If you pass <tt>:layout => false</tt>, it will only cache your action # If you pass <tt>layout: false</tt>, it will only cache your action
# content. That's useful when your layout has dynamic information. # content. That's useful when your layout has dynamic information.
# #
# Warning: If the format of the request is determined by the Accept HTTP # Warning: If the format of the request is determined by the Accept HTTP
@ -162,9 +162,9 @@ module ActionController #:nodoc:
class ActionCachePath class ActionCachePath
attr_reader :path, :extension attr_reader :path, :extension
# If +infer_extension+ is true, the cache path extension is looked up from the request's # If +infer_extension+ is +true+, the cache path extension is looked up from the request's
# path and format. This is desirable when reading and writing the cache, but not when # path and format. This is desirable when reading and writing the cache, but not when
# expiring the cache - expire_action should expire the same files regardless of the # expiring the cache - +expire_action+ should expire the same files regardless of the
# request format. # request format.
def initialize(controller, options = {}, infer_extension = true) def initialize(controller, options = {}, infer_extension = true)
if infer_extension if infer_extension

26
actionpack/lib/action_controller/caching/fragments.rb
View file

@ -1,20 +1,20 @@
module ActionController #:nodoc: module ActionController
module Caching module Caching
# Fragment caching is used for caching various blocks within # Fragment caching is used for caching various blocks within
# views without caching the entire action as a whole. This is # views without caching the entire action as a whole. This is
# useful when certain elements of an action change frequently or # useful when certain elements of an action change frequently or
# depend on complicated state while other parts rarely change or # depend on complicated state while other parts rarely change or
# can be shared amongst multiple parties. The caching is done using # can be shared amongst multiple parties. The caching is done using
# the <tt>cache</tt> helper available in the Action View. See # the +cache+ helper available in the Action View. See
# ActionView::Helpers::CacheHelper for more information. # ActionView::Helpers::CacheHelper for more information.
# #
# While it's strongly recommended that you use key-based cache # While it's strongly recommended that you use key-based cache
# expiration (see links in CacheHelper for more information), # expiration (see links in CacheHelper for more information),
# it is also possible to manually expire caches. For example: # it is also possible to manually expire caches. For example:
# #
# expire_fragment("name_of_cache") # expire_fragment('name_of_cache')
module Fragments module Fragments
# Given a key (as described in <tt>expire_fragment</tt>), returns # Given a key (as described in +expire_fragment+), returns
# a key suitable for use in reading, writing, or expiring a # a key suitable for use in reading, writing, or expiring a
# cached fragment. All keys are prefixed with <tt>views/</tt> and uses # cached fragment. All keys are prefixed with <tt>views/</tt> and uses
# ActiveSupport::Cache.expand_cache_key for the expansion. # ActiveSupport::Cache.expand_cache_key for the expansion.
@ -22,8 +22,8 @@ module ActionController #:nodoc:
ActiveSupport::Cache.expand_cache_key(key.is_a?(Hash) ? url_for(key).split("://").last : key, :views) ActiveSupport::Cache.expand_cache_key(key.is_a?(Hash) ? url_for(key).split("://").last : key, :views)
end end
# Writes <tt>content</tt> to the location signified by # Writes +content+ to the location signified by
# <tt>key</tt> (see <tt>expire_fragment</tt> for acceptable formats). # +key+ (see +expire_fragment+ for acceptable formats).
def write_fragment(key, content, options = nil) def write_fragment(key, content, options = nil)
return content unless cache_configured? return content unless cache_configured?
@ -35,8 +35,8 @@ module ActionController #:nodoc:
content content
end end
# Reads a cached fragment from the location signified by <tt>key</tt> # Reads a cached fragment from the location signified by +key+
# (see <tt>expire_fragment</tt> for acceptable formats). # (see +expire_fragment+ for acceptable formats).
def read_fragment(key, options = nil) def read_fragment(key, options = nil)
return unless cache_configured? return unless cache_configured?
@ -48,7 +48,7 @@ module ActionController #:nodoc:
end end
# Check if a cached fragment from the location signified by # Check if a cached fragment from the location signified by
# <tt>key</tt> exists (see <tt>expire_fragment</tt> for acceptable formats) # +key+ exists (see +expire_fragment+ for acceptable formats).
def fragment_exist?(key, options = nil) def fragment_exist?(key, options = nil)
return unless cache_configured? return unless cache_configured?
key = fragment_cache_key(key) key = fragment_cache_key(key)
@ -65,7 +65,7 @@ module ActionController #:nodoc:
# * String - This would normally take the form of a path, like # * String - This would normally take the form of a path, like
# <tt>pages/45/notes</tt>. # <tt>pages/45/notes</tt>.
# * Hash - Treated as an implicit call to +url_for+, like # * Hash - Treated as an implicit call to +url_for+, like
# <tt>{:controller => "pages", :action => "notes", :id => 45}</tt> # <tt>{ controller: 'pages', action: 'notes', id: 45}</tt>
# * Regexp - Will remove any fragment that matches, so # * Regexp - Will remove any fragment that matches, so
# <tt>%r{pages/\d*/notes}</tt> might remove all notes. Make sure you # <tt>%r{pages/\d*/notes}</tt> might remove all notes. Make sure you
# don't use anchors in the regex (<tt>^</tt> or <tt>$</tt>) because # don't use anchors in the regex (<tt>^</tt> or <tt>$</tt>) because
@ -74,8 +74,8 @@ module ActionController #:nodoc:
# only supported on caches that can iterate over all keys (unlike # only supported on caches that can iterate over all keys (unlike
# memcached). # memcached).
# #
# +options+ is passed through to the cache store's <tt>delete</tt> # +options+ is passed through to the cache store's +delete+
# method (or <tt>delete_matched</tt>, for Regexp keys.) # method (or <tt>delete_matched</tt>, for Regexp keys).
def expire_fragment(key, options = nil) def expire_fragment(key, options = nil)
return unless cache_configured? return unless cache_configured?
key = fragment_cache_key(key) unless key.is_a?(Regexp) key = fragment_cache_key(key) unless key.is_a?(Regexp)
@ -89,7 +89,7 @@ module ActionController #:nodoc:
end end
end end
def instrument_fragment_cache(name, key) def instrument_fragment_cache(name, key) # :nodoc:
ActiveSupport::Notifications.instrument("#{name}.action_controller", :key => key){ yield } ActiveSupport::Notifications.instrument("#{name}.action_controller", :key => key){ yield }
end end
end end

91
actionpack/lib/action_controller/caching/pages.rb
View file

@ -1,60 +1,72 @@
require 'fileutils' require 'fileutils'
require 'active_support/core_ext/class/attribute_accessors' require 'active_support/core_ext/class/attribute_accessors'
module ActionController #:nodoc: module ActionController
module Caching module Caching
# Page caching is an approach to caching where the entire action output of is stored as a HTML file that the web server # Page caching is an approach to caching where the entire action output of is
# can serve without going through Action Pack. This is the fastest way to cache your content as opposed to going dynamically # stored as a HTML file that the web server can serve without going through
# through the process of generating the content. Unfortunately, this incredible speed-up is only available to stateless pages # Action Pack. This is the fastest way to cache your content as opposed to going
# where all visitors are treated the same. Content management systems -- including weblogs and wikis -- have many pages that are # dynamically through the process of generating the content. Unfortunately, this
# a great fit for this approach, but account-based systems where people log in and manipulate their own data are often less # incredible speed-up is only available to stateless pages where all visitors are
# likely candidates. # treated the same. Content management systems -- including weblogs and wikis --
# have many pages that are a great fit for this approach, but account-based systems
# where people log in and manipulate their own data are often less likely candidates.
# #
# Specifying which actions to cache is done through the <tt>caches_page</tt> class method: # Specifying which actions to cache is done through the +caches_page+ class method:
# #
# class WeblogController < ActionController::Base # class WeblogController < ActionController::Base
# caches_page :show, :new # caches_page :show, :new
# end # end
# #
# This will generate cache files such as <tt>weblog/show/5.html</tt> and <tt>weblog/new.html</tt>, which match the URLs used # This will generate cache files such as <tt>weblog/show/5.html</tt> and
# that would normally trigger dynamic page generation. Page caching works by configuring a web server to first check for the # <tt>weblog/new.html</tt>, which match the URLs used that would normally trigger
# existence of files on disk, and to serve them directly when found, without passing the request through to Action Pack. # dynamic page generation. Page caching works by configuring a web server to first
# This is much faster than handling the full dynamic request in the usual way. # check for the existence of files on disk, and to serve them directly when found,
# without passing the request through to Action Pack. This is much faster than
# handling the full dynamic request in the usual way.
# #
# Expiration of the cache is handled by deleting the cached file, which results in a lazy regeneration approach where the cache # Expiration of the cache is handled by deleting the cached file, which results
# is not restored before another hit is made against it. The API for doing so mimics the options from +url_for+ and friends: # in a lazy regeneration approach where the cache is not restored before another
# hit is made against it. The API for doing so mimics the options from +url_for+ and friends:
# #
# class WeblogController < ActionController::Base # class WeblogController < ActionController::Base
# def update # def update
# List.update(params[:list][:id], params[:list]) # List.update(params[:list][:id], params[:list])
# expire_page :action => "show", :id => params[:list][:id] # expire_page action: 'show', id: params[:list][:id]
# redirect_to :action => "show", :id => params[:list][:id] # redirect_to action: 'show', id: params[:list][:id]
# end # end
# end # end
# #
# Additionally, you can expire caches using Sweepers that act on changes in the model to determine when a cache is supposed to be # Additionally, you can expire caches using Sweepers that act on changes in
# expired. # the model to determine when a cache is supposed to be expired.
module Pages module Pages
extend ActiveSupport::Concern extend ActiveSupport::Concern
included do included do
# The cache directory should be the document root for the web server and is set using <tt>Base.page_cache_directory = "/document/root"</tt>. # The cache directory should be the document root for the web server and is
# For Rails, this directory has already been set to Rails.public_path (which is usually set to <tt>Rails.root + "/public"</tt>). Changing # set using <tt>Base.page_cache_directory = "/document/root"</tt>. For Rails,
# this setting can be useful to avoid naming conflicts with files in <tt>public/</tt>, but doing so will likely require configuring your # this directory has already been set to Rails.public_path (which is usually
# web server to look in the new location for cached files. # set to <tt>Rails.root + "/public"</tt>). Changing this setting can be useful
# to avoid naming conflicts with files in <tt>public/</tt>, but doing so will
# likely require configuring your web server to look in the new location for
# cached files.
class_attribute :page_cache_directory class_attribute :page_cache_directory
self.page_cache_directory ||= '' self.page_cache_directory ||= ''
# Most Rails requests do not have an extension, such as <tt>/weblog/new</tt>. In these cases, the page caching mechanism will add one in # Most Rails requests do not have an extension, such as <tt>/weblog/new</tt>.
# order to make it easy for the cached files to be picked up properly by the web server. By default, this cache extension is <tt>.html</tt>. # In these cases, the page caching mechanism will add one in order to make it
# If you want something else, like <tt>.php</tt> or <tt>.shtml</tt>, just set Base.page_cache_extension. In cases where a request already has an # easy for the cached files to be picked up properly by the web server. By
# extension, such as <tt>.xml</tt> or <tt>.rss</tt>, page caching will not add an extension. This allows it to work well with RESTful apps. # default, this cache extension is <tt>.html</tt>. If you want something else,
# like <tt>.php</tt> or <tt>.shtml</tt>, just set Base.page_cache_extension.
# In cases where a request already has an extension, such as <tt>.xml</tt>
# or <tt>.rss</tt>, page caching will not add an extension. This allows it
# to work well with RESTful apps.
class_attribute :page_cache_extension class_attribute :page_cache_extension
self.page_cache_extension ||= '.html' self.page_cache_extension ||= '.html'
# The compression used for gzip. If false (default), the page is not compressed. # The compression used for gzip. If +false+ (default), the page is not compressed.
# If can be a symbol showing the ZLib compression method, for example, :best_compression # If can be a symbol showing the ZLib compression method, for example, <tt>:best_compression</tt>
# or :best_speed or an integer configuring the compression level. # or <tt>:best_speed</tt> or an integer configuring the compression level.
class_attribute :page_cache_compression class_attribute :page_cache_compression
self.page_cache_compression ||= false self.page_cache_compression ||= false
end end
@ -62,7 +74,7 @@ module ActionController #:nodoc:
module ClassMethods module ClassMethods
# Expires the page that was cached with the +path+ as a key. # Expires the page that was cached with the +path+ as a key.
# #
# expire_page "/lists/show" # expire_page '/lists/show'
def expire_page(path) def expire_page(path)
return unless perform_caching return unless perform_caching
path = page_cache_path(path) path = page_cache_path(path)
@ -75,7 +87,7 @@ module ActionController #:nodoc:
# Manually cache the +content+ in the key determined by +path+. # Manually cache the +content+ in the key determined by +path+.
# #
# cache_page "I'm the cached content", "/lists/show" # cache_page "I'm the cached content", '/lists/show'
def cache_page(content, path, extension = nil, gzip = Zlib::BEST_COMPRESSION) def cache_page(content, path, extension = nil, gzip = Zlib::BEST_COMPRESSION)
return unless perform_caching return unless perform_caching
path = page_cache_path(path, extension) path = page_cache_path(path, extension)
@ -90,19 +102,19 @@ module ActionController #:nodoc:
end end
# Caches the +actions+ using the page-caching approach that'll store # Caches the +actions+ using the page-caching approach that'll store
# the cache in a path within the page_cache_directory that # the cache in a path within the +page_cache_directory+ that
# matches the triggering url. # matches the triggering url.
# #
# You can also pass a :gzip option to override the class configuration one. # You can also pass a <tt>:gzip</tt> option to override the class configuration one.
# #
# # cache the index action # # cache the index action
# caches_page :index # caches_page :index
# #
# # cache the index action except for JSON requests # # cache the index action except for JSON requests
# caches_page :index, :if => Proc.new { !request.format.json? } # caches_page :index, if: Proc.new { !request.format.json? }
# #
# # don't gzip images # # don't gzip images
# caches_page :image, :gzip => false # caches_page :image, gzip: false
def caches_page(*actions) def caches_page(*actions)
return unless perform_caching return unless perform_caching
options = actions.extract_options! options = actions.extract_options!
@ -144,7 +156,7 @@ module ActionController #:nodoc:
# Expires the page that was cached with the +options+ as a key. # Expires the page that was cached with the +options+ as a key.
# #
# expire_page :controller => "lists", :action => "show" # expire_page controller: 'lists', action: 'show'
def expire_page(options = {}) def expire_page(options = {})
return unless self.class.perform_caching return unless self.class.perform_caching
@ -161,10 +173,11 @@ module ActionController #:nodoc:
end end
end end
# Manually cache the +content+ in the key determined by +options+. If no content is provided, the contents of response.body is used. # Manually cache the +content+ in the key determined by +options+. If no content is provided,
# If no options are provided, the url of the current request being handled is used. # the contents of response.body is used. If no options are provided, the url of the current
# request being handled is used.
# #
# cache_page "I'm the cached content", :controller => "lists", :action => "show" # cache_page "I'm the cached content", controller: 'lists', action: 'show'
def cache_page(content = nil, options = nil, gzip = Zlib::BEST_COMPRESSION) def cache_page(content = nil, options = nil, gzip = Zlib::BEST_COMPRESSION)
return unless self.class.perform_caching && caching_allowed? return unless self.class.perform_caching && caching_allowed?

27
actionpack/lib/action_controller/caching/sweeping.rb
View file

@ -1,38 +1,41 @@
module ActionController #:nodoc: module ActionController
module Caching module Caching
# Sweepers are the terminators of the caching world and responsible for expiring caches when Active Record objects change. # Sweepers are the terminators of the caching world and responsible for expiring
# They do this by being half-observers, half-filters and implementing callbacks for both roles. A Sweeper example: # caches when Active Record objects change. They do this by being half-observers,
# half-filters and implementing callbacks for both roles.
# #
# class ListSweeper < ActionController::Caching::Sweeper # class ListSweeper < ActionController::Caching::Sweeper
# observe List, Item # observe List, Item
# #
# def after_save(record) # def after_save(record)
# list = record.is_a?(List) ? record : record.list # list = record.is_a?(List) ? record : record.list
# expire_page(:controller => "lists", :action => %w( show public feed ), :id => list.id) # expire_page(controller: 'lists', action: %w( show public feed ), id: list.id)
# expire_action(:controller => "lists", :action => "all") # expire_action(controller: 'lists', action: 'all')
# list.shares.each { |share| expire_page(:controller => "lists", :action => "show", :id => share.url_key) } # list.shares.each { |share| expire_page(controller: 'lists', action: 'show', id: share.url_key) }
# end # end
# end # end
# #
# The sweeper is assigned in the controllers that wish to have its job performed using the <tt>cache_sweeper</tt> class method: # The sweeper is assigned in the controllers that wish to have its job performed using
# the +cache_sweeper+ class method:
# #
# class ListsController < ApplicationController # class ListsController < ApplicationController
# caches_action :index, :show, :public, :feed # caches_action :index, :show, :public, :feed
# cache_sweeper :list_sweeper, :only => [ :edit, :destroy, :share ] # cache_sweeper :list_sweeper, only: [ :edit, :destroy, :share ]
# end # end
# #
# In the example above, four actions are cached and three actions are responsible for expiring those caches. # In the example above, four actions are cached and three actions are responsible for expiring those caches.
# #
# You can also name an explicit class in the declaration of a sweeper, which is needed if the sweeper is in a module: # You can also name an explicit class in the declaration of a sweeper, which is needed
# if the sweeper is in a module:
# #
# class ListsController < ApplicationController # class ListsController < ApplicationController
# caches_action :index, :show, :public, :feed # caches_action :index, :show, :public, :feed
# cache_sweeper OpenBar::Sweeper, :only => [ :edit, :destroy, :share ] # cache_sweeper OpenBar::Sweeper, only: [ :edit, :destroy, :share ]
# end # end
module Sweeping module Sweeping
extend ActiveSupport::Concern extend ActiveSupport::Concern
module ClassMethods #:nodoc: module ClassMethods # :nodoc:
def cache_sweeper(*sweepers) def cache_sweeper(*sweepers)
configuration = sweepers.extract_options! configuration = sweepers.extract_options!
@ -51,7 +54,7 @@ module ActionController #:nodoc:
end end
if defined?(ActiveRecord) and defined?(ActiveRecord::Observer) if defined?(ActiveRecord) and defined?(ActiveRecord::Observer)
class Sweeper < ActiveRecord::Observer #:nodoc: class Sweeper < ActiveRecord::Observer # :nodoc:
attr_accessor :controller attr_accessor :controller
def initialize(*args) def initialize(*args)