concurrent-ruby 1.0.0.pre1 → 1.0.0.pre2

data/lib/concurrent/atom.rb

@@ -1,6 +1,7 @@
-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'
 
 module Concurrent
 
@@ -18,11 +19,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_volatile_with_cas(:value)
+    public :value
 
     # Create a new atom with the given initial value.
     #
@@ -34,25 +74,19 @@ 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
+      super(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 +102,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 +121,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/atomic_boolean.rb

@@ -94,6 +94,8 @@ module Concurrent
   #   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)

data/lib/concurrent/atomic/atomic_fixnum.rb

@@ -111,6 +111,8 @@ module Concurrent
   #   fixnum 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::MutexAtomicFixnum...
   #         3.130000   0.000000   3.130000 (  3.136505)

data/lib/concurrent/atomic/cyclic_barrier.rb

@@ -4,7 +4,7 @@ module Concurrent
 
   # A synchronization aid that allows a set of threads to all wait for each
   # other to reach a common barrier point.
-  class CyclicBarrier < Synchronization::Object
+  class CyclicBarrier < Synchronization::LockableObject
 
     # @!visibility private
     Generation = Struct.new(:status)

data/lib/concurrent/atomic/event.rb

@@ -13,7 +13,7 @@ module Concurrent
   # `#reset` at any time once it has been set.
   #
   # @see http://msdn.microsoft.com/en-us/library/windows/desktop/ms682655.aspx
-  class Event < Synchronization::Object
+  class Event < Synchronization::LockableObject
 
     # Creates a new `Event` in the unset state. Threads calling `#wait` on the
     # `Event` will block.

data/lib/concurrent/atomic/mutex_atomic_boolean.rb

@@ -5,7 +5,7 @@ module Concurrent
   # @!macro atomic_boolean
   # @!visibility private
   # @!macro internal_implementation_note
-  class MutexAtomicBoolean < Synchronization::Object
+  class MutexAtomicBoolean < Synchronization::LockableObject
 
     # @!macro atomic_boolean_method_initialize
     def initialize(initial = false)

data/lib/concurrent/atomic/mutex_atomic_fixnum.rb

@@ -5,7 +5,7 @@ module Concurrent
   # @!macro atomic_fixnum
   # @!visibility private
   # @!macro internal_implementation_note
-  class MutexAtomicFixnum < Synchronization::Object
+  class MutexAtomicFixnum < Synchronization::LockableObject
 
     # http://stackoverflow.com/questions/535721/ruby-max-integer
     MIN_VALUE = -(2**(0.size * 8 - 2))

data/lib/concurrent/atomic/mutex_count_down_latch.rb

@@ -5,7 +5,7 @@ module Concurrent
   # @!macro count_down_latch
   # @!visibility private
   # @!macro internal_implementation_note
-  class MutexCountDownLatch < Synchronization::Object
+  class MutexCountDownLatch < Synchronization::LockableObject
 
     # @!macro count_down_latch_method_initialize
     def initialize(count = 1)

data/lib/concurrent/atomic/mutex_semaphore.rb

@@ -5,7 +5,7 @@ module Concurrent
   # @!macro semaphore
   # @!visibility private
   # @!macro internal_implementation_note
-  class MutexSemaphore < Synchronization::Object
+  class MutexSemaphore < Synchronization::LockableObject
 
     # @!macro semaphore_method_initialize
     def initialize(count)
@@ -78,7 +78,7 @@ module Concurrent
     # @raise [ArgumentError] if `@free` - `@reduction` is less than zero
     #
     # @return [nil]
-    # 
+    #
     # @!visibility private
     def reduce_permits(reduction)
       unless reduction.is_a?(Fixnum) && reduction >= 0

data/lib/concurrent/atomic/read_write_lock.rb

@@ -41,10 +41,12 @@ module Concurrent
     # @!visibility private
     MAX_WRITERS    = RUNNING_WRITER - MAX_READERS - 1
 
-    # Implementation notes: 
+    safe_initialization!
+
+    # Implementation notes:
     # A goal is to make the uncontended path for both readers/writers lock-free
     # Only if there is reader-writer or writer-writer contention, should locks be used
-    # Internal state is represented by a single integer ("counter"), and updated 
+    # Internal state is represented by a single integer ("counter"), and updated
     #  using atomic compare-and-swap operations
     # When the counter is 0, the lock is free
     # Each reader increments the counter by 1 when acquiring a read lock
@@ -54,11 +56,10 @@ module Concurrent
 
     # Create a new `ReadWriteLock` in the unlocked state.
     def initialize
+      super()
       @Counter   = AtomicFixnum.new(0) # single integer which represents lock state
       @ReadLock  = Synchronization::Lock.new
       @WriteLock = Synchronization::Lock.new
-      ensure_ivar_visibility!
-      super()
     end
 
     # Execute a block operation within a read lock.

data/lib/concurrent/atomic/reentrant_read_write_lock.rb

@@ -99,13 +99,15 @@ module Concurrent
     # @!visibility private
     WRITE_LOCK_MASK = MAX_WRITERS
 
+    safe_initialization!
+
     # Create a new `ReentrantReadWriteLock` in the unlocked state.
     def initialize
+      super()
       @Counter    = AtomicFixnum.new(0)       # single integer which represents lock state
       @ReadQueue  = Synchronization::Lock.new # used to queue waiting readers
       @WriteQueue = Synchronization::Lock.new # used to queue waiting writers
       @HeldCount  = ThreadLocalVar.new(0)     # indicates # of R & W locks held by this thread
-      ensure_ivar_visibility!
     end
 
     # Execute a block operation within a read lock.

data/lib/concurrent/atomic/thread_local_var.rb

@@ -68,6 +68,8 @@ module Concurrent
   #   A `ThreadLocalVar` is a variable where the value is different for each thread.
   #   Each variable may have a default value, but when you modify the variable only
   #   the current thread will ever see that change.
+  #
+  #   @!macro thread_safe_variable_comparison
   #   
   #   @example
   #     v = ThreadLocalVar.new(14)

data/lib/concurrent/atomic_reference/mutex_atomic.rb

@@ -8,7 +8,7 @@ module Concurrent
   #
   # @!visibility private
   # @!macro internal_implementation_note
-  class MutexAtomicReference < Synchronization::Object
+  class MutexAtomicReference < Synchronization::LockableObject
     include Concurrent::AtomicDirectUpdate
     include Concurrent::AtomicNumericCompareAndSetWrapper
 

data/lib/concurrent/atomics.rb

@@ -2,30 +2,32 @@
 #
 #   An object reference that may be updated atomically.
 #
+#   @!macro thread_safe_variable_comparison
+#
 #   @see http://docs.oracle.com/javase/8/docs/api/java/util/concurrent/atomic/AtomicReference.html
 #   @see http://docs.oracle.com/javase/8/docs/api/java/util/concurrent/atomic/package-summary.html
 #
 #   @!method initialize
 #     @!macro [new] atomic_reference_method_initialize
 #       @param [Object] value The initial value.
-#   
+#
 #   @!method get
 #     @!macro [new] atomic_reference_method_get
 #       Gets the current value.
 #       @return [Object] the current value
-#   
+#
 #   @!method set
 #     @!macro [new] atomic_reference_method_set
 #       Sets to the given value.
 #       @param [Object] new_value the new value
 #       @return [Object] the new value
-#   
+#
 #   @!method get_and_set
 #     @!macro [new] atomic_reference_method_get_and_set
 #       Atomically sets to the given value and returns the old value.
 #       @param [Object] new_value the new value
 #       @return [Object] the old value
-#   
+#
 #   @!method compare_and_set
 #     @!macro [new] atomic_reference_method_compare_and_set
 #

data/lib/concurrent/collection/copy_on_notify_observer_set.rb

@@ -7,23 +7,17 @@ module Concurrent
     # observers are added and removed from a thread safe collection; every time
     # a notification is required the internal data structure is copied to
     # prevent concurrency issues
-    # 
+    #
     # @api private
-    class CopyOnNotifyObserverSet < Synchronization::Object
+    class CopyOnNotifyObserverSet < Synchronization::LockableObject
 
       def initialize
         super()
         synchronize { ns_initialize }
       end
 
-      # Adds an observer to this set. If a block is passed, the observer will be
-      # created by this method and no other params should be passed
-      #
-      # @param [Object] observer the observer to add
-      # @param [Symbol] func the function to call on the observer during notification.
-      #   Default is :update
-      # @return [Object] the added observer
-      def add_observer(observer=nil, func=:update, &block)
+      # @!macro observable_add_observer
+      def add_observer(observer = nil, func = :update, &block)
         if observer.nil? && block.nil?
           raise ArgumentError, 'should pass observer as a first argument or block'
         elsif observer && block
@@ -41,8 +35,7 @@ module Concurrent
         end
       end
 
-      # @param [Object] observer the observer to remove
-      # @return [Object] the deleted observer
+      # @!macro observable_delete_observer
       def delete_observer(observer)
         synchronize do
           @observers.delete(observer)
@@ -50,8 +43,7 @@ module Concurrent
         end
       end
 
-      # Deletes all observers
-      # @return [CopyOnWriteObserverSet] self
+      # @!macro observable_delete_observers
       def delete_observers
         synchronize do
           @observers.clear
@@ -59,7 +51,7 @@ module Concurrent
         end
       end
 
-      # @return [Integer] the observers count
+      # @!macro observable_count_observers
       def count_observers
         synchronize { @observers.count }
       end

data/lib/concurrent/collection/copy_on_write_observer_set.rb

@@ -6,23 +6,17 @@ module Concurrent
     # A thread safe observer set implemented using copy-on-write approach:
     # every time an observer is added or removed the whole internal data structure is
     # duplicated and replaced with a new one.
-    # 
+    #
     # @api private
-    class CopyOnWriteObserverSet < Synchronization::Object
+    class CopyOnWriteObserverSet < Synchronization::LockableObject
 
       def initialize
         super()
         synchronize { ns_initialize }
       end
 
-      # Adds an observer to this set
-      # If a block is passed, the observer will be created by this method and no
-      #   other params should be passed
-      # @param [Object] observer the observer to add
-      # @param [Symbol] func the function to call on the observer during notification.
-      #   Default is :update
-      # @return [Object] the added observer
-      def add_observer(observer=nil, func=:update, &block)
+      # @!macro observable_add_observer
+      def add_observer(observer = nil, func = :update, &block)
         if observer.nil? && block.nil?
           raise ArgumentError, 'should pass observer as a first argument or block'
         elsif observer && block
@@ -42,8 +36,7 @@ module Concurrent
         end
       end
 
-      # @param [Object] observer the observer to remove
-      # @return [Object] the deleted observer
+      # @!macro observable_delete_observer
       def delete_observer(observer)
         synchronize do
           new_observers = @observers.dup
@@ -53,14 +46,13 @@ module Concurrent
         end
       end
 
-      # Deletes all observers
-      # @return [CopyOnWriteObserverSet] self
+      # @!macro observable_delete_observers
       def delete_observers
         self.observers = {}
         self
       end
 
-      # @return [Integer] the observers count
+      # @!macro observable_count_observers
       def count_observers
         observers.count
       end