concurrent-ruby 0.8.0.pre2-java → 0.9.0-java

data/lib/concurrent/async.rb

@@ -5,16 +5,81 @@ require 'concurrent/errors'
 require 'concurrent/ivar'
 require 'concurrent/executor/immediate_executor'
 require 'concurrent/executor/serialized_execution'
+require 'concurrent/concern/deprecation'
 
 module Concurrent
 
-  # {include:file:doc/async.md}
+  # A mixin module that provides simple asynchronous behavior to any standard
+  # class/object or object. 
+  # 
+  # ```cucumber
+  # Feature:
+  #   As a stateful, plain old Ruby class/object
+  #   I want safe, asynchronous behavior
+  #   So my long-running methods don't block the main thread
+  # ```
+  # 
+  # Stateful, mutable objects must be managed carefully when used asynchronously.
+  # But Ruby is an object-oriented language so designing with objects and classes
+  # plays to Ruby's strengths and is often more natural to many Ruby programmers.
+  # The `Async` module is a way to mix simple yet powerful asynchronous capabilities
+  # into any plain old Ruby object or class. These capabilities provide a reasonable
+  # level of thread safe guarantees when used correctly.
+  # 
+  # When this module is mixed into a class or object it provides to new methods:
+  # `async` and `await`. These methods are thread safe with respect to the enclosing
+  # object. The former method allows methods to be called asynchronously by posting
+  # to the global thread pool. The latter allows a method to be called synchronously
+  # on the current thread but does so safely with respect to any pending asynchronous
+  # method calls. Both methods return an `IVar` which can be inspected for
+  # the result of the method call. Calling a method with `async` will return a
+  # `:pending` `IVar` whereas `await` will return a `:complete` `IVar`.
+  # 
+  # Very loosely based on the `async` and `await` keywords in C#.
+  # 
+  # ### An Important Note About Thread Safe Guarantees
+  # 
+  # > Thread safe guarantees can only be made when asynchronous method calls
+  # > are not mixed with synchronous method calls. Use only synchronous calls
+  # > when the object is used exclusively on a single thread. Use only
+  # > `async` and `await` when the object is shared between threads. Once you
+  # > call a method using `async`, you should no longer call any methods
+  # > directly on the object. Use `async` and `await` exclusively from then on.
+  # > With careful programming it is possible to switch back and forth but it's
+  # > also very easy to create race conditions and break your application.
+  # > Basically, it's "async all the way down."
+  # 
+  # @example
+  # 
+  #   class Echo
+  #     include Concurrent::Async
+  #   
+  #     def echo(msg)
+  #       sleep(rand)
+  #       print "#{msg}\n"
+  #       nil
+  #     end
+  #   end
+  #   
+  #   horn = Echo.new
+  #   horn.echo('zero')      # synchronous, not thread-safe
+  #   
+  #   horn.async.echo('one') # asynchronous, non-blocking, thread-safe
+  #   horn.await.echo('two') # synchronous, blocking, thread-safe
   #
-  # @since 0.6.0
-  #
-  # @see Concurrent::Obligation
+  # @see Concurrent::IVar
   module Async
 
+    # @!method self.new(*args, &block)
+    #
+    #   Instanciate a new object and ensure proper initialization of the
+    #   synchronization mechanisms.
+    #
+    #   @param [Array<Object>] args Zero or more arguments to be passed to the
+    #     object's initializer.
+    #   @param [Proc] bloc Optional block to pass to the object's initializer.
+    #   @return [Object] A properly initialized object of the asynchronous class.
+
     # Check for the presence of a method on an object and determine if a given
     # set of arguments matches the required arity.
     #
@@ -34,7 +99,9 @@ module Concurrent
     # @see http://www.ruby-doc.org/core-2.1.1/Method.html#method-i-arity Method#arity
     # @see http://ruby-doc.org/core-2.1.0/Object.html#method-i-respond_to-3F Object#respond_to?
     # @see http://www.ruby-doc.org/core-2.1.0/BasicObject.html#method-i-method_missing BasicObject#method_missing
