@@ -2,58 +2,58 @@ require "pstore" require "monitor" # == TimedCache -# +# # TimedCache implements a cache in which you can place objects # and specify a timeout value. -# +# # If you attempt to retrieve the object within the specified timeout # period, the object will be returned. If the timeout period has elapsed, # the TimedCache will return nil. -# +# # e.g.: # cache = TimedCache.new # cache.put :my_object_key, "Expensive data", 10 # => "Expensive data" -# +# # cache.get :my_object_key # => "Expensive data" # cache[:my_object_key] # => "Expensive data" -# +# # ... 10 seconds later: # cache.get :my_object_key # => nil -# +# # === Default timeout -# +# # When creating a new TimedCache, a default timeout value can be set. This value # will be used for each object added to the cache, unless a different timeout value # is specifically set for that object. -# +# # e.g.: -# +# # cache = TimedCache.new(:default_timeout => 120) # cache.default_timeout # => 120 -# +# # === File-based cache -# -# By default, TimedCache will use an in-memory store. A file-based store (using the +# +# By default, TimedCache will use an in-memory store. A file-based store (using the # PStore library) can also be used. -# +# # e.g.: -# +# # TimedCache.new(:type => :file, :filename => "my_cache.db") -# -# The file-based cache makes it possible to easily share a cache between several ruby +# +# The file-based cache makes it possible to easily share a cache between several ruby # processes. -# +# # Note that objects that cannot be marshalled (e.g. a Proc) can't be stored using the file-based cache. class TimedCache VERSION = "0.3" - + attr_reader :default_timeout - + # Create a new TimedCache. Available options are: # <tt>type</tt>:: <tt>:memory</tt> or <tt>:file</tt> (defaults to <tt>:memory</tt>). # <tt>default_timeout</tt>:: Timeout to use if none is specified when adding an object to the cache. # <tt>filename</tt>:: Must be specified when using the <tt>:file</tt> type store. - # + # # e.g.: # TimedCache.new(:type => :file, :filename => "cache.db") def initialize(opts = {}) @@ -62,65 +62,65 @@ class TimedCache @store = new_store(opts) @store.extend(MonitorMixin) end - + # Add an object to the cache. e.g.: # cache.put(:session_id, 12345) - # - # The third parameter is an optional timeout value. If not specified, the + # + # The third parameter is an optional timeout value. If not specified, the # <tt>:default_timeout</tt> for this TimedCache will be used instead. def put(key, value, timeout = @default_timeout) @store.synchronize do @store.put(key, value, timeout) unless value.nil? end end - + # Retrieve the object which the given +key+. If the object has expired or # is not present, +nil+ is returned. - # + # # Optionally, a block can be given. The result of evaluating the block will # be substituted as the cache value, if the cache has expired. - # + # # e.g.: - # + # # cache.get("slow_database_query") do # MyDatabase.query("SELECT * FROM bigtable...") # end - # + # def get(key, &block) @store.synchronize do @store.get(key, &block) end end - + # Add to the cache using a hash-like syntax. e.g.: # cache[:name] = "Nick" - # + # # Note that adding to the cache this way does not allow you to specify timeout values # on a per-object basis. def []=(key, value) put(key, value) end - + # Fetch objects using the hash syntax. e.g.: # cache[:name] # => "Nick" def [](key) get(key) end - + protected - + def new_store(options) #:nodoc: self.class.const_get(options[:type].to_s.capitalize + "Store").new(self, options) end - + class Store #:nodoc: def initialize(timed_cache, options) @timed_cache = timed_cache @options = options end - + protected - + def generic_get(key, timeout, callback, fetch_key = lambda {|k| @cache[key]}) if object_store = fetch_key.call(key) if object_store.expired? @@ -137,40 +137,40 @@ class TimedCache run_callback_and_add_to_cache(key, object_store, callback, timeout) end end - + def run_callback_and_add_to_cache(key, object_store, callback, timeout) object_store.no_expiry! if object_store - + begin result = callback.call rescue object_store.reset_expiry! if object_store raise end - + @timed_cache.put(key, result, timeout) result end end - + class MemoryStore < Store #:nodoc: def initialize(*args) super(*args) @cache = Hash.new end - + def put(key, value, timeout) @cache[key] = ObjectContainer.new(value, timeout) # Return just the given value, so that references to the # ObjectStore instance can't be held outside this TimedCache: value end - + def get(key, timeout = @timed_cache.default_timeout, &block) generic_get(key, timeout, block) end end - + class FileStore < Store #:nodoc: def initialize(*args) super(*args) @@ -180,15 +180,15 @@ class TimedCache end @cache = PStore.new(filename) end - + def put(key, value, timeout) @cache.transaction { @cache[key] = ObjectContainer.new(value, timeout) } - + # Return just the given value, so that references to the # ObjectStore instance can't be held outside this TimedCache: value end - + def get(key, timeout = @timed_cache.default_timeout, &block) if block generic_get(key, timeout, block, lambda {|k| @cache.transaction { @cache[key] } }) @@ -197,17 +197,17 @@ class TimedCache end end end - + class ObjectContainer #:nodoc: attr_accessor :object - + def initialize(object, timeout) @created_at = Time.now.utc @timeout = timeout @object = object @frozen = false end - + def expired? if @frozen false @@ -215,11 +215,11 @@ class TimedCache (Time.now.utc - @timeout) > @created_at end end - + def no_expiry! @frozen = true end - + def reset_expiry! @frozen = false end lib/timedcache.rb @@ -8,59 +8,59 @@ describe "Adding and retrieving objects from the cache" do @file_cache = TimedCache.new(:type => :file, :filename => $filename) @caches = [@memory_cache, @file_cache] end - + after do File.delete($filename) end - + it "Can add an object to the cache, specifying a timeout value" do @caches.each do |cache| cache.put(:myobject, "This needs caching", 10).should == "This needs caching" end end - - it "Cache should hold seperate values for each key" do - @caches.each do |cache| + + it "Cache should hold separate values for each key" do + @caches.each do |cache| cache.put(:myobject, "This needs caching", 10).should == "This needs caching" cache.put(:my_other_object, "...and this too", 10).should == "...and this too" cache.get(:myobject).should == "This needs caching" cache.get(:my_other_object).should == "...and this too" end end - + it "String and symbol keys are not treated as equivalent" do @caches.each do |cache| cache[:symbolkey] = "Referenced by symbol" cache["stringkey"] = "Referenced by string" - + cache[:symbolkey].should == "Referenced by symbol" cache["symbolkey"].should == nil - + cache["stringkey"].should == "Referenced by string" cache[:stringkey].should == nil end end - + it "After the specified timeout value has elapsed, nil should be returned" do - @caches.each do |cache| + @caches.each do |cache| cache.put(:myobject, "This needs caching", 0).should == "This needs caching" cache.get(:myobject).should == nil end end - + it "If no object matching the given key is found, nil should be returned" do @caches.each do |cache| cache.get(:my_nonexistant_object).should == nil end end - + it "Should be able to use an array as a cache key" do @caches.each do |cache| cache.put([123,234], "Array").should == "Array" cache.get([123,234]).should == "Array" end end - + it "Passing a block to the TimedCache#get method should substitute the " + "result of the block as the value for the given key" do @caches.each do |cache| @@ -69,8 +69,8 @@ describe "Adding and retrieving objects from the cache" do cache.get("block_test").should == 2001 end end - - it "Passing a block to TimedCache#get should add the result of the callback " + + + it "Passing a block to TimedCache#get should add the result of the callback " + "when there is no existing value for the key given" do @caches.each do |cache| cache.get("new_key_with_block").should == nil @@ -85,13 +85,13 @@ describe "Specifying a default timeout" do cache.should be_kind_of(TimedCache) cache.default_timeout.should == 20 end - + it "If no default timeout is set, 60 seconds should be used" do cache = TimedCache.new cache.should be_kind_of(TimedCache) cache.default_timeout.should == 60 end - + it "Timeout specified when putting a new object into the cache should override default timeout" do cache = TimedCache.new(:default_timeout => 20) cache.default_timeout.should == 20 spec/timed_cache_spec.rb c8434e72dce665d0781f0a3afd251de7ec20e010 Nicholas Dainty nick@npad.co.uk http://github.com/nickpad/timedcache/commit/6fbe83ee5d3cab567cf3bc631812355174a6f411 6fbe83ee5d3cab567cf3bc631812355174a6f411 2009-03-29T05:31:13-07:00 2009-03-29T05:31:13-07:00 tidying. 3f6b384600f480a9a557c2eb438c65aac102713c Nicholas Dainty nick@npad.co.uk