vendor/rails/activesupport/lib/active_support/cache.rb

   1 require 'benchmark'
   2
   3 module ActiveSupport
   4   # See ActiveSupport::Cache::Store for documentation.
   5   module Cache
   6     autoload :FileStore, 'active_support/cache/file_store'
   7     autoload :MemoryStore, 'active_support/cache/memory_store'
   8     autoload :SynchronizedMemoryStore, 'active_support/cache/synchronized_memory_store'
   9     autoload :DRbStore, 'active_support/cache/drb_store'
  10     autoload :MemCacheStore, 'active_support/cache/mem_cache_store'
  11     autoload :CompressedMemCacheStore, 'active_support/cache/compressed_mem_cache_store'
  12
  13     module Strategy
  14       autoload :LocalCache, 'active_support/cache/strategy/local_cache'
  15     end
  16
  17     # Creates a new CacheStore object according to the given options.
  18     #
  19     # If no arguments are passed to this method, then a new
  20     # ActiveSupport::Cache::MemoryStore object will be returned.
  21     #
  22     # If you pass a Symbol as the first argument, then a corresponding cache
  23     # store class under the ActiveSupport::Cache namespace will be created.
  24     # For example:
  25     #
  26     #   ActiveSupport::Cache.lookup_store(:memory_store)
  27     #   # => returns a new ActiveSupport::Cache::MemoryStore object
  28     #
  29     #   ActiveSupport::Cache.lookup_store(:drb_store)
  30     #   # => returns a new ActiveSupport::Cache::DRbStore object
  31     #
  32     # Any additional arguments will be passed to the corresponding cache store
  33     # class's constructor:
  34     #
  35     #   ActiveSupport::Cache.lookup_store(:file_store, "/tmp/cache")
  36     #   # => same as: ActiveSupport::Cache::FileStore.new("/tmp/cache")
  37     #
  38     # If the first argument is not a Symbol, then it will simply be returned:
  39     #
  40     #   ActiveSupport::Cache.lookup_store(MyOwnCacheStore.new)
  41     #   # => returns MyOwnCacheStore.new
  42     def self.lookup_store(*store_option)
  43       store, *parameters = *([ store_option ].flatten)
  44
  45       case store
  46       when Symbol
  47         store_class_name = (store == :drb_store ? "DRbStore" : store.to_s.camelize)
  48         store_class = ActiveSupport::Cache.const_get(store_class_name)
  49         store_class.new(*parameters)
  50       when nil
  51         ActiveSupport::Cache::MemoryStore.new
  52       else
  53         store
  54       end
  55     end
  56
  57     def self.expand_cache_key(key, namespace = nil)
  58       expanded_cache_key = namespace ? "#{namespace}/" : ""
  59
  60       if ENV["RAILS_CACHE_ID"] || ENV["RAILS_APP_VERSION"]
  61         expanded_cache_key << "#{ENV["RAILS_CACHE_ID"] || ENV["RAILS_APP_VERSION"]}/"
  62       end
  63
  64       expanded_cache_key << case
  65         when key.respond_to?(:cache_key)
  66           key.cache_key
  67         when key.is_a?(Array)
  68           key.collect { |element| expand_cache_key(element) }.to_param
  69         when key
  70           key.to_param
  71         end.to_s
  72
  73       expanded_cache_key
  74     end
  75
  76     # An abstract cache store class. There are multiple cache store
  77     # implementations, each having its own additional features. See the classes
  78     # under the ActiveSupport::Cache module, e.g.
  79     # ActiveSupport::Cache::MemCacheStore. MemCacheStore is currently the most
  80     # popular cache store for large production websites.
  81     #
  82     # ActiveSupport::Cache::Store is meant for caching strings. Some cache
  83     # store implementations, like MemoryStore, are able to cache arbitrary
  84     # Ruby objects, but don't count on every cache store to be able to do that.
  85     #
  86     #   cache = ActiveSupport::Cache::MemoryStore.new
  87     #
  88     #   cache.read("city")   # => nil
  89     #   cache.write("city", "Duckburgh")
  90     #   cache.read("city")   # => "Duckburgh"
  91     class Store
  92       cattr_accessor :logger
  93
  94       def silence!
  95         @silence = true
  96         self
  97       end
  98
  99       # Fetches data from the cache, using the given key. If there is data in
 100       # the cache with the given key, then that data is returned.
 101       #
 102       # If there is no such data in the cache (a cache miss occurred), then
 103       # then nil will be returned. However, if a block has been passed, then
 104       # that block will be run in the event of a cache miss. The return value
 105       # of the block will be written to the cache under the given cache key,
 106       # and that return value will be returned.
 107       #
 108       #   cache.write("today", "Monday")
 109       #   cache.fetch("today")  # => "Monday"
 110       #
 111       #   cache.fetch("city")   # => nil
 112       #   cache.fetch("city") do
 113       #     "Duckburgh"
 114       #   end
 115       #   cache.fetch("city")   # => "Duckburgh"
 116       #
 117       # You may also specify additional options via the +options+ argument.
 118       # Setting <tt>:force => true</tt> will force a cache miss:
 119       #
 120       #   cache.write("today", "Monday")
 121       #   cache.fetch("today", :force => true)  # => nil
 122       #
 123       # Other options will be handled by the specific cache store implementation.
 124       # Internally, #fetch calls #read, and calls #write on a cache miss.
 125       # +options+ will be passed to the #read and #write calls.
 126       #
 127       # For example, MemCacheStore's #write method supports the +:expires_in+
 128       # option, which tells the memcached server to automatically expire the
 129       # cache item after a certain period. We can use this option with #fetch
 130       # too:
 131       #
 132       #   cache = ActiveSupport::Cache::MemCacheStore.new
 133       #   cache.fetch("foo", :force => true, :expires_in => 5.seconds) do
 134       #     "bar"
 135       #   end
 136       #   cache.fetch("foo")  # => "bar"
 137       #   sleep(6)
 138       #   cache.fetch("foo")  # => nil
 139       def fetch(key, options = {})
 140         @logger_off = true
 141         if !options[:force] && value = read(key, options)
 142           @logger_off = false
 143           log("hit", key, options)
 144           value
 145         elsif block_given?
 146           @logger_off = false
 147           log("miss", key, options)
 148
 149           value = nil
 150           ms = Benchmark.ms { value = yield }
 151
 152           @logger_off = true
 153           write(key, value, options)
 154           @logger_off = false
 155
 156           log('write (will save %.2fms)' % ms, key, nil)
 157
 158           value
 159         end
 160       end
 161
 162       # Fetches data from the cache, using the given key. If there is data in
 163       # the cache with the given key, then that data is returned. Otherwise,
 164       # nil is returned.
 165       #
 166       # You may also specify additional options via the +options+ argument.
 167       # The specific cache store implementation will decide what to do with
 168       # +options+.
 169       def read(key, options = nil)
 170         log("read", key, options)
 171       end
 172
 173       # Writes the given value to the cache, with the given key.
 174       #
 175       # You may also specify additional options via the +options+ argument.
 176       # The specific cache store implementation will decide what to do with
 177       # +options+.
 178       #
 179       # For example, MemCacheStore supports the +:expires_in+ option, which
 180       # tells the memcached server to automatically expire the cache item after
 181       # a certain period:
 182       #
 183       #   cache = ActiveSupport::Cache::MemCacheStore.new
 184       #   cache.write("foo", "bar", :expires_in => 5.seconds)
 185       #   cache.read("foo")  # => "bar"
 186       #   sleep(6)
 187       #   cache.read("foo")  # => nil
 188       def write(key, value, options = nil)
 189         log("write", key, options)
 190       end
 191
 192       def delete(key, options = nil)
 193         log("delete", key, options)
 194       end
 195
 196       def delete_matched(matcher, options = nil)
 197         log("delete matched", matcher.inspect, options)
 198       end
 199
 200       def exist?(key, options = nil)
 201         log("exist?", key, options)
 202       end
 203
 204       def increment(key, amount = 1)
 205         log("incrementing", key, amount)
 206         if num = read(key)
 207           write(key, num + amount)
 208         else
 209           nil
 210         end
 211       end
 212
 213       def decrement(key, amount = 1)
 214         log("decrementing", key, amount)
 215         if num = read(key)
 216           write(key, num - amount)
 217         else
 218           nil
 219         end
 220       end
 221
 222       private
 223         def log(operation, key, options)
 224           logger.debug("Cache #{operation}: #{key}#{options ? " (#{options.inspect})" : ""}") if logger && !@silence && !@logger_off
 225         end
 226     end
 227   end
 228 end