-    def validate_argc(obj, method, *args)
+    #
+    # @!visibility private
+    def self.validate_argc(obj, method, *args)
       argc = args.length
       arity = obj.method(method).arity
 
@@ -44,12 +111,28 @@ module Concurrent
         raise ArgumentError.new("wrong number of arguments (#{argc} for #{arity}..*)")
       end
     end
-    module_function :validate_argc
+
+    # @!visibility private
+    def self.included(base)
+      base.singleton_class.send(:alias_method, :original_new, :new)
+      base.extend(ClassMethods)
+      super(base)
+    end
+
+    # @!visibility private
+    module ClassMethods
+      def new(*args, &block)
+        obj = original_new(*args, &block)
+        obj.send(:init_synchronization)
+        obj
+      end
+    end
+    private_constant :ClassMethods
 
     # Delegates asynchronous, thread-safe method calls to the wrapped object.
     #
     # @!visibility private
-    class AsyncDelegator # :nodoc:
+    class AsyncDelegator
 
       # Create a new delegator object wrapping the given delegate,
       # protecting it with the given serializer, and executing it on the
@@ -84,14 +167,11 @@ module Concurrent
         self.define_singleton_method(method) do |*args2|
           Async::validate_argc(@delegate, method, *args2)
           ivar = Concurrent::IVar.new
-          value, reason = nil, nil
           @serializer.post(@executor.value) do
             begin
-              value = @delegate.send(method, *args2, &block)
+              ivar.set(@delegate.send(method, *args2, &block))
             rescue => reason
-              # caught
-            ensure
-              ivar.complete(reason.nil?, value, reason)
+              ivar.fail(reason)
             end
           end
           ivar.value if @blocking
@@ -101,6 +181,7 @@ module Concurrent
         self.send(method, *args)
       end
     end
+    private_constant :AsyncDelegator
 
     # Causes the chained method call to be performed asynchronously on the
     # global thread pool. The method called by this method will return a
@@ -115,26 +196,24 @@ module Concurrent
     # library, some edge cases will be missed. For more information see
     # the documentation for the `validate_argc` method.
     #
-    # @note The method call is guaranteed to be thread safe  with respect to
-    #   all other method calls against the same object that are called with
-    #   either `async` or `await`. The mutable nature of Ruby references
-    #   (and object orientation in general) prevent any other thread safety
-    #   guarantees. Do NOT mix non-protected method calls with protected
-    #   method call. Use *only* protected method calls when sharing the object
-    #   between threads.
+    # @!macro [attach] async_thread_safety_warning
+    #   @note The method call is guaranteed to be thread safe with respect to
+    #     all other method calls against the same object that are called with
+    #     either `async` or `await`. The mutable nature of Ruby references
+    #     (and object orientation in general) prevent any other thread safety
+    #     guarantees. Do NOT mix non-protected method calls with protected
+    #     method call. Use *only* protected method calls when sharing the object
+    #     between threads.
     #
     # @return [Concurrent::IVar] the pending result of the asynchronous operation
     #
-    # @raise [Concurrent::InitializationError] `#init_mutex` has not been called
     # @raise [NameError] the object does not respond to `method` method
     # @raise [ArgumentError] the given `args` do not match the arity of `method`
     #
     # @see Concurrent::IVar
     def async
-      raise InitializationError.new('#init_mutex was never called') unless @__async_initialized__
       @__async_delegator__.value
     end
-    alias_method :future, :async
 
     # Causes the chained method call to be performed synchronously on the
     # current thread. The method called by this method will return an
@@ -149,58 +228,71 @@ module Concurrent
     # library, some edge cases will be missed. For more information see
     # the documentation for the `validate_argc` method.
     #
