Initial commit

Author: Brian Durand

.gitignore

@@ -0,0 +1,4 @@
+pkg
+tmp
+rdoc
+*.rbc

MIT_LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2010 Brian Durand
+
+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.

README.rdoc

@@ -0,0 +1,35 @@
+This library provides implementations of various types of object references for Ruby as well as some common utilities for working with references. Reference objects are pretty much pointers, but they come in three distinct flavors that interact differently with the garbage collector.
+
+* References::StrongReference - This is a plain old pointer to another object.
+* References::WeakReference - This is a pointer to another object, but it is not seen by the garbage collector and the memory used by the object can be reclaimed at any time.
+* References::SoftReference - This is similar to a weak reference, but the garbage collector is not as eager to reclaim the referenced object.
+
+All of these classes extend from a common References::Reference class.
+
+Weak and soft references are useful when you have instantiated objects that you may want to use again but can recreate if necessary. Since the garbage collector determines when to reclaim the memory used by the objects, you don't need to worry about bloating the Ruby heap.
+
+== Example Usage
+
+  ref = References::WeakReference.new("hello")
+  ref.object # should be "hello"
+  ObjectSpace.garbage_collect
+  ref.object # should be nil (assuming the garbage collector reclaimed the reference)
+
+== Goodies
+
+This library also includes tools for some common uses of weak and soft references.
+
+* References::WeakKeyMap - A map of keys to values where the keys are weak references
+* References::WeakValueMap - A map of keys to values where the values are weak references
+* References::SoftKeyMap - A map of keys to values where the keys are soft references
+* References::SoftValueMap - A map of keys to values where the values are soft references
+* References::ReferenceQueue - A thread safe implementation of a queue that will add references to itself as their objects are garbage collected.
+
+== Problems with WeakRef
+
+Ruby does come with the WeakRef class in the standard library. However, there are issues with this class across several different Ruby runtimes. This gem provides a common interface to weak references that works across MRI, Ruby Enterprise Edition, YARV, Jruby, Rubinius, and IronRuby.
+
+1. MRI and REE 1.8 - WeakRef extends from Delegator which is a very heavy weight class under Ruby 1.8. Creating a WeakRef object will allocate thousands of other objects and use up hundreds of kilobytes of memory. This makes WeakRef all but unusable even if you only need several hundred of them.
+2. YARV 1.9 - WeakRef is unsafe to use because the garbage collector can run in a different system thread than a thread allocating memory. This exposes a bug where a WeakRef may end up pointing to a completely different object than it originally referenced.
+3. Jruby and IronRuby - Jruby and IronRuby using the Ruby 1.8 libraries suffers from the same performance issue with the Delegator class. Furthermore, these VM's don't implement the method used to load an object from the heap using an object id and so cannot use a pure Ruby method to implement weak references.
+4. Rubinius - Rubinius implements WeakRef with a lighter weight version of delegation and works very well.

Rakefile

@@ -0,0 +1,77 @@
+require 'rake'
+require 'rake/rdoctask'
+require 'rake/testtask'
+require 'rake/gempackagetask'
+require File.expand_path('../lib/references', __FILE__)
+
+desc 'Default: run unit tests.'
+task :default => :test
+
+Rake::TestTask.new do |t|
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.warning = true
+  t.verbose = true
+end
+
+desc 'Generate documentation.'
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.options << '--title' << 'References' << '--line-numbers' << '--inline-source' << '--main' << 'README.rdoc'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+spec = eval(File.read(File.expand_path('../references.gemspec', __FILE__)))
+
+Rake::GemPackageTask.new(spec) do |p|
+  p.gem_spec = spec
+end
+Rake.application["package"].prerequisites.unshift("java:build")
+
+desc "Release to gemcutter"
+task :release => :package do
+  require 'rake/gemcutter'
+  Rake::Gemcutter::Tasks.new(spec).define
+  Rake::Task['gem:push'].invoke
+end
+
+namespace :java do
+  desc "Build the jar files for Jruby support"
+  task :build do
+    base_dir = File.dirname(__FILE__)
+    tmp_dir = File.join(base_dir, "tmp")
+    classes_dir = File.join(tmp_dir, "classes")
+    FileUtils.rm_rf(classes_dir)
+    ext_dir = File.join(base_dir, "ext", "java")
+    source_files = FileList["#{base_dir}/**/*.java"]
+    FileUtils.mkdir_p(classes_dir)
+    `#{ENV['JAVA_HOME']}/bin/javac -classpath '#{"#{ENV['JRUBY_HOME']}/lib/jruby.jar"}' -d '#{classes_dir}' -sourcepath '#{ext_dir}' '#{source_files.join("' '")}'`
+    `#{ENV['JAVA_HOME']}/bin/jar cf '#{base_dir}/lib/references/java_support.jar' -C '#{classes_dir}' references`
+    FileUtils.rm_rf(classes_dir)
+  end
+end
+
+namespace :test do
+  namespace :performance do
+    desc "Run a speed test on how long it takes to create 100000 weak references"
+    task :weak_reference do
+      puts "Testing performance of weak references..."
+      t = Time.now
+      100000.times do
+        References::WeakReference.new(Object.new)
+      end
+      puts "Creating 100,000 weak references took #{Time.now - t} seconds"
+    end
+    
+    desc "Run a speed test on how long it takes to create 100000 soft references"
+    task :soft_reference do
+      puts "Testing performance of soft references..."
+      t = Time.now
+      100000.times do |i|
+        References::SoftReference.new(Object.new)
+      end
+      puts "Creating 100,000 soft references took #{Time.now - t} seconds"
+    end
+  end
+end

