ref 1.0.5 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 6eb5f8b9c225f1e9ebac1aaa62ef9f3984cfe14f
-  data.tar.gz: a19284185151618e6bcb5f33cb7abe336b87ae42
+  metadata.gz: 65d0ceb85d4d1208144f2ad51c92269c4f0f689f
+  data.tar.gz: 7ee73e669c4d7532ed44743ea17f4acbd2d983fd
 SHA512:
-  metadata.gz: 7a4f349540019ab696d4ecdacf589e523804daecc90ff3b3798f3d9b9382efe5dedf14c4634d6c8203672911027da17cd1d052cc54e5bf76cfd7a3ba6b63f9ea
-  data.tar.gz: 3ccad9fcd17a871de36d032a57f130deca6df40605c8798bcf86bdcb204cdb40376eba445100772f5636acddffe72f3c00cd8bee5c7e0a796ea3b5602f062cba
+  metadata.gz: 22589cec63a2275a3a4f71e903e858d5fe33180a866ac3108c8d4768b08b8f1998dc85e32f8f3a81ce5647b7265e9b4a24a1c22d80ed5368e2e1c6d76167a154
+  data.tar.gz: db38d2ca1d6a8fbe96a2fcb8c6d1308226648928d95c6cf62ece3832fccb7bf7e9241d13f1f87d0d55c1b8cac7715fdb361dc1d50fbdf5351aa896244c78d690

data/README.md

