From dea8bf5dc42ea081cce1702e3a7566cbdef50a69 Mon Sep 17 00:00:00 2001 From: Neeraj Singh Date: Wed, 28 Jul 2010 11:22:35 -0400 Subject: editing the documentation regarding :race_condition_ttl and :expires_in option in AS cache --- activesupport/lib/active_support/cache.rb | 45 ++++++++++++++++--------------- 1 file changed, 23 insertions(+), 22 deletions(-) (limited to 'activesupport/lib/active_support/cache.rb') diff --git a/activesupport/lib/active_support/cache.rb b/activesupport/lib/active_support/cache.rb index acf2d2bc85..037cfffae2 100644 --- a/activesupport/lib/active_support/cache.rb +++ b/activesupport/lib/active_support/cache.rb @@ -129,13 +129,6 @@ module ActiveSupport # cache.namespace = lambda { @last_mod_time } # Set the namespace to a variable # @last_mod_time = Time.now # Invalidate the entire cache by changing namespace # - # All caches support auto expiring content after a specified number of seconds. - # To set the cache entry time to live, you can either specify +:expires_in+ as - # an option to the constructor to affect all entries or to the +fetch+ - # or +write+ methods for just one entry. - # - # cache = ActiveSupport::Cache::MemoryStore.new(:expire_in => 5.minutes) - # cache.write(key, value, :expire_in => 1.minute) # Set a lower value for one entry # # Caches can also store values in a compressed format to save space and reduce # time spent sending data. Since there is some overhead, values must be large @@ -211,23 +204,30 @@ module ActiveSupport # Setting :compress will store a large cache entry set by the call # in a compressed format. # - # Setting :expires_in will set an expiration time on the cache - # entry if it is set by call. # - # Setting :race_condition_ttl will invoke logic on entries set with - # an :expires_in option. If an entry is found in the cache that is - # expired and it has been expired for less than the number of seconds specified - # by this option and a block was passed to the method call, then the expiration - # future time of the entry in the cache will be updated to that many seconds - # in the and the block will be evaluated and written to the cache. + # Setting :expires_in will set an expiration time on the cache. All caches + # support auto expiring content after a specified number of seconds. This value can + # be specified as an option to the construction in which call all entries will be + # affected. Or it can be supplied to the +fetch+ or +write+ method for just one entry. + # + # cache = ActiveSupport::Cache::MemoryStore.new(:expire_in => 5.minutes) + # cache.write(key, value, :expire_in => 1.minute) # Set a lower value for one entry + # + # Setting :race_condition_ttl is very useful in situations where a cache entry + # is used very frequently unver heavy load. If a cache expires and due to heavy load + # seven different processes will try to read data natively and then they all will try to + # write to cache. To avoid that case the first process to find an expired cache entry will + # bump the cache expiration time by the value set in :race_condition_ttl. Yes + # this process is extending the time for a stale value by another few seconds. Because + # of extended life of the previous cache, other processes will continue to use slightly + # stale data for a just a big longer. In the meantime that first process will go ahead + # and will write into cache the new value. After that all the processes will start + # getting new value. The key is to keep :race_condition_ttl small. # - # This is very useful in situations where a cache entry is used very frequently - # under heavy load. The first process to find an expired cache entry will then - # become responsible for regenerating that entry while other processes continue - # to use the slightly out of date entry. This can prevent race conditions where - # too many processes are trying to regenerate the entry all at once. If the - # process regenerating the entry errors out, the entry will be regenerated - # after the specified number of seconds. + # If the process regenerating the entry errors out, the entry will be regenerated + # after the specified number of seconds. Also note that the life of stale cache is + # extended only if it expired recently. Otherwise a new value is generated and + # :race_condition_ttl does not play any role. # # # Set all values to expire after one minute. # cache = ActiveSupport::Cache::MemoryCache.new(:expires_in => 1.minute) @@ -252,6 +252,7 @@ module ActiveSupport # # # val_1 => "new value 1" # # val_2 => "original value" + # # sleep 10 # First thread extend the life of cache by another 10 seconds # # cache.fetch("foo") => "new value 1" # # Other options will be handled by the specific cache store implementation. -- cgit v1.2.3