fast_cache 1.0.0

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/.rspec

@@ -0,0 +1,2 @@
+--format progress
+--color

data/.simplecov

@@ -0,0 +1,4 @@
+SimpleCov.start do
+  add_filter "/spec/"
+  add_filter "/tmp/"
+end

data/.yardopts

@@ -0,0 +1,3 @@
+lib/**/*.rb
+-
+LICENSE.txt

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in fast_cache.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013 Simeon Simeonov & Swoop, Inc.
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,185 @@
+# FastCache
+
+
+There are two reasons why you may want to immediately leave this page:
+
+1. This is yet another caching gem, which is grounds for extreme suspicion.
+
+2. Many Ruby developers don't care about performance.
+
+If you're still reading, there are three reasons why you may want to check this out:
+
+1. Performance is a feature users love. Products from 37signals' to Google's have proven this time and time again. Performance almost never matters if you are not successful but almost always does if you are. At [Swoop](http://swoop.com) we have tens of millions of users. We care about correctness, simplicity and maintainability but also, quite a bit, about performance.
+
+2. This cache benchmarks 10-100x faster than ActiveSupport::Cache::MemoryStore without breaking a sweat. You can switch to FastCache in a couple minutes and, most likely, you won't have to refactor your tests. FastCache has 100% test coverage at 20+ hits/line. There are no third party runtime dependencies so you can use this anywhere with Ruby 1.9+.
+
+3. The implementation exploits some neat features of Ruby's native data structures that could be useful and fun to learn about.
+
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'fast_cache'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install fast_cache
+
+
+## Usage
+
+FastCache::Cache is an in-process cache with least recently used (LRU) and time to live (TTL) expiration semantics, which makes it an easy replacement for ActiveSupport::Cache::MemoryStore as well as a great candidate for the in-process portion of a hierarchical caching system (FastCache sitting in front of, say, memcached or Redis).
+
+The current implementation is not thread-safe because at [Swoop](http://swoop.com) we prefer to handle simple concurrency in MRI Ruby via the [reactor pattern](http://en.wikipedia.org/wiki/Reactor_pattern) with [eventmachine](https://github.com/eventmachine/eventmachine). An easy way to add thread safety would be via a [synchronizing subclass](https://github.com/SamSaffron/lru_redux/blob/master/lib/lru_redux/thread_safe_cache.rb) or decorator. Send a pull request, please!
+
+The implementation does not use a separate thread for expiring stale cached values. Instead, before a value is returned from the cache, its expiration time is checked. In order to avoid the case where a value that is never accessed cannot be removed, every _N_ operations the cache removes all expired values.
+
+```ruby
+require 'fast_cache'
+
+# Creates a cache of one million items at most an hour old
+cache = FastCache::Cache.new(1_000_000, 60*60)
+
+# Sames as above but removes expired items after every 10,000 operations.
+# The default is after 100 operations.
+cache = FastCache::Cache.new(1_000_000, 60*60, 10_000)
+
+# Cache the result of an expensive operation
+cached_value = cache.fetch('my_key') do
+  HardProblem.new(inputs).solve.result
+end
+
+# Proactively release as much memory as you can
+cache.expire!
+```
+
+
+## Performance
+
+If you are looking for an in-process cache with LRU and time-to-live expiration semantics the go-to implementation is ActiveSupport::Cache::MemoryStore, which as of Rails 3.1 [started marshaling](http://apidock.com/rails/v3.2.13/ActiveSupport/Cache/Entry/value) the data even though the keys and values never leave the process boundary. The performance of the cache is dominated by marshaling and loading, i.e., by the size and complexity of keys and values. The better job you do of finding large, complex, cacheable data structures, the slower it will run. That doesn't feel right for an in-process cache.
+
+We benchmark against [LruRedux::Cache](https://github.com/SamSaffron/lru_redux), which was the inspiration behind FastCache::Cache and, of course, ActiveSupport::Cache::MemoryStore.
+
+```bash
+gem install lru_redux
+gem install activesupport
+bin/fast-cache-benchmark
+```
+
+The [benchmark](bin/fast-cache-benchmark) includes a simple value test (caching just the Symbol `:value`) and a more complex value test (caching a [medium-size data structure](bench/caching_sample.json)). Both tests run for one million iterations with an expected cache hit rate of 50%.
+
+```
+12009[SPX/fast_cache(master *#)]$ bin/fast-cache-benchmark
+Simple value benchmark
+Rehearsal ------------------------------------------------
+lru_redux      2.200000   0.020000   2.220000 (  2.213863)
+fast_cache    10.840000   0.040000  10.880000 ( 10.879686)
+memory_store  53.300000   0.150000  53.450000 ( 53.459458)
+-------------------------------------- total: 66.550000sec
+
+                   user     system      total        real
+lru_redux      4.140000   0.010000   4.150000 (  4.153546)
+fast_cache    14.140000   0.040000  14.180000 ( 14.177038)
+memory_store  71.510000   0.140000  71.650000 ( 71.659656)
+
+Complex value benchmark
+Rehearsal ------------------------------------------------
+lru_redux      6.150000   0.030000   6.180000 (  6.180459)
+fast_cache    17.020000   0.040000  17.060000 ( 17.058475)
+memory_store 1053.360000   1.620000 1054.980000 (1055.275237)
+------------------------------------ total: 1078.220000sec
+
+                   user     system      total        real
+lru_redux      7.830000   0.020000   7.850000 (  7.854760)
+fast_cache    19.620000   0.030000  19.650000 ( 19.650379)
+memory_store 1286.790000   1.850000 1288.640000 (1289.115472)
+```
+
+In both tests FastCache::Cache is 2-3x slower than LruRedux::Cache, which only provides LRU semantics. For small values, FastCache::Cache is 5x faster than ActiveSupport::Cache::MemoryStore. For more complex values the difference grows to 50+x (67x in the particular benchmark).
+
+In one case where we were generating CSVs where every row involved looking up model attributes the performance difference was 100x and operations that took many minutes now happen in seconds.
+
+
+## Implementation
+
+[Sam Saffron](https://github.com/SamSaffron) noticed that Ruby 1.9 Hash's property to preserve insertion order can be used as a second index (in addition to indexing by a key).  That led Sam to create the [lru_redux](https://github.com/SamSaffron/lru_redux) gem, whose cache behaves in a very non-intuitive way at first glance. For example, the simplified pseudocode for the cache get operation is:
+
+```
+cache[key]:
+  value = @hash.delete(key)
+  @hash[key] = value
+  value
+```
+
+In other words, the code performs two mutating operations (delete and insert) in order to satisfy a single non-mutating operation (get). Why? The reason is that this is how the cache maintains its least recently used removal property. The picture below shows the get operation step-by-step using a fictitious cache of names against some difficult-to-compute score.
+
+![lru](https://www.lucidchart.com/publicSegments/view/525be92f-6034-40f7-b3b6-377d0a005604/image.png)
+If the cache gets full, it can create space by removing elements from the head of its items array. For those of you familiar with [Redis](http://redis.io), this approach to using a Ruby Hash may remind you of [sorted sets](http://redis.io/commands#sorted_set).
+
+To add time-based expiration, we need to:
+
+1. Keep track of expiration times.
+
+2. Index by expiration time, to clean up in `expire!`.
+
+3. Efficiently remove items from the expiration index when a stale item is detected.
+
+By exploiting the dual index property of Hash we can achieve this with just one extra hash. The diagram below shows the object relationships.
+
+![lru-and-ttl](https://www.lucidchart.com/publicSegments/view/525be9d7-fe08-40fb-9dd2-37850a005603/image.png)
+### A note about Time
+
+Those who peek at the code may notice the expression `Time.now.to_f`. Rails has some very nice time extensions, e.g., dealing with time zones and the ability to add and subtract duration objects from date/time objects. All this sugar, which is of no use to us here, comes at a significant overhead so much so that I have benchmarked the cache running several times slower in a Rails environment without the conversion of the time object to a simple number.
+
+
+## Contributing
+
+1. Fork the repo
+2. Create a topic branch (`git checkout -b my-new-feature`)
+4. Commit your changes (`git commit -am 'Add some feature'`)
+5. Push to the branch (`git push origin my-new-feature`)
+6. Create new Pull Request
+
+Please don't change the version and add solid tests: [simplecov](https://github.com/colszowka/simplecov) is set to 100% minimum coverage.
+
+
+## Credits
+
+I'd like to thank [Sam Saffron](https://github.com/SamSaffron) for his guiding insight as well as [Richard Schneeman](https://github.com/schneems) and [Piotr Sarnacki](https://github.com/drogus) for [helping me improve](https://github.com/rails/rails/issues/11512) ActiveSupport::Cache::MemoryStore.
+
+Who says Ruby can't be fun **and** fast?
+
+![swoop](http://blog.swoop.com/Portals/160747/images/logo1.png)
+
+fast_cache was written by [Simeon Simeonov](https://github.com/ssimeonov) and is maintained and funded by [Swoop, Inc,](http://swoop.com).
+
+License
+-------
+
+fast_cache is Copyright © 2013 Simeon Simeonov and Swoop, Inc. It is free software, and may be redistributed under the terms specified below.
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/bench/caching_sample.json

@@ -0,0 +1,133 @@
+[
+  {
+    "example_taken_from" : "http://adobe.github.io/Spry/samples/data_region/JSONDataSetSample.html"
+  },
+  {
+    "id" :      "0001",
+    "type" :    "donut",
+    "name" :    "Cake",
+    "ppu" :     0.55,
+    "batters" : {
+      "batter" : [
+        {
+          "id" :   "1001",
+          "type" : "Regular"
+        },
+        {
+          "id" :   "1002",
+          "type" : "Chocolate"
+        },
+        {
+          "id" :   "1003",
+          "type" : "Blueberry"
+        },
+        {
+          "id" :   "1004",
+          "type" : "Devil's Food"
+        }
+      ]
+    },
+    "topping" : [
+      {
+        "id" :   "5001",
+        "type" : "None"
+      },
+      {
+        "id" :   "5002",
+        "type" : "Glazed"
+      },
+      {
+        "id" :   "5005",
+        "type" : "Sugar"
+      },
+      {
+        "id" :   "5007",
+        "type" : "Powdered Sugar"
+      },
+      {
+        "id" :   "5006",
+        "type" : "Chocolate with Sprinkles"
+      },
+      {
+        "id" :   "5003",
+        "type" : "Chocolate"
+      },
+      {
+        "id" :   "5004",
+        "type" : "Maple"
+      }
+    ]
+  },
+  {
+    "id" :      "0002",
+    "type" :    "donut",
+    "name" :    "Raised",
+    "ppu" :     0.55,
+    "batters" : {
+      "batter" : [
+        {
+          "id" :   "1001",
+          "type" : "Regular"
+        }
+      ]
+    },
+    "topping" : [
+      {
+        "id" :   "5001",
+        "type" : "None"
+      },
+      {
+        "id" :   "5002",
+        "type" : "Glazed"
+      },
+      {
+        "id" :   "5005",
+        "type" : "Sugar"
+      },
+      {
+        "id" :   "5003",
+        "type" : "Chocolate"
+      },
+      {
+        "id" :   "5004",
+        "type" : "Maple"
+      }
+    ]
+  },
+  {
+    "id" :      "0003",
+    "type" :    "donut",
+    "name" :    "Old Fashioned",
+    "ppu" :     0.55,
+    "batters" : {
+      "batter" : [
+        {
+          "id" :   "1001",
+          "type" : "Regular"
+        },
+        {
+          "id" :   "1002",
+          "type" : "Chocolate"
+        }
+      ]
+    },
+    "topping" : [
+      {
+        "id" :   "5001",
+        "type" : "None"
+      },
+      {
+        "id" :   "5002",
+        "type" : "Glazed"
+      },
+      {
+        "id" :   "5003",
+        "type" : "Chocolate"
+      },
+      {
+        "id" :   "5004",
+        "type" : "Maple"
+      }
+    ]
+  }
+]

data/bin/fast-cache-benchmark

@@ -0,0 +1,52 @@
+#!/usr/bin/env ruby
+
+lib = File.expand_path('../../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+
+require 'fast_cache'
+require 'lru_redux'
+require 'active_support/cache'
+require 'json'
+
+class ModifiedLru < LruRedux::Cache
+  # Modify API to be consistent with other caches
+  def fetch(key, &block)
+    getset(key, &block)
+  end
+end
+
+def make_caches(size, exemplar_value, ttl)
+  marshaled = Marshal.dump(exemplar_value)
+  {
+      lru_redux: ModifiedLru.new(size),
+      fast_cache: FastCache::Cache.new(size, ttl),
+      memory_store: ActiveSupport::Cache.lookup_store(:memory_store, size: size * marshaled.length + 1)
+  }
+end
+
+def complex_value
+  sample_file = File.expand_path('../../bench/caching_sample.json',  __FILE__)
+  JSON.parse(File.read(sample_file))
+end
+
+def run_test(size, value, ttl = 60*60)
+  caches = make_caches(size, value, ttl)
+
+  Benchmark.bmbm do |bm|
+    caches.each.map(&:last).map(&:clear)
+
+    caches.each_pair do |name, cache|
+      bm.report name do
+        1000000.times do
+          cache.fetch(rand(2 * size)) { value }
+        end
+      end
+    end
+  end
+end
+
+puts "Simple value benchmark\n"
+run_test 1_000, :value
+
+puts "\nComplex value benchmark\n"
+run_test 1_000, complex_value

data/fast_cache.gemspec

@@ -0,0 +1,27 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'fast_cache/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "fast_cache"
+  spec.version       = FastCache::VERSION
+  spec.authors       = ["Simeon Simeonov"]
+  spec.email         = ["sim@swoop.com"]
+  spec.description   = %q{Very fast LRU + TTL cache}
+  spec.summary       = %q{FastCache is an in-process cache with both least-recently used (LRU) and time to live (TTL) expiration semantics. It is typically 5-100x faster than ActiveSupport::Cache::MemoryStore, depending on the cached data.}
+  spec.homepage      = "https://github.com/swoop-inc/fast_cache"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files`.split($/)
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.3"
+  spec.add_development_dependency "rake"
+  spec.add_development_dependency "rspec"
+  spec.add_development_dependency "simplecov"
+  spec.add_development_dependency "awesome_print"
+  spec.add_development_dependency "timecop"
+end

data/lib/fast_cache.rb

@@ -0,0 +1,2 @@
+require 'fast_cache/version'
+require 'fast_cache/cache'

data/lib/fast_cache/cache.rb

@@ -0,0 +1,221 @@
+module FastCache
+
+  # @author {https://github.com/ssimeonov Simeon Simeonov}, {http://swoop.com Swoop, Inc.}
+  #
+  # In-process cache with least-recently used (LRU) and time-to-live (TTL)
+  # expiration semantics.
+  #
+  # This implementation is not thread-safe. It does not use a thread to clean
+  # up expired values. Instead, an expiration check is performed:
+  #
+  # 1. Every time you retrieve a value, against that value. If the value has
+  #    expired, it will be removed and `nil` will be returned.
+  #
+  # 2. Every `expire_interval` operations as the cache is used to remove all
+  #    expired values up to that point.
+  #
+  # For manual expiration call {#expire!}.
+  #
+  # @example
+  #
+  #   # Create cache with one million elements no older than 1 hour
+  #   cache = FastCache::Cache.new(1_000_000, 60 * 60)
+  #   cached_value = cache.fetch('cached_value_key') do
+  #     # Expensive computation that returns the value goes here
+  #   end
+  class Cache
+
+    # Initializes the cache.
+    #
+    # @param [Integer] max_size Maximum number of elements in the cache.
+    # @param [Numeric] ttl Maximum time, in seconds, for a value to stay in
+    #                      the cache.
+    # @param [Integer] expire_interval Number of cache operations between
+    #                                  calls to {#expire!}.
+    def initialize(max_size, ttl, expire_interval = 100)
+      @max_size = max_size
+      @ttl = ttl.to_f
+      @expire_interval = expire_interval
+      @op_count = 0
+      @data = {}
+      @expires_at = {}
+    end
+
+    # Retrieves a value from the cache, if available and not expired, or
+    # yields to a block that calculates the value to be stored in the cache.
+    #
+    # @param key [Object] the key to look up or store at
+    # @return [Object] the value at the key
+    # @yield yields when the value is not present
+    # @yieldreturn [Object] the value to store in the cache.
+    def fetch(key)
+      found, value = get(key)
+      if found
+        value
+      else
+        store(key, yield)
+      end
+    end
+
+    # Retrieves a value from the cache.
+    #
+    # @param key [Object] the key to look up
+    # @return [Object, nil] the value at the key, when present, or `nil`
+    def [](key)
+      _, value = get(key)
+      value
+    end
+
+    # Stores a value in the cache.
+    #
+    # @param key [Object] the key to store at
+    # @param val [Object] the value to store
+    # @return [Object] the value
+    def []=(key, val)
+      expire!
+      store(key, val)
+    end
+
+    # Removes a value from the cache.
+    #
+    # @param key [Object] the key to remove at
+    # @return [Object, nil] the value at the key, when present, or `nil`
+    def delete(key)
+      entry = @data.delete(key)
+      if entry
+        @expires_at.delete(entry)
+        entry.value
+      else
+        nil
+      end
+    end
+
+    # Checks whether the cache is empty.
+    #
+    # @note calls to {#empty?} do not count against `expire_interval`.
+    #
+    # @return [Boolean]
+    def empty?
+      count == 0
+    end
+
+    # Clears the cache.
+    #
+    # @return [self]
+    def clear
+      @data.clear
+      @expires_at.clear
+      self
+    end
+
+    # Returns the number of elements in the cache.
+    #
+    # @note calls to {#empty?} do not count against `expire_interval`.
+    #       Therefore, the number of elements is that prior to any expiration.
+    #
+    # @return [Integer] number of elements in the cache.
+    def count
+      @data.count
+    end
+
+    alias_method :size, :count
+    alias_method :length, :count
+
+    # Allows iteration over the items in the cache.
+    #
+    # Enumeration is stable: it is not affected by changes to the cache,
+    # including value expiration. Expired values are removed first.
+    #
+    # @note The returned values could have expired by the time the client
+    #       code gets to accessing them.
+    # @note Because of its stability, this operation is very expensive.
+    #       Use with caution.
+    #
+    # @return [Enumerator, Array<key, value>] an Enumerator, when a block is
+    #     not provided, or an array of key/value pairs.
+    # @yield [Array<key, value>] key/value pairs, when a block is provided.
+    def each(&block)
+      expire!
+      @data.map { |key, entry| [key, entry.value] }.each(&block)
+    end
+
+    # Removes expired values from the cache.
+    #
+    # @return [self]
+    def expire!
+      check_expired(Time.now.to_f)
+      self
+    end
+
+    # Returns information about the number of objects in the cache, its
+    # maximum size and TTL.
+    #
+    # @return [String]
+    def inspect
+      "<#{self.class.name} count=#{count} max_size=#{@max_size} ttl=#{@ttl}>"
+    end
+
+    private
+
+    # @private
+    class Entry
+      attr_reader :value
+      attr_reader :expires_at
+
+      def initialize(value, expires_at)
+        @value = value
+        @expires_at = expires_at
+      end
+    end
+
+    def get(key)
+      t = Time.now.to_f
+      check_expired(t)
+      found = true
+      entry = @data.delete(key) { found = false }
+      if found
+        if entry.expires_at <= t
+          @expires_at.delete(entry)
+          return false, nil
+        else
+          @data[key] = entry
+          return true, entry.value
+        end
+      else
+        return false, nil
+      end
+    end
+
+    def store(key, val)
+      expires_at = Time.now.to_f + @ttl
+      entry = Entry.new(val, expires_at)
+      store_entry(key, entry)
+      val
+    end
+
+    def store_entry(key, entry)
+      @data.delete(key)
+      @data[key] = entry
+      @expires_at[entry] = key
+      shrink_if_needed
+    end
+
+    def shrink_if_needed
+      if @data.length > @max_size
+        entry = delete(@data.shift)
+        @expires_at.delete(entry)
+      end
+    end
+
+    def check_expired(t)
+      if (@op_count += 1) % @expire_interval == 0
+        while (key_value_pair = @expires_at.first) &&
+            (entry = key_value_pair.first).expires_at <= t
+          key = @expires_at.delete(entry)
+          @data.delete(key)
+        end
+      end
+    end
+  end
+
+end

data/lib/fast_cache/version.rb

@@ -0,0 +1,3 @@
+module FastCache
+  VERSION = '1.0.0'
+end

data/spec/lib/fast_cache/cache_spec.rb

@@ -0,0 +1,227 @@
+require 'spec_helper'
+
+describe FastCache::Cache do
+
+  context 'empty cache' do
+    subject { described_class.new(5, 60, 1) }
+
+    its(:empty?) { should be_true }
+    its(:length) { should eq 0 }
+    its(:size) { should eq 0 }
+    its(:count) { should eq 0 }
+
+    it 'returns nil' do
+      subject[:foo].should be_nil
+    end
+  end
+
+  context 'non-empty cache' do
+    before do
+      @cache = described_class.new(3, 60, 1)
+      @cache[:a] = 1
+      @cache[:b] = 2
+      @cache[:c] = 3
+    end
+    subject { @cache }
+
+    its(:empty?) { should be_false }
+    its(:length) { should eq 3 }
+    its(:size) { should eq 3 }
+    its(:count) { should eq 3 }
+
+    it 'returns stored values' do
+      subject[:a].should eq 1
+      subject[:b].should eq 2
+      subject[:c].should eq 3
+    end
+
+    it 'replaces stored values' do
+      subject[:a] = 10
+
+      subject[:a].should eq 10
+    end
+
+    describe '#fetch' do
+      it 'fetches from the cache when a key is present' do
+        subject.fetch(:a) do
+          'failure'.should eq 'fetch body should not be called'
+        end.should eq 1
+      end
+
+      it 'evaluates and stores the value when it is absent' do
+        subject.fetch(:d) do
+          5
+        end.should eq 5
+        subject[:d].should eq 5
+      end
+    end
+
+    describe '#delete' do
+      it 'deletes entries' do
+        subject.delete(:a).should eq 1
+        subject.count.should eq 2
+        subject.delete(:c).should eq 3
+        subject.count.should eq 1
+      end
+
+      it 'returns nil for missing keys' do
+        subject.delete(:d).should be_nil
+        subject.count.should eq 3
+      end
+    end
+
+    describe '#clear' do
+      it 'clears the cache' do
+        subject.clear
+
+        subject.should be_empty
+      end
+    end
+
+    describe '#each' do
+      it 'yields key value pairs' do
+        expect do |b|
+          subject.each(&b)
+        end.to yield_successive_args([:a, 1], [:b, 2], [:c, 3])
+      end
+
+      it 'returns an Enumerator when called without a block' do
+        subject.each.should be_kind_of Enumerator
+      end
+    end
+
+    describe '#inspect' do
+      it do
+        subject.inspect.should eq '<FastCache::Cache count=3 max_size=3 ttl=60.0>'
+      end
+    end
+
+    describe 'LRU behaviors' do
+      it 'removes least recently accessed entries when full' do
+        subject[:d] = 4
+
+        subject[:a].should be_nil
+        subject[:b].should eq 2
+
+        subject[:b] # access
+        subject[:e] = 6
+
+        subject[:b].should eq 2
+        subject[:c].should be_nil
+        subject[:d].should eq 4
+        subject[:e].should eq 6
+      end
+    end
+  end
+
+  describe 'TTL behaviors' do
+    context 'immediate expiration' do
+      before do
+        @cache = described_class.new(3, 0, 1)
+        @cache[:a] = 1
+      end
+      subject { @cache }
+
+      it 'reports the element count prior to expiration checking' do
+        subject.count.should eq 1
+      end
+
+      it 'expires all entries' do
+        subject.expire!
+
+        subject.count.should eq 0
+      end
+
+      it 'removes all entries upon access' do
+        subject[:a].should be_nil
+
+        subject.fetch(:a) do
+          true.should be_true
+          5
+        end.should == 5
+
+        subject[:a].should be_nil
+      end
+    end
+
+    context '1 min expiration' do
+      before do
+        @t = Time.now
+        @cache = described_class.new(3, 60, 1)
+        @cache[:a] = 1
+      end
+      subject { @cache }
+
+      it 'removes expired values upon access' do
+        Timecop.freeze(@t + 61) do
+          subject[:a].should be_nil
+        end
+      end
+
+      it 'removes expired values when other values are written' do
+        Timecop.freeze(@t + 61) do
+          subject.count.should eq 1
+
+          subject[:b] = 2
+
+          subject.count.should eq 1
+          subject[:a].should be_nil
+          subject[:b].should eq 2
+        end
+      end
+
+      it 'removes expired values when other values are accessed' do
+        Timecop.freeze(@t + 30) do
+          subject[:b] = 2
+        end
+
+        Timecop.freeze(@t + 61) do
+          subject.count.should eq 2
+
+          subject[:b] # access
+
+          subject.count.should eq 1
+          subject[:a].should be_nil
+          subject[:b].should eq 2
+        end
+      end
+
+      it 'expires entries' do
+        Timecop.freeze(@t + 30) do
+          subject[:b] = 2
+        end
+
+        Timecop.freeze(@t + 61) do
+          subject.expire!
+
+          subject.count.should eq 1
+          subject[:b].should eq 2
+        end
+      end
+    end
+
+    context 'delayed expiration check' do
+      before do
+        @t = Time.now
+        @cache = described_class.new(3, 60, 10)
+        @cache[:a] = 1 # 1 op
+        @cache[:b] = 2 # 2 ops
+      end
+      subject { @cache }
+
+      it 'removes expired values after a specified number of operations' do
+        Timecop.freeze(@t + 61) do
+          subject.count.should eq 2
+          7.times do # 3..9 ops
+            subject[:a].should eq nil
+            subject.count.should == 1
+          end
+          # 10 ops
+          subject[:a].should eq nil
+          subject.count.should eq 0
+        end
+      end
+    end
+  end
+
+end

data/spec/spec_helper.rb

@@ -0,0 +1,16 @@
+require 'simplecov'
+SimpleCov.start
+SimpleCov.minimum_coverage 100
+
+require 'pp'
+require 'timecop'
+
+require 'fast_cache'
+
+Dir['spec/support/**/*.rb'].each { |f| require File.expand_path(f) }
+
+RSpec.configure do |config|
+  config.after do
+    Timecop.return
+  end
+end

metadata

@@ -0,0 +1,164 @@
+--- !ruby/object:Gem::Specification
+name: fast_cache
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+  prerelease: 
+platform: ruby
+authors:
+- Simeon Simeonov
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-10-14 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.3'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: awesome_print
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: timecop
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Very fast LRU + TTL cache
+email:
+- sim@swoop.com
+executables:
+- fast-cache-benchmark
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- .rspec
+- .simplecov
+- .yardopts
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- bench/caching_sample.json
+- bin/fast-cache-benchmark
+- fast_cache.gemspec
+- lib/fast_cache.rb
+- lib/fast_cache/cache.rb
+- lib/fast_cache/version.rb
+- spec/lib/fast_cache/cache_spec.rb
+- spec/spec_helper.rb
+homepage: https://github.com/swoop-inc/fast_cache
+licenses:
+- MIT
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.25
+signing_key: 
+specification_version: 3
+summary: FastCache is an in-process cache with both least-recently used (LRU) and
+  time to live (TTL) expiration semantics. It is typically 5-100x faster than ActiveSupport::Cache::MemoryStore,
+  depending on the cached data.
+test_files:
+- spec/lib/fast_cache/cache_spec.rb
+- spec/spec_helper.rb
+has_rdoc: