fifo-cache 0.1.0

data/.document

@@ -0,0 +1,5 @@
+lib/**/*.rb
+bin/*
+- 
+features/**/*.feature
+LICENSE.txt

data/Gemfile

@@ -0,0 +1,12 @@
+source "http://rubygems.org"
+# Add dependencies required to use your gem here.
+# Example:
+   gem "depq", ">= 0.4"
+   gem "hash-utils", ">= 0.7.0"
+
+# Add dependencies to develop your gem here.
+# Include everything needed to run rake, tests, features, etc.
+group :development do
+  gem "bundler", "~> 1.0.0"
+  gem "jeweler", "~> 1.5.2"
+end

data/Gemfile.lock

@@ -0,0 +1,20 @@
+GEM
+  remote: http://rubygems.org/
+  specs:
+    depq (0.4)
+    git (1.2.5)
+    hash-utils (0.7.0)
+    jeweler (1.5.2)
+      bundler (~> 1.0.0)
+      git (>= 1.2.5)
+      rake
+    rake (0.8.7)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bundler (~> 1.0.0)
+  depq (>= 0.4)
+  hash-utils (>= 0.7.0)
+  jeweler (~> 1.5.2)

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2010 - 2011 Martin Kozák (martinkozak@martinkozak.net)
+
+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,77 @@
+FIFO Cache
+==========
+
+**FIFO Cache** is fast hash-like fixed size cache class with FIFO 
+functionality which removes oldest or less accessed records based on 
+[implicit heap][1].
+
+### Examples and Tracking & Handicap Factor
+
+Cache allows track both hits and puts and remove items from cache 
+according these statistics. They are turned off by default, but can be 
+turned on by setting `#factor` (or `:factor` in costructor) to another 
+value than `0`.
+
+*Handicap factor* is multiplier of the minimal hits count of all items 
+in the cache. It's important set it in some cases.
+
+If tracking is turned on and no handicap factor is explicitly set, 
+handicap 1 is assigned to new items. It's safe, but not very acceptable 
+because cache will become static after filling. So it's necessary (or at 
+least higly reasonable) to set priority weighting factor to number 
+higher than 1 according dynamics of your application.
+
+Usage is simple (examples here are for demonstration purposes written
+without factor set):
+    
+    require "fifocache"
+    
+    cache = Fifocache::new(3, :puts => true)   # or 300000, od sure :-)
+    cache[:alfa] = 'alfa'
+    cache[:beta] = 'beta'
+    cache[:gama] = 'gama'
+    cache[:delta] = 'delta'     # in this moment, :alfa is removed
+    
+But multiple addings are tracked, so subsequent call:
+
+    cache[:beta] = 'beta'      # :beta, :gama, :delta in cache
+    cache[:alfa] = 'alfa'      # :beta, :delta, :alfa in cache
+    
+…will cause `:gama` will be removed, not `:beta` because `:beta` is 
+fresher now. If hits tracking is turned on:
+
+    cache.hits = true           # you can do it in costructor too
+    
+    puts cache[:delta]          # cache hit
+    cache[:gama] = 'gama'       # :beta, :delta, :gama in cache
+    
+…because `:beta` has been put-in two times, `:delta` has been hit 
+recently, so `:alfa` is less accessed row and has been removed. In case 
+of hits tracking turned off, `:delta` would be removed of sure and 
+`:alfa` kept.
+    
+Changing size of existing cache is possible although reducing the size
+is generally rather slow because of necessity to remove all redundant 
+"oldest" rows.
+    
+
+Contributing
+------------
+
+1. Fork it.
+2. Create a branch (`git checkout -b 20101220-my-change`).
+3. Commit your changes (`git commit -am "Added something"`).
+4. Push to the branch (`git push origin 20101220-my-change`).
+5. Create an [Issue][2] with a link to your branch.
+6. Enjoy a refreshing Diet Coke and wait.
+
+
+Copyright
+---------
+
+Copyright © 2011 [Martin Kozák][3]. See `LICENSE.txt` for
+further details.
+
+[1]: http://www.cs.princeton.edu/courses/archive/spr09/cos423/Lectures/i-heaps.pdf
+[2]: http://github.com/martinkozak/qrpc/issues
+[3]: http://www.martinkozak.net/

