concurrent-ruby 0.9.2-java → 1.0.0-java

data/lib/concurrent/atom.rb

@@ -1,6 +1,41 @@
-require 'concurrent/concern/dereferenceable'
 require 'concurrent/atomic/atomic_reference'
-require 'concurrent/synchronization/object'
+require 'concurrent/collection/copy_on_notify_observer_set'
+require 'concurrent/concern/observable'
+require 'concurrent/synchronization'
+
+# @!macro [new] thread_safe_variable_comparison
+#
+#   ## Thread-safe Variable Classes
+#
+#   Each of the thread-safe variable classes is designed to solve a different
+#   problem. In general:
+#
+#   * *{Concurrent::Agent}:* Shared, mutable variable providing independent,
+#     uncoordinated, *asynchronous* change of individual values. Best used when
+#     the value will undergo frequent, complex updates. Suitable when the result
+#     of an update does not need to be known immediately.
+#   * *{Concurrent::Atom}:* Shared, mutable variable providing independent,
+#     uncoordinated, *synchronous* change of individual values. Best used when
+#     the value will undergo frequent reads but only occasional, though complex,
+#     updates. Suitable when the result of an update must be known immediately.
+#   * *{Concurrent::AtomicReference}:* A simple object reference that can be
+#     atomically. Updates are synchronous but fast. Bast used when updates a
+#     simple set operations. Not suitable when updates are complex.
+#     {Concurrent::AtomicBoolean} and {Concurrent::AtomicFixnum} are similar
+#     but optimized for the given data type.
+#   * *{Concurrent::Exchanger}:* Shared, stateless synchronization point. Used
+#     when two or more threads need to exchange data. The threads will pair then
+#     block on each other until the exchange is complete.
+#   * *{Concurrent::MVar}:* Shared synchronization point. Used when one thread
+#     must give a value to another, which must take the value. The threads will
+#     block on each other until the exchange is complete.
+#   * *{Concurrent::ThreadLocalVar}:* Shared, mutable, isolated variable which
+#     holds a different value for each thread which has access. Often used as
+#     an instance variable in objects which must maintain different state
+#     for different threads.
+#   * *{Concurrent::TVar}:* Shared, mutable variables which provide
+#     *coordinated*, *synchronous*, change of *many* stated. Used when multiple
+#     value must change together, in an all-or-nothing transaction.
 
 module Concurrent
 
@@ -18,11 +53,50 @@ module Concurrent
   # new value to the result of running the given block if and only if that
   # value validates.
   #
-  # @!macro copy_options
+  # ## Example
+  #
+  # ```
+  # def next_fibonacci(set = nil)
+  #   return [0, 1] if set.nil?
+  #   set + [set[-2..-1].reduce{|sum,x| sum + x }]
+  # end
+  #
+  # # create an atom with aninitial value
+  # atom = Concurrent::Atom.new(next_fibonacci)
+  #
+  # # send a few update requests
+  # 5.times do
+  #   atom.swap{|set| next_fibonacci(set) }
+  # end
+  #
+  # # get the current value
+  # atom.value #=> [0, 1, 1, 2, 3, 5, 8]
+  # ```
+  #
+  # ## Observation
+  #
+  # Atoms support observers through the {Concurrent::Observable} mixin module.
+  # Notification of observers occurs every time the value of the Atom changes.
+  # When notified the observer will receive three arguments: `time`, `old_value`,
+  # and `new_value`. The `time` argument is the time at which the value change
+  # occurred. The `old_value` is the value of the Atom when the change began
+  # The `new_value` is the value to which the Atom was set when the change
+  # completed. Note that `old_value` and `new_value` may be the same. This is
+  # not an error. It simply means that the change operation returned the same
+  # value.
+  #
+  # Unlike in Clojure, `Atom` cannot participate in {Concurrent::TVar} transactions.
+  #
+  # @!macro thread_safe_variable_comparison
   #
   # @see http://clojure.org/atoms Clojure Atoms
+  # @see http://clojure.org/state Values and Change - Clojure's approach to Identity and State
   class Atom < Synchronization::Object
-    include Concern::Dereferenceable
+    include Concern::Observable
+
+    safe_initialization!
+    private(*attr_atomic(:value))
+    public :value
 
     # Create a new atom with the given initial value.
     #
@@ -34,25 +108,20 @@ module Concurrent
     #   is acceptable else return false (preferrably) or raise an exception.
     #
     # @!macro deref_options
-    # 
+    #
     # @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!
+      @Validator     = opts.fetch(:validator, -> v { true })
+      self.observers = Collection::CopyOnNotifyObserverSet.new
+      self.value     = value
     end
 
-    # The current value of the atom.
+    # @!method value
+    #   The current value of the atom.
     #
-    # @return [Object] The current value.
-    def value
-      apply_deref_options(@value.value)
-    end
+    #   @return [Object] The current value.
+
     alias_method :deref, :value
 
     # Atomically swaps the value of atom using the given block. The current
@@ -68,7 +137,7 @@ module Concurrent
     # 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.
     #
