lru_cache 1.0.0

data/.rspec

@@ -0,0 +1,3 @@
+--color
+-fd
+--fail-fast

data/LICENSE

@@ -0,0 +1,21 @@
+Copyright (c) 2012 by Brendan Baldwin
+
+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.markdown

@@ -0,0 +1,41 @@
+# LRUCache
+
+It's a simple in-memory cache that expires the least recently used item
+in the cache when the count of items in the cache reaches a fixed limit. 
+
+## Usage
+
+    require "lru_cache"
+
+    # create a new cache with a 1,000 item limit
+    cache = LRUCache.new(1_000)
+
+    # get or set item in cache
+    cache["some key"] ||= expensive_operation
+
+By default the LRUCache is not thread-safe.  If you intend to access the
+cache in multi-threaded code, use LRUCache::ThreadSafe.
+
+    require "lru_cache/thread_safe"
+
+    # create a new thread-safe cache with a 1,000 item limit
+    cache = LRUCache::ThreadSafe.new(1_000)
+
+    # get or set item in cache
+    cache["some key"] ||= expensive_operation
+
+## Public Instance Methods
+
+ * `#clear` empties the cache
+ * `#count` returns the number of items currently in cache
+ * `#delete(key)` removes an item from the cache
+ * `#get(key)` returns the cached value or nil
+ * `#limit` returns the cache limit (defaults to 1)
+ * `#limit=value` sets the cache limit to value
+ * `#set(key, value)` stores the value in the cache
+ * `#[key]` alias for `#get(key)`
+ * `#[key]=value` alias for `#set(key, value)`
+
+## License
+
+This code is released under the MIT license, and is copyright 2012 by Brendan Baldwin. Please see the accompanying LICENSE file for the full text of the license.

data/lib/lru_cache.rb

@@ -0,0 +1,95 @@
+class LRUCache
+
+  Error             = Class.new RuntimeError
+  InvalidLimitError = Class.new Error
+  NoLimitError      = Class.new Error
+
+  Node = Struct.new(:key, :value, :mru, :lru)
+
+  attr_reader :count, :limit
+
+  # Sets up the new cache, optionally assigning given limit.
+  def initialize(limit=nil)
+    @index = {}
+    @count = 0
+    self.limit = limit if limit
+  end
+
+  # Empties the cache of all values.
+  def clear
+    count.times.each { delete_lru }
+  end
+
+  # Remove and return value from cache.
+  def delete(key)
+    node = @index.delete(key)
+    return unless node
+    @count -= 1
+    node.mru.lru = node.lru if node.mru
+    node.lru.mru = node.mru if node.lru
+    @mru = node.lru if @mru == node
+    @lru = node.mru if @lru == node
+    node.value
+  end
+
+  # Return value from cache and sets it as most-recently-used.
+  def get(key)
+    node = @index[key]
+    if node
+      set_mru(node)
+      node.value
+    end
+  end
+
+  # Assigns a new limit to the cache.  Deletes least recently used
+  # values if new limit is less than the count.
+  def limit=(new_limit)
+    new_limit and new_limit >= 1 or raise InvalidLimitError, "limit must be 1 or greater"
+    extra_count = count - new_limit
+    extra_count.times { delete_lru }
+    @limit = new_limit
+  end
+
+  # Stores a value in the cache.
+  def set(key, value)
+    node = @index[key]
+    unless node
+      node = Node.new(key)
+      @index[key] = node
+      @count += 1
+      delete_lru if count > ensure_limit
+    end
+    set_mru(node)
+    node.value = value
+  end
+
+  alias [] get
+  alias []= set
+
+  private
+
+  # Deletes the least recently used value from the cache.
+  def delete_lru
+    return unless @lru
+    @count -= 1
+    @index.delete(@lru.key)
+    @lru = @lru.mru
+    @lru.lru = nil if @lru
+  end
+
+  # Returns the limit if set, otherwise raises exception.
+  def ensure_limit
+    limit || raise(NoLimitError, "limit not set for LRUCache")
+  end
+
+  # Advances a node to the most recently used spot.
+  def set_mru(node)
+    return if node == @mru
+    @mru.mru = node if @mru
+    node.lru.mru = node.mru if node.lru
+    node.lru = @mru
+    @lru = node.mru if count > 1 and @lru == node
+    @lru ||= node
+    @mru = node
+  end
+end

data/lib/lru_cache/thread_safe.rb

@@ -0,0 +1,37 @@
+require "lru_cache"
+require "thread"
+
+class LRUCache::ThreadSafe < LRUCache
+
+	def initialize(limit=nil)
+    super
+    @mutex = Mutex.new
+  end
+
+  def count
+    @mutex.synchronize { super }
+  end
+
+  def clear
+    @mutex.synchronize { super }
+  end
+
+  def delete(key)
+    @mutex.synchronize { super }
+  end
+
+  def get(key)
+    @mutex.synchronize { super }
+  end
+
+  def limit=(new_limit)
+    @mutex.synchronize { super }
+  end
+
+  def set(key, value)
+    @mutex.synchronize { super }
+  end
+
+  alias [] get
+  alias []= set
+end

data/lru_cache.gemspec