@@ -0,0 +1,41 @@
+# Ref
+
+[![Gem Version](https://badge.fury.io/rb/ref.svg)](http://badge.fury.io/rb/ref) [![Build Status](https://travis-ci.org/ruby-concurrency/ref.svg?branch=master)](https://travis-ci.org/ruby-concurrency/ref) [![Coverage Status](https://img.shields.io/coveralls/ruby-concurrency/ref/master.svg)](https://coveralls.io/r/ruby-concurrency/ref) [![Code Climate](https://codeclimate.com/github/ruby-concurrency/ref.svg)](https://codeclimate.com/github/ruby-concurrency/ref) [![Dependency Status](https://gemnasium.com/ruby-concurrency/ref.svg)](https://gemnasium.com/ruby-concurrency/ref) [![License](https://img.shields.io/badge/license-MIT-green.svg)](http://opensource.org/licenses/MIT) [![Gitter chat](http://img.shields.io/badge/gitter-join%20chat%20%E2%86%92-brightgreen.svg)](https://gitter.im/ruby-concurrency/concurrent-ruby)
+
+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
+
+```ruby
+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](https://bugs.ruby-lang.org/issues/4168) across several different Ruby runtimes. This gem provides a common interface to weak references that works across MRI, Ruby Enterprise Edition, YARV, JRuby and Rubinius.
+
+1. Rubinius - Rubinius implements `WeakRef` with a lighter weight version of delegation and works very well.
+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. MRI Ruby 2.0+ has a good implementation of `WeakRef`.
+

data/lib/ref.rb

@@ -1,45 +1,44 @@
 module Ref
-  require File.join(File.dirname(__FILE__), "ref", "abstract_reference_value_map.rb")
-  require File.join(File.dirname(__FILE__), "ref", "abstract_reference_key_map.rb")
-  require File.join(File.dirname(__FILE__), "ref", "reference.rb")
-  require File.join(File.dirname(__FILE__), "ref", "reference_queue.rb")
-  require File.join(File.dirname(__FILE__), "ref", "safe_monitor.rb")
+  $LOAD_PATH.unshift(File.dirname(__FILE__))
 
-  # Set the best implementation for weak references based on the runtime.
-  if defined?(RUBY_PLATFORM) && RUBY_PLATFORM == 'java'
-    # Use native Java references
+  require 'ref/abstract_reference_value_map'
+  require 'ref/abstract_reference_key_map'
+  require 'ref/reference'
+  require 'ref/reference_queue'
+
+  if defined?(Java)
     begin
-      $LOAD_PATH.unshift(File.dirname(__FILE__))
+      require 'ref_ext'
       require 'org/jruby/ext/ref/references'
-    ensure
-      $LOAD_PATH.shift if $LOAD_PATH.first == File.dirname(__FILE__)
+    rescue LoadError
+      require 'ref/soft_reference'
+      require 'ref/weak_reference'
+      warn 'Error loading Rspec rake tasks, probably building the gem...'
     end
   else
-    require 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.
-      require File.join(File.dirname(__FILE__), "ref", "weak_reference", "iron_ruby.rb")
-    elsif defined?(RUBY_ENGINE) && RUBY_ENGINE == 'rbx'
+    require 'ref/soft_reference'
+    if 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.
-      require File.join(File.dirname(__FILE__), "ref", "weak_reference", "weak_ref.rb")
+      require 'ref/weak_reference/weak_ref'
     elsif defined?(::ObjectSpace::WeakMap)
       # Ruby 2.0 has a working implementation of weakref.rb backed by the new ObjectSpace::WeakMap
-      require File.join(File.dirname(__FILE__), "ref", "weak_reference", "weak_ref.rb")
+      require 'ref/weak_reference/weak_ref'
     elsif defined?(::ObjectSpace._id2ref)
       # If ObjectSpace can lookup objects from their object_id, then use the pure ruby implementation.
-      require File.join(File.dirname(__FILE__), "ref", "weak_reference", "pure_ruby.rb")
+      require 'ref/weak_reference/pure_ruby'
     else
       # Otherwise, wrap the standard library WeakRef class
-      require File.join(File.dirname(__FILE__), "ref", "weak_reference", "weak_ref.rb")
+      require 'ref/weak_reference/weak_ref'
     end
   end
-  
-  require File.join(File.dirname(__FILE__), "ref", "soft_key_map.rb")
-  require File.join(File.dirname(__FILE__), "ref", "soft_value_map.rb")
-  require File.join(File.dirname(__FILE__), "ref", "strong_reference.rb")
-  require File.join(File.dirname(__FILE__), "ref", "weak_key_map.rb")
-  require File.join(File.dirname(__FILE__), "ref", "weak_value_map.rb")
-  
-  # Used for testing
-  autoload :Mock, File.join(File.dirname(__FILE__), "ref", "mock.rb")
+
+  require 'ref/soft_key_map'
+  require 'ref/soft_value_map'
+  require 'ref/strong_reference'
+  require 'ref/weak_key_map'
+  require 'ref/weak_value_map'
+
+  def self.jruby?
+    defined?(Java)
+  end
 end

data/lib/ref/abstract_reference_key_map.rb

@@ -9,29 +9,33 @@ module Ref
       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
+      @lock = Monitor.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
+      @lock.synchronize do
+        rkey = ref_key(key)
+        @values[rkey] if rkey
+      end
     end
 
+    alias_method :get, :[]
+
     # Add a key/value to the map.
     def []=(key, value)
       ObjectSpace.define_finalizer(key, @reference_cleanup)
@@ -41,14 +45,18 @@ module Ref
       end
     end
 
+    alias_method :put, :[]=
+
     # 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
+      @lock.synchronize do
+        rkey = ref_key(key)
+        if rkey
+          @references_to_keys_map.delete(rkey)
+          @values.delete(rkey)
+        else
+          nil
+        end
       end
     end
 
@@ -56,14 +64,21 @@ module Ref
     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
-    
+
+    # Returns a hash containing the names and values for the struct’s members.
+    def to_h
+      hash = {}
+      each{|k,v| hash[k] = v}
+      hash
+    end
+
     # Iterate through all the key/value pairs in the map that have not been reclaimed
     # by the garbage collector.
     def each
@@ -81,13 +96,42 @@ module Ref
       end
     end
 
+    # Returns a new struct containing the contents of `other` and the contents
+    # of `self`. If no block is specified, the value for entries with duplicate
+    # keys will be that of `other`. Otherwise the value for each duplicate key
+    # is determined by calling the block with the key, its value in `self` and
+    # its value in `other`.
+    def merge(other_hash, &block)
+      to_h.merge(other_hash, &block).reduce(self.class.new) do |map, pair|
+        map[pair.first] = pair.last
+        map
+      end
+    end
+
     # Merge the values from another hash into this map.
     def merge!(other_hash)
-      other_hash.each do |key, value|
-        self[key] = value
+      @lock.synchronize do
+        other_hash.each { |key, value| self[key] = value }
       end
     end
 
+    # The number of entries in the map
+    def size
+      @references_to_keys_map.count do |_, ref|
+        ref.object
+      end
+    end
+
+    alias_method :length, :size
+
+    # True if there are entries that exist in the map
+    def empty?
+      @references_to_keys_map.each do |_, ref|
+        return false if ref.object
+      end
+      true
+    end
+
     def inspect
       live_entries = {}
       each do |key, value|
@@ -98,20 +142,20 @@ module Ref
 
     private
 
-      def ref_key (key)
-        ref = @references_to_keys_map[key.__id__]
-        if ref && ref.object
-          ref.referenced_object_id
-        else
-          nil
-        end
+    def ref_key (key)
+      ref = @references_to_keys_map[key.__id__]
+      if ref && ref.object
+        ref.referenced_object_id
+      else
+        nil
       end
-      
-      def remove_reference_to(object_id)
-        @lock.synchronize do
-          @references_to_keys_map.delete(object_id)
-          @values.delete(object_id)
-        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

@@ -9,30 +9,34 @@ module Ref
       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
+      @lock = Monitor.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
+      @lock.synchronize do
+        ref = @references[key]
+        value = ref.object if ref
+        value
+      end
     end
 
+    alias_method :get, :[]
+
     # Add a key/value to the map.
     def []=(key, value)
       ObjectSpace.define_finalizer(value, @reference_cleanup)
@@ -49,6 +53,8 @@ module Ref
       value
     end
 
+    alias_method :put, :[]=
+
     # Remove the entry associated with the key from the map.
     def delete(key)
       ref = @references.delete(key)
@@ -70,14 +76,21 @@ module Ref
       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
-    
+
+    # Returns a hash containing the names and values for the struct’s members.
+    def to_h
+      hash = {}
+      each{|k,v| hash[k] = v}
+      hash
+    end
+
     # Iterate through all the key/value pairs in the map that have not been reclaimed
     # by the garbage collector.
     def each
@@ -95,13 +108,43 @@ module Ref
       end
     end
 
+    # Returns a new struct containing the contents of `other` and the contents
+    # of `self`. If no block is specified, the value for entries with duplicate
+    # keys will be that of `other`. Otherwise the value for each duplicate key
+    # is determined by calling the block with the key, its value in `self` and
+    # its value in `other`.
+    def merge(other_hash, &block)
+      to_h.merge(other_hash, &block).reduce(self.class.new) do |map, pair|
+        map[pair.first] = pair.last
+        map
+      end
+    end
+
     # Merge the values from another hash into this map.
     def merge!(other_hash)
-      other_hash.each do |key, value|
-        self[key] = value
+      @lock.synchronize do
+        other_hash.each { |key, value| self[key] = value }
       end
     end
 
+    # The number of entries in the map
+    def size
+      @references.count do |_, ref|
+        ref.object
+      end
+    end
+
+    alias_method :length, :size
+
+    # True if there are entries that exist in the map
+    def empty?
+      @references.each do |_, ref|
+        return false if ref.object
+      end
+
+      true
+    end
+
     def inspect
       live_entries = {}
       each do |key, value|
@@ -112,16 +155,16 @@ module Ref
 
     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)
+    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/reference_queue.rb

@@ -18,7 +18,7 @@ module Ref
   #       # Do something...
   #     end
   #   end
-  #   
+  #
   #   queue = Ref::ReferenceQueue.new
   #   ref = MyRef.new(Object.new)
   #   queue.monitor(ref)
@@ -30,7 +30,7 @@ module Ref
     def initialize
       @queue = []
       @references = {}
-      @lock = SafeMonitor.new
+      @lock = Monitor.new
       @finalizer = lambda do |object_id|
         @lock.synchronize do
           ref = @references.delete(object_id)
@@ -38,7 +38,7 @@ module 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)
@@ -52,7 +52,7 @@ module Ref
         push(reference)
       end
     end
-    
+
     # Add a reference to the queue.
     def push(reference)
       if reference
@@ -61,26 +61,26 @@ module Ref
         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