@@ -87,45 +156,66 @@ module Concurrent
     def swap(*args)
       raise ArgumentError.new('no block given') unless block_given?
 
-      begin
-        loop do
-          old_value = @value.value
+      loop do
+        old_value = value
+        begin
           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)
+          break old_value unless valid?(new_value)
+          break new_value if compare_and_set(old_value, new_value)
+        rescue
+          break old_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.
+    # 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.
+    # @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.
+    # @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
+      if valid?(new_value) && compare_and_set_value(old_value, new_value)
+        observers.notify_observers(Time.now, old_value, new_value)
+        true
+      else
+        false
+      end
     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)
+    # Atomically sets the value of atom to the new value without regard for the
+    # current value so long as the new value successfully validates against the
+    # (optional) validator given at construction.
+    #
+    # @param [Object] new_value The intended new value.
+    #
+    # @return [Object] The final value of the atom after all operations and
+    #   validations are complete.
+    def reset(new_value)
+      old_value = value
+      if valid?(new_value)
+        self.value = new_value
+        observers.notify_observers(Time.now, old_value, new_value)
+        new_value
       else
-        false
+        old_value
       end
     end
+
+    private
+
+    # Is the new value valid?
+    #
+    # @param [Object] new_value The intended new value.
+    # @return [Boolean] false if the validator function returns false or raises
+    #   an exception else true
+    def valid?(new_value)
+      @Validator.call(new_value)
+    rescue
+      false
+    end
   end
 end

data/lib/concurrent/atomic/abstract_thread_local_var.rb

@@ -0,0 +1,38 @@
+require 'concurrent/constants'
+
+module Concurrent
+
+  # @!macro thread_local_var
+  # @!macro internal_implementation_note
+  # @!visibility private
+  class AbstractThreadLocalVar
+
+    # @!macro thread_local_var_method_initialize
+    def initialize(default = nil)
+      @default = default
+      allocate_storage
+    end
+
+    # @!macro thread_local_var_method_get
+    def value
+      raise NotImplementedError
+    end
+
+    # @!macro thread_local_var_method_set
+    def value=(value)
+      raise NotImplementedError
+    end
+
+    # @!macro thread_local_var_method_bind
+    def bind(value, &block)
+      raise NotImplementedError
+    end
+
+    protected
+
+    # @!visibility private
+    def allocate_storage
+      raise NotImplementedError
+    end
+  end
+end

data/lib/concurrent/atomic/atomic_boolean.rb

@@ -1,118 +1,85 @@
-require 'concurrent/utility/native_extension_loader'
+require 'concurrent/atomic/mutex_atomic_boolean'
 require 'concurrent/synchronization'
 
 module Concurrent
 
-  # @!macro [attach] atomic_boolean
+  ###################################################################
+
+  # @!macro [new] atomic_boolean_method_initialize
   #
-  #   A boolean value that can be updated atomically. Reads and writes to an atomic
-  #   boolean and thread-safe and guaranteed to succeed. Reads and writes may block
-  #   briefly but no explicit locking is required.
+  #   Creates a new `AtomicBoolean` with the given initial value.
   #
-  #       Testing with ruby 2.1.2
-  #       Testing with Concurrent::MutexAtomicBoolean...
-  #         2.790000   0.000000   2.790000 (  2.791454)
-  #       Testing with Concurrent::CAtomicBoolean...
-  #         0.740000   0.000000   0.740000 (  0.740206)
+  #   @param [Boolean] initial the initial value
+
+  # @!macro [new] atomic_boolean_method_value_get
   #
-  #       Testing with jruby 1.9.3
-  #       Testing with Concurrent::MutexAtomicBoolean...
-  #         5.240000   2.520000   7.760000 (  3.683000)
-  #       Testing with Concurrent::JavaAtomicBoolean...
-  #         3.340000   0.010000   3.350000 (  0.855000)
+  #   Retrieves the current `Boolean` value.
   #
-  #   @see http://docs.oracle.com/javase/7/docs/api/java/util/concurrent/atomic/AtomicBoolean.html java.util.concurrent.atomic.AtomicBoolean
+  #   @return [Boolean] the current value
+
+  # @!macro [new] atomic_boolean_method_value_set
   #
-  # @!visibility private
+  #   Explicitly sets the value.
   #
-  # @!macro internal_implementation_note
-  class MutexAtomicBoolean < Synchronization::Object
-
-    # @!macro [attach] atomic_boolean_method_initialize
-    #
-    #   Creates a new `AtomicBoolean` with the given initial value.
-    #
-    #   @param [Boolean] initial the initial value
-    def initialize(initial = false)
-      super()
-      synchronize { ns_initialize(initial) }
-    end
-
-    # @!macro [attach] atomic_boolean_method_value_get
-    #
-    #   Retrieves the current `Boolean` value.
-    #
-    #   @return [Boolean] the current value
-    def value
-      synchronize { @value }
-    end
-
-    # @!macro [attach] atomic_boolean_method_value_set
-    #
-    #   Explicitly sets the value.
-    #
-    #   @param [Boolean] value the new value to be set
-    #
-    #   @return [Boolean] the current value
-    def value=(value)
-      synchronize { @value = !!value }
-    end
+  #   @param [Boolean] value the new value to be set
+  #
+  #   @return [Boolean] the current value
 