VERSION

@@ -0,0 +1 @@
+0.0.1

ext/java/references/JavaSupportService.java

@@ -0,0 +1,31 @@
+package references;
+
+import references.weak_reference.JavaImpl;
+
+import java.io.IOException;
+import org.jruby.Ruby;
+import org.jruby.RubyClass;
+import org.jruby.RubyModule;
+import org.jruby.runtime.builtin.IRubyObject;
+import org.jruby.runtime.load.BasicLibraryService;
+
+/**
+ * This library adds native Java support for weak and soft references.
+ * 
+ * @author Brian Durand
+ */
+public class JavaSupportService implements BasicLibraryService {
+  public boolean basicLoad(Ruby runtime) throws IOException {
+    RubyModule referencesModule = runtime.getModule("References");
+    
+    RubyClass weakReferenceClass = referencesModule.getClass("WeakReference");
+    RubyClass javaWeakReferenceClass = runtime.defineClassUnder("JavaImpl", runtime.getObject(), JavaImpl.ALLOCATOR, weakReferenceClass);
+    javaWeakReferenceClass.defineAnnotatedMethods(JavaImpl.class);
+    
+    RubyClass referenceClass = referencesModule.getClass("Reference");
+    RubyClass rubySoftReferenceClass = runtime.defineClassUnder("SoftReference", referenceClass, RubySoftReference.ALLOCATOR, referencesModule);
+    rubySoftReferenceClass.defineAnnotatedMethods(RubySoftReference.class);
+    
+    return true;
+  }
+}

ext/java/references/RubySoftReference.java

@@ -0,0 +1,43 @@
+package references;
+
+import java.lang.ref.SoftReference;
+import org.jruby.Ruby;
+import org.jruby.RubyClass;
+import org.jruby.RubyObject;
+import org.jruby.anno.JRubyMethod;
+import org.jruby.runtime.builtin.IRubyObject;
+import org.jruby.runtime.ObjectAllocator;
+import org.jruby.runtime.ThreadContext;
+import org.jruby.runtime.Visibility;
+
+public class RubySoftReference extends RubyObject {
+  private SoftReference _ref;
+  private static final String REFERENCED_OBJECT_ID_VARIABLE = "@referenced_object_id".intern();
+
+  public RubySoftReference(Ruby runtime, RubyClass klass) {
+    super(runtime, klass);
+  }
+  
+  public static final ObjectAllocator ALLOCATOR = new ObjectAllocator() {
+    public IRubyObject allocate(Ruby runtime, RubyClass klass) {
+      return new RubySoftReference(runtime, klass);
+    }
+  };
+  
+  @JRubyMethod(name = "initialize", frame = true, visibility = Visibility.PRIVATE)
+  public IRubyObject initialize(ThreadContext context, IRubyObject obj) {
+    _ref = new SoftReference<IRubyObject>(obj);
+    fastSetInstanceVariable(REFERENCED_OBJECT_ID_VARIABLE, obj.id());
+    return context.getRuntime().getNil();
+  }
+
+  @JRubyMethod(name = "object")
+  public IRubyObject object() {
+    IRubyObject obj = (IRubyObject)_ref.get();
+    if (obj != null) {
+      return obj;
+    } else {
+      return getRuntime().getNil();
+    }
+  }
+}

