ref 1.0.0

data/README.rdoc

@@ -0,0 +1,35 @@
+This library provides object references for Ruby as well as some common utilities for working with references. Object references are used to point to other objects and come in three distinct flavors that interact differently with the garbage collector.
+
+* Ref::StrongReference - This is a plain old pointer to another object.
+* Ref::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.
+* Ref::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 Ref::Reference class and have a common interface.
+
+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 = Ref::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.
+
+* Ref::WeakKeyMap - A map of keys to values where the keys are weak references
+* Ref::WeakValueMap - A map of keys to values where the values are weak references
+* Ref::SoftKeyMap - A map of keys to values where the keys are soft references
+* Ref::SoftValueMap - A map of keys to values where the values are soft references
+* Ref::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.

data/VERSION

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

data/ext/java/org/jruby/ext/ref/ReferencesService.java

@@ -0,0 +1,28 @@
+package org.jruby.ext.ref;
+
+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 ReferencesService implements BasicLibraryService {
+  public boolean basicLoad(Ruby runtime) throws IOException {
+    RubyModule refModule = runtime.getModule("Ref");
+    RubyClass referenceClass = refModule.getClass("Reference");
+    
+    RubyClass rubyWeakReferenceClass = runtime.defineClassUnder("WeakReference", referenceClass, RubyWeakReference.ALLOCATOR, refModule);
+    rubyWeakReferenceClass.defineAnnotatedMethods(RubyWeakReference.class);
+    
+    RubyClass rubySoftReferenceClass = runtime.defineClassUnder("SoftReference", referenceClass, RubySoftReference.ALLOCATOR, refModule);
+    rubySoftReferenceClass.defineAnnotatedMethods(RubySoftReference.class);
+    
+    return true;
+  }
+}

data/ext/java/org/jruby/ext/ref/RubySoftReference.java

@@ -0,0 +1,43 @@
+package org.jruby.ext.ref;
+
+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();
+    }
+  }
+}

data/ext/java/org/jruby/ext/ref/RubyWeakReference.java

@@ -0,0 +1,43 @@
+package org.jruby.ext.ref;
+
+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 RubyWeakReference extends RubyObject {
+  private WeakReference _ref;
+  private static final String REFERENCED_OBJECT_ID_VARIABLE = "@referenced_object_id".intern();
+
+  public RubyWeakReference(Ruby runtime, RubyClass klass) {
+    super(runtime, klass);
+  }
+  
+  public static final ObjectAllocator ALLOCATOR = new ObjectAllocator() {
+    public IRubyObject allocate(Ruby runtime, RubyClass klass) {
+      return new RubyWeakReference(runtime, klass);
+    }
+  };
+  
+  @JRubyMethod(name = "initialize", frame = true, visibility = Visibility.PRIVATE)
+  public IRubyObject initialize(ThreadContext context, IRubyObject obj) {
+    _ref = new WeakReference<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();
+    }
+  }
+}

data/lib/ref.rb

