ref 1.0.0

data/lib/ref/reference.rb

@@ -0,0 +1,24 @@
+module Ref
+  # This class serves as a generic reference mechanism to other objects. The
+  # actual reference can be either a WeakReference, SoftReference, or StrongReference.
+  class Reference
+    # The object id of the object being referenced.
+    attr_reader :referenced_object_id
+    
+    # Create a new reference to an object.
+    def initialize(obj)
+      raise NotImplementedError.new("cannot instantiate a generic reference")
+    end
+    
+    # Get the referenced object. This could be nil if the reference
+    # is a WeakReference or a SoftReference and the object has been reclaimed by the garbage collector.
+    def object
+      raise NotImplementedError
+    end
+
+    def inspect
+      obj = object
+      "<##{self.class.name}: #{obj ? obj.inspect : "##{referenced_object_id} (not accessible)"}>"
+    end
+  end
+end

data/lib/ref/reference_queue.rb

@@ -0,0 +1,89 @@
+module Ref
+  # This class provides a simple thread safe container to hold a reference queue. Instances
+  # of WeakReference can be added to the queue and as the objects pointed to by those references
+  # are cleaned up by the garbage collector, the references will be added to the queue.
+  #
+  # The reason for using a reference queue is that it tends to be more efficient than adding
+  # individual finalizers to objects and the cleanup code can be handled by a thread outside
+  # of garbage collection.
+  #
+  # In general, you should create your own subclass of WeakReference that contains the logic
+  # needed to complete the cleanup. The object pointed to will have already been cleaned up
+  # and the reference cannot maintain a reference to the object.
+  #
+  # === Example usage:
+  #
+  #   class MyRef < References::WeakReference
+  #     def cleanup
+  #       # Do something...
+  #     end
+  #   end
+  #   
+  #   queue = References::ReferenceQueue.new
+  #   ref = MyRef.new(Object.new)
+  #   queue.monitor(ref)
+  #   queue.shift                 # = nil
+  #   ObjectSpace.garbage_collect
+  #   r = queue.shift             # = ref
+  #   r.cleanup
+  class ReferenceQueue
+    def initialize
+      @queue = []
+      @references = {}
+      @lock = SafeMonitor.new
+      @finalizer = lambda do |object_id|
+        @lock.synchronize do
+          ref = @references.delete(object_id)
+          @queue.push(ref) if ref
+        end
+      end
+    end
+    
+    # Monitor a reference. When the object the reference points to is garbage collected,
+    # the reference will be added to the queue.
+    def monitor(reference)
+      obj = reference.object
+      if obj
+        @lock.synchronize do
+          @references[reference.referenced_object_id] = reference
+        end
+        ObjectSpace.define_finalizer(obj, @finalizer)
+      else
+        push(reference)
+      end
+    end
+    
+    # Add a reference to the queue.
+    def push(reference)
+      if reference
+        @lock.synchronize do
+          @queue.push(reference)
+        end
+      end
+    end
+    
+    # Pull the last reference off the queue. Returns +nil+ if their are no references.
+    def pop
+      @lock.synchronize do
+        @queue.pop
+      end
+    end
+    
+    # Pull the next reference off the queue. Returns +nil+ if there are no references.
+    def shift
+      @lock.synchronize do
+        @queue.shift
+      end
+    end
+    
+    # Return +true+ if the queue is empty.
+    def empty?
+      @queue.empty?
+    end
+    
+    # Get the current size of the queue.
+    def size
+      @queue.size
+    end
+  end
+end

data/lib/ref/safe_monitor.rb