data/Rakefile

@@ -0,0 +1,37 @@
+# encoding: utf-8
+require 'rubygems'
+require 'bundler'
+begin
+  Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+  $stderr.puts e.message
+  $stderr.puts "Run `bundle install` to install missing gems"
+  exit e.status_code
+end
+require 'rake'
+
+require 'jeweler'
+Jeweler::Tasks.new do |gem|
+  # gem is a Gem::Specification... see http://docs.rubygems.org/read/chapter/20 for more options
+  gem.name = "fifo-cache"
+  gem.homepage = "http://github.com/martinkozak/fifo-cache"
+  gem.license = "MIT"
+  gem.summary = 'Fast hash-like fixed size cache class with FIFO functionality which removes oldest or less accessed records based on implicit heap.'
+  gem.email = "martinkozak@martinkozak.net"
+  gem.authors = ["Martin Kozák"]
+  # Include your dependencies below. Runtime dependencies are required when using your gem,
+  # and development dependencies are only needed for development (ie running rake tasks, tests, etc)
+  #  gem.add_runtime_dependency 'jabber4r', '> 0.1'
+  #  gem.add_development_dependency 'rspec', '> 1.2.3'
+end
+Jeweler::RubygemsDotOrgTasks.new
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "qrpc #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

@@ -0,0 +1 @@
+0.1.0

data/lib/fifocache.rb