@@ -0,0 +1,39 @@
+module Ref
+  autoload :AbstractReferenceValueMap, File.join(File.dirname(__FILE__), "ref", "abstract_reference_value_map.rb")
+  autoload :AbstractReferenceKeyMap, File.join(File.dirname(__FILE__), "ref", "abstract_reference_key_map.rb")
+  autoload :Mock, File.join(File.dirname(__FILE__), "ref", "mock.rb")
+  autoload :Reference, File.join(File.dirname(__FILE__), "ref", "reference.rb")
+  autoload :ReferenceQueue, File.join(File.dirname(__FILE__), "ref", "reference_queue.rb")
+  autoload :SafeMonitor, File.join(File.dirname(__FILE__), "ref", "safe_monitor.rb")
+  autoload :SoftKeyMap, File.join(File.dirname(__FILE__), "ref", "soft_key_map.rb")
+  autoload :SoftValueMap, File.join(File.dirname(__FILE__), "ref", "soft_value_map.rb")
+  autoload :StrongReference, File.join(File.dirname(__FILE__), "ref", "strong_reference.rb")
+  autoload :WeakKeyMap, File.join(File.dirname(__FILE__), "ref", "weak_key_map.rb")
+  autoload :WeakValueMap, File.join(File.dirname(__FILE__), "ref", "weak_value_map.rb")
+
+  # Set the best implementation for weak references based on the runtime.
+  if defined?(RUBY_PLATFORM) && RUBY_PLATFORM == 'java'
+    # Use native Java references
+    begin
+      $LOAD_PATH.unshift(File.dirname(__FILE__))
+      require 'org/jruby/ext/ref/references'
+    ensure
+      $LOAD_PATH.shift if $LOAD_PATH.first == File.dirname(__FILE__)
+    end
+  else
+    autoload :SoftReference, File.join(File.dirname(__FILE__), "ref", "soft_reference.rb")
+    if defined?(RUBY_ENGINE) && RUBY_ENGINE == 'ironruby'
+      # IronRuby has it's own implementation of weak references.
+      autoload :WeakReference, File.join(File.dirname(__FILE__), "ref", "weak_reference", "iron_ruby.rb")
+    elsif defined?(RUBY_ENGINE) && RUBY_ENGINE == 'rbx'
+      # If using Rubinius set the implementation to use WeakRef since it is very efficient and using finalizers is not.
+      autoload :WeakReference, File.join(File.dirname(__FILE__), "ref", "weak_reference", "weak_ref.rb")
+    elsif defined?(ObjectSpace._id2ref)
+      # If ObjectSpace can lookup objects from their object_id, then use the pure ruby implementation.
+      autoload :WeakReference, File.join(File.dirname(__FILE__), "ref", "weak_reference", "pure_ruby.rb")
+    else
+      # Otherwise, wrap the standard library WeakRef class
+      autoload :WeakReference, File.join(File.dirname(__FILE__), "ref", "weak_reference", "weak_ref.rb")
+    end
+  end
+end

data/lib/ref/abstract_reference_key_map.rb

@@ -0,0 +1,117 @@
+module Ref
+  # Abstract base class for WeakKeyMap and SoftKeyMap.
+  #
+  # The classes behave similar to Hashes, but the keys in the map are not strong references
+  # and can be reclaimed by the garbage collector at any time. When a key is reclaimed, the
+  # map entry will be removed.
+  class AbstractReferenceKeyMap
+    class << self
+      def reference_class=(klass) #:nodoc:
+        @reference_class = klass
+      end
+    
+      def reference_class #:nodoc:
+        raise NotImplementedError.new("#{name} is an abstract class and cannot be instantiated") unless @reference_class
+        @reference_class
+      end
+    end
+    
+    # Create a new map. Values added to the hash will be cleaned up by the garbage
+    # collector if there are no other reference except in the map.
+    def initialize
+      @values = {}
+      @references_to_keys_map = {}
+      @lock = SafeMonitor.new
+      @reference_cleanup = lambda{|object_id| remove_reference_to(object_id)}
+    end
+
+    # Get a value from the map by key. If the value has been reclaimed by the garbage
+    # collector, this will return nil.
+    def [](key)
+      rkey = ref_key(key)
+      @values[rkey] if rkey
+    end
+
+    # Add a key/value to the map.
+    def []=(key, value)
+      ObjectSpace.define_finalizer(key, @reference_cleanup)
+      @lock.synchronize do
+        @references_to_keys_map[key.__id__] = self.class.reference_class.new(key)
+        @values[key.__id__] = value
+      end
+    end
+
+    # Remove the value associated with the key from the map.
+    def delete(key)
+      rkey = ref_key(key)
+      if rkey
+        @references_to_keys_map.delete(rkey)
+        @values.delete(rkey)
+      else
+        nil
+      end
+    end
+
+    # Get an array of keys that have not yet been garbage collected.
+    def keys
+      @values.keys.collect{|rkey| @references_to_keys_map[rkey].object}.compact
+    end
+    
+    # Turn the map into an arry of [key, value] entries.
+    def to_a
+      array = []
+      each{|k,v| array << [k, v]}
+      array
+    end
+    
+    # Iterate through all the key/value pairs in the map that have not been reclaimed
+    # by the garbage collector.
+    def each
+      @references_to_keys_map.each do |rkey, ref|
+        key = ref.object
+        yield(key, @values[rkey]) if key
+      end
+    end
+
+    # Clear the map of all key/value pairs.
+    def clear
+      @lock.synchronize do
+        @values.clear
+        @references_to_keys_map.clear
+      end
+    end
+
+    # Merge the values from another hash into this map.
+    def merge!(other_hash)
+      other_hash.each do |key, value|
+        self[key] = value
+      end
+    end
+
+    def inspect
+      live_entries = {}
+      each do |key, value|
+        live_entries[key] = value
+      end
+      live_entries.inspect
+    end
+
+    private
+
+      def ref_key (key)
+        ref = @references_to_keys_map[key.__id__]
+        if ref && ref.object
+          ref.referenced_object_id
+        else
+          nil
+        end
+      end
+      
+      def remove_reference_to(object_id)
+        @lock.synchronize do
+          @references_to_keys_map.delete(object_id)
+          @values.delete(object_id)
+        end
+      end
+  end
+end

