weak_hash 1.0.0

data/.document

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

data/.gitignore

@@ -0,0 +1,21 @@
+## MAC OS
+.DS_Store
+
+## TEXTMATE
+*.tmproj
+tmtags
+
+## EMACS
+*~
+\#*
+.\#*
+
+## VIM
+*.swp
+
+## PROJECT::GENERAL
+coverage
+rdoc
+pkg
+
+## PROJECT::SPECIFIC

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Emmanuel Oga
+
+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.rdoc

@@ -0,0 +1,47 @@
+= weak_hash
+
+A Weak Hash is a hash that stores references to objects
+while retaining the garbage collector's ability to
+reclaim the object.
+
+The API is similar to that of a Hash:
+
+object = Object.new
+
+wh = WeakHash.new
+wh["value"] = object
+
+wh["value"]        # => object
+
+object = nil
+wh["value"]        # => object (if garbage collector has not collected the object yet)
+
+GC.start; GC.start # very probable that the object is collected now.
+
+wh["value"]        # => nil
+
+== Credits
+
+This gem is based on two blog posts by Mauricio Fernández, including code by
+him and Robert Klemme:
+
+http://eigenclass.org/hiki/weakhash+and+weakref
+http://eigenclass.org/hiki/deferred-finalizers-in-Ruby
+
+I wrapped this on a gem for convenience, replaced a Thread.critical call
+on SimpleWeakHash with a mutex (for making it work with 1.9) and
+added some very simple specs.
+
+== Note on Patches/Pull Requests
+
+* Fork the project.
+* Make your feature addition or bug fix.
+* Add tests for it. This is important so I don't break it in a
+  future version unintentionally.
+* Commit, do not mess with rakefile, version, or history.
+  (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
+* Send me a pull request. Bonus points for topic branches.
+
+== Copyright
+
+Copyright (c) 2010 Emmanuel Oga. See LICENSE for details.

data/Rakefile

@@ -0,0 +1,45 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "weak_hash"
+    gem.summary = %Q{Weak Hash implementation}
+    gem.description = %Q{a hash that stores objects until they are garbage collected}
+    gem.email = "EmmanuelOga@gmail.com"
+    gem.homepage = "http://github.com/EmmanuelOga/weak_hash"
+    gem.authors = ["Emmanuel Oga"]
+    gem.add_development_dependency "rspec", ">= 1.2.9"
+    gem.add_development_dependency "yard", ">= 0"
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler"
+end
+
+require 'spec/rake/spectask'
+Spec::Rake::SpecTask.new(:spec) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.spec_files = FileList['spec/**/*_spec.rb']
+end
+
+Spec::Rake::SpecTask.new(:rcov) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.pattern = 'spec/**/*_spec.rb'
+  spec.rcov = true
+end
+
+task :spec => :check_dependencies
+
+task :default => :spec
+
+begin
+  require 'yard'
+  YARD::Rake::YardocTask.new
+rescue LoadError
+  task :yardoc do
+    abort "YARD is not available. In order to run yardoc, you must: sudo gem install yard"
+  end
+end

data/VERSION

@@ -0,0 +1 @@
+1.0.0

data/lib/rk_weak_hash.rb

@@ -0,0 +1,42 @@
+# NOTE:
+# RKWeakHash is based on two blog posts by Mauricio Fernández,
+# including code by him and Robert Klemme. The RKWeakHash
+# class is attributed to Robert (hence the RK prefix).
+
+require 'delegate'
+require 'weakref'
+
+RKWeakHash = DelegateClass(Hash)
+
+# This is a weak hash similar in semantics to SimpleWeakHash but
+# implemented using the standard libraries 'delegate' and 'weakref'.
+# In theory using DelegateClass and WeakRef should make this work
+# slower than the alternative implementation (SimpleWeakHash).
+class RKWeakHash
+
+  # note: I added this method so I could provide a default value
+  # (a new Hash) instead of demanding it from the user.
+  def initialize(cache = Hash.new)
+    super(cache)
+  end
+
+  def []=(key,val) # !> method redefined; discarding old []=
+    __getobj__[WeakRef.new(key)] = WeakRef.new(val)
+  end
+
+  def [](key) # !> method redefined; discarding old []
+    __getobj__[WeakRef.new(key)]
+  end
+
+  def each(&b) # !> method redefined; discarding old each
+    __getobj__.each do |k,v|
+      b[k.__getobj__, v.__getobj__] unless k.__getobj__.nil?
+    end
+    self
+  end
+
+  def cleanup
+    delete_if {|k,v| k.__getobj__.nil?}
+  end
+end
+

data/lib/simple_weak_hash.rb

@@ -0,0 +1,68 @@
+# NOTE:
+# SimpleWeakHash is based on two blog posts by Mauricio Fernández,
+# including code by him and Robert Klemme. SimpleWeakHash was created by
+# Mauricio Fernández.
+
+# SimpleWeakHash is a weak hash with more relaxed semantics than a WeakHash:
+#
+# * the key->value associations can disappear at any time
+# * all existent associations are wiped out when the GC kicks in
+#
+# In particular, it removes the tacit requirement that an association remain
+# alive as long as there is an external reference (i.e. outside the hash) to
+# either the key or the value. The advantage is increased speed.
+#
+class SimpleWeakHash
+
+  def initialize
+    @valid = false
+    @mutex = Mutex.new
+  end
+
+  # retrieve object with the given key
+  # returns the object if present and it has not been
+  # garbage collected. Otherwise it returns nil.
+  def [](key)
+    __get_hash__[key]
+  end
+
+  # "store" object into the weak hash using the given key
+  # a weak reference is stored so the object stays references
+  # as long as it isn't garbage collected.
+  def []=(key, value)
+    __get_hash__[key] = value
+  end
+
+  # an addition to Mauricio's implementation,
+  # simple method that act's like Hash#update method.
+  def update(hash)
+    hash.each { |key, val| send(:[]=, key, val) }
+    self
+  end
+
+private
+
+  # This used to use Thread.critical, but that's no longer available on ruby 1.9
+  # so I replaced it with a Mutex.
+  def __get_hash__
+    @mutex.synchronize do
+      set_internal_hash unless @valid
+      recover_hash
+    end
+  end
+
+  def recover_hash
+    ObjectSpace._id2ref(@hash_id)
+  rescue RangeError
+    set_internal_hash
+    ObjectSpace._id2ref(@hash_id)
+  end
+
+  def set_internal_hash
+    hash = {}
+    @hash_id = hash.object_id
+    @valid = true
+    ObjectSpace.define_finalizer hash, lambda { |id| @valid = id != @hash_id }
+    hash = nil
+  end
+end

data/lib/weak_hash.rb

@@ -0,0 +1,80 @@
+# NOTE:
+# WeakHash is based on two blog posts by Mauricio Fernández,
+# including code by him and Robert Klemme. WeakHash was created by
+# Mauricio Fernández.
+
+# This is a Hash where an association is removed as soon as either the key or
+# the value are GCed.
+#
+# When storing a value, the key is cloned and used in an internal hash
+# (the cache) referetting to the object_id of the corresponding value.
+#
+class WeakHash
+
+  attr_reader :cache
+
+  def initialize( cache = Hash.new )
+    @cache = cache
+    @key_map = {}
+    @rev_cache = Hash.new{|h,k| h[k] = {}}
+
+    @reclaim_value = lambda do |value_id|
+      if @rev_cache.has_key? value_id
+        @rev_cache[value_id].each_key{|key| @cache.delete key}
+        @rev_cache.delete value_id
+      end
+    end
+
+    @reclaim_key = lambda do |key_id|
+      if @key_map.has_key? key_id
+        @cache.delete @key_map[key_id]
+      end
+    end
+  end
+
+  # retrieve object with the given key
+  # returns the object if present and it has not been
+  # garbage collected. Otherwise it returns nil.
+  def []( key )
+    value_id = @cache[key]
+    return ObjectSpace._id2ref(value_id) unless value_id.nil?
+    nil
+  rescue RangeError
+    nil
+  end
+
+  # "store" object into the weak hash using the given key
+  # a weak reference is stored so the object stays references
+  # as long as it isn't garbage collected.
+  def []=( key, value )
+    case key
+    when Fixnum, Symbol, true, false
+      key2 = key
+    else
+      key2 = key.dup
+    end
+
+    @rev_cache[value.object_id][key2] = true
+    @cache[key2] = value.object_id
+    @key_map[key.object_id] = key2
+
+    begin
+      ObjectSpace.define_finalizer(value, @reclaim_value)
+    rescue ArgumentError
+      # Some objects will never be reclaimed by ObjectSpace, e.g. Fixnums
+    end
+
+    begin
+      ObjectSpace.define_finalizer(key, @reclaim_key)
+    rescue ArgumentError
+      # Some objects will never be reclaimed by ObjectSpace, e.g. Fixnums
+    end
+  end
+
+  # an addition to Mauricio's implementation,
+  # simple method that act's like Hash#update method.
+  def update(hash)
+    hash.each { |key, val| send(:[]=, key, val) }
+    self
+  end
+end

data/scripts/benchmark.rb

@@ -0,0 +1,61 @@
+require 'benchmark'
+
+$LOAD_PATH.unshift File.expand_path(File.join(File.dirname(__FILE__), "../lib"))
+
+require 'weak_hash'
+require 'rk_weak_hash'
+require 'simple_weak_hash'
+
+TIMES = 100_000
+
+Benchmark.bmbm(30) do |bm|
+
+  wh1 = RKWeakHash.new({})
+  wh2 = WeakHash.new
+  wh3 = SimpleWeakHash.new
+
+  bm.report("RKWeakHash init")    { TIMES.times{ |i| wh1[i.to_s] = i.to_s } }
+  bm.report("WeakHash init")      { TIMES.times{ |i| wh2[i.to_s] = i.to_s } }
+  bm.report("SimpleWeakHash init"){ TIMES.times{ |i| wh3[i.to_s] = i.to_s } }
+
+  vals = (0..100).inject({}) { |s,x| s[x] = x; s }
+
+  bm.report("RKWeakHash lookup") do
+    wh1.update(vals)
+    vals.each{|i| wh1[i]}
+  end
+
+  bm.report("WeakHash lookup") do
+    wh2.update(vals)
+    vals.each{|i| wh2[i]}
+  end
+
+  bm.report("SimpleWeakHash lookup") do
+    wh3.update(vals)
+    vals.each{|i| wh3[i]}
+  end
+end
+
+__END__
+▸ ruby -v
+ruby 1.9.1p376 (2009-12-07 revision 26041) [x86_64-linux]
+
+▸ uname -a
+Linux goingmerry 2.6.32-ARCH #1 SMP PREEMPT Thu Jan 7 22:28:29 CET 2010 x86_64 AMD Athlon(tm) 64 X2 Dual Core Processor 6000+ AuthenticAMD GNU/Linux
+
+Rehearsal -----------------------------------------------------------------
+RKWeakHash init                 6.680000   0.070000   6.750000 (  6.771348)
+WeakHash init                   2.170000   0.030000   2.200000 (  2.209112)
+SimpleWeakHash init             0.530000   0.000000   0.530000 (  0.533288)
+RKWeakHash lookup               0.000000   0.000000   0.000000 (  0.000874)
+WeakHash lookup                 0.010000   0.000000   0.010000 (  0.003856)
+SimpleWeakHash lookup           0.000000   0.000000   0.000000 (  0.000454)
+-------------------------------------------------------- total: 9.490000sec
+
+                                    user     system      total        real
+RKWeakHash init                12.980000   0.050000  13.030000 ( 13.025488)
+WeakHash init                   2.750000   0.020000   2.770000 (  2.771461)
+SimpleWeakHash init             0.300000   0.000000   0.300000 (  0.307679)
+RKWeakHash lookup               0.000000   0.000000   0.000000 (  0.000906)
+WeakHash lookup                 0.010000   0.000000   0.010000 (  0.003932)
+SimpleWeakHash lookup           0.000000   0.000000   0.000000 (  0.000408)

data/spec/rk_weak_hash_spec.rb

@@ -0,0 +1,16 @@
+require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
+
+describe RKWeakHash do
+  before do
+    @key = "key"
+    @value = "value"
+    @weak_hash = RKWeakHash.new
+
+    @weak_hash[@key] = @value
+  end
+
+  it "stores objects until a garbage collection happens" do
+    GC.start; GC.start
+    @weak_hash[@key].should_not == @value
+  end
+end

data/spec/simple_weak_hash_spec.rb

@@ -0,0 +1,16 @@
+require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
+
+describe SimpleWeakHash do
+  before do
+    @key = "key"
+    @value = "value"
+    @weak_hash = SimpleWeakHash.new
+
+    @weak_hash[@key] = @value
+  end
+
+  it "stores objects until a garbage collection happens" do
+    GC.start; GC.start
+    @weak_hash[@key].should_not == @value
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,10 @@
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+require 'weak_hash'
+require 'rk_weak_hash'
+require 'simple_weak_hash'
+require 'spec'
+require 'spec/autorun'
+
+Spec::Runner.configure do |config|
+end

data/spec/weak_hash_spec.rb

@@ -0,0 +1,31 @@
+require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
+
+describe WeakHash do
+  before do
+    @key = "key"
+    @value = "value"
+    @weak_hash = WeakHash.new
+
+    @weak_hash[@key] = @value
+  end
+
+  it "stores objects until the key is garbage collected" do
+    1.upto(10) do
+      @weak_hash[@key].should == @value
+    end
+
+    @key = nil
+    GC.start; GC.start
+    @weak_hash[@key].should_not == @value
+  end
+
+  it "stores objects until the value is garbage collected" do
+    1.upto(10) do
+      @weak_hash[@key].should == @value
+    end
+
+    @value = nil
+    GC.start; GC.start
+    @weak_hash[@key].should_not == @value
+  end
+end

metadata

@@ -0,0 +1,104 @@
+--- !ruby/object:Gem::Specification 
+name: weak_hash
+version: !ruby/object:Gem::Version 
+  prerelease: false
+  segments: 
+  - 1
+  - 0
+  - 0
+  version: 1.0.0
+platform: ruby
+authors: 
+- Emmanuel Oga
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-03-08 00:00:00 -03:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 1
+        - 2
+        - 9
+        version: 1.2.9
+  type: :development
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: yard
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id002
+description: a hash that stores objects until they are garbage collected
+email: EmmanuelOga@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- LICENSE
+- README.rdoc
+files: 
+- .document
+- .gitignore
+- LICENSE
+- README.rdoc
+- Rakefile
+- VERSION
+- lib/rk_weak_hash.rb
+- lib/simple_weak_hash.rb
+- lib/weak_hash.rb
+- scripts/benchmark.rb
+- spec/rk_weak_hash_spec.rb
+- spec/simple_weak_hash_spec.rb
+- spec/spec_helper.rb
+- spec/weak_hash_spec.rb
+has_rdoc: true
+homepage: http://github.com/EmmanuelOga/weak_hash
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.6
+signing_key: 
+specification_version: 3
+summary: Weak Hash implementation
+test_files: 
+- spec/rk_weak_hash_spec.rb
+- spec/spec_helper.rb
+- spec/weak_hash_spec.rb
+- spec/simple_weak_hash_spec.rb