@@ -0,0 +1,284 @@
+# encoding: utf-8
+# (c) 2010-2011 Martin Kozák (martinkozak@martinkozak.net)
+
+require "hash-utils/object"
+require "depq"
+
+##
+# Represents cache object accessible by similar way as hash,
+# but with fixed capacity with FIFO funcionality.
+#
+# It's useful for limited size caches. Oldest cache records are removed.
+# Also can be used by dynamic mode, so the less putted or less accessed 
+# (or both) cache records are removed instead of the oldest records in 
+# that cases.
+#
+# For touches tracking utilizes implicit heap queue.
+#
+    
+class Fifocache
+
+    @data
+    @queue
+    @counts
+    
+    ##
+    # Integer overflow protection.
+    #
+    
+    INFINITY = 1.0/0
+    
+    ##
+    # Contains maximal size of the cache.
+    # @return [Integer] maximal size of the cache
+    #
+    
+    attr_reader :size
+    @size
+    
+    ##
+    # Indicates puts should be tracked.
+    # @return [Boolean]
+    #
+    
+    attr_accessor :puts
+    @puts
+    
+    ##
+    # Indicates hits should be tracked.
+    # @return [Boolean]
+    #
+    
+    attr_accessor :hits
+    @hits
+    
+    ##
+    # Indicates new items handicap factor.
+    #
+    # Handicap factor is multiplier of the min hits count of all items in 
+    # the cache. It's important set it in some cases. See {#[]=}.
+    #
+    # @return [Float]
+    # @see #[]=
+    #
+    
+    attr_accessor :factor
+    @factor
+
+    ##
+    # Constructor. Initializes cache to appropriate size.
+    #
+    # @param [Integer] site size of the cache
+    # @param [Hash] opts tracking options
+    # @option opts [Boolean] :puts indicates, puts should be tracked
+    # @option opts [Boolean] :hits indicates, hits should be tracked
+    # @option opts [Float, Integer] :factor indicates new items priority correction factor
+    #
+    
+    def initialize(size, opts = {  })
+        @data = { }
+        @queue = Depq::new
+        @counts = { }
+
+        @size = size
+        @puts = opts[:puts].to_b
+        @hits = opts[:hits].to_b
+        @factor = opts[:factor].to_f
+    end
+
+    ##
+    # Puts item with key to cache.
+    #
+    # If tracking is turned on and no {#factor} explicitly set, handicap
+    # 1 is assigned to new items. It's safe, but not very acceptable 
+    # because cache will become static after filling. So it's necessary 
+    # (or at least higly reasonable) to set priority weighting factor to 
+    # number higher than 1 according dynamics of your application.
+    #
+    # @param [Object] key item key
+    # @param [Object] item item value
+    # @see #factor
+    #
+    
+    def []=(key, item)
+
+        # Adds to cache
+        
+        if not self.has_key? key
+        
+            # Inserts to tracking structures
+            @data[key] = item
+            locator = @queue.insert(key, __new_priority)
+            @counts[key] = locator
+                
+            # Eventually removes first (last)
+            if self.length > @size
+                self.clean!
+            end
+            
+        elsif @puts
+            self.touch(key)
+        end
+
+    end
+
+    ##
+    # Returns item from cache.
+    #
+    # @param [Object] key item key
+    # @return [Object] item value
+    #
+    
+    def [](key)
+        if @hits
+            self.touch(key)
+        end
+        
+        @data[key]
+    end
+    
+    ##
+    # Indicates key is in cache.
+    #
+    # @param [Object] key item key
+    # @return [Boolean] +true+ it it is, +false+ otherwise
+    #
+    
+    def has_key?(key)
+        @data.has_key? key
+    end
+    
+    alias :"include?" :"has_key?"
+    
+    ##
+    # Touches key in cache.
+    # @param [Object] key item key
+    #
+    
+    def touch(key)
+        locator = @counts[key]
+        priority = locator.priority + 1
+        
+        if priority != self.class::INFINITY
+            locator.update(key, locator.priority + 1)
+        end
+    end
+    
+    ##
+    # Indicates current size of the cache.
+    # @return [Integer] current size of the cache
+    #
+    
+    def length
+        @data.length
+    end
+    
+    ##
+    # Sets new size.
+    # @param [Integer] size new size
+    #
+    
+    def size=(size)
+        if size < self.length
+            self.clean(self.length - size)
+        end
+    end
+    
+    alias :resize :"size="
+    
+    ##
+    # Removes key.
+    #
+    # @param [Object] key item key
+    # @return [Object] removed item value
+    #
+    
+    def remove(key)
+        if self.has_key? key
+            # Heap queue
+            locator = @counts[key]
+            @queue.delete_locator(locator)
+            
+            # Data holders
+            result = __purge(key)
+        else
+            result = nil
+        end
+            
+        return result
+    end
+    
+    ##
+    # Cleans specified number of slots.
+    # @return [Hash] removed pairs
+    #
+    
+    def clean!(count = 1)
+        result = { }
+        count.times do
+            dkey = @queue.delete_min
+            result[dkey] = __purge(dkey)  
+            
+            if @data.empty?
+                break
+            end
+        end
+        
+        return result
+    end
+    
+    alias :clean :"clean!"
+    
+    ##
+    # Clear whole cache.
+    #
+    
+    def clear!
+        @data.replace({ })
+        @counts.replace({ })
+        @queue.clear
+    end
+    
+    alias :clear :"clear!"
+    
+    ##
+    # Converts to hash.
+    # @return [Hash] cache data
+    #
+    
+    def to_h
+        @data.dup
+    end
+    
+    
+    private
+    
+    ##
+    # Purges item from data holders.
+    #
+    
+    def __purge(key)
+        result = @data[key]
+        @data.delete(key)
+        @counts.delete(key)
+
+        return result
+    end
+    
+    ##
+    # Returns new priority.
+    #
+    
+    def __new_priority
+        if (@puts or @hits) and (@factor != 0)
+            min = @queue.find_min_locator
+            priority = min.nil? ? 1 : (min.priority * @factor)
+        else
+            priority = 1
+        end
+        
+        return priority
+    end
+    
+end
+    

data/qrpc.gemspec