data/lib/ref/abstract_reference_value_map.rb

@@ -0,0 +1,127 @@
+module Ref
+  # Abstract base class for WeakValueMap and SoftValueMap.
+  #
+  # The classes behave similar to Hashes, but the values in the map are not strong references
+  # and can be reclaimed by the garbage collector at any time. When a value is reclaimed, the
+  # map entry will be removed.
+  class AbstractReferenceValueMap
+    class << self
+      def reference_class=(klass) #:nodoc:
+        @reference_class = klass
+      end
+    
+      def reference_class #:nodoc:
+        raise NotImplementedError.new("#{name} is an abstract class and cannot be instantiated") unless @reference_class
+        @reference_class
+      end
+    end
+    
+    # Create a new map. Values added to the map will be cleaned up by the garbage
+    # collector if there are no other reference except in the map.
+    def initialize
+      @references = {}
+      @references_to_keys_map = {}
+      @lock = SafeMonitor.new
+      @reference_cleanup = lambda{|object_id| remove_reference_to(object_id)}
+    end
+
+    # Get a value from the map by key. If the value has been reclaimed by the garbage
+    # collector, this will return nil.
+    def [](key)
+      ref = @references[key]
+      value = ref.object if ref
+      value
+    end
+
+    # Add a key/value to the map.
+    def []=(key, value)
+      ObjectSpace.define_finalizer(value, @reference_cleanup)
+      key = key.dup if key.is_a?(String)
+      @lock.synchronize do
+        @references[key] = self.class.reference_class.new(value)
+        keys_for_id = @references_to_keys_map[value.__id__]
+        unless keys_for_id
+          keys_for_id = []
+          @references_to_keys_map[value.__id__] = keys_for_id
+        end
+        keys_for_id << key
+      end
+      value
+    end
+
+    # Remove the entry associated with the key from the map.
+    def delete(key)
+      ref = @references.delete(key)
+      if ref
+        keys_to_id = @references_to_keys_map[ref.referenced_object_id]
+        if keys_to_id
+          keys_to_id.delete(key)
+          @references_to_keys_map.delete(ref.referenced_object_id) if keys_to_id.empty?
+        end
+        ref.object
+      else
+        nil
+      end
+    end
+
+    # Get the list of all values that have not yet been garbage collected.
+    def values
+      vals = []
+      each{|k,v| vals << v}
+      vals
+    end
+    
+    # Turn the map into an arry of [key, value] entries
+    def to_a
+      array = []
+      each{|k,v| array << [k, v]}
+      array
+    end
+    
+    # Iterate through all the key/value pairs in the map that have not been reclaimed
+    # by the garbage collector.
+    def each
+      @references.each do |key, ref|
+        value = ref.object
+        yield(key, value) if value
+      end
+    end
+
+    # Clear the map of all key/value pairs.
+    def clear
+      @lock.synchronize do
+        @references.clear
+        @references_to_keys_map.clear
+      end
+    end
+
+    # Merge the values from another hash into this map.
+    def merge!(other_hash)
+      other_hash.each do |key, value|
+        self[key] = value
+      end
+    end
+
+    def inspect
+      live_entries = {}
+      each do |key, value|
+        live_entries[key] = value
+      end
+      live_entries.inspect
+    end
+
+    private
+
+      def remove_reference_to(object_id)
+        @lock.synchronize do
+          keys = @references_to_keys_map[object_id]
+          if keys
+            keys.each do |key|
+              @references.delete(key)
+            end
+            @references_to_keys_map.delete(object_id)
+          end
+        end
+      end
+  end
+end

