ActiveSupport::Cache refactoring

All Caches

* Add default options to initializer that will be sent to all read, write, fetch, exist?, increment, and decrement
* Add support for the :expires_in option to fetch and write for all caches. Cache entries are stored with the create timestamp and a ttl so that expiration can be handled independently of the implementation.
* Add support for a :namespace option. This can be used to set a global prefix for cache entries.
* Deprecate expand_cache_key on ActiveSupport::Cache and move it to ActionController::Caching and ActionDispatch::Http::Cache since the logic in the method used some Rails specific environment variables and was only used by ActionPack classes. Not very DRY but there didn't seem to be a good shared spot and ActiveSupport really shouldn't be Rails specific.
* Add support for :race_condition_ttl to fetch. This setting can prevent race conditions on fetch calls where several processes try to regenerate a recently expired entry at once.
* Add support for :compress option to fetch and write which will compress any data over a configurable threshold.
* Nil values can now be stored in the cache and are distinct from cache misses for fetch.
* Easier API to create new implementations. Just need to implement the methods read_entry, write_entry, and delete_entry instead of overwriting existing methods.
* Since all cache implementations support storing objects, update the docs to state that ActiveCache::Cache::Store implementations should store objects. Keys, however, must be strings since some implementations require that.
* Increase test coverage.
* Document methods which are provided as convenience but which may not be universally available.

MemoryStore

* MemoryStore can now safely be used as the cache for single server sites.
* Make thread safe so that the default cache implementation used by Rails is thread safe. The overhead is minimal and it is still the fastest store available.
* Provide :size initialization option indicating the maximum size of the cache in memory (defaults to 32Mb).
* Add prune logic that removes the least recently used cache entries to keep the cache size from exceeding the max.
* Deprecated SynchronizedMemoryStore since it isn't needed anymore.

FileStore

* Escape key values so they will work as file names on all file systems, be consistent, and case sensitive
* Use a hash algorithm to segment the cache into sub directories so that a large cache doesn't exceed file system limits.
* FileStore can be slow so implement the LocalCache strategy to cache reads for the duration of a request.
* Add cleanup method to keep the disk from filling up with expired entries.
* Fix increment and decrement to use file system locks so they are consistent between processes.

MemCacheStore

* Support all keys. Previously keys with spaces in them would fail
* Deprecate CompressedMemCacheStore since it isn't needed anymore (use :compress => true)

[#4452 state:committed]

Signed-off-by: Jeremy Kemper <jeremy@bitsweat.net>

6 files changed, 483 insertions, 252 deletions

diff --git a/activesupport/lib/active_support/cache/compressed_mem_cache_store.rb b/activesupport/lib/active_support/cache/compressed_mem_cache_store.rb
index d2370d78c5..7c7d1c4b00 100644
--- a/activesupport/lib/active_support/cache/compressed_mem_cache_store.rb
+++ b/activesupport/lib/active_support/cache/compressed_mem_cache_store.rb
@@ -1,21 +1,12 @@
-require 'active_support/gzip'
-
 module ActiveSupport
   module Cache
     class CompressedMemCacheStore < MemCacheStore
-      def read(name, options = nil)
-        if value = super(name, (options || {}).merge(:raw => true))
-          if raw?(options)
-            value
-          else
-            Marshal.load(ActiveSupport::Gzip.decompress(value))
-          end
-        end
-      end
-
-      def write(name, value, options = nil)
-        value = ActiveSupport::Gzip.compress(Marshal.dump(value)) unless raw?(options)
-        super(name, value, (options || {}).merge(:raw => true))
+      def initialize(*args)
+        ActiveSupport::Deprecation.warn('ActiveSupport::Cache::CompressedMemCacheStore has been deprecated in favor of ActiveSupport::Cache::MemCacheStore(:compress => true).', caller)
+        addresses = args.dup
+        options = addresses.extract_options!
+        args = addresses + [options.merge(:compress => true)]
+        super(*args)
       end
     end
   end
diff --git a/activesupport/lib/active_support/cache/file_store.rb b/activesupport/lib/active_support/cache/file_store.rb
index 7521efe7c5..fc225e77a2 100644
--- a/activesupport/lib/active_support/cache/file_store.rb
+++ b/activesupport/lib/active_support/cache/file_store.rb
@@ -3,73 +3,171 @@ require 'active_support/core_ext/file/atomic'
 module ActiveSupport
   module Cache
     # A cache store implementation which stores everything on the filesystem.
+    #
+    # FileStore implements the Strategy::LocalCache strategy which implements
+    # an in memory cache inside of a block.
     class FileStore < Store
       attr_reader :cache_path
 
-      def initialize(cache_path)
+      DIR_FORMATTER = "%03X"
+      ESCAPE_FILENAME_CHARS = /[^a-z0-9_.-]/i
+      UNESCAPE_FILENAME_CHARS = /%[0-9A-F]{2}/
+
+      def initialize(cache_path, options = nil)
+        super(options)
         @cache_path = cache_path
+        extend Strategy::LocalCache
       end
 
-      # Reads a value from the cache.
-      #
-      # Possible options:
-      # - +:expires_in+ - the number of seconds that this value may stay in
-      #   the cache.
-      def read(name, options = nil)
-        super do
-          file_name = real_file_path(name)
-          expires = expires_in(options)
-
-          if File.exist?(file_name) && (expires <= 0 || Time.now - File.mtime(file_name) < expires)
-            File.open(file_name, 'rb') { |f| Marshal.load(f) }
-          end
+      def clear(options = nil)
+        root_dirs = Dir.entries(cache_path).reject{|f| ['.', '..'].include?(f)}
+        FileUtils.rm_r(root_dirs.collect{|f| File.join(cache_path, f)})
+      end
+
+      def cleanup(options = nil)
+        options = merged_options(options)
+        each_key(options) do |key|
+          entry = read_entry(key, options)
+          delete_entry(key, options) if entry && entry.expired?
         end
       end
 
-      # Writes a value to the cache.
-      def write(name, value, options = nil)
-        super do
-          ensure_cache_path(File.dirname(real_file_path(name)))
-          File.atomic_write(real_file_path(name), cache_path) { |f| Marshal.dump(value, f) }
-          value
+      def increment(name, amount = 1, options = nil)
+        file_name = key_file_path(namespaced_key(name, options))
+        lock_file(file_name) do
+          options = merged_options(options)
+          if num = read(name, options)
+            num = num.to_i + amount
+            write(name, num, options)
+            num
+          else
+            nil
+          end
         end
-      rescue => e
-        logger.error "Couldn't create cache directory: #{name} (#{e.message})" if logger
       end
 
-      def delete(name, options = nil)
-        super do
-          File.delete(real_file_path(name))
+      def decrement(name, amount = 1, options = nil)
+        file_name = key_file_path(namespaced_key(name, options))
+        lock_file(file_name) do
+          options = merged_options(options)
+          if num = read(name, options)
+            num = num.to_i - amount
+            write(name, num, options)
+            num
+          else
+            nil
+          end
         end
-      rescue SystemCallError => e
-        # If there's no cache, then there's nothing to complain about
       end
 
       def delete_matched(matcher, options = nil)
-        super do
-          search_dir(@cache_path) do |f|
-            if f =~ matcher
-              begin
-                File.delete(f)
-              rescue SystemCallError => e
-                # If there's no cache, then there's nothing to complain about
+        options = merged_options(options)
+        instrument(:delete_matched, matcher.inspect) do
+          matcher = key_matcher(matcher, options)
+          search_dir(cache_path) do |path|
+            key = file_path_key(path)
+            delete_entry(key, options) if key.match(matcher)
+          end
+        end
+      end
+
+      protected
+
+        def read_entry(key, options)
+          file_name = key_file_path(key)
+          if File.exist?(file_name)
+            entry = File.open(file_name) { |f| Marshal.load(f) }
+            if entry && !entry.expired? && !entry.expires_in && !self.options[:expires_in]
+              # Check for deprecated use of +:expires_in+ option from versions < 3.0
+              deprecated_expires_in = options[:expires_in]
+              if deprecated_expires_in
+                ActiveSupport::Deprecation.warn('Setting :expires_in on read has been deprecated in favor of setting it on write.', caller)
+                if entry.created_at + deprecated_expires_in.to_f <= Time.now.to_f
+                  delete_entry(key, options)
+                  entry = nil
+                end
               end
             end
+            entry
           end
+        rescue
+          nil
         end
-      end
 
-      def exist?(name, options = nil)
-        super do
-          File.exist?(real_file_path(name))
+        def write_entry(key, entry, options)
+          file_name = key_file_path(key)
+          ensure_cache_path(File.dirname(file_name))
+          File.atomic_write(file_name, cache_path) {|f| Marshal.dump(entry, f)}
+          true
+        end
+
+        def delete_entry(key, options)
+          file_name = key_file_path(key)
+          if File.exist?(file_name)
+            begin
+              File.delete(file_name)
+              delete_empty_directories(File.dirname(file_name))
+              true
+            rescue => e
+              # Just in case the error was caused by another process deleting the file first.
+              raise e if File.exist?(file_name)
+              false
+            end
+          end
         end
-      end
 
       private
-        def real_file_path(name)
-          '%s/%s.cache' % [@cache_path, name.gsub('?', '.').gsub(':', '.')]
+        # Lock a file for a block so only one process can modify it at a time.
+        def lock_file(file_name, &block) # :nodoc:
+          if File.exist?(file_name)
+            File.open(file_name, 'r') do |f|
+              begin
+                f.flock File::LOCK_EX
+                yield
+              ensure
+                f.flock File::LOCK_UN
+              end
+            end
+          else
+            yield
+          end
+        end
+
+        # Translate a key into a file path.
+        def key_file_path(key)
+          fname = key.to_s.gsub(ESCAPE_FILENAME_CHARS){|match| "%#{match.ord.to_s(16).upcase}"}
+          hash = Zlib.adler32(fname)
+          hash, dir_1 = hash.divmod(0x1000)
+          dir_2 = hash.modulo(0x1000)
+          fname_paths = []
+          # Make sure file name is < 255 characters so it doesn't exceed file system limits.
+          if fname.size <= 255
+            fname_paths << fname
+          else
+            while fname.size <= 255
+              fname_path << fname[0, 255]
+              fname = fname[255, -1]
+            end
+          end
+          File.join(cache_path, DIR_FORMATTER % dir_1, DIR_FORMATTER % dir_2, *fname_paths)
+        end
+
+        # Translate a file path into a key.
+        def file_path_key(path)
+          fname = path[cache_path.size, path.size].split(File::SEPARATOR, 4).last
+          fname.gsub(UNESCAPE_FILENAME_CHARS){|match| $1.ord.to_s(16)}
+        end
+
+        # Delete empty directories in the cache.
+        def delete_empty_directories(dir)
+          return if dir == cache_path
+          if Dir.entries(dir).reject{|f| ['.', '..'].include?(f)}.empty?
+            File.delete(dir) rescue nil
+            delete_empty_directories(File.dirname(dir))
+          end
         end
 
+        # Make sure a file path's directories exist.
         def ensure_cache_path(path)
           FileUtils.makedirs(path) unless File.exist?(path)
         end
diff --git a/activesupport/lib/active_support/cache/mem_cache_store.rb b/activesupport/lib/active_support/cache/mem_cache_store.rb
index c56fedc12e..d8377a208f 100644
--- a/activesupport/lib/active_support/cache/mem_cache_store.rb
+++ b/activesupport/lib/active_support/cache/mem_cache_store.rb
@@ -1,5 +1,5 @@
 require 'memcache'
-require 'active_support/core_ext/array/extract_options'
+require 'digest/md5'
 
 module ActiveSupport
   module Cache
@@ -13,8 +13,9 @@ module ActiveSupport
     #   and MemCacheStore will load balance between all available servers. If a
     #   server goes down, then MemCacheStore will ignore it until it goes back
     #   online.
-    # - Time-based expiry support. See #write and the <tt>:expires_in</tt> option.
-    # - Per-request in memory cache for all communication with the MemCache server(s).
+    #
+    # MemCacheStore implements the Strategy::LocalCache strategy which implements
+    # an in memory cache inside of a block.
     class MemCacheStore < Store
       module Response # :nodoc:
         STORED      = "STORED\r\n"
@@ -24,6 +25,8 @@ module ActiveSupport
         DELETED     = "DELETED\r\n"
       end
 
+      ESCAPE_KEY_CHARS = /[\x00-\x20%\x7F-\xFF]/
+
       def self.build_mem_cache(*addresses)
         addresses = addresses.flatten
         options = addresses.extract_options!
@@ -45,108 +48,139 @@ module ActiveSupport
       #   require 'memcached' # gem install memcached; uses C bindings to libmemcached
       #   ActiveSupport::Cache::MemCacheStore.new(Memcached::Rails.new("localhost:11211"))
       def initialize(*addresses)
+        addresses = addresses.flatten
+        options = addresses.extract_options!
+        super(options)
+
         if addresses.first.respond_to?(:get)
           @data = addresses.first
         else
-          @data = self.class.build_mem_cache(*addresses)
+          mem_cache_options = options.dup
+          UNIVERSAL_OPTIONS.each{|name| mem_cache_options.delete(name)}
+          @data = self.class.build_mem_cache(*(addresses + [mem_cache_options]))
         end
 
         extend Strategy::LocalCache
+        extend LocalCacheWithRaw
       end
 
-      # Reads multiple keys from the cache.
-      def read_multi(*keys)
-        @data.get_multi keys
-      end
-
-      def read(key, options = nil) # :nodoc:
-        super do
-          @data.get(key, raw?(options))
-        end
-      rescue MemCache::MemCacheError => e
-        logger.error("MemCacheError (#{e}): #{e.message}") if logger
-        nil
-      end
-
-      # Writes a value to the cache.
-      #
-      # Possible options:
-      # - <tt>:unless_exist</tt> - set to true if you don't want to update the cache
-      #   if the key is already set.
-      # - <tt>:expires_in</tt> - the number of seconds that this value may stay in
-      #   the cache. See ActiveSupport::Cache::Store#write for an example.
-      def write(key, value, options = nil)
-        super do
-          method = options && options[:unless_exist] ? :add : :set
-          # memcache-client will break the connection if you send it an integer
-          # in raw mode, so we convert it to a string to be sure it continues working.
-          value = value.to_s if raw?(options)
-          response = @data.send(method, key, value, expires_in(options), raw?(options))
-          response == Response::STORED
-        end
-      rescue MemCache::MemCacheError => e
-        logger.error("MemCacheError (#{e}): #{e.message}") if logger
-        false
-      end
-
-      def delete(key, options = nil) # :nodoc:
-        super do
-          response = @data.delete(key)
-          response == Response::DELETED
-        end
-      rescue MemCache::MemCacheError => e
-        logger.error("MemCacheError (#{e}): #{e.message}") if logger
-        false
-      end
-
-      def exist?(key, options = nil) # :nodoc:
-        # Doesn't call super, cause exist? in memcache is in fact a read
-        # But who cares? Reading is very fast anyway
-        # Local cache is checked first, if it doesn't know then memcache itself is read from
-        super do
-          !read(key, options).nil?
+      # Reads multiple keys from the cache using a single call to the
+      # servers for all keys. Options can be passed in the last argument.
+      def read_multi(*names)
+        options = names.extract_options!
+        options = merged_options(options)
+        keys_to_names = names.inject({}){|map, name| map[escape_key(namespaced_key(name, options))] = name; map}
+        raw_values = @data.get_multi(keys_to_names.keys, :raw => true)
+        values = {}
+        raw_values.each do |key, value|
+          entry = deserialize_entry(value)
+          values[keys_to_names[key]] = entry.value unless entry.expired?
         end
+        values
       end
 
-      def increment(key, amount = 1) # :nodoc:
-        response = instrument(:increment, key, :amount => amount) do
-          @data.incr(key, amount)
+      # Increment a cached value. This method uses the memcached incr atomic
+      # operator and can only be used on values written with the :raw option.
+      # Calling it on a value not stored with :raw will initialize that value
+      # to zero.
+      def increment(name, amount = 1, options = nil) # :nodoc:
+        options = merged_options(options)
+        response = instrument(:increment, name, :amount => amount) do
+          @data.incr(escape_key(namespaced_key(name, options)), amount)
         end
-
-        response == Response::NOT_FOUND ? nil : response
+        response == Response::NOT_FOUND ? nil : response.to_i
       rescue MemCache::MemCacheError
         nil
       end
 
-      def decrement(key, amount = 1) # :nodoc:
-        response = instrument(:decrement, key, :amount => amount) do
-          @data.decr(key, amount)
+      # Decrement a cached value. This method uses the memcached decr atomic
+      # operator and can only be used on values written with the :raw option.
+      # Calling it on a value not stored with :raw will initialize that value
+      # to zero.
+      def decrement(name, amount = 1, options = nil) # :nodoc:
+        options = merged_options(options)
+        response = instrument(:decrement, name, :amount => amount) do
+          @data.decr(escape_key(namespaced_key(name, options)), amount)
         end
-
-        response == Response::NOT_FOUND ? nil : response
+        response == Response::NOT_FOUND ? nil : response.to_i
       rescue MemCache::MemCacheError
         nil
       end
 
-      def delete_matched(matcher, options = nil) # :nodoc:
-        # don't do any local caching at present, just pass
-        # through and let the error happen
-        super
-        raise "Not supported by Memcache"
-      end
-
-      def clear
+      # Clear the entire cache on all memcached servers. This method should
+      # be used with care when using a shared cache.
+      def clear(options = nil)
         @data.flush_all
       end
 
+      # Get the statistics from the memcached servers.
       def stats
         @data.stats
       end
 
+      protected
+        # Read an entry from the cache.
+        def read_entry(key, options) # :nodoc:
+          deserialize_entry(@data.get(escape_key(key), true))
+        rescue MemCache::MemCacheError => e
+          logger.error("MemCacheError (#{e}): #{e.message}") if logger
+          nil
+        end
+
+        # Write an entry to the cache.
+        def write_entry(key, entry, options) # :nodoc:
+          method = options && options[:unless_exist] ? :add : :set
+          value = options[:raw] ? entry.value.to_s : entry
+          expires_in = options[:expires_in].to_i
+          if expires_in > 0 && !options[:raw]
+            # Set the memcache expire a few minutes in the future to support race condition ttls on read
+            expires_in += 5.minutes
+          end
+          response = @data.send(method, escape_key(key), value, expires_in, options[:raw])
+          response == Response::STORED
+        rescue MemCache::MemCacheError => e
+          logger.error("MemCacheError (#{e}): #{e.message}") if logger
+          false
+        end
+
+        # Delete an entry from the cache.
+        def delete_entry(key, options) # :nodoc:
+          response = @data.delete(escape_key(key))
+          response == Response::DELETED
+        rescue MemCache::MemCacheError => e
+          logger.error("MemCacheError (#{e}): #{e.message}") if logger
+          false
+        end
+
       private
-        def raw?(options)
-          options && options[:raw]
+        def escape_key(key)
+          key = key.to_s.gsub(ESCAPE_KEY_CHARS){|match| "%#{match[0].to_s(16).upcase}"}
+          key = "#{key[0, 213]}:md5:#{Digest::MD5.hexdigest(key)}" if key.size > 250
+          key
         end
+
+        def deserialize_entry(raw_value)
+          if raw_value
+            entry = Marshal.load(raw_value) rescue raw_value
+            entry.is_a?(Entry) ? entry : Entry.new(entry)
+          else
+            nil
+          end
+        end
+
+      # Provide support for raw values in the local cache strategy.
+      module LocalCacheWithRaw # :nodoc:
+        protected
+          def write_entry(key, entry, options) # :nodoc:
+            retval = super
+            if options[:raw] && local_cache && retval
+              raw_entry = Entry.new(entry.value.to_s)
+              raw_entry.expires_at = entry.expires_at
+              local_cache.write_entry(key, raw_entry, options)
+            end
+            retval
+          end
+      end
     end
   end
 end
diff --git a/activesupport/lib/active_support/cache/memory_store.rb b/activesupport/lib/active_support/cache/memory_store.rb
index 379922f986..b1d14a0d8f 100644
--- a/activesupport/lib/active_support/cache/memory_store.rb
+++ b/activesupport/lib/active_support/cache/memory_store.rb
@@ -1,4 +1,4 @@
-require 'active_support/core_ext/object/duplicable'
+require 'monitor'
 
 module ActiveSupport
   module Cache
@@ -6,60 +6,154 @@ module ActiveSupport
     # same process. If you're running multiple Ruby on Rails server processes
     # (which is the case if you're using mongrel_cluster or Phusion Passenger),
     # then this means that your Rails server process instances won't be able
-    # to share cache data with each other. If your application never performs
-    # manual cache item expiry (e.g. when you're using generational cache keys),
-    # then using MemoryStore is ok. Otherwise, consider carefully whether you
-    # should be using this cache store.
+    # to share cache data with each other and this may not be the most
+    # appropriate cache for you.
     #
-    # MemoryStore is not only able to store strings, but also arbitrary Ruby
-    # objects.
+    # This cache has a bounded size specified by the :size options to the
+    # initializer (default is 32Mb). When the cache exceeds the alotted size,
+    # a cleanup will occur which tries to prune the cache down to three quarters
+    # of the maximum size by removing the least recently used entries.
     #
-    # MemoryStore is not thread-safe. Use SynchronizedMemoryStore instead
-    # if you need thread-safety.
+    # MemoryStore is thread-safe.
     class MemoryStore < Store
-      def initialize
+      def initialize(options = nil)
+        options ||= {}
+        super(options)
         @data = {}
+        @key_access = {}
+        @max_size = options[:size] || 32.megabytes
+        @max_prune_time = options[:max_prune_time] || 2
+        @cache_size = 0
+        @monitor = Monitor.new
+        @pruning = false
       end
 
-      def read_multi(*names)
-        results = {}
-        names.each { |n| results[n] = read(n) }
-        results
+      def clear(options = nil)
+        synchronize do
+          @data.clear
+          @key_access.clear
+          @cache_size = 0
+        end
       end
 
-      def read(name, options = nil)
-        super do
-          @data[name]
+      def cleanup(options = nil)
+        options = merged_options(options)
+        instrument(:cleanup, :size => @data.size) do
+          keys = synchronize{ @data.keys }
+          keys.each do |key|
+            entry = @data[key]
+            delete_entry(key, options) if entry && entry.expired?
+          end
         end
       end
 
-      def write(name, value, options = nil)
-        super do
-          @data[name] = (value.duplicable? ? value.dup : value).freeze
+      # Prune the cache down so the entries fit within the specified memory size by removing
+      # the least recently accessed entries.
+      def prune(target_size, max_time = nil)
+        return if pruning?
+        @pruning = true
+        begin
+          start_time = Time.now
+          cleanup
+          instrument(:prune, target_size, :from => @cache_size) do
+            keys = synchronize{ @key_access.keys.sort{|a,b| @key_access[a].to_f <=> @key_access[b].to_f} }
+            keys.each do |key|
+              delete_entry(key, options)
+              return if @cache_size <= target_size || (max_time && Time.now - start_time > max_time)
+            end
+          end
+        ensure
+          @pruning = false
         end
       end
 
-      def delete(name, options = nil)
-        super do
-          @data.delete(name)
+      # Return true if the cache is currently be pruned to remove older entries.
+      def pruning?
+        @pruning
+      end
+
+      # Increment an integer value in the cache.
+      def increment(name, amount = 1, options = nil)
+        synchronize do
+          options = merged_options(options)
+          if num = read(name, options)
+            num = num.to_i + amount
+            write(name, num, options)
+            num
+          else
+            nil
+          end
         end
       end
 
-      def delete_matched(matcher, options = nil)
-        super do
-          @data.delete_if { |k,v| k =~ matcher }
+      # Decrement an integer value in the cache.
+      def decrement(name, amount = 1, options = nil)
+        synchronize do
+          options = merged_options(options)
+          if num = read(name, options)
+            num = num.to_i - amount
+            write(name, num, options)
+            num
+          else
+            nil
+          end
         end
       end
 
-      def exist?(name, options = nil)
-        super do
-          @data.has_key?(name)
+      def delete_matched(matcher, options = nil)
+        options = merged_options(options)
+        instrument(:delete_matched, matcher.inspect) do
+          matcher = key_matcher(matcher, options)
+          keys = synchronize { @data.keys }
+          keys.each do |key|
+            delete_entry(key, options) if key.match(matcher)
+          end
         end
       end
 
-      def clear
-        @data.clear
+      def inspect # :nodoc:
+        "<##{self.class.name} entries=#{@data.size}, size=#{@cache_size}, options=#{@options.inspect}>"
+      end
+
+      # Synchronize calls to the cache. This should be called wherever the underlying cache implementation
+      # is not thread safe.
+      def synchronize(&block) # :nodoc:
+        @monitor.synchronize(&block)
       end
+
+      protected
+        def read_entry(key, options) # :nodoc:
+          entry = @data[key]
+          synchronize do
+            if entry
+              @key_access[key] = Time.now.to_f
+            else
+              @key_access.delete(key)
+            end
+          end
+          entry
+        end
+
+        def write_entry(key, entry, options) # :nodoc:
+          synchronize do
+            old_entry = @data[key]
+            @cache_size -= old_entry.size if old_entry
+            @cache_size += entry.size
+            @key_access[key] = Time.now.to_f
+            @data[key] = entry
+            prune(@max_size * 0.75, @max_prune_time) if @cache_size > @max_size
+            true
+          end
+        end
+
+        def delete_entry(key, options) # :nodoc:
+          synchronize do
+            @key_access.delete(key)
+            entry = @data.delete(key)
+            @cache_size -= entry.size if entry
+            !!entry
+          end
+        end
     end
   end
 end
diff --git a/activesupport/lib/active_support/cache/strategy/local_cache.rb b/activesupport/lib/active_support/cache/strategy/local_cache.rb
index bbbd643736..8942587ac8 100644
--- a/activesupport/lib/active_support/cache/strategy/local_cache.rb
+++ b/activesupport/lib/active_support/cache/strategy/local_cache.rb
@@ -4,17 +4,54 @@ require 'active_support/core_ext/string/inflections'
 module ActiveSupport
   module Cache
     module Strategy
+      # Caches that implement LocalCache will be backed by an in memory cache for the
+      # duration of a block. Repeated calls to the cache for the same key will hit the
+      # in memory cache for faster access.
       module LocalCache
-        # this allows caching of the fact that there is nothing in the remote cache
-        NULL = 'remote_cache_store:null'
+        # Simple memory backed cache. This cache is not thread safe but is intended only
+        # for serving as a temporary memory cache for a single thread.
+        class LocalStore < Store
+          def initialize
+            super
+            @data = {}
+          end
+
+          # Since it isn't thread safe, don't allow synchronizing.
+          def synchronize # :nodoc:
+            yield
+          end
+
+          def clear(options = nil)
+            @data.clear
+          end
+
+          def read_entry(key, options)
+            @data[key]
+          end
 
+          def write_entry(key, value, options)
+            @data[key] = value
+            true
+          end
+
+          def delete_entry(key, options)
+            !!@data.delete(key)
+          end
+        end
+
+        # Use a local cache to front for the cache for the duration of a block.
         def with_local_cache
-          Thread.current[thread_local_key] = MemoryStore.new
-          yield
-        ensure
-          Thread.current[thread_local_key] = nil
+          save_val = Thread.current[thread_local_key]
+          begin
+            Thread.current[thread_local_key] = LocalStore.new
+            yield
+          ensure
+            Thread.current[thread_local_key] = save_val
+          end
         end
 
+        # Middleware class can be inserted as a Rack handler to use a local cache for the
+        # duration of a request.
         def middleware
           @middleware ||= begin
             klass = Class.new
@@ -24,7 +61,7 @@ module ActiveSupport
               end
 
               def call(env)
-                Thread.current[:#{thread_local_key}] = MemoryStore.new
+                Thread.current[:#{thread_local_key}] = LocalStore.new
                 @app.call(env)
               ensure
                 Thread.current[:#{thread_local_key}] = nil
@@ -39,73 +76,86 @@ module ActiveSupport
           end
         end
 
-        def read(key, options = nil)
-          value = local_cache && local_cache.read(key)
-          if value == NULL
-            nil
-          elsif value.nil?
-            value = super
-            local_cache.mute { local_cache.write(key, value || NULL) } if local_cache
-            value.duplicable? ? value.dup : value
-          else
-            # forcing the value to be immutable
-            value.duplicable? ? value.dup : value
-          end
-        end
-
-        def write(key, value, options = nil)
-          value = value.to_s if respond_to?(:raw?) && raw?(options)
-          local_cache.mute { local_cache.write(key, value || NULL) } if local_cache
+        def clear(options = nil) # :nodoc:
+          local_cache.clear(options) if local_cache
           super
         end
 
-        def delete(key, options = nil)
-          local_cache.mute { local_cache.write(key, NULL) } if local_cache
+        def cleanup(options = nil) # :nodoc:
+          local_cache.clear(options) if local_cache
           super
         end
 
-        def exist(key, options = nil)
-          value = local_cache.read(key) if local_cache
-          if value == NULL
-            false
-          elsif value
-            true
-          else
-            super
+        def increment(name, amount = 1, options = nil) # :nodoc:
+          value = bypass_local_cache{super}
+          if local_cache
+            local_cache.mute do
+              if value
+                local_cache.write(name, value, options)
+              else
+                local_cache.delete(name, options)
+              end
+            end
           end
+          value
         end
 
-        def increment(key, amount = 1)
-          if value = super
-            local_cache.mute { local_cache.write(key, value.to_s) } if local_cache
-            value
-          else
-            nil
+        def decrement(name, amount = 1, options = nil) # :nodoc:
+          value = bypass_local_cache{super}
+          if local_cache
+            local_cache.mute do
+              if value
+                local_cache.write(name, value, options)
+              else
+                local_cache.delete(name, options)
+              end
+            end
           end
+          value
         end
 
-        def decrement(key, amount = 1)
-          if value = super
-            local_cache.mute { local_cache.write(key, value.to_s) } if local_cache
-            value
-          else
-            nil
+        protected
+          def read_entry(key, options) # :nodoc:
+            if local_cache
+              entry = local_cache.read_entry(key, options)
+              unless entry
+                entry = super
+                local_cache.write_entry(key, entry, options)
+              end
+              entry
+            else
+              super
+            end
           end
-        end
 
-        def clear
-          local_cache.clear if local_cache
-          super
-        end
+          def write_entry(key, entry, options) # :nodoc:
+            local_cache.write_entry(key, entry, options) if local_cache
+            super
+          end
+
+          def delete_entry(key, options) # :nodoc:
+            local_cache.delete_entry(key, options) if local_cache
+            super
+          end
 
         private
           def thread_local_key
-            @thread_local_key ||= "#{self.class.name.underscore}_local_cache".gsub("/", "_").to_sym
+            @thread_local_key ||= "#{self.class.name.underscore}_local_cache_#{self.object_id}".gsub("/", "_").to_sym
           end
 
           def local_cache
             Thread.current[thread_local_key]
           end
+
+          def bypass_local_cache
+            save_cache = Thread.current[thread_local_key]
+            begin
+              Thread.current[thread_local_key] = nil
+              yield
+            ensure
+              Thread.current[thread_local_key] = save_cache
+            end
+          end
       end
     end
   end
diff --git a/activesupport/lib/active_support/cache/synchronized_memory_store.rb b/activesupport/lib/active_support/cache/synchronized_memory_store.rb
index ea03a119c6..37caa6b6f1 100644
--- a/activesupport/lib/active_support/cache/synchronized_memory_store.rb
+++ b/activesupport/lib/active_support/cache/synchronized_memory_store.rb
@@ -2,45 +2,9 @@ module ActiveSupport
   module Cache
     # Like MemoryStore, but thread-safe.
     class SynchronizedMemoryStore < MemoryStore
-      def initialize
+      def initialize(*args)
+        ActiveSupport::Deprecation.warn('ActiveSupport::Cache::SynchronizedMemoryStore has been deprecated in favor of ActiveSupport::Cache::MemoryStore.', caller)
         super
-        @guard = Monitor.new
-      end
-
-      def fetch(key, options = {})
-        @guard.synchronize { super }
-      end
-
-      def read(name, options = nil)
-        @guard.synchronize { super }
-      end
-
-      def write(name, value, options = nil)
-        @guard.synchronize { super }
-      end
-
-      def delete(name, options = nil)
-        @guard.synchronize { super }
-      end
-
-      def delete_matched(matcher, options = nil)
-        @guard.synchronize { super }
-      end
-
-      def exist?(name,options = nil)
-        @guard.synchronize { super }
-      end
-
-      def increment(key, amount = 1)
-        @guard.synchronize { super }
-      end
-
-      def decrement(key, amount = 1)
-        @guard.synchronize { super }
-      end
-
-      def clear
-        @guard.synchronize { super }
       end
     end
   end