-    # @note The method call is guaranteed to be thread safe  with respect to
-    #   all other method calls against the same object that are called with
-    #   either `async` or `await`. The mutable nature of Ruby references
-    #   (and object orientation in general) prevent any other thread safety
-    #   guarantees. Do NOT mix non-protected method calls with protected
-    #   method call. Use *only* protected method calls when sharing the object
-    #   between threads.
+    # @!macro async_thread_safety_warning
     #
     # @return [Concurrent::IVar] the completed result of the synchronous operation
     #
-    # @raise [Concurrent::InitializationError] `#init_mutex` has not been called
     # @raise [NameError] the object does not respond to `method` method
     # @raise [ArgumentError] the given `args` do not match the arity of `method`
     #
     # @see Concurrent::IVar
     def await
-      raise InitializationError.new('#init_mutex was never called') unless @__async_initialized__
       @__await_delegator__.value
     end
-    alias_method :delay, :await
 
-    # Set a new executor
+    # Set a new executor.
     #
-    # @raise [Concurrent::InitializationError] `#init_mutex` has not been called
-    # @raise [ArgumentError] executor has already been set
+    # @raise [ArgumentError] executor has already been set.
     def executor=(executor)
-      raise InitializationError.new('#init_mutex was never called') unless @__async_initialized__
       @__async_executor__.reconfigure { executor } or
         raise ArgumentError.new('executor has already been set')
     end
 
-    # Initialize the internal serializer and other synchronization objects. This method
-    # *must* be called from the constructor of the including class or explicitly
-    # by the caller prior to calling any other methods. If `init_mutex` is *not*
-    # called explicitly the async/await/executor methods will raize a
-    # `Concurrent::InitializationError`. This is the only way thread-safe
-    # initialization can be guaranteed.
+    # Initialize the internal serializer and other stnchronization mechanisms.
     #
-    # @note This method *must* be called from the constructor of the including
-    #       class or explicitly by the caller prior to calling any other methods.
-    #       This is the only way thread-safe initialization can be guaranteed.
+    # @note This method *must* be called immediately upon object construction.
+    #   This is the only way thread-safe initialization can be guaranteed.
     #
     # @raise [Concurrent::InitializationError] when called more than once
+    #
+    # @!visibility private
+    # @deprecated
     def init_mutex
-      raise InitializationError.new('#init_mutex was already called') if @__async_initialized__
+      deprecated 'mutex synchronization now happens automatically'
+      init_synchronization
+    rescue InitializationError
+      # suppress
+    end
+
+    private
+
+    # Initialize the internal serializer and other stnchronization mechanisms.
+    #
+    # @note This method *must* be called immediately upon object construction.
+    #   This is the only way thread-safe initialization can be guaranteed.
+    #
+    # @raise [Concurrent::InitializationError] when called more than once
+    #
+    # @!visibility private
+    def init_synchronization
+      return self if @__async_initialized__
+
       @__async_initialized__ = true
       serializer = Concurrent::SerializedExecution.new
-      @__async_executor__ = Delay.new{ Concurrent.configuration.global_operation_pool }
-      @__await_delegator__ = Delay.new{ AsyncDelegator.new(
-        self, Delay.new{ Concurrent::ImmediateExecutor.new }, serializer, true) }
-      @__async_delegator__ = Delay.new{ AsyncDelegator.new(
-        self, @__async_executor__, serializer, false) }
+
+      @__async_executor__ = Delay.new {
+        Concurrent.global_io_executor
+      }
+
+      @__await_delegator__ = Delay.new {
+        AsyncDelegator.new(self, Delay.new{ Concurrent::ImmediateExecutor.new }, serializer, true)
+      }
+
+      @__async_delegator__ = Delay.new {
+        AsyncDelegator.new(self, @__async_executor__, serializer, false)
+      }
+
+      self
     end
   end
 end

data/lib/concurrent/atom.rb

@@ -0,0 +1,131 @@
+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 copy_options
+  #
+  # @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 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!
+    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