data/lib/ref/mock.rb

@@ -0,0 +1,145 @@
+module Ref
+  # This module provides mock weak and strong references that are designed to be
+  # used in tests. You can define a block where all weak and soft references created
+  # will be mock references. You can then mimic running the garbage collector on
+  # the objects pointed to by the references.
+  #
+  # Example usage:
+  #
+  #   References::Mock.use do
+  #     obj = Object.new
+  #     ref = References::WeakReference.new(obj)
+  #     ref.object   # obj
+  #     References::Mock.gc(obj)  # mimics the garbage collector reclaiming the referenced object
+  #     ref.object   # nil
+  #   end
+  module Mock
+    class << self
+      # Use the mock implementation inside a block and then restore the original implementation.
+      def use
+        if object_space
+          yield
+        else
+          setup
+          begin
+            yield
+          ensure
+            cleanup
+          end
+        end
+      end
+      
+      # Start using mock references.
+      def setup
+        raise "Ref::Mock already setup" if object_space
+        
+        @object_space = {}
+        
+        class << ObjectSpace
+          unless method_defined?(:define_finalizer_with_mock_reference)
+            def define_finalizer_with_mock_reference(obj, finalizer)
+              if ::Ref::Mock.object_space.include?(obj.__id__)
+                ::Ref::Mock.object_space[obj.__id__] << finalizer
+              else
+                define_finalizer_without_mock_reference(obj, finalizer)
+              end
+            end
+          end
+          
+          alias_method :define_finalizer_without_mock_reference, :define_finalizer
+          alias_method :define_finalizer, :define_finalizer_with_mock_reference
+        end
+        
+        class << WeakReference
+          unless method_defined?(:new_with_mock_reference)
+            def new_with_mock_reference(obj)
+              if self == Mock::MockWeakReference
+                new_without_mock_reference(obj)
+              else
+                Mock::MockWeakReference.new(obj)
+              end
+            end
+          end
+          
+          alias_method :new_without_mock_reference, :new
+          alias_method :new, :new_with_mock_reference
+        end
+        
+        class << SoftReference
+          unless method_defined?(:new_with_mock_reference)
+            def new_with_mock_reference(obj)
+              if self == Mock::MockSoftReference
+                new_without_mock_reference(obj)
+              else
+                Mock::MockSoftReference.new(obj)
+              end
+            end
+          end
+          
+          alias_method :new_without_mock_reference, :new
+          alias_method :new, :new_with_mock_reference
+        end
+      end
+      
+      # Stop using mock references.
+      def cleanup
+        @object_space = nil
+        class << ObjectSpace
+          alias_method :define_finalizer_with_mock_reference, :define_finalizer
+          alias_method :define_finalizer, :define_finalizer_without_mock_reference
+        end
+        
+        class << WeakReference
+          alias_method :new_with_mock_reference, :new
+          alias_method :new, :new_without_mock_reference
+        end
+        
+        class << SoftReference
+          alias_method :new_with_mock_reference, :new
+          alias_method :new, :new_without_mock_reference
+        end
+      end
+
+      def object_space # :nodoc:
+        @object_space if instance_variable_defined?(:@object_space)
+      end
+
+      # Simulate garbage collection of the objects passed in as arguments. If no objects
+      # are specified, all objects will be reclaimed.
+      def gc(*objects)
+        objects = object_space.keys if objects.empty?
+        objects.each do |obj|
+          finalizers = object_space.delete(obj.__id__)
+          if finalizers
+            finalizers.each{|finalizer| finalizer.call(obj.__id__)}
+          end
+        end
+      end
+    end
+    
+    module MockReference #:nodoc:
+      def initialize(obj)
+        @object = obj
+        @referenced_object_id = obj.__id__
+        raise "Reference::Mock not setup yet" unless Mock.object_space
+        Mock.object_space[obj.__id__] ||= []
+      end
+    
+      def object
+        if @object && Mock.object_space.include?(@object.__id__)
+          @object
+        else
+          @object = nil
+        end
+      end
+    end
+  
+    class MockWeakReference < WeakReference #:nodoc:
+      include MockReference
+    end
+  
+    class MockSoftReference < SoftReference #:nodoc:
+      include MockReference
+    end
+  end  
+end