@@ -0,0 +1,56 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run 'rake gemspec'
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{qrpc}
+  s.version = "0.1.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Martin Kozák"]
+  s.date = %q{2011-02-10}
+  s.email = %q{martinkozak@martinkozak.net}
+  s.extra_rdoc_files = [
+    "LICENSE.txt",
+    "README.md"
+  ]
+  s.files = [
+    ".document",
+    "Gemfile",
+    "Gemfile.lock",
+    "LICENSE.txt",
+    "README.md",
+    "Rakefile",
+    "VERSION",
+    "lib/fifocache.rb",
+    "test"
+  ]
+  s.homepage = %q{http://github.com/martinkozak/fifo-cache}
+  s.licenses = ["MIT"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.5.1}
+  s.summary = %q{Fast hash-like fixed size cache class with FIFO functionality which removes oldest or less accessed records based on implicit heap.}
+
+  if s.respond_to? :specification_version then
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
+      s.add_runtime_dependency(%q<depq>, [">= 0.4"])
+      s.add_runtime_dependency(%q<hash-utils>, [">= 0.7.0"])
+      s.add_development_dependency(%q<bundler>, ["~> 1.0.0"])
+      s.add_development_dependency(%q<jeweler>, ["~> 1.5.2"])
+    else
+      s.add_dependency(%q<depq>, [">= 0.4"])
+      s.add_dependency(%q<hash-utils>, [">= 0.7.0"])
+      s.add_dependency(%q<bundler>, ["~> 1.0.0"])
+      s.add_dependency(%q<jeweler>, ["~> 1.5.2"])
+    end
+  else
+    s.add_dependency(%q<depq>, [">= 0.4"])
+    s.add_dependency(%q<hash-utils>, [">= 0.7.0"])
+    s.add_dependency(%q<bundler>, ["~> 1.0.0"])
+    s.add_dependency(%q<jeweler>, ["~> 1.5.2"])
+  end
+end
+

data/test

@@ -0,0 +1,37 @@
+#!/usr/bin/env ruby
+# encoding: utf-8
+
+$:.push("./lib")
+require "fifocache"
+
+
+cache = Fifocache::new(100000, :puts => false, :factor => 0)
+200000.times do |i|
+    cache[i] = i
+end
+
+exit
+
+cache = Fifocache::new(3, :puts => true)
+cache[:alfa] = 'alfa'
+cache[:beta] = 'beta'
+cache[:gama] = 'gama'
+cache[:delta] = 'delta'     # in this moment, :alfa is removed
+
+puts cache.to_h.inspect
+
+cache[:beta] = 'beta'      # :beta, :gama, :delta in cache
+cache[:alfa] = 'alfa'      # :beta, :delta, :alfa in cache
+
+puts cache.to_h.inspect
+
+cache.hits = true           # you can do it in costructor too   
+puts cache[:delta]          # cache hit
+cache[:gama] = 'gama'       # :beta, :delta, :gama in cache
+
+puts cache.to_h.inspect
+
+cache.resize(0)
+
+puts cache.to_h.inspect
+

metadata

@@ -0,0 +1,112 @@
+--- !ruby/object:Gem::Specification 
+name: fifo-cache
+version: !ruby/object:Gem::Version 
+  prerelease: 
+  version: 0.1.0
+platform: ruby
+authors: 
+- "Martin Koz\xC3\xA1k"
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-02-10 00:00:00 +01:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: depq
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0.4"
+  type: :runtime
+  prerelease: false
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: hash-utils
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 0.7.0
+  type: :runtime
+  prerelease: false
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: bundler
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        version: 1.0.0
+  type: :development
+  prerelease: false
+  version_requirements: *id003
+- !ruby/object:Gem::Dependency 
+  name: jeweler
+  requirement: &id004 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        version: 1.5.2
+  type: :development
+  prerelease: false
+  version_requirements: *id004
+description: 
+email: martinkozak@martinkozak.net
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- LICENSE.txt
+- README.md
+files: 
+- .document
+- Gemfile
+- Gemfile.lock
+- LICENSE.txt
+- README.md
+- Rakefile
+- VERSION
+- lib/fifocache.rb
+- qrpc.gemspec
+- test
+has_rdoc: true
+homepage: http://github.com/martinkozak/fifo-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 
+      hash: 2127215493640234633
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.5.1
+signing_key: 
+specification_version: 3
+summary: Fast hash-like fixed size cache class with FIFO functionality which removes oldest or less accessed records based on implicit heap.
+test_files: []
+