ext/java/references/weak_reference/JavaImpl.java

@@ -0,0 +1,41 @@
+package references.weak_reference;
+
+import java.lang.ref.WeakReference;
+import org.jruby.Ruby;
+import org.jruby.RubyClass;
+import org.jruby.RubyObject;
+import org.jruby.anno.JRubyMethod;
+import org.jruby.runtime.builtin.IRubyObject;
+import org.jruby.runtime.ObjectAllocator;
+import org.jruby.runtime.ThreadContext;
+import org.jruby.runtime.Visibility;
+
+public class JavaImpl extends RubyObject {
+  private WeakReference _ref;
+
+  public JavaImpl(Ruby runtime, RubyClass klass) {
+    super(runtime, klass);
+  }
+  
+  public static final ObjectAllocator ALLOCATOR = new ObjectAllocator() {
+    public IRubyObject allocate(Ruby runtime, RubyClass klass) {
+      return new JavaImpl(runtime, klass);
+    }
+  };
+  
+  @JRubyMethod(name = "initialize", frame = true, visibility = Visibility.PRIVATE)
+  public IRubyObject initialize(ThreadContext context, IRubyObject obj) {
+    _ref = new WeakReference<IRubyObject>(obj);
+    return context.getRuntime().getNil();
+  }
+
+  @JRubyMethod(name = "object")
+  public IRubyObject object() {
+    IRubyObject obj = (IRubyObject)_ref.get();
+    if (obj != null) {
+      return obj;
+    } else {
+      return getRuntime().getNil();
+    }
+  }
+}

lib/references.rb

@@ -0,0 +1,36 @@
+require 'monitor'
+
+module References
+  autoload :AbstractReferenceValueMap, File.join(File.dirname(__FILE__), "references", "abstract_reference_value_map.rb")
+  autoload :AbstractReferenceKeyMap, File.join(File.dirname(__FILE__), "references", "abstract_reference_key_map.rb")
+  autoload :Reference, File.join(File.dirname(__FILE__), "references", "reference.rb")
+  autoload :ReferenceQueue, File.join(File.dirname(__FILE__), "references", "reference_queue.rb")
+  autoload :SoftKeyMap, File.join(File.dirname(__FILE__), "references", "soft_key_map.rb")
+  autoload :SoftValueMap, File.join(File.dirname(__FILE__), "references", "soft_value_map.rb")
+  autoload :StrongReference, File.join(File.dirname(__FILE__), "references", "strong_reference.rb")
+  autoload :WeakReference, File.join(File.dirname(__FILE__), "references", "weak_reference.rb")
+  autoload :WeakKeyMap, File.join(File.dirname(__FILE__), "references", "weak_key_map.rb")
+  autoload :WeakValueMap, File.join(File.dirname(__FILE__), "references", "weak_value_map.rb")
+
+  # Set the best implementation for weak references based on the runtime.
+  if defined?(RUBY_PLATFORM) && RUBY_PLATFORM == 'java'
+    begin
+      $LOAD_PATH.unshift(File.dirname(__FILE__))
+      require 'references/java_support'
+      WeakReference.implementation = WeakReference::JavaImpl
+    ensure
+      $LOAD_PATH.shift if $LOAD_PATH.first == File.dirname(__FILE__)
+    end
+  else
+    autoload :SoftReference, File.join(File.dirname(__FILE__), "references", "soft_reference.rb")
+    if defined?(RUBY_ENGINE) && RUBY_ENGINE == 'ironruby'
+      WeakReference.implementation = WeakReference::IronRubyImpl
+    elsif defined?(RUBY_ENGINE) && RUBY_ENGINE == 'rbx'
+      # If using Rubinius set the implementation to use WeakRef since it is very efficient.
+      require 'weakref'
+      WeakReference.implementation = WeakReference::WeakRefImpl
+    else
+      WeakReference.implementation = WeakReference::RubyImpl
+    end
+  end
+end