@@ -0,0 +1,15 @@
+Gem::Specification.new do |s|
+  s.name          = 'lru_cache'
+  s.version       = '1.0.0'
+  s.authors       = ['Brendan Baldwin']
+  s.email         = ['brendan@usergenic.com']
+  s.homepage      = 'https://github.com/brendan/lru_cache'
+  s.summary       = %q{a simple LRU cache in ruby that uses a doubley-linked list and a hash}
+  s.description   = %q{its performant / constant o(1)}
+  s.files         = `git ls-files`.split("\n")
+  s.executables   = s.files.grep(/^bin\//).map{ |f| File.basename(f) }
+  s.require_paths = ['lib']
+
+  s.add_development_dependency 'rspec'
+end
+

data/spec/lru_cache_spec.rb

@@ -0,0 +1,142 @@
+require "lru_cache"
+
+describe LRUCache do
+
+  alias cache subject
+
+  describe ".new" do
+
+    it "allows assignment of the limit" do
+      LRUCache.new.limit.should be_nil
+      LRUCache.new(5).limit.should == 5
+    end
+  end
+
+  describe "#clear" do
+
+    it "empties the cache of all items" do
+      cache.limit = 3
+      cache.count.should == 0
+      cache.set("x", :x)
+      cache.set("y", :y)
+      cache.set("z", :z)
+      cache.count.should == 3
+      cache.get("x").should == :x
+
+      cache.clear
+      
+      cache.count.should == 0
+      cache.get("x").should be_nil
+    end
+  end
+
+  describe "#count" do
+
+    it "returns the number of items currently in cache" do
+      cache.limit = 3
+      cache.count.should == 0
+      cache.set("x", :x)
+      cache.count.should == 1
+      cache.set("y", :y)
+      cache.count.should == 2
+      cache.set("x", :x2)
+      cache.count.should == 2
+    end
+  end
+
+  describe "#delete" do
+
+    it "removes the item from the cache" do
+      cache.limit = 1
+      cache.count.should == 0
+      cache.set("x", :x)
+      cache.get("x").should == :x
+      cache.count.should == 1
+      cache.delete("x").should == :x
+      cache.count.should == 0
+      cache.get("x").should be_nil
+    end
+  end
+
+  describe "#get" do
+
+    it "returns an item for key when present in the cache" do
+      cache.limit = 1
+      cache.set("x", :x)
+      cache.get("x").should == :x
+    end
+
+    it "returns nil when key is not in the cache" do
+      cache.get("x").should be_nil
+    end
+  end
+
+  describe "#limit" do
+
+    it "returns the maximum number of items in cache" do
+      cache.limit = 500
+      cache.limit.should == 500
+    end
+
+    it "has no default value" do
+      LRUCache.new.limit.should be_nil
+    end
+  end
+
+  describe "#limit=" do
+
+    it "does not accept numbers less than 1" do
+      expect { cache.limit = 0 }.to raise_error LRUCache::InvalidLimitError
+    end
+
+    it "sets the maximum number of items in cache" do
+      cache.limit = 500
+      cache.limit.should == 500
+    end
+
+    it "drops items from cache if limit is newly less than count" do
+      cache.limit = 3
+
+      cache.set("x", :x)
+      cache.set("y", :y)
+      cache.set("z", :z)
+
+      cache.count.should == 3
+
+      cache.limit = 2
+      cache.count.should == 2
+
+      cache.get("x").should be_nil
+      cache.get("y").should == :y
+      cache.get("z").should == :z
+    end
+  end
+
+  describe "#set" do
+
+    it "puts an item in the cache" do
+      cache.limit = 1
+      cache.get("x").should be_nil
+      cache.set("x", :x)
+      cache.get("x").should == :x
+    end
+
+    it "will raise an exception when limit is not set" do
+      expect { LRUCache.new.set("x", :x) }.to raise_error LRUCache::NoLimitError
+    end
+  end
+
+  describe "#[]" do
+
+    it "is an alias for get" do
+      cache.method(:[]).should == cache.method(:get)
+    end
+  end
+
+  describe "#[]=" do
+
+    it "is an alias for set" do
+      cache.method(:[]=).should == cache.method(:set)
+    end
+  end
+end

data/spec/thread_safe_spec.rb

@@ -0,0 +1,7 @@
+require "lru_cache/thread_safe"
+
+describe LRUCache::ThreadSafe do
+
+  # TODO: Do something clever to demonstrate that mutex synchronization ensures thread safety.
+
+end

metadata

@@ -0,0 +1,69 @@
+--- !ruby/object:Gem::Specification
+name: lru_cache
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+  prerelease: 
+platform: ruby
+authors:
+- Brendan Baldwin
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-11-10 00:00:00.000000000 Z
+dependencies:
+- !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'
+description: its performant / constant o(1)
+email:
+- brendan@usergenic.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .rspec
+- LICENSE
+- README.markdown
+- lib/lru_cache.rb
+- lib/lru_cache/thread_safe.rb
+- lru_cache.gemspec
+- spec/lru_cache_spec.rb
+- spec/thread_safe_spec.rb
+homepage: https://github.com/brendan/lru_cache
+licenses: []
+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.24
+signing_key: 
+specification_version: 3
+summary: a simple LRU cache in ruby that uses a doubley-linked list and a hash
+test_files: []