concurrent-ruby 0.8.0 → 0.9.0.pre2

data/lib/concurrent/atom.rb

@@ -0,0 +1,171 @@
+require 'concurrent/concern/dereferenceable'
+require 'concurrent/atomic/atomic_reference'
+require 'concurrent/synchronization/object'
+
+module Concurrent
+
+  # Atoms provide a way to manage shared, synchronous, independent state.
+  #
+  # An atom is initialized with an initial value and an optional validation
+  # proc. At any time the value of the atom can be synchronously and safely
+  # changed. If a validator is given at construction then any new value
+  # will be checked against the validator and will be rejected if the
+  # validator returns false or raises an exception.
+  #
+  # There are two ways to change the value of an atom: {#compare_and_set} and
+  # {#swap}. The former will set the new value if and only if it validates and
+  # the current value matches the new value. The latter will atomically set the
+  # new value to the result of running the given block if and only if that
+  # value validates.
+  #
+  # @!macro [attach] copy_options
+  #   ## Copy Options
+  #
+  #   Object references in Ruby are mutable. This can lead to serious
+  #   problems when the {#value} of an object is a mutable reference. Which
+  #   is always the case unless the value is a `Fixnum`, `Symbol`, or similar
+  #   "primative" data type. Each instance can be configured with a few
+  #   options that can help protect the program from potentially dangerous
+  #   operations. Each of these options can be optionally set when the oject
+  #   instance is created: 
+  #
+  #   * `:dup_on_deref` When true the object will call the `#dup` method on
+  #     the `value` object every time the `#value` methid is called
+  #     (default: false)
+  #   * `:freeze_on_deref` When true the object will call the `#freeze`
+  #     method on the `value` object every time the `#value` method is called
+  #     (default: false)
+  #   * `:copy_on_deref` When given a `Proc` object the `Proc` will be run
+  #     every time   the `#value` method is called. The `Proc` will be given
+  #     the current `value` as its only argument and the result returned by
+  #     the block will be the return   value of the `#value` call. When `nil`
+  #     this option will be ignored (default: nil)
+  #  
+  #   When multiple deref options are set the order of operations is strictly defined.
+  #   The order of deref operations is:
+  #   * `:copy_on_deref`
+  #   * `:dup_on_deref`
+  #   * `:freeze_on_deref`
+  #  
+  #   Because of this ordering there is no need to `#freeze` an object created by a
+  #   provided `:copy_on_deref` block. Simply set `:freeze_on_deref` to `true`.
+  #   Setting both `:dup_on_deref` to `true` and `:freeze_on_deref` to `true` is
+  #   as close to the behavior of a "pure" functional language (like Erlang, Clojure,
+  #   or Haskell) as we are likely to get in Ruby.
+  #
+  # @see http://clojure.org/atoms Clojure Atoms
+  class Atom < Synchronization::Object
+    include Concern::Dereferenceable
+
+    # Create a new atom with the given initial value.
+    #
+    # @param [Object] value The initial value
+    # @param [Hash] opts The options used to configure the atom
+    # @option opts [Proc] :validator (nil) Optional proc used to validate new
+    #   values. It must accept one and only one argument which will be the
+    #   intended new value. The validator will return true if the new value
+    #   is acceptable else return false (preferrably) or raise an exception.
+    #
+    # @!macro [attach] deref_options
+    #   @option opts [Boolean] :dup_on_deref (false) Call `#dup` before
+    #     returning the data from {#value}
+    #   @option opts [Boolean] :freeze_on_deref (false) Call `#freeze` before
+    #     returning the data from {#value}
+    #   @option opts [Proc] :copy_on_deref (nil) When calling the {#value}
+    #     method, call the given proc passing the internal value as the sole
+    #     argument then return the new value returned from the proc.
+    # 
+    # @raise [ArgumentError] if the validator is not a `Proc` (when given)
+    def initialize(value, opts = {})
+      super()
+
+      @validator = opts.fetch(:validator, ->(v){ true })
+      raise ArgumentError.new('validator must be a proc') unless @validator.is_a? Proc
+
+      @value = Concurrent::AtomicReference.new(value)
+      ns_set_deref_options(opts)
+      ensure_ivar_visibility!
+    end
+
+    # The current value of the atom.
+    #
+    # @return [Object] The current value.
+    def value
+      apply_deref_options(@value.value)
+    end
+    alias_method :deref, :value
+
+    # Atomically swaps the value of atom using the given block. The current
+    # value will be passed to the block, as will any arguments passed as
+    # arguments to the function. The new value will be validated against the
+    # (optional) validator proc given at construction. If validation fails the
+    # value will not be changed.
+    #
+    # Internally, {#swap} reads the current value, applies the block to it, and
+    # attempts to compare-and-set it in. Since another thread may have changed
+    # the value in the intervening time, it may have to retry, and does so in a
+    # spin loop. The net effect is that the value will always be the result of
+    # the application of the supplied block to a current value, atomically.
+    # However, because the block might be called multiple times, it must be free
+    # of side effects.
+    # 
+    # @note The given block may be called multiple times, and thus should be free
+    #   of side effects.
+    #
+    # @param [Object] args Zero or more arguments passed to the block.
+    #
+    # @yield [value, args] Calculates a new value for the atom based on the
+    #   current value and any supplied agruments.
+    # @yieldparam value [Object] The current value of the atom.
+    # @yieldparam args [Object] All arguments passed to the function, in order.
+    # @yieldreturn [Object] The intended new value of the atom.
+    #
+    # @return [Object] The final value of the atom after all operations and
+    #   validations are complete.
+    #
+    # @raise [ArgumentError] When no block is given.
+    def swap(*args)
+      raise ArgumentError.new('no block given') unless block_given?
+
+      begin
+        loop do
+          old_value = @value.value
+          new_value = yield(old_value, *args)
+          return old_value unless @validator.call(new_value)
+          return new_value if compare_and_set!(old_value, new_value)
+        end
+      rescue
+        return @value.value
+      end
+    end
+
+    # @!macro [attach] atom_compare_and_set
+    #   Atomically sets the value of atom to the new value if and only if the
+    #   current value of the atom is identical to the old value and the new
+    #   value successfully validates against the (optional) validator given
+    #   at construction.
+    #
+    #   @param [Object] old_value The expected current value.
+    #   @param [Object] new_value The intended new value.
+    #
+    #   @return [Boolean] True if the value is changed else false.
+    def compare_and_set(old_value, new_value)
+      compare_and_set!(old_value, new_value)
+    rescue
+      false
+    end
+
+    private
+
+    # @!macro atom_compare_and_set
+    # @raise [Exception] if the validator proc raises an exception
+    # @!visibility private
+    def compare_and_set!(old_value, new_value)
+      if @validator.call(new_value) # may raise exception
+        @value.compare_and_set(old_value, new_value)
+      else
+        false
+      end
+    end
+  end
+end

data/lib/concurrent/atomic/atomic_boolean.rb

@@ -1,4 +1,5 @@
-require_relative '../../extension_helper'
+require 'concurrent/utility/native_extension_loader'
+require 'concurrent/synchronization'
 
 module Concurrent
 
@@ -21,7 +22,11 @@ module Concurrent
   #         3.340000   0.010000   3.350000 (  0.855000)
   #
   #   @see http://docs.oracle.com/javase/7/docs/api/java/util/concurrent/atomic/AtomicBoolean.html java.util.concurrent.atomic.AtomicBoolean
-  class MutexAtomicBoolean
+  #
+  # @!visibility private
+  #
+  # @!macro internal_implementation_note
+  class MutexAtomicBoolean < Synchronization::Object
 
     # @!macro [attach] atomic_boolean_method_initialize
     #
@@ -29,8 +34,8 @@ module Concurrent
     #
     #   @param [Boolean] initial the initial value
     def initialize(initial = false)
-      @value = !!initial
-      @mutex = Mutex.new
+      super()
+      synchronize { ns_initialize(initial) }
     end
 
     # @!macro [attach] atomic_boolean_method_value_get
@@ -39,10 +44,7 @@ module Concurrent
     #
     #   @return [Boolean] the current value
     def value
-      @mutex.lock
-      @value
-    ensure
-      @mutex.unlock
+      synchronize { @value }
     end
 
     # @!macro [attach] atomic_boolean_method_value_set
@@ -53,11 +55,7 @@ module Concurrent
     #
     #   @return [Boolean] the current value
     def value=(value)
