cache.rb in activesupport-5.0.0.beta4

- old
+ new

@@ -156,24 +156,24 @@
       cattr_accessor :logger, :instance_writer => true
 
       attr_reader :silence, :options
       alias :silence? :silence
 
-      # Create a new cache. The options will be passed to any write method calls
+      # Creates a new cache. The options will be passed to any write method calls
       # except for <tt>:namespace</tt> which can be used to set the global
       # namespace for the cache.
       def initialize(options = nil)
         @options = options ? options.dup : {}
       end
 
-      # Silence the logger.
+      # Silences the logger.
       def silence!
         @silence = true
         self
       end
 
-      # Silence the logger within a block.
+      # Silences the logger within a block.
       def mute
         previous_silence, @silence = defined?(@silence) && @silence, true
         yield
       ensure
         @silence = previous_silence
@@ -196,15 +196,22 @@
       #     'Duckburgh'
       #   end
       #   cache.fetch('city')   # => "Duckburgh"
       #
       # You may also specify additional options via the +options+ argument.
-      # Setting <tt>force: true</tt> will force a cache miss:
+      # Setting <tt>force: true</tt> forces a cache "miss," meaning we treat
+      # the cache value as missing even if it's present. Passing a block is
+      # required when `force` is true so this always results in a cache write.
       #
       #   cache.write('today', 'Monday')
-      #   cache.fetch('today', force: true)  # => nil
+      #   cache.fetch('today', force: true) { 'Tuesday' } # => 'Tuesday'
+      #   cache.fetch('today', force: true) # => ArgumentError
       #
+      # The `:force` option is useful when you're calling some other method to
+      # ask whether you should force a cache write. Otherwise, it's clearer to
+      # just call `Cache#write`.
+      #
       # Setting <tt>:compress</tt> will store a large cache entry set by the call
       # in a compressed format.
       #
       # Setting <tt>:expires_in</tt> will set an expiration time on the cache.
       # All caches support auto-expiring content after a specified number of
@@ -290,10 +297,12 @@
           if entry
             get_entry_value(entry, name, options)
           else
             save_block_result_to_cache(name, options) { |_name| yield _name }
           end
+        elsif options && options[:force]
+          raise ArgumentError, 'Missing block: Calling `Cache#fetch` with `force: true` requires a block.'
         else
           read(name, options)
         end
       end
 
@@ -321,11 +330,11 @@
             nil
           end
         end
       end
 
-      # Read multiple values at once from the cache. Options can be passed
+      # Reads multiple values at once from the cache. Options can be passed
       # in the last argument.
       #
       # Some cache implementation may optimize this method.
       #
       # Returns a hash mapping the names provided to the values found.
@@ -411,58 +420,58 @@
           entry = read_entry(normalize_key(name, options), options)
           (entry && !entry.expired?) || false
         end
       end
 
-      # Delete all entries with keys matching the pattern.
+      # Deletes all entries with keys matching the pattern.
       #
       # Options are passed to the underlying cache implementation.
       #
       # All implementations may not support this method.
       def delete_matched(matcher, options = nil)
         raise NotImplementedError.new("#{self.class.name} does not support delete_matched")
       end
 
-      # Increment an integer value in the cache.
+      # Increments an integer value in the cache.
       #
       # Options are passed to the underlying cache implementation.
       #
       # All implementations may not support this method.
       def increment(name, amount = 1, options = nil)
         raise NotImplementedError.new("#{self.class.name} does not support increment")
       end
 
-      # Decrement an integer value in the cache.
+      # Decrements an integer value in the cache.
       #
       # Options are passed to the underlying cache implementation.
       #
       # All implementations may not support this method.
       def decrement(name, amount = 1, options = nil)
         raise NotImplementedError.new("#{self.class.name} does not support decrement")
       end
 
-      # Cleanup the cache by removing expired entries.
+      # Cleanups the cache by removing expired entries.
       #
       # Options are passed to the underlying cache implementation.
       #
       # All implementations may not support this method.
       def cleanup(options = nil)
         raise NotImplementedError.new("#{self.class.name} does not support cleanup")
       end
 
-      # Clear the entire cache. Be careful with this method since it could
+      # Clears the entire cache. Be careful with this method since it could
       # affect other processes if shared cache is being used.
       #
       # The options hash is passed to the underlying cache implementation.
       #
       # All implementations may not support this method.
       def clear(options = nil)
         raise NotImplementedError.new("#{self.class.name} does not support clear")
       end
 
       protected
