ruby-cache 0.3.0

data/Manual.rd

@@ -0,0 +1,155 @@
+=begin
+
+= Ruby/Cache Reference Manual
+
+This is the reference manual for
+((<"Ruby/Cache"|URL:http://www.nongnu.org/pupa/ruby-cache.html>)) version 0.3.
+
+Ruby/Cache provides a class for caching arbitrary objects based on LRU
+algorithm. The class (({Cache})) looks like a variant of (({Hash})), and,
+in fact, (({Cache})) supports most of the methods of (({Hash})).
+
+To control how to invalidate excessive objects, Ruby/Cache allows you to
+adjust the limit by four factors: the size of an object, the total size
+of objects, the number of objects, and a last access time.
+
+== Class:
+
+Cache
+
+== Superclass:
+
+Object
+
+== Included module:
+
+Enumerable
+
+== Class methods:
+
+--- Cache.version
+    Return the version number.
+
+--- Cache.new([max_obj_size, max_size, max_num, expiration, &hook])
+--- Cache.new(hash, &hook)
+    Create a new Cache object.
+    
+    ((|max_obj_size|)) is the maximum size per object allowed to be cached.
+    The size is currently determined by (({obj.to_s.size})).
+    
+    ((|max_size|)) is the maximum size of all objects allowed to be cached.
+    The size is currently determined by the sum of the sizes of all objects.
+    
+    ((|max_num|)) is the maximum number of cached objects.
+    
+    ((|expiration|)) is the maximum life time of each object after the last
+    access time, and is specified by seconds.
+    
+    ((|hook|)) is called whenever an object is invalidated, in the form
+    (({hook(key, value)})). So you can use ((|hook|)) for cleanups.
+    
+    If the latter form is used, ((|hash|)) must be a Hash object, and it
+    represents keyword arguments. ((|hash|)) can have any combination of
+    these keys: (({:max_obj_size})), (({:max_size})), (({:max_num})) and
+    (({:expiration})). The meanings are the same as above.
+
+== Methods:
+
+--- max_obj_size
+    Return the maximum size per object.
+
+--- max_size
+    Return the maximum size of all objects.
+
+--- max_num
+    Return the maximum number of objects.
+
+--- expiration
+    Return the maximum life time.
+
+--- cached?(key)
+--- include?(key)
+--- member?(key)
+--- key?(key)
+--- has_key?(key)
+    Return (({true})), if the key ((|key|)) is cached.
+
+--- cached_value?(val)
+--- has_value?(val)
+--- value?(val)
+    Return (({true})), if the value ((|val|)) is cached.
+
+--- index(val)
+    Return the key corresponding to the value ((|val|)), if any. Otherwise
+    return (({nil})).
+
+--- keys
+    Return an array of keys.
+
+--- values
+    Return an array of cached objects.
+
+--- length
+--- size
+    Return the number of cached objects.
+
+--- to_hash
+    Return keys and cached objects as a Hash object.
+
+--- invalidate(key)
+--- invalidate(key) {|key| ... }
+--- delete(key)
+--- delete(key) {|key| ... }
+    Invalidate a cached object indexed by the key ((|key|)), and return
+    the object. If the key isn't present, return (({nil})). If a block
+    is given and the key is invalid, evaluate the block and return the
+    result.
+
+--- invalidate_all
+--- clear
+    Invalidate all cached objects.
+
+--- expire
+    Invalidate expired objects. This method is often called from other methods
+    automatically, so you wouldn't have to call it explicitly.
+
+--- self[key]
+    Return a cached object corresponding to the key ((|key|)). If the key
+    isn't found, return (({nil})).
+
+--- self[key]=value
+--- store(key, value)
+    Cache the object ((|value|)) with the key ((|key|)), if possible.
+    Return ((|value|)).
+
+--- each_pair {|key, obj| ... }
+--- each {|key, obj| ... }
+    Evaluate the block with each key and a cached object corresponding to
+    the key.
+
+--- each_key {|key| ... }
+    Evaluate the block with each key.
+
+--- each_value {|obj| ... }
+    Evaluate the block with each cached object.
+
+--- empty?
+    Return (({true})), if no object is cached.
+
+--- fetch(key[, default])
+--- fetch(key) {|key| ... }
+    Return a cached object corresponding to the key ((|key|)).
+    If the key isn't found and ((|default|)) is given, cache ((|default|))
+    as a object corresponding to ((|key|)) and return ((|default|)).
+    Or, if the key isn't found and a block is given, evaluate the block
+    with ((|key|)), cache the result, and return it.
+    
+    Normally, you should use this method rather than (({self[key]})) plus
+    (({self[key]=value})), because this is safer.
+
+--- statistics
+    Return an array of the total size of cached objects, the number of
+    cached objects, the number of cache hits, and the number of cache
+    misses.
+
+=end

data/README.rd

@@ -0,0 +1,53 @@
+=begin
+= Ruby/Cache 0.3
+== What is Ruby/Cache
+
+Ruby/Cache is a library for caching objects based on the LRU algorithm
+for Ruby. The official page is
+((<URL:http://www.nongnu.org/pupa/ruby-cache.html>)).
+
+== How to install
+
+(1) $ ruby install.rb config
+(2) $ ruby install.rb setup
+(3) $ ruby install.rb install
+
+== How to use
+
+Here is a simple usage:
+
+ require 'cache'
+
+ cache = Cache.new
+ cache['foo'] = 'bar'
+ p cache['foo']
+ cache.invalidate('foo')
+ p cache['foo']
+
+ =>
+
+ "bar"
+ nil
+
+This is a more complicated example:
+
+ # Set the maximum number of cached objects and the expiration time to
+ # 100 and 60 (secs), respectively.
+ cache = Cache.new(nil, nil, 100, 60)
+ puts 'I will generate a prime number greater than any given number!'
+ while true
+   puts 'Input an integer: '
+   i = gets.to_i
+   puts cache.fetch(i) { generate_prime_greater_than(i) }
+ end
+
+== License
+
+You may redistribute it and/or modify it under the same term as Ruby's.
+
+== Author
+
+((<Yoshinori K. Okuji|URL:http://www.enbug.org/>))
+((<<okuji@enbug.org>|URL:mailto:okuji@enbug.org>))
+
+=end

data/Rakefile

@@ -0,0 +1,21 @@
+require 'rubygems'
+require 'rake/gempackagetask'
+
+spec = Gem::Specification.new do |s|
+  s.name = "ruby-cache"
+  s.version = "0.3.0"
+  s.summary = "Ruby/Cache is a library for caching objects based on the LRU algorithm for Ruby"
+  s.author = "Yoshinori K. Okuji"
+  s.email = "okuji@enbug.org"
+  s.homepage = "http://www.enbug.org/"
+  s.description = s.summary
+  s.rubyforge_project = "N/A"
+  s.has_rdoc = true
+  files = Dir.glob("{lib,sample}/*")
+  files << 'README.rd' << 'Manual.rd' << 'Rakefile'
+  s.files = files
+end
+
+Rake::GemPackageTask.new(spec) do |pkg|
+  pkg.need_zip = true
+end

data/lib/cache.rb

@@ -0,0 +1,296 @@
+#! /usr/bin/env ruby
+#
+# Copyright (C) 2002  Yoshinori K. Okuji <okuji@enbug.org>
+#
+# You may redistribute it and/or modify it under the same term as Ruby.
+
+# Cache manager based on the LRU algorithm.
+class Cache
+
+  CACHE_OBJECT = Struct.new('CacheObject', :content, :size, :atime)
+  CACHE_VERSION = '0.3'
+
+  include Enumerable
+  
+  def self.version
+    CACHE_VERSION
+  end
+
+  # initialize(max_obj_size = nil, max_size = nil, max_num = nil,
+  #            expiration = nil, &hook)
+  # initialize(hash, &hook)
+  def initialize(*args, &hook)
+    if args.size == 1 and args[0].kind_of?(Hash)
+      @max_obj_size = @max_size = @max_num = @expiration = nil
+      args[0].each do |k, v|
+	k = k.intern if k.respond_to?(:intern)
+	case k
+	when :max_obj_size
+	  @max_obj_size = v
+	when :max_size
+	  @max_size = v
+	when :max_num
+	  @max_num = v
+	when :expiration
+	  @expiration = v
+	end
+      end
+    else
+      @max_obj_size, @max_size, @max_num, @expiration = args
+    end
+
+    # Sanity checks.
+    if @max_obj_size and @max_size and @max_obj_size > @max_size
+      raise ArgumentError, "max_obj_size exceeds max_size (#{@max_obj_size} > #{@max_size})"
+    end
+    if @max_obj_size and @max_obj_size <= 0
+      raise ArgumentError, "invalid max_obj_size `#{@max_obj_size}'"
+    end
+    if @max_size and @max_size <= 0
+      raise ArgumentError, "invalid max_size `#{@max_size}'"
+    end
+    if @max_num and @max_num <= 0
+      raise ArgumentError, "invalid max_num `#{@max_num}'"
+    end
+    if @expiration and @expiration <= 0
+      raise ArgumentError, "invalid expiration `#{@expiration}'"
+    end
+    
+    @hook = hook
+    
+    @objs = {}
+    @size = 0
+    @list = []
+    
+    @hits = 0
+    @misses = 0
+  end
+
+  attr_reader :max_obj_size, :max_size, :max_num, :expiration
+
+  def cached?(key)
+    @objs.include?(key)
+  end
+  alias :include? :cached?
+  alias :member? :cached?
+  alias :key? :cached?
+  alias :has_key? :cached?
+
+  def cached_value?(val)
+    self.each_value do |v|
+      return true if v == val
+    end
+    false
+  end
+  alias :has_value? :cached_value?
+  alias :value? :cached_value?
+
+  def index(val)
+    self.each_pair do |k,v|
+      return k if v == val
+    end
+    nil
+  end
+
+  def keys
+    @objs.keys
+  end
+
+  def length
+    @objs.length
+  end
+  alias :size :length
+
+  def to_hash
+    @objs.dup
+  end
+
+  def values
+    @objs.collect {|key, obj| obj.content}
+  end
+  
+  def invalidate(key)
+    obj = @objs[key]
+    if obj
+      if @hook
+	@hook.call(key, obj.content)
+      end
+      @size -= obj.size
+      @objs.delete(key)
+      @list.each_index do |i|
+	if @list[i] == key
+	  @list.delete_at(i)
+	  break
+	end
+      end
+    elsif block_given?
+      return yield(key)
+    end
+    obj.content
+  end
+  alias :delete :invalidate
+
+  def invalidate_all()
+    if @hook
+      @objs.each do |key, obj|
+	@hook.call(key, obj)
+      end
+    end
+
+    @objs.clear
+    @list.clear
+    @size = 0
+  end
+  alias :clear :invalidate_all
+  
+  def expire()
+    if @expiration
+      now = Time.now.to_i
+      @list.each_index do |i|
+	key = @list[i]
+	
+	break unless @objs[key].atime + @expiration <= now
+	self.invalidate(key)
+      end
+    end
+#    GC.start
+  end
+	
+  def [](key)
+    self.expire()
+    
+    unless @objs.include?(key)
+      @misses += 1
+      return nil
+    end
+    
+    obj = @objs[key]
+    obj.atime = Time.now.to_i
+
+    @list.each_index do |i|
+      if @list[i] == key
+	@list.delete_at(i)
+	break
+      end
+    end
+    @list.push(key)
+
+    @hits += 1
+    obj.content
+  end
+  
+  def []=(key, obj)
+    self.expire()
+    
+    if self.cached?(key)
+      self.invalidate(key)
+    end
+
+    size = obj.to_s.size
+    if @max_obj_size and @max_obj_size < size
+      if $DEBUG
+	$stderr.puts("warning: `#{obj.inspect}' isn't cached because its size exceeds #{@max_obj_size}")
+      end
+      return obj
+    end
+    if @max_obj_size.nil? and @max_size and @max_size < size
+      if $DEBUG
+	$stderr.puts("warning: `#{obj.inspect}' isn't cached because its size exceeds #{@max_size}")
+      end
+      return obj
+    end
+      
+    if @max_num and @max_num == @list.size
+      self.invalidate(@list.first)
+    end
+
+    @size += size
+    if @max_size
+      while @max_size < @size
+	self.invalidate(@list.first)
+      end
+    end
+
+    @objs[key] = CACHE_OBJECT.new(obj, size, Time.now.to_i)
+    @list.push(key)
+
+    obj
+  end
+
+  def store(key, value)
+    self[key] = value
+  end
+
+  def each_pair
+    @objs.each do |key, obj|
+      yield key, obj.content
+    end
+    self
+  end
+  alias :each :each_pair
+
+  def each_key
+    @objs.each_key do |key|
+      yield key
+    end
+    self
+  end
+
+  def each_value
+    @objs.each_value do |obj|
+      yield obj.content
+    end
+    self
+  end
+
+  def empty?
+    @objs.empty?
+  end
+
+  def fetch(key, default = nil)
+    val = self[key]
+    if val.nil?
+      if default
+	val = self[key] = default
+      elsif block_given?
+	val = self[key] = yield(key)
+      else
+	raise IndexError, "invalid key `#{key}'"
+      end
+    end
+    val
+  end
+  
+  # The total size of cached objects, the number of cached objects,
+  # the number of cache hits, and the number of cache misses.
+  def statistics()
+    [@size, @list.size, @hits, @misses]
+  end
+end
+
+# Run a test, if executed.
+if __FILE__ == $0
+  cache = Cache.new(100 * 1024, 100 * 1024 * 1024, 256, 1)
+  1000.times do
+    key = rand(1000)
+    cache[key] = key.to_s
+  end
+  1000.times do
+    key = rand(1000)
+    puts cache[key]
+  end
+  sleep 1
+  1000.times do
+    key = rand(1000)
+    puts cache[key]
+  end
+  
+  stat = cache.statistics()
+  hits = stat[2]
+  misses = stat[3]
+  ratio = hits.to_f / (hits + misses)
+  
+  puts "Total size:\t#{stat[0]}"
+  puts "Number:\t\t#{stat[1]}"
+  puts "Hit ratio:\t#{ratio * 100}% (#{hits} / #{hits + misses})"
+end

data/sample/filecache.rb

@@ -0,0 +1,51 @@
+# Copyright (C) 2002  Koji Arai
+# Copyright (C) 2002  Yoshinori K. Okuji
+#
+# You may redistribute it and/or modify it under the same term as Ruby.
+
+require 'cache'
+
+class FileCache
+  def initialize(maxopen = 10)
+    @cache = Cache.new(:max_num => maxopen) {|key, obj| obj.close}
+    @saw = {}
+  end
+  
+  def open(file)
+    @cache.fetch(file) do
+      mode = if @saw.key?(file) then 'a' else 'w' end
+      @saw[file] = true
+      File.open(file, mode)
+    end
+  end
+  
+  def close
+    @cache.invalidate_all
+  end
+end
+
+if $0 == __FILE__
+  File.open("/tmp/foo", "w") {|f|
+    1000.times {|i|
+      f.printf("file%03d %d\n", rand(100), i)
+    }
+  }
+  
+  # /tmp/foo
+  # foo001 0
+  # foo099 1
+  # foo050 2
+  # foo001 3
+  #   :
+  #   :
+  
+  cacheout = FileCache.new(10)
+  
+  File.open("/tmp/foo") {|f|
+    while line = f.gets
+      file, number = line.split
+      
+      cacheout.open(file).puts number
+    end
+  }
+end

metadata

@@ -0,0 +1,59 @@
+--- !ruby/object:Gem::Specification 
+name: ruby-cache
+version: !ruby/object:Gem::Version 
+  version: 0.3.0
+platform: ruby
+authors: 
+- Yoshinori K. Okuji
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-11-21 00:00:00 -08:00
+default_executable: 
+dependencies: []
+
+description: Ruby/Cache is a library for caching objects based on the LRU algorithm for Ruby
+email: okuji@enbug.org
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- lib/cache.rb
+- sample/filecache.rb
+- README.rd
+- Manual.rd
+- Rakefile
+has_rdoc: true
+homepage: http://www.enbug.org/
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: N/A
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 3
+summary: Ruby/Cache is a library for caching objects based on the LRU algorithm for Ruby
+test_files: []
+