-      @mutex.lock
-      @value = !!value
-      @value
-    ensure
-      @mutex.unlock
+      synchronize { @value = !!value }
     end
 
     # @!macro [attach] atomic_boolean_method_true_question
@@ -66,22 +64,16 @@ module Concurrent
     #
     #   @return [Boolean] true if the current value is `true`, else false
     def true?
-      @mutex.lock
-      @value
-    ensure
-      @mutex.unlock
+      synchronize { @value }
     end
 
-    # @!macro atomic_boolean_method_false_question
+    # @!macro [attach] atomic_boolean_method_false_question
     #
     #   Is the current value `false`
     #
     #   @return [Boolean] true if the current value is `false`, else false
     def false?
-      @mutex.lock
-      !@value
-    ensure
-      @mutex.unlock
+      synchronize { !@value }
     end
 
     # @!macro [attach] atomic_boolean_method_make_true
@@ -90,12 +82,7 @@ module Concurrent
     #
     #   @return [Boolean] true is value has changed, otherwise false
     def make_true
-      @mutex.lock
-      old = @value
-      @value = true
-      !old
-    ensure
-      @mutex.unlock
+      synchronize { ns_make_value(true) }
     end
 
     # @!macro [attach] atomic_boolean_method_make_false
@@ -104,98 +91,61 @@ module Concurrent
     #
     #   @return [Boolean] true is value has changed, otherwise false
     def make_false
-      @mutex.lock
-      old = @value
-      @value = false
-      old
-    ensure
-      @mutex.unlock
+      synchronize { ns_make_value(false) }
     end
-  end
 
-  if RUBY_PLATFORM == 'java'
-
-    # @!macro atomic_boolean
-    class JavaAtomicBoolean
-
-      # @!macro atomic_boolean_method_initialize
-      #
-      def initialize(initial = false)
-        @atomic = java.util.concurrent.atomic.AtomicBoolean.new(!!initial)
-      end
-
-      # @!macro atomic_boolean_method_value_get
-      #
-      def value
-        @atomic.get
-      end
-
-      # @!macro atomic_boolean_method_value_set
-      #
-      def value=(value)
-        @atomic.set(!!value)
-      end
-
-      # @!macro atomic_boolean_method_true_question
-      def true?
-        @atomic.get
-      end
-
-      # @!macro atomic_boolean_method_false_question
-      def false?
-        !@atomic.get
-      end
-
-      # @!macro atomic_boolean_method_make_true
-      def make_true
-        @atomic.compareAndSet(false, true)
-      end
-
-      # @!macro atomic_boolean_method_make_false
-      def make_false
-        @atomic.compareAndSet(true, false)
-      end
-    end
+    protected
 
-    # @!macro atomic_boolean
-    class AtomicBoolean < JavaAtomicBoolean
+    # @!visibility private
+    def ns_initialize(initial)
+      @value = !!initial
     end
 
-  elsif defined?(CAtomicBoolean)
-
-    # @!macro atomic_boolean
-    class CAtomicBoolean
-
-      # @!method initialize
-      #   @!macro atomic_boolean_method_initialize
+    # @!visibility private
+    def ns_make_value(value)
+      old = @value
+      @value = value
+      old != @value
+    end
+  end
 
-      # @!method value
-      #   @!macro atomic_boolean_method_value_get
+  # @!visibility private
+  # @!macro internal_implementation_note
+  AtomicBooleanImplementation = case
+                                when Concurrent.on_jruby?
+                                  JavaAtomicBoolean
+                                when defined?(CAtomicBoolean)
+                                  CAtomicBoolean
+                                else
+                                  MutexAtomicBoolean
+                                end
+  private_constant :AtomicBooleanImplementation
+
+  # @!macro atomic_boolean
+  #
+  # @see Concurrent::MutexAtomicBoolean
+  class AtomicBoolean < AtomicBooleanImplementation
 
-      # @!method value=
-      #   @!macro atomic_boolean_method_value_set
+    # @!method initialize(initial = false)
+    #   @!macro atomic_boolean_method_initialize
 
-      # @!method true?
-      #   @!macro atomic_boolean_method_true_question
+    # @!method value
+    #   @!macro atomic_boolean_method_value_get
 
-      # @!method false?
-      #   @!macro atomic_boolean_method_false_question
+    # @!method value=(value)
+    #   @!macro atomic_boolean_method_value_set
 