-        # Add the namespace defined in the options to a pattern designed to
+        # Adds the namespace defined in the options to a pattern designed to
         # match keys. Implementations that support delete_matched should call
         # this method to translate a pattern that matches names into one that
         # matches namespaced keys.
         def key_matcher(pattern, options)
           prefix = options[:namespace].is_a?(Proc) ? options[:namespace].call : options[:namespace]
@@ -477,39 +486,39 @@
           else
             pattern
           end
         end
 
-        # Read an entry from the cache implementation. Subclasses must implement
+        # Reads an entry from the cache implementation. Subclasses must implement
         # this method.
         def read_entry(key, options) # :nodoc:
           raise NotImplementedError.new
         end
 
-        # Write an entry to the cache implementation. Subclasses must implement
+        # Writes an entry to the cache implementation. Subclasses must implement
         # this method.
         def write_entry(key, entry, options) # :nodoc:
           raise NotImplementedError.new
         end
 
-        # Delete an entry from the cache implementation. Subclasses must
+        # Deletes an entry from the cache implementation. Subclasses must
         # implement this method.
         def delete_entry(key, options) # :nodoc:
           raise NotImplementedError.new
         end
 
       private
-        # Merge the default options with ones specific to a method call.
+        # Merges the default options with ones specific to a method call.
         def merged_options(call_options) # :nodoc:
           if call_options
             options.merge(call_options)
           else
             options.dup
           end
         end
 
-        # Expand key to be a consistent string value. Invoke +cache_key+ if
+        # Expands key to be a consistent string value. Invokes +cache_key+ if
         # object responds to +cache_key+. Otherwise, +to_param+ method will be
         # called. If the key is a Hash, then keys will be sorted alphabetically.
         def expanded_key(key) # :nodoc:
           return key.cache_key.to_s if key.respond_to?(:cache_key)
 
@@ -525,11 +534,11 @@
           end
 
           key.to_param
         end
 
-        # Prefix a key with the namespace. Namespace and key will be delimited
+        # Prefixes a key with the namespace. Namespace and key will be delimited
         # with a colon.
         def normalize_key(key, options)
           key = expanded_key(key)
           namespace = options[:namespace] if options
           prefix = namespace.is_a?(Proc) ? namespace.call : namespace
@@ -573,16 +582,16 @@
           end
           entry
         end
 
         def get_entry_value(entry, name, options)
-          instrument(:fetch_hit, name, options) { |payload| }
+          instrument(:fetch_hit, name, options) { }
           entry.value
         end
 
         def save_block_result_to_cache(name, options)
-          result = instrument(:generate, name, options) do |payload|
+          result = instrument(:generate, name, options) do
             yield(name)
           end
 
           write(name, result, options)
           result
@@ -596,11 +605,11 @@
     # Since cache entries in most instances will be serialized, the internals of this class are highly optimized
     # using short instance variable names that are lazily defined.
     class Entry # :nodoc:
       DEFAULT_COMPRESS_LIMIT = 16.kilobytes
 
-      # Create a new cache entry for the specified value. Options supported are
+      # Creates a new cache entry for the specified value. Options supported are
       # +:compress+, +:compress_threshold+, and +:expires_in+.
       def initialize(value, options = {})
         if should_compress?(value, options)
           @value = compress(value)
           @compressed = true
@@ -615,11 +624,11 @@
 
       def value
         compressed? ? uncompress(@value) : @value
       end
 
-      # Check if the entry is expired. The +expires_in+ parameter can override
+      # Checks if the entry is expired. The +expires_in+ parameter can override
       # the value set when the entry was created.
       def expired?
         @expires_in && @created_at + @expires_in <= Time.now.to_f
       end
 
@@ -650,10 +659,10 @@
             @s = Marshal.dump(@value).bytesize
           end
         end
       end
 
-      # Duplicate the value in a class. This is used by cache implementations that don't natively
+      # Duplicates the value in a class. This is used by cache implementations that don't natively
       # serialize entries to protect against accidental cache modifications.
       def dup_value!
         if @value && !compressed? && !(@value.is_a?(Numeric) || @value == true || @value == false)
           if @value.is_a?(String)
             @value = @value.dup