@@ -0,0 +1,50 @@
+begin
+  require 'thread'
+rescue LoadError
+  # Threads not available. Monitor will do nothing.
+end
+
+module Ref
+  # The Monitor class in Ruby 1.8 has some bugs and also threads may not be available on all
+  # runtimes. This class provides a simple, safe re-entrant mutex as an alternative.
+  class SafeMonitor
+    def initialize
+      @owner = nil
+      @count = 0
+      @mutex = defined?(Mutex) ? Mutex.new : nil
+    end
+  
+    # Acquire an exclusive lock.
+    def lock
+      if @mutex
+        if @owner != Thread.current.object_id
+          @mutex.lock
+          @owner = Thread.current.object_id
+        end
+        @count += 1
+      end
+      true
+    end
+    
+    # Release the exclusive lock.
+    def unlock
+      if @mutex
+        if @owner == Thread.current.object_id
+          @count -= 1
+          if @count == 0
+            @owner = nil
+            @mutex.unlock
+          end
+        end
+      end
+    end
+  
+    # Run a block of code with an exclusive lock.
+    def synchronize
+      lock
+      yield
+    ensure
+      unlock
+    end
+  end
+end

data/lib/ref/soft_key_map.rb

@@ -0,0 +1,26 @@
+module Ref
+  # Implementation of a map in which only softly referenced keys are kept to the map values.
+  # This allows the garbage collector to reclaim these objects if the only reference to them
+  # is the soft reference in the map.
+  #
+  # This is often useful for cache implementations since the map can be allowed to grow
+  # without bound and the garbage collector can be relied on to clean it up as necessary.
+  # One must be careful, though, when accessing entries since they can be collected at
+  # any time until there is a strong reference to the key.
+  #
+  # === Example usage:
+  #
+  #   cache = References::SoftKeyMap.new
+  #   obj = MyObject.find_by_whatever
+  #   obj_info = Service.lookup_object_info(obj)
+  #   cache[obj] = Service.lookup_object_info(obj)
+  #   cache[obj]  # The values looked up from the service
+  #   obj = nil
+  #   ObjectSpace.garbage_collect
+  #   cache.keys  # empty array since the keys and values have been reclaimed
+  #
+  # See AbstractReferenceKeyMap for details.
+  class SoftKeyMap < AbstractReferenceKeyMap
+    self.reference_class = SoftReference
+  end
+end

data/lib/ref/soft_reference.rb

@@ -0,0 +1,67 @@
+module Ref
+  # A SoftReference represents a reference to an object that is not seen by
+  # the tracing phase of the garbage collector. This allows the referenced
+  # object to be garbage collected as if nothing is referring to it.
+  #
+  # A SoftReference differs from a WeakReference in that the garbage collector
+  # is not so eager to reclaim soft references so they should persist longer.
+  #
+  # === Example usage:
+  #
+  #   foo = Object.new
+  #   ref = References::SoftReference.new(foo)
+  #   ref.object			# should be foo
+  #   ObjectSpace.garbage_collect
+  #   ref.object			# should be foo
+  #   ObjectSpace.garbage_collect
+  #   ObjectSpace.garbage_collect
+  #   ref.object			# should be nil
+  class SoftReference < Reference
+    @@strong_references = [{}]
+    @@gc_flag_set = false
+    
+    # Number of garbage collection cycles after an object is used before a reference to it can be reclaimed.
+    MIN_GC_CYCLES = 10
+    
+    @@lock = SafeMonitor.new
+    
+    @@finalizer = lambda do |object_id|
+      @@lock.synchronize do
+        while @@strong_references.size >= MIN_GC_CYCLES do
+          @@strong_references.shift
+        end
+        @@strong_references.push({}) if @@strong_references.size < MIN_GC_CYCLES
+        @@gc_flag_set = false
+      end
+    end
+    
+    # Create a new soft reference to an object.
+    def initialize(obj)
+      @referenced_object_id = obj.__id__
+      @weak_reference = WeakReference.new(obj)
+      add_strong_reference(obj)
+    end
+    
+    # Get the referenced object. If the object has been reclaimed by the
+    # garbage collector, then this will return nil.
+    def object
+      obj = @weak_reference.object
+      # add a temporary strong reference each time the object is referenced.
+      add_strong_reference(obj) if obj
+      obj
+    end
+    
+    private
+      # Create a strong reference to the object. This reference will live
+      # for three passes of the garbage collector.
+      def add_strong_reference(obj) #:nodoc:
+        @@lock.synchronize do
+          @@strong_references.last[obj] = true
+          unless @@gc_flag_set
+            @@gc_flag_set = true
+            ObjectSpace.define_finalizer(Object.new, @@finalizer)
+          end
+        end
+      end
+  end
+end

