concurrent-ruby 0.7.0.rc0-java → 0.7.0.rc1-java

data/README.md

@@ -1,5 +1,5 @@
 # Concurrent Ruby
-[![Gem Version](https://badge.fury.io/rb/concurrent-ruby.png)](http://badge.fury.io/rb/concurrent-ruby) [![Build Status](https://travis-ci.org/ruby-concurrency/concurrent-ruby.svg?branch=master)](https://travis-ci.org/ruby-concurrency/concurrent-ruby) [![Coverage Status](https://coveralls.io/repos/ruby-concurrency/concurrent-ruby/badge.png)](https://coveralls.io/r/ruby-concurrency/concurrent-ruby) [![Code Climate](https://codeclimate.com/github/ruby-concurrency/concurrent-ruby.png)](https://codeclimate.com/github/ruby-concurrency/concurrent-ruby) [![Inline docs](http://inch-ci.org/github/ruby-concurrency/concurrent-ruby.png)](http://inch-ci.org/github/ruby-concurrency/concurrent-ruby) [![Dependency Status](https://gemnasium.com/ruby-concurrency/concurrent-ruby.png)](https://gemnasium.com/ruby-concurrency/concurrent-ruby)
+[![Gem Version](https://badge.fury.io/rb/concurrent-ruby.png)](http://badge.fury.io/rb/concurrent-ruby) [![Build Status](https://travis-ci.org/ruby-concurrency/concurrent-ruby.svg?branch=master)](https://travis-ci.org/ruby-concurrency/concurrent-ruby) [![Coverage Status](https://coveralls.io/repos/ruby-concurrency/concurrent-ruby/badge.png)](https://coveralls.io/r/ruby-concurrency/concurrent-ruby) [![Code Climate](https://codeclimate.com/github/ruby-concurrency/concurrent-ruby.png)](https://codeclimate.com/github/ruby-concurrency/concurrent-ruby) [![Inline docs](http://inch-ci.org/github/ruby-concurrency/concurrent-ruby.png)](http://inch-ci.org/github/ruby-concurrency/concurrent-ruby) [![Dependency Status](https://gemnasium.com/ruby-concurrency/concurrent-ruby.png)](https://gemnasium.com/ruby-concurrency/concurrent-ruby) [![Gitter chat](https://badges.gitter.im/ruby-concurrency.png)](https://gitter.im/ruby-concurrency)
 
 <table>
   <tr>
@@ -67,8 +67,6 @@ into several general groups:
   [Promise](https://github.com/ruby-concurrency/concurrent-ruby/wiki/Promise),
   [ScheduledTask](https://github.com/ruby-concurrency/concurrent-ruby/wiki/ScheduledTask),
   and [TimerTask](https://github.com/ruby-concurrency/concurrent-ruby/wiki/TimerTask) 
-* Erlang-inspired [Supervisor](https://github.com/ruby-concurrency/concurrent-ruby/wiki/Supervisor) and other lifecycle classes/mixins
-  for managing long-running threads
 * Thread-safe variables including [M-Structures](https://github.com/ruby-concurrency/concurrent-ruby/wiki/MVar-(M-Structure)),
   [I-Structures](https://github.com/ruby-concurrency/concurrent-ruby/wiki/IVar-(I-Structure)),
   [thread-local variables](https://github.com/ruby-concurrency/concurrent-ruby/wiki/ThreadLocalVar),
@@ -133,23 +131,30 @@ sleep(3)   # do other stuff
 task.value #=> 25.96
 ```
 
-## Contributors
+## Maintainers
 
 * [Jerry D'Antonio](https://github.com/jdantonio)
 * [Michele Della Torre](https://github.com/mighe)
 * [Chris Seaton](https://github.com/chrisseaton)
 * [Lucas Allan](https://github.com/lucasallan)
 * [Petr Chalupa](https://github.com/pitr-ch)
-* [Ravil Bayramgalin](https://github.com/brainopia)
-* [Larry Lv](https://github.com/larrylv)
-* [Giuseppe Capizzi](https://github.com/gcapizzi)
+
+### Contributors
+
 * [Bill Dueber](https://github.com/billdueber)
 * [Brian Shirai](https://github.com/brixen)
 * [Chip Miller](https://github.com/chip-miller)
+* [Giuseppe Capizzi](https://github.com/gcapizzi)
 * [Jamie Hodge](https://github.com/jamiehodge)
+* [Larry Lv](https://github.com/larrylv)
+* [Maxim Chechel](https://github.com/maximchick)
+* [Ravil Bayramgalin](https://github.com/brainopia)
+* [René Föhring](https://github.com/rrrene)
+* [Shane Wilton](https://github.com/ShaneWilton)
+* [sheaney](https://github.com/sheaney)
 * [Zander Hill](https://github.com/zph)
 
-## Contributing
+### Contributing
 
 1. Fork it
 2. Create your feature branch (`git checkout -b my-new-feature`)

data/lib/concurrent.rb

@@ -25,7 +25,6 @@ require 'concurrent/observable'
 require 'concurrent/options_parser'
 require 'concurrent/promise'
 require 'concurrent/scheduled_task'
-require 'concurrent/supervisor'
 require 'concurrent/timer_task'
 require 'concurrent/tvar'
 

data/lib/concurrent/actress.rb

@@ -11,8 +11,8 @@ module Concurrent
   # -  Inspired by Akka and Erlang.
   #
   # Actors are sharing a thread-pool by default which makes them very cheap to create and discard.
-  # Thousands of actors can be created allowing to brake the program to small maintainable pieces
-  # without breaking single responsibility principles.
+  # Thousands of actors can be created, allowing you to break the program into small maintainable pieces,
+  # without violating the single responsibility principle.
   #
   # ## What is an actor model?
   #
@@ -26,7 +26,7 @@ module Concurrent
   # ## Why?
   #
   # Concurrency is hard this is one of many ways how to simplify the problem.
-  # It is simpler to reason about actors then about locks (and all their possible states).
+  # It is simpler to reason about actors than about locks (and all their possible states).
   #
   # ## How to use it
   #
@@ -145,7 +145,7 @@ module Concurrent
       Thread.current[:__current_actor__]
     end
 
-    # implements ROOT
+    # implements the root actor
     class Root
       include Context
       # to allow spawning of new actors, spawn needs to be called inside the parent Actor
@@ -158,8 +158,12 @@ module Concurrent
       end
     end
 
+    @root = Delay.new { Core.new(parent: nil, name: '/', class: Root).reference }
+
     # A root actor, a default parent of all actors spawned outside an actor
-    ROOT = Core.new(parent: nil, name: '/', class: Root).reference
+    def self.root
+      @root.value
+    end
 
     # Spawns a new actor.
     #
@@ -184,7 +188,7 @@ module Concurrent
       if Actress.current
         Core.new(spawn_optionify(*args).merge(parent: Actress.current), &block).reference
       else
-        ROOT.ask([:spawn, spawn_optionify(*args), block]).value
+        root.ask([:spawn, spawn_optionify(*args), block]).value
       end
     end
 

data/lib/concurrent/actress/core.rb

@@ -17,7 +17,7 @@ module Concurrent
       #   @return [String] the name of this instance, it should be uniq (not enforced right now)
       # @!attribute [r] path
       #   @return [String] a path of this actor. It is used for easier orientation and logging.
-      #     Path is constructed recursively with: `parent.path + self.name` up to a {Actress::ROOT},
+      #     Path is constructed recursively with: `parent.path + self.name` up to a {Actress.root},
       #     e.g. `/an_actor/its_child`.
       #     (It will also probably form a supervision path (failures will be reported up to parents)
       #     in future versions.)

data/lib/concurrent/async.rb

@@ -3,8 +3,8 @@ require 'concurrent/configuration'
 require 'concurrent/delay'
 require 'concurrent/errors'
 require 'concurrent/ivar'
-require 'concurrent/future'
-require 'concurrent/executor/thread_pool_executor'
+require 'concurrent/executor/immediate_executor'
+require 'concurrent/executor/serialized_execution'
 
 module Concurrent
 
@@ -124,69 +124,24 @@ module Concurrent
     end
     module_function :validate_argc
 
-    # Delegates synchronous, thread-safe method calls to the wrapped object.
-    #
-    # @!visibility private
-    class AwaitDelegator # :nodoc:
-
-      # Create a new delegator object wrapping the given `delegate` and
-      # protecting it with the given `mutex`.
-      #
-      # @param [Object] delegate the object to wrap and delegate method calls to
-      # @param [Mutex] mutex the mutex lock to use when delegating method calls
-      def initialize(delegate, mutex)
-        @delegate = delegate
-        @mutex = mutex
-      end
-
-      # Delegates method calls to the wrapped object. For performance,
-      # dynamically defines the given method on the delegator so that
-      # all future calls to `method` will not be directed here.
-      #
-      # @param [Symbol] method the method being called
-      # @param [Array] args zero or more arguments to the method
-      #
-      # @return [IVar] the result of the method call
-      #
-      # @raise [NameError] the object does not respond to `method` method
-      # @raise [ArgumentError] the given `args` do not match the arity of `method`
-      def method_missing(method, *args, &block)
-        super unless @delegate.respond_to?(method)
-        Async::validate_argc(@delegate, method, *args)
-
-        self.define_singleton_method(method) do |*args|
-          Async::validate_argc(@delegate, method, *args)
-          ivar = Concurrent::IVar.new
-          value, reason = nil, nil
-          begin
-            @mutex.synchronize do
-              value = @delegate.send(method, *args, &block)
-            end
-          rescue => reason
-            # caught
-          ensure
-            return ivar.complete(reason.nil?, value, reason)
-          end
-        end
-
-        self.send(method, *args)
-      end
-    end
-
     # Delegates asynchronous, thread-safe method calls to the wrapped object.
     #
     # @!visibility private
     class AsyncDelegator # :nodoc:
 
-      # Create a new delegator object wrapping the given `delegate` and
-      # protecting it with the given `mutex`.
+      # Create a new delegator object wrapping the given delegate,
+      # protecting it with the given serializer, and executing it on the
+      # given executor. Block if necessary.
       #
       # @param [Object] delegate the object to wrap and delegate method calls to
-      # @param [Mutex] mutex the mutex lock to use when delegating method calls
-      def initialize(delegate, executor, mutex)
+      # @param [Concurrent::Delay] executor a `Delay` wrapping the executor on which to execute delegated method calls
+      # @param [Concurrent::SerializedExecution] serializer the serializer to use when delegating method calls
+      # @param [Boolean] blocking will block awaiting result when `true`
+      def initialize(delegate, executor, serializer, blocking = false)
         @delegate = delegate
         @executor = executor
-        @mutex = mutex
+        @serializer = serializer
+        @blocking = blocking
       end
 
       # Delegates method calls to the wrapped object. For performance,
@@ -206,11 +161,19 @@ module Concurrent
 
         self.define_singleton_method(method) do |*args|
           Async::validate_argc(@delegate, method, *args)
-          Concurrent::Future.execute(executor: @executor.value) do
-            @mutex.synchronize do
-              @delegate.send(method, *args, &block)
+          ivar = Concurrent::IVar.new
+          value, reason = nil, nil
+          @serializer.post(@executor.value) do
+            begin
+              value = @delegate.send(method, *args, &block)
+            rescue => reason
+              # caught
+            ensure
+              ivar.complete(reason.nil?, value, reason)
             end
           end
+          ivar.value if @blocking
+          ivar
         end
 
         self.send(method, *args)
@@ -219,9 +182,9 @@ module Concurrent
 
     # Causes the chained method call to be performed asynchronously on the
     # global thread pool. The method called by this method will return a
-    # `Future` object in the `:pending` state and the method call will have
+    # future object in the `:pending` state and the method call will have
     # been scheduled on the global thread pool. The final disposition of the
-    # method call can be obtained by inspecting the returned `Future`.
+    # method call can be obtained by inspecting the returned future.
     #
     # Before scheduling the method on the global thread pool a best-effort
     # attempt will be made to validate that the method exists on the object
@@ -238,15 +201,15 @@ module Concurrent
     #   method call. Use *only* protected method calls when sharing the object
     #   between threads.
     #
-    # @return [Concurrent::Future] the pending result of the asynchronous operation
+    # @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::Future
+    # @see Concurrent::IVar
     def async
-      raise InitializationError.new('#init_mutex was never called') unless @__async__mutex__
+      raise InitializationError.new('#init_mutex was never called') unless @__async_initialized__
       @__async_delegator__.value
     end
     alias_method :future, :async
@@ -280,7 +243,7 @@ module Concurrent
     #
     # @see Concurrent::IVar
     def await
-      raise InitializationError.new('#init_mutex was never called') unless @__async__mutex__
+      raise InitializationError.new('#init_mutex was never called') unless @__async_initialized__
       @__await_delegator__.value
     end
     alias_method :delay, :await
@@ -290,12 +253,12 @@ module Concurrent
     # @raise [Concurrent::InitializationError] `#init_mutex` has not been called
     # @raise [ArgumentError] executor has already been set
     def executor=(executor)
-      raise InitializationError.new('#init_mutex was never called') unless @__async__mutex__
-      @__async__executor__.reconfigure { executor } or
+      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 mutex and other synchronization objects. This method
+    # 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
@@ -308,12 +271,14 @@ module Concurrent
     #
     # @raise [Concurrent::InitializationError] when called more than once
     def init_mutex
-      raise InitializationError.new('#init_mutex was already called') if @__async__mutex__
-      (@__async__mutex__ = Mutex.new).lock
-      @__async__executor__ = Delay.new{ Concurrent.configuration.global_operation_pool }
-      @__await_delegator__ = Delay.new{ AwaitDelegator.new(self, @__async__mutex__) }
-      @__async_delegator__ = Delay.new{ AsyncDelegator.new(self, @__async__executor__, @__async__mutex__) }
-      @__async__mutex__.unlock
+      raise InitializationError.new('#init_mutex was already called') 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) }
     end
   end
 end

data/lib/concurrent/atomic.rb

@@ -16,30 +16,50 @@ end
 
 if defined? Concurrent::JavaAtomic
 
+  # @!macro [attach] atomic_reference
+  #
+  #   An object reference that may be updated atomically.
+  #
+  #   @since 0.7.0.rc0
+  #   @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
   class Concurrent::Atomic < Concurrent::JavaAtomic
   end
 
 elsif defined? Concurrent::CAtomic
 
+  # @!macro [attach] concurrent_update_error
+  #
+  # This exception may be thrown by methods that have detected concurrent
+  # modification of an object when such modification is not permissible.
   class Concurrent::Atomic < Concurrent::CAtomic
   end
 
 elsif defined? Concurrent::RbxAtomic
 
+  # @!macro atomic_reference
   class Concurrent::Atomic < Concurrent::RbxAtomic
   end
 
 else
 
+  # @!macro atomic_reference
   class Concurrent::Atomic < Concurrent::MutexAtomic
   end
 end
 
+# @!macro atomic_reference
 class Atomic < Concurrent::Atomic
 
+  # @!macro concurrent_update_error
   ConcurrentUpdateError = Class.new(Concurrent::ConcurrentUpdateError)
 
-  def initialize(*args)
+  # @!macro [attach] atomic_reference_method_initialize
+  #
+  # Creates a new Atomic reference with null initial value.
+  #
+  # @param [Object] value the initial value
+  def initialize(value)
     warn "[DEPRECATED] Please use Concurrent::Atomic instead."
     super
   end

data/lib/concurrent/atomic_reference/concurrent_update_error.rb

@@ -1,5 +1,6 @@
 module Concurrent
 
+  # @!macro atomic_reference
   class ConcurrentUpdateError < ThreadError
     # frozen pre-allocated backtrace to speed ConcurrentUpdateError
     CONC_UP_ERR_BACKTRACE = ['backtrace elided; set verbose to enable'].freeze

data/lib/concurrent/atomic_reference/direct_update.rb

@@ -4,14 +4,36 @@ module Concurrent
 
   # Define update methods that use direct paths
   module AtomicDirectUpdate
+
+    # @!macro [attach] atomic_reference_method_update
+    #
     # Pass the current value to the given block, replacing it
     # with the block's result. May retry if the value changes
     # during the block's execution.
+    # 
+    # @yield [Object] Calculate a new value for the atomic reference using
+    #   given (old) value
+    # @yieldparam [Object] old_value the starting value of the atomic reference
+    #
+    # @return [Object] the new value
     def update
       true until compare_and_set(old_value = get, new_value = yield(old_value))
       new_value
     end
 
+    # @!macro [attach] atomic_reference_method_try_update
+    #
+    # Pass the current value to the given block, replacing it
+    # with the block's result. Raise an exception if the update
+    # fails.
+    # 
+    # @yield [Object] Calculate a new value for the atomic reference using
+    #   given (old) value
+    # @yieldparam [Object] old_value the starting value of the atomic reference
+    #
+    # @return [Object] the new value
+    #
+    # @raise [Concurrent::ConcurrentUpdateError] if the update fails
     def try_update
       old_value = get
       new_value = yield old_value

data/lib/concurrent/atomic_reference/jruby.rb

@@ -2,6 +2,8 @@ require 'concurrent_ruby_ext'
 require 'concurrent/atomic_reference/direct_update'
 
 module Concurrent
+
+  # @!macro atomic_reference
   class JavaAtomic
     include Concurrent::AtomicDirectUpdate
   end

data/lib/concurrent/atomic_reference/mutex_atomic.rb

@@ -4,26 +4,46 @@ require 'concurrent/atomic_reference/numeric_cas_wrapper'
 
 module Concurrent
 
-  # Portable/generic (but not very memory or scheduling-efficient) fallback
-  class MutexAtomic #:nodoc: all
+  # @!macro atomic_reference
+  class MutexAtomic
     include Concurrent::AtomicDirectUpdate
     include Concurrent::AtomicNumericCompareAndSetWrapper
 
+    # @!macro atomic_reference_method_initialize
     def initialize(value = nil)
       @mutex = Mutex.new
       @value = value
     end
 
+    # @!macro [attach] atomic_reference_method_get
+    #
+    #   Gets the current value.
+    #
+    #   @return [Object] the current value
     def get
       @mutex.synchronize { @value }
     end
-    alias value get
+    alias_method :value, :get
 
+    # @!macro [attach] atomic_reference_method_set
+    #
+    #   Sets to the given value.
+    #
+    #   @param [Object] new_value the new value
+    #
+    #   @return [Object] the new value
     def set(new_value)
       @mutex.synchronize { @value = new_value }
     end
-    alias value= set
+    alias_method :value=, :set
 
+    # @!macro [attach] 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
     def get_and_set(new_value)
       @mutex.synchronize do
         old_value = @value
@@ -31,9 +51,19 @@ module Concurrent
         old_value
       end
     end
-    alias swap get_and_set
+    alias_method :swap, :get_and_set
 
-    def _compare_and_set(old_value, new_value)
+    # @!macro [attach] atomic_reference_method_compare_and_set
+    #
+    #   Atomically sets the value to the given updated value if
+    #   the current value == the expected value.
+    #
+    #   @param [Object] old_value the expected value
+    #   @param [Object] new_value the new value
+    #
+    #   @return [Boolean] `true` if successful. A `false` return indicates
+    #   that the actual value was not equal to the expected value.
+    def _compare_and_set(old_value, new_value) #:nodoc:
       return false unless @mutex.try_lock
       begin
         return false unless @value.equal? old_value