Dereferenceable is now in the Concern module.

Author: jdantonio

lib/concurrent/agent.rb

@@ -1,5 +1,5 @@
 require 'thread'
-require 'concurrent/dereferenceable'
+require 'concurrent/concern/dereferenceable'
 require 'concurrent/observable'
 require 'concurrent/logging'
 require 'concurrent/executor/executor'
@@ -79,7 +79,7 @@ module Concurrent
   # @!attribute [r] timeout
   #   @return [Fixnum] the maximum number of seconds before an update is cancelled
   class Agent
-    include Dereferenceable
+    include Concern::Dereferenceable
     include Observable
     include Logging
     include Deprecation

lib/concurrent/atom.rb

@@ -1,4 +1,4 @@
-require 'concurrent/dereferenceable'
+require 'concurrent/concern/dereferenceable'
 require 'concurrent/atomic/atomic_reference'
 require 'concurrent/synchronization/object'
 
@@ -22,7 +22,7 @@ module Concurrent
   #
   # @see http://clojure.org/atoms Clojure Atoms
   class Atom < Synchronization::Object
-    include Dereferenceable
+    include Concern::Dereferenceable
 
     # Create a new atom with the given initial value.
     #

lib/concurrent/concern/dereferenceable.rb

@@ -0,0 +1,88 @@
+module Concurrent
+  module Concern
+
+    # Object references in Ruby are mutable. This can lead to serious problems when
+    # the `#value` of a concurrent object is a mutable reference. Which is always the
+    # case unless the value is a `Fixnum`, `Symbol`, or similar "primitive" data type.
+    # Most classes in this library that expose a `#value` getter method do so using the
+    # `Dereferenceable` mixin module.
+    #
+    # @!macro copy_options
+    module Dereferenceable
+
+      # Return the value this object represents after applying the options specified
+      # by the `#set_deref_options` method.
+      #
+      # @return [Object] the current value of the object
+      def value
+        mutex.synchronize { apply_deref_options(@value) }
+      end
+      alias_method :deref, :value
+
+      protected
+
+      # Set the internal value of this object
+      #
+      # @param [Object] value the new value
+      def value=(value)
+        mutex.synchronize{ @value = value }
+      end
+
+      # A mutex lock used for synchronizing thread-safe operations. Methods defined
+      # by `Dereferenceable` are synchronized using the `Mutex` returned from this
+      # method. Operations performed by the including class that operate on the
+      # `@value` instance variable should be locked with this `Mutex`.
+      #
+      # @return [Mutex] the synchronization object
+      def mutex
+        @mutex
+      end
+
+      # Initializes the internal `Mutex`.
+      #
+      # @note This method *must* be called from within the constructor of the including class.
+      #
+      # @see #mutex
+      def init_mutex(mutex = Mutex.new)
+        @mutex = mutex
+      end
+
+      # @!macro [attach] dereferenceable_set_deref_options
+      #   Set the options which define the operations #value performs before
+      #   returning data to the caller (dereferencing).
+      #  
+      #   @note Most classes that include this module will call `#set_deref_options`
+      #   from within the constructor, thus allowing these options to be set at
+      #   object creation.
+      #  
+      #   @param [Hash] opts the options defining dereference behavior.
+      #   @option opts [String] :dup_on_deref (false) call `#dup` before returning the data
+      #   @option opts [String] :freeze_on_deref (false) call `#freeze` before returning the data
+      #   @option opts [String] :copy_on_deref (nil) call the given `Proc` passing
+      #     the internal value and returning the value returned from the proc
+      def set_deref_options(opts = {})
+        mutex.synchronize{ ns_set_deref_options(opts) }
+      end
+
+      # @!macro dereferenceable_set_deref_options
+      # @!visibility private
+      def ns_set_deref_options(opts)
+        @dup_on_deref = opts[:dup_on_deref] || opts[:dup]
+        @freeze_on_deref = opts[:freeze_on_deref] || opts[:freeze]
+        @copy_on_deref = opts[:copy_on_deref] || opts[:copy]
+        @do_nothing_on_deref = !(@dup_on_deref || @freeze_on_deref || @copy_on_deref)
+        nil
+      end
+
+      # @!visibility private
+      def apply_deref_options(value)
+        return nil if value.nil?
+        return value if @do_nothing_on_deref
+        value = @copy_on_deref.call(value) if @copy_on_deref
+        value = value.dup if @dup_on_deref
+        value = value.freeze if @freeze_on_deref
+        value
+      end
+    end
+  end
+end

lib/concurrent/delay.rb

@@ -26,7 +26,7 @@ module Concurrent
   # return the cached value. The operation will only be run once. This means that
   # any side effects created by the operation will only happen once as well.
   #
-  # `Delay` includes the `Concurrent::Dereferenceable` mixin to support thread
+  # `Delay` includes the `Concurrent::Concern::Dereferenceable` mixin to support thread
   # safety of the reference returned by `#value`.
   #
   # @!macro copy_options
@@ -39,7 +39,7 @@ module Concurrent
   #     constructor option. This will cause the delayed operation to be
   #     execute on the given executor, allowing the call to timeout.
   #
-  # @see Concurrent::Dereferenceable
+  # @see Concurrent::Concern::Dereferenceable
   class Delay < Synchronization::Object
     include Obligation
 

lib/concurrent/dereferenceable.rb

@@ -10,7 +10,7 @@ module Concurrent
   # the `MVar` constructors.
   # 
   # @see Concurrent::MVar
-  # @see Concurrent::Dereferenceable
+  # @see Concurrent::Concern::Dereferenceable
   # @see http://docs.oracle.com/javase/7/docs/api/java/util/concurrent/Exchanger.html java.util.concurrent.Exchanger
   class Exchanger
 

lib/concurrent/exchanger.rb

@@ -1,4 +1,4 @@
-require 'concurrent/dereferenceable'
+require 'concurrent/concern/dereferenceable'
 
 module Concurrent
 
@@ -69,7 +69,7 @@ module Concurrent
   #    (PoPL), 1996.
   class MVar
 
-    include Dereferenceable
+    include Concern::Dereferenceable
 
     # Unique value that represents that an `MVar` was empty
     EMPTY = Object.new

lib/concurrent/mvar.rb

@@ -1,14 +1,14 @@
 require 'thread'
 require 'timeout'
 
-require 'concurrent/dereferenceable'
+require 'concurrent/concern/dereferenceable'
 require 'concurrent/atomic/event'
 require 'concurrent/utility/deprecation'
 
 module Concurrent
 
   module Obligation
-    include Dereferenceable
+    include Concern::Dereferenceable
     include Deprecation
 
     # Has the obligation been fulfilled?

lib/concurrent/obligation.rb

@@ -1,4 +1,4 @@
-require 'concurrent/dereferenceable'
+require 'concurrent/concern/dereferenceable'
 require 'concurrent/observable'
 require 'concurrent/atomic/atomic_boolean'
 require 'concurrent/executor/executor_service'
@@ -150,7 +150,7 @@ module Concurrent
   # @see http://ruby-doc.org/stdlib-2.0/libdoc/observer/rdoc/Observable.html
   # @see http://docs.oracle.com/javase/7/docs/api/java/util/TimerTask.html
   class TimerTask < RubyExecutorService
-    include Dereferenceable
+    include Concern::Dereferenceable
     include Observable
 
     # Default `:execution_interval` in seconds.

lib/concurrent/timer_task.rb

@@ -1,4 +1,4 @@
-require_relative 'dereferenceable_shared'
+require_relative 'concern/dereferenceable_shared'
 require_relative 'observable_shared'
 
 module Concurrent