data/lib/ref/soft_value_map.rb

@@ -0,0 +1,28 @@
+module Ref
+  # Implementation of a map in which soft references are kept to the map values.
+  # This allows the garbage collector to reclaim these objects if the
+  # only reference to them is the soft reference in the map.
+  #
+  # This is often useful for cache  implementations since the map can be allowed to grow
+  # without bound and the  garbage collector can be relied on to clean it up as necessary.
+  # One must be careful,  though, when accessing entries since the values can be collected
+  # at any time until there is a strong reference to them.
+  #
+  # === Example usage:
+  #
+  #   cache = References::SoftValueMap.new
+  #   foo = "foo"
+  #   cache["strong"] = foo  # add a value with a strong reference
+  #   cache["soft"] = "bar"  # add a value without a strong reference
+  #   cache["strong"]        # "foo"
+  #   cache["soft"]          # "bar"
+  #   ObjectSpace.garbage_collect
+  #   ObjectSpace.garbage_collect
+  #   cache["strong"]        # "foo"
+  #   cache["soft"]          # nil
+  #
+  # See AbstractReferenceValueMap for details.
+  class SoftValueMap < AbstractReferenceValueMap
+    self.reference_class = SoftReference
+  end
+end

data/lib/ref/strong_reference.rb

@@ -0,0 +1,17 @@
+module Ref
+  # This implementation of Reference holds a strong reference to an object. The
+  # referenced object will not be garbage collected as long as the strong reference
+  # exists.
+  class StrongReference < Reference
+    # Create a new strong reference to an object.
+    def initialize(obj)
+      @obj = obj
+      @referenced_object_id = obj.__id__
+    end
+    
+    # Get the referenced object.
+    def object
+      @obj
+    end
+  end
+end

data/lib/ref/weak_key_map.rb

@@ -0,0 +1,26 @@
+module Ref
+  # Implementation of a map in which only weakly referenced keys are kept to the map values.
+  # This allows the garbage collector to reclaim these objects if the only reference to them
+  # is the weak reference in the map.
+  #
+  # This is often useful for cache implementations since the map can be allowed to grow
+  # without bound and the garbage collector can be relied on to clean it up as necessary.
+  # One must be careful, though, when accessing entries since they can be collected at
+  # any time until there is a strong reference to the key.
+  #
+  # === Example usage:
+  #
+  #   cache = References::WeakKeyMap.new
+  #   obj = MyObject.find_by_whatever
+  #   obj_info = Service.lookup_object_info(obj)
+  #   cache[obj] = Service.lookup_object_info(obj)
+  #   cache[obj]  # The values looked up from the service
+  #   obj = nil
+  #   ObjectSpace.garbage_collect
+  #   cache.keys  # empty array since the keys and values have been reclaimed
+  #
+  # See AbstractReferenceKeyMap for details.
+  class WeakKeyMap < AbstractReferenceKeyMap
+    self.reference_class = WeakReference
+  end
+end

data/lib/ref/weak_reference.rb

@@ -0,0 +1,26 @@
+module Ref
+  # A WeakReference represents a reference to an object that is not seen by
+  # the tracing phase of the garbage collector. This allows the referenced
+  # object to be garbage collected as if nothing is referring to it.
+  #
+  # === Example usage:
+  #
+  #   foo = Object.new
+  #   ref = References::WeakReference.new(foo)
+  #   ref.object			# should be foo
+  #   ObjectSpace.garbage_collect
+  #   ref.object			# should be nil
+  class WeakReference < Reference
+    
+    # Create a weak reference to an object.
+    def initialize(obj)
+      raise NotImplementedError.new("This is an abstract class; you must require an implementation")
+    end
+
+    # Get the referenced object. If the object has been reclaimed by the
+    # garbage collector, then this will return nil.
+    def object
+      raise NotImplementedError.new("This is an abstract class; you must require an implementation")
+    end
+  end
+end