-    # @!macro [attach] atomic_boolean_method_true_question
-    #
-    #   Is the current value `true`
-    #
-    #   @return [Boolean] true if the current value is `true`, else false
-    def true?
-      synchronize { @value }
-    end
+  # @!macro [new] atomic_boolean_method_true_question
+  #
+  #   Is the current value `true`
+  #
+  #   @return [Boolean] true if the current value is `true`, else false
 
-    # @!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?
-      synchronize { !@value }
-    end
+  # @!macro [new] atomic_boolean_method_false_question
+  #
+  #   Is the current value `false`
+  #
+  #   @return [Boolean] true if the current value is `false`, else false
 
-    # @!macro [attach] atomic_boolean_method_make_true
-    #
-    #   Explicitly sets the value to true.
-    #
-    #   @return [Boolean] true is value has changed, otherwise false
-    def make_true
-      synchronize { ns_make_value(true) }
-    end
+  # @!macro [new] atomic_boolean_method_make_true
+  #
+  #   Explicitly sets the value to true.
+  #
+  #   @return [Boolean] true is value has changed, otherwise false
 
-    # @!macro [attach] atomic_boolean_method_make_false
-    #
-    #   Explicitly sets the value to false.
-    #
-    #   @return [Boolean] true is value has changed, otherwise false
-    def make_false
-      synchronize { ns_make_value(false) }
-    end
+  # @!macro [new] atomic_boolean_method_make_false
+  #
+  #   Explicitly sets the value to false.
+  #
+  #   @return [Boolean] true is value has changed, otherwise false
 
-    protected
+  ###################################################################
 
-    # @!visibility private
-    def ns_initialize(initial)
-      @value = !!initial
-    end
+  # @!macro [new] atomic_boolean_public_api
+  #
+  #   @!method initialize(initial = false)
+  #     @!macro  atomic_boolean_method_initialize
+  #
+  #   @!method value
+  #     @!macro  atomic_boolean_method_value_get
+  #
+  #   @!method value=(value)
+  #     @!macro  atomic_boolean_method_value_set
+  #
+  #   @!method true?
+  #     @!macro  atomic_boolean_method_true_question
+  #
+  #   @!method false?
+  #     @!macro  atomic_boolean_method_false_question
+  #
+  #   @!method make_true
+  #     @!macro  atomic_boolean_method_make_true
+  #
+  #   @!method make_false
+  #     @!macro  atomic_boolean_method_make_false
 
-    # @!visibility private
-    def ns_make_value(value)
-      old = @value
-      @value = value
-      old != @value
-    end
-  end
+  ###################################################################
 
   # @!visibility private
   # @!macro internal_implementation_note
   AtomicBooleanImplementation = case
-                                when Concurrent.on_jruby?
+                                when defined?(JavaAtomicBoolean)
                                   JavaAtomicBoolean
                                 when defined?(CAtomicBoolean)
                                   CAtomicBoolean
@@ -121,31 +88,29 @@ module Concurrent
                                 end
   private_constant :AtomicBooleanImplementation
 
-  # @!macro atomic_boolean
+  # @!macro [attach] atomic_boolean
+  #
+  #   A boolean value that can be updated atomically. Reads and writes to an atomic
+  #   boolean and thread-safe and guaranteed to succeed. Reads and writes may block
+  #   briefly but no explicit locking is required.
+  #
+  #   @!macro thread_safe_variable_comparison
+  #
+  #       Testing with ruby 2.1.2
+  #       Testing with Concurrent::MutexAtomicBoolean...
+  #         2.790000   0.000000   2.790000 (  2.791454)
+  #       Testing with Concurrent::CAtomicBoolean...
+  #         0.740000   0.000000   0.740000 (  0.740206)
+  #
+  #       Testing with jruby 1.9.3
+  #       Testing with Concurrent::MutexAtomicBoolean...
+  #         5.240000   2.520000   7.760000 (  3.683000)
+  #       Testing with Concurrent::JavaAtomicBoolean...
+  #         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
   #
-  # @see Concurrent::MutexAtomicBoolean
+  # @!macro atomic_boolean_public_api
   class AtomicBoolean < AtomicBooleanImplementation
-
-    # @!method initialize(initial = false)
-    #   @!macro atomic_boolean_method_initialize
-
-    # @!method value
-    #   @!macro atomic_boolean_method_value_get
-
-    # @!method value=(value)
-    #   @!macro atomic_boolean_method_value_set
-
-    # @!method true?
-    #   @!macro atomic_boolean_method_true_question
-
-    # @!method false?
-    #   @!macro atomic_boolean_method_false_question
-
-    # @!method make_true
-    #   @!macro atomic_boolean_method_make_true
-
-    # @!method make_false
-    #   @!macro atomic_boolean_method_make_false
-
   end
 end