Ruby on Rails | Screencasts | Download | Documentation | Weblog | Community | Source

Ticket #7315: docs_for_fragment_caching.patch

File docs_for_fragment_caching.patch, 5.5 kB (added by bscofield, 2 years ago)

  • caching.rb

    old new  
    216216           
    217217      end 
    218218       
    219       class ActionCachePath 
     219      class ActionCachePath #:nodoc: 
    220220        attr_reader :controller, :options 
    221221         
    222222        class << self 
    …… 
    269269    #     <%= render :partial => "topic", :collection => Topic.find(:all) %> 
    270270    #   <% end %> 
    271271    # 
    272     # This cache will bind to the name of action that called it. So you would be able to invalidate it using 
    273     # <tt>expire_fragment(:controller => "topics", :action => "list")</tt> -- if that was the controller/action used. This is not too helpful 
    274     # if you need to cache multiple fragments per action or if the action itself is cached using <tt>caches_action</tt>. So instead we should 
    275     # qualify the name of the action used with something like: 
     272    # This cache will bind to the name of the action that called it, so if this code was part of the view for the topics/list action, you would  
     273    # be able to invalidate it using <tt>expire_fragment(:controller => "topics", :action => "list")</tt>.  
     274    #  
     275    # This default behavior is of limited use if you need to cache multiple fragments per action or if the action itself is cached using  
     276    # <tt>caches_action</tt>, so we also have the option to qualify the name of the cached fragment with something like: 
    276277    # 
    277278    #   <% cache(:action => "list", :action_suffix => "all_topics") do %> 
    278279    # 
    279     # That would result in a name such as "/topics/list/all_topics", which wouldn't conflict with any action cache and neither with another 
    280     # fragment using a different suffix. Note that the URL doesn't have to really exist or be callable. We're just using the url_for system 
    281     # to generate unique cache names that we can refer to later for expirations. The expiration call for this example would be 
    282     # <tt>expire_fragment(:controller => "topics", :action => "list", :action_suffix => "all_topics")</tt>. 
     280    # That would result in a name such as "/topics/list/all_topics", avoiding conflicts with the action cache and with any fragments that use a  
     281    # different suffix. Note that the URL doesn't have to really exist or be callable - the url_for system is just used to generate unique  
     282    # cache names that we can refer to when we need to expire the cache.  
     283    #  
     284    # The expiration call for this example is: 
     285    #  
     286    #   expire_fragment(:controller => "topics", :action => "list", :action_suffix => "all_topics") 
    283287    # 
    284288    # == Fragment stores 
    285289    # 
    286     # In order to use the fragment caching, you need to designate where the caches should be stored. This is done by assigning a fragment store 
    287     # of which there are four different kinds: 
     290    # By default, cached fragments are stored in memory. The available store options are: 
    288291    # 
    289     # * FileStore: Keeps the fragments on disk in the +cache_path+, which works well for all types of environments and shares the fragments for 
    290     #   all the web server processes running off the same application directory. 
     292    # * FileStore: Keeps the fragments on disk in the +cache_path+, which works well for all types of environments and allows all  
     293    #   processes running from the same application directory to access the cached content. 
    291294    # * MemoryStore: Keeps the fragments in memory, which is fine for WEBrick and for FCGI (if you don't care that each FCGI process holds its 
    292295    #   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 
    293296    #   up a lot of memory since each process keeps all the caches in memory. 
    …… 
    309312          @@fragment_cache_store = MemoryStore.new 
    310313          cattr_reader :fragment_cache_store 
    311314 
     315          # Defines the storage option for cached fragments 
    312316          def self.fragment_cache_store=(store_option) 
    313317            store, *parameters = *([ store_option ].flatten) 
    314318            @@fragment_cache_store = if store.is_a?(Symbol) 
    …… 
    322326        end 
    323327      end 
    324328 
     329      # Given a name (as described in <tt>expire_fragment</tt>), returns a key suitable for use in reading,  
     330      # writing, or expiring a cached fragment. If the name is a hash, the generated name is the return 
     331      # value of url_for on that hash (without the protocol). 
    325332      def fragment_cache_key(name) 
    326333        name.is_a?(Hash) ? url_for(name).split("://").last : name 
    327334      end 
    …… 
    341348        end 
    342349      end 
    343350 
     351      # Writes <tt>content</tt> to the location signified by <tt>name</tt> (see <tt>expire_fragment</tt> for acceptable formats) 
    344352      def write_fragment(name, content, options = nil) 
    345353        return unless perform_caching 
    346354 
    …… 
    351359        content 
    352360      end 
    353361 
     362      # Reads a cached fragment from the location signified by <tt>name</tt> (see <tt>expire_fragment</tt> for acceptable formats) 
    354363      def read_fragment(name, options = nil) 
    355364        return unless perform_caching 
    356365 
    …… 
    367376      #     %r{pages/\d*/notes} 
    368377      #   Ensure you do not specify start and finish in the regex (^$) because 
    369378      #   the actual filename matched looks like ./cache/filename/path.cache 
    370       #   Regexp expiration is not supported on caches which can't iterate over 
    371       #   all keys, such as memcached. 
     379      #   Regexp expiration is only supported on caches that can iterate over 
     380      #   all keys (unlike memcached). 
    372381      def expire_fragment(name, options = nil) 
    373382        return unless perform_caching 
    374383