data/lib/ref/weak_reference/iron_ruby.rb

@@ -0,0 +1,14 @@
+module Ref
+  class WeakReference < Reference
+  # This implementation of a weak reference wraps the System::WeakReference class
+  # that comes with IronRuby.
+    def initialize(obj) #:nodoc:
+      @referenced_object_id = obj.__id__
+      @ref = ::System::WeakReference.new(obj)
+    end
+
+    def object #:nodoc:
+      @ref.target
+    end
+  end
+end

data/lib/ref/weak_reference/pure_ruby.rb

@@ -0,0 +1,91 @@
+module Ref
+  # This is a pure ruby implementation of a weak reference. It is much more
+  # efficient than the bundled WeakRef implementation because it does not
+  # subclass Delegator which is very heavy to instantiate and utilizes a
+  # fair amount of memory under Ruby 1.8.
+  class WeakReference < Reference
+    
+    class ReferencePointer
+      def initialize(object)
+        @referenced_object_id = object.__id__
+        add_backreference(object)
+      end
+      
+      def cleanup
+        obj = ObjectSpace._id2ref(@referenced_object_id) rescue nil
+        remove_backreference(obj) if obj
+      end
+      
+      def object
+        obj = ObjectSpace._id2ref(@referenced_object_id)
+        obj if verify_backreferences(obj)
+      rescue RangeError
+        nil
+      end
+      
+      private
+        # Verify that the object is the same one originally set for the weak reference.
+        def verify_backreferences(obj) #:nodoc:
+          backreferences = obj.instance_variable_get(:@__weak_backreferences__) if obj.instance_variable_defined?(:@__weak_backreferences__)
+          backreferences && backreferences.include?(object_id)
+        end
+      
+        # Add a backreference to the object.
+        def add_backreference(obj) #:nodoc:
+          backreferences = obj.instance_variable_get(:@__weak_backreferences__) if obj.instance_variable_defined?(:@__weak_backreferences__)
+          unless backreferences
+            backreferences = []
+            obj.instance_variable_set(:@__weak_backreferences__, backreferences)
+          end
+          backreferences << object_id
+        end
+      
+        # Remove backreferences from the object.
+        def remove_backreference(obj) #:nodoc:
+          backreferences = obj.instance_variable_get(:@__weak_backreferences__) if obj.instance_variable_defined?(:@__weak_backreferences__)
+          if backreferences
+            backreferences.dup.delete(object_id)
+            obj.send(:remove_instance_variable, :@__weak_backreferences__) if backreferences.empty?
+          end
+        end
+    end
+    
+    @@weak_references = {}
+    @@lock = SafeMonitor.new
+
+    # Finalizer that cleans up weak references when references are destroyed.
+    @@reference_finalizer = lambda do |object_id|
+      @@lock.synchronize do
+        reference_pointer = @@weak_references.delete(object_id)
+        reference_pointer.cleanup if reference_pointer
+      end
+    end
+
+    # Create a new weak reference to an object. The existence of the weak reference
+    # will not prevent the garbage collector from reclaiming the referenced object.
+    def initialize(obj) #:nodoc:
+      @referenced_object_id = obj.__id__
+      @@lock.synchronize do
+        @reference_pointer = ReferencePointer.new(obj)
+        @@weak_references[self.object_id] = @reference_pointer
+      end
+      ObjectSpace.define_finalizer(self, @@reference_finalizer)
+    end
+
+    # Get the reference object. If the object has already been garbage collected,
+    # then this method will return nil.
+    def object #:nodoc:
+      if @reference_pointer
+        obj = @reference_pointer.object
+        unless obj
+          @@lock.synchronize do
+            @@weak_references.delete(object_id)
+            @reference_pointer.cleanup
+            @reference_pointer = nil
+          end
+        end
+        obj
+      end
+    end
+  end
+end