-      # @!method make_true
-      #   @!macro atomic_boolean_method_make_true
+    # @!method true?
+    #   @!macro atomic_boolean_method_true_question
 
-      # @!method make_false
-      #   @!macro atomic_boolean_method_make_false
-    end
+    # @!method false?
+    #   @!macro atomic_boolean_method_false_question
 
-    # @!macro atomic_boolean
-    class AtomicBoolean < CAtomicBoolean
-    end
+    # @!method make_true
+    #   @!macro atomic_boolean_method_make_true
 
-  else
+    # @!method make_false
+    #   @!macro atomic_boolean_method_make_false
 
-    # @!macro atomic_boolean
-    class AtomicBoolean < MutexAtomicBoolean
-    end
   end
 end

data/lib/concurrent/atomic/atomic_fixnum.rb

@@ -1,4 +1,5 @@
-require_relative '../../extension_helper'
+require 'concurrent/utility/native_extension_loader'
+require 'concurrent/synchronization'
 
 module Concurrent
 
@@ -21,7 +22,10 @@ module Concurrent
   #         4.520000   0.030000   4.550000 (  1.187000)
   #
   #   @see http://docs.oracle.com/javase/7/docs/api/java/util/concurrent/atomic/AtomicLong.html java.util.concurrent.atomic.AtomicLong
-  class MutexAtomicFixnum
+  #
+  # @!visibility private
+  # @!macro internal_implementation_note
+  class MutexAtomicFixnum < Synchronization::Object
 
     # http://stackoverflow.com/questions/535721/ruby-max-integer
     MIN_VALUE = -(2**(0.size * 8 - 2))
@@ -31,12 +35,11 @@ module Concurrent
     #
     #   Creates a new `AtomicFixnum` with the given initial value.
     #
-    #   @param [Fixnum] init the initial value
+    #   @param [Fixnum] initial the initial value
     #   @raise [ArgumentError] if the initial value is not a `Fixnum`
-    def initialize(init = 0)
-      raise ArgumentError.new('initial value must be a Fixnum') unless init.is_a?(Fixnum)
-      @value = init
-      @mutex = Mutex.new
+    def initialize(initial = 0)
+      super()
+      synchronize { ns_initialize(initial) }
     end
 
     # @!macro [attach] atomic_fixnum_method_value_get
@@ -45,10 +48,7 @@ module Concurrent
     #
     #   @return [Fixnum] the current value
     def value
-      @mutex.lock
-      @value
-    ensure
-      @mutex.unlock
+      synchronize { @value }
     end
 
     # @!macro [attach] atomic_fixnum_method_value_set
@@ -61,11 +61,7 @@ module Concurrent
     #
     #   @raise [ArgumentError] if the new value is not a `Fixnum`
     def value=(value)
-      raise ArgumentError.new('value must be a Fixnum') unless value.is_a?(Fixnum)
-      @mutex.lock
-      @value = value
-    ensure
-      @mutex.unlock
+      synchronize { ns_set(value) }
     end
 
     # @!macro [attach] atomic_fixnum_method_increment
@@ -74,10 +70,7 @@ module Concurrent
     #
     #   @return [Fixnum] the current value after incrementation
     def increment
-      @mutex.lock
-      @value += 1
-    ensure
-      @mutex.unlock
+      synchronize { ns_set(@value + 1) }
     end
 
     alias_method :up, :increment
@@ -88,115 +81,94 @@ module Concurrent
     #
     #   @return [Fixnum] the current value after decrementation
     def decrement
-      @mutex.lock
-      @value -= 1
-    ensure
-      @mutex.unlock
+      synchronize { ns_set(@value -1) }
     end
 
     alias_method :down, :decrement
 
     # @!macro [attach] atomic_fixnum_method_compare_and_set
-    # 
+    #
     #   Atomically sets the value to the given updated value if the current
     #   value == the expected value.
     #
     #   @param [Fixnum] expect the expected value
     #   @param [Fixnum] update the new value
     #
-    #   @return [Boolean] true if the value was updated else false 
+    #   @return [Fixnum] true if the value was updated else false
     def compare_and_set(expect, update)
-      @mutex.lock
-      if @value == expect
-        @value = update
-        true
-      else
-        false
+      synchronize do
+        if @value == expect
+          @value = update
+          true
+        else
+          false
+        end
       end
-    ensure
-      @mutex.unlock
     end
-  end
-
-  if RUBY_PLATFORM == 'java'
-
-    # @!macro atomic_fixnum
-    class JavaAtomicFixnum
 
-      MIN_VALUE = Java::JavaLang::Long::MIN_VALUE
-      MAX_VALUE = Java::JavaLang::Long::MAX_VALUE
+    protected
 
-      # @!macro atomic_fixnum_method_initialize
-      def initialize(init = 0)
-        raise ArgumentError.new('initial value must be a Fixnum') unless init.is_a?(Fixnum)
-        @atomic = java.util.concurrent.atomic.AtomicLong.new(init)
-      end
-
-      # @!macro atomic_fixnum_method_value_get
-      def value
-        @atomic.get
-      end
-
-      # @!macro atomic_fixnum_method_value_set
-      def value=(value)
-        raise ArgumentError.new('value must be a Fixnum') unless value.is_a?(Fixnum)
-        @atomic.set(value)
-      end
-
-      # @!macro atomic_fixnum_method_increment
-      def increment
-        @atomic.increment_and_get
-      end
-      alias_method :up, :increment
+    # @!visibility private
+    def ns_initialize(initial)
+      ns_set(initial)
+    end
 
-      # @!macro atomic_fixnum_method_decrement
-      def decrement
-        @atomic.decrement_and_get
-      end
-      alias_method :down, :decrement
+    private
 
-      # @!macro atomic_fixnum_method_compare_and_set
-      def compare_and_set(expect, update)
-        @atomic.compare_and_set(expect, update)
-      end
+    # @!visibility private
+    def ns_set(value)
+      range_check!(value)
+      @value = value
     end
 
-    # @!macro atomic_fixnum
-    class AtomicFixnum < JavaAtomicFixnum
+    # @!visibility private
+    def range_check!(value)
+      if !value.is_a?(Fixnum)
+        raise ArgumentError.new('value value must be a Fixnum')
+      elsif value > MAX_VALUE
+        raise RangeError.new("#{value} is greater than the maximum value of #{MAX_VALUE}")
+      elsif value < MIN_VALUE
+        raise RangeError.new("#{value} is less than the maximum value of #{MIN_VALUE}")
+      else
+        value
+      end
     end
+  end
 
-  elsif defined?(CAtomicFixnum)
-
-    # @!macro atomic_fixnum
-    class CAtomicFixnum
+  # @!visibility private
+  # @!macro internal_implementation_note
+  AtomicFixnumImplementation = case
+                               when Concurrent.on_jruby?
+                                 JavaAtomicFixnum
+                               when defined?(CAtomicFixnum)
+                                 CAtomicFixnum
+                               else
+                                 MutexAtomicFixnum
+                               end
+  private_constant :AtomicFixnumImplementation
+
+  # @!macro atomic_fixnum
+  #
+  # @see Concurrent::MutexAtomicFixnum
+  class AtomicFixnum < AtomicFixnumImplementation
 
-      # @!method initialize
-      #   @!macro atomic_fixnum_method_initialize
+    # @!method initialize(initial = 0)
+    #   @!macro atomic_fixnum_method_initialize
 
-      # @!method value
-      #   @!macro atomic_fixnum_method_value_get
+    # @!method value
+    #   @!macro atomic_fixnum_method_value_get
 
-      # @!method value=
-      #   @!macro atomic_fixnum_method_value_set
+    # @!method value=(value)
+    #   @!macro atomic_fixnum_method_value_set
 
-      # @!method increment
-      #   @!macro atomic_fixnum_method_increment
+    # @!method increment
+    #   @!macro atomic_fixnum_method_increment
 
-      # @!method decrement
-      #   @!macro atomic_fixnum_method_decrement
+    # @!method decrement
+    #   @!macro atomic_fixnum_method_decrement
 
-      # @!method compare_and_set
-      #   @!macro atomic_fixnum_method_compare_and_set
-    end
+    # @!method compare_and_set(expect, update)
+    #   @!macro atomic_fixnum_method_compare_and_set
 
-    # @!macro atomic_fixnum
-    class AtomicFixnum < CAtomicFixnum
-    end
-
-  else
-
-    # @!macro atomic_fixnum
-    class AtomicFixnum < MutexAtomicFixnum
-    end
   end
 end