concurrent-ruby 0.5.0 → 0.6.0.pre.1

data/lib/concurrent/async.rb

@@ -0,0 +1,290 @@
+require 'thread'
+require 'concurrent/configuration'
+require 'concurrent/ivar'
+require 'concurrent/future'
+require 'concurrent/thread_pool_executor'
+
+module Concurrent
+
+  # A mixin module that provides simple asynchronous behavior to any standard
+  # class/object or object. 
+  #
+  #   Scenario:
+  #     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 +Obligation+ which can be inspected for
+  # the result of the method call. Calling a method with +async+ will return a
+  # +:pending+ +Obligation+ whereas +await+ will return a +:complete+ +Obligation+.
+  #
+  # Very loosely based on the +async+ and +await+ keywords in C#.
+  #
+  # @example Defining an asynchronous class
+  #   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
+  #
+  # @example Monkey-patching an existing object
+  #   numbers = 1_000_000.times.collect{ rand }
+  #   numbers.extend(Concurrent::Async)
+  #   
+  #   future = numbers.async.max
+  #   future.state #=> :pending
+  #   
+  #   sleep(2)
+  #   
+  #   future.state #=> :fulfilled
+  #   future.value #=> 0.999999138918843
+  #
+  # @note 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."
+  #
+  # @since 0.6.0
+  #
+  # @see Concurrent::Obligation
+  module Async
+
+    # Check for the presence of a method on an object and determine if a given
+    # set of arguments matches the required arity.
+    #
+    # @param [Object] obj the object to check against
+    # @param [Symbol] method the method to check the object for
+    # @param [Array] args zero or more arguments for the arity check
+    #
+    # @raise [NameError] the object does not respond to +method+ method
+    # @raise [ArgumentError] the given +args+ do not match the arity of +method+
+    #
+    # @note This check is imperfect because of the way Ruby reports the arity of
+    #   methods with a variable number of arguments. It is possible to determine
+    #   if too few arguments are given but impossible to determine if too many
+    #   arguments are given. This check may also fail to recognize dynamic behavior
+    #   of the object, such as methods simulated with +method_missing+.
+    #
+    # @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)
+      argc = args.length
+      arity = obj.method(method).arity
+
+      if arity >= 0 && argc != arity
+        raise ArgumentError.new("wrong number of arguments (#{argc} for #{arity})")
+      elsif arity < 0 && (arity = (arity + 1).abs) > argc
+        raise ArgumentError.new("wrong number of arguments (#{argc} for #{arity}..*)")
+      end
+    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
+
+      # The lock used when delegating methods to the wrapped object.
+      #
+      # @!visibility private
+      attr_reader :mutex # :nodoc:
+    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+.
+      #
+      # @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)
+        @delegate = delegate
+        @executor = executor
+        @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)
+          Concurrent::Future.execute(executor: @executor) do
+            mutex.synchronize do
+              @delegate.send(method, *args, &block)
+            end
+          end
+        end
+
+        self.send(method, *args)
+      end
+
+      private
+
+      # The lock used when delegating methods to the wrapped object.
+      #
+      # @!visibility private
+      attr_reader :mutex # :nodoc:
+    end
+
+    # 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
+    # been scheduled on the global thread pool. The final disposition of the
+    # 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
+    # and that the given arguments match the arity of the requested function.
+    # Due to the dynamic nature of Ruby and limitations of its reflection
+    # 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.
+    #
+    # @return [Concurrent::Future] the pending result of the asynchronous operation
+    #
+    # @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
+    def async
+      @__async_delegator__ ||= AsyncDelegator.new(self, executor, await.mutex)
+    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
+    # +IVar+ object in either the +:fulfilled+ or +rejected+ state and the
+    # method call will have completed. The final disposition of the
+    # method call can be obtained by inspecting the returned +IVar+.
+    #
+    # 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
+    # and that the given arguments match the arity of the requested function.
+    # Due to the dynamic nature of Ruby and limitations of its reflection
+    # 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.
+    #
+    # @return [Concurrent::IVar] the completed result of the synchronous operation
+    #
+    # @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
+      @__await_delegator__ ||= AwaitDelegator.new(self, Mutex.new)
+    end
+    alias_method :delay, :await
+
+    def executor=(executor)
+      raise ArgumentError.new('executor has already been set') unless @__async__executor__.nil?
+      @__async__executor__ = executor
+    end
+
+    private
+
+    def executor
+      @__async__executor__ ||= Concurrent.configuration.global_task_pool
+    end
+  end
+end

data/lib/concurrent/atomic.rb

@@ -3,8 +3,7 @@ module Concurrent
   # @!visibility private
   module MutexAtomicFixnum # :nodoc:
 
-    # @!visibility private
-    def allocate_storage(init) # :nodoc:
+    def allocate_storage(init)
       @value = init
       @mutex = Mutex.new
     end
@@ -34,8 +33,7 @@ module Concurrent
       end
     end
 
-    # @!visibility private
-    def compare_and_set(expect, update) # :nodoc:
+    def compare_and_set(expect, update)
       @mutex.synchronize do
         if @value == expect
           @value = update
@@ -50,8 +48,7 @@ module Concurrent
   # @!visibility private
   module JavaAtomicFixnum # :nodoc:
 
-    # @!visibility private
-    def allocate_storage(init) # :nodoc:
+    def allocate_storage(init)
       @atomic = java.util.concurrent.atomic.AtomicLong.new(init)
     end
 
@@ -72,8 +69,7 @@ module Concurrent
       @atomic.decrement_and_get
     end
 
-    # @!visibility private
-    def compare_and_set(expect, update) # :nodoc:
+    def compare_and_set(expect, update)
       @atomic.compare_and_set(expect, update)
     end
   end
@@ -113,7 +109,7 @@ module Concurrent
       allocate_storage(init)
     end
 
-    if defined? java.util
+    if RUBY_PLATFORM == 'java'
       include JavaAtomicFixnum
     else
       include MutexAtomicFixnum

data/lib/concurrent/cached_thread_pool.rb

@@ -1,143 +1,45 @@
-require 'thread'
-
-require 'concurrent/event'
-require 'concurrent/cached_thread_pool/worker'
+require 'concurrent/ruby_cached_thread_pool'
 
 module Concurrent
 
-  class CachedThreadPool
-
-    MIN_POOL_SIZE = 1
-    MAX_POOL_SIZE = 256
-
-    DEFAULT_THREAD_IDLETIME = 60
-
-    attr_accessor :max_threads
-
-    def initialize(opts = {})
-      @idletime = (opts[:idletime] || DEFAULT_THREAD_IDLETIME).to_i
-      raise ArgumentError.new('idletime must be greater than zero') if @idletime <= 0
-
-      @max_threads = opts[:max_threads] || opts[:max] || MAX_POOL_SIZE
-      if @max_threads < MIN_POOL_SIZE || @max_threads > MAX_POOL_SIZE
-        raise ArgumentError.new("size must be from #{MIN_POOL_SIZE} to #{MAX_POOL_SIZE}")
-      end
-
-      @state = :running
-      @pool = []
-      @terminator = Event.new
-      @mutex = Mutex.new
-
-      @busy = []
-      @idle = []
-    end
-
-    def <<(block)
-      self.post(&block)
-      return self
-    end
-
-    def post(*args, &block)
-      raise ArgumentError.new('no block given') if block.nil?
-      @mutex.synchronize do
-        break false unless @state == :running
-
-        if @idle.empty?
-          if @idle.length + @busy.length < @max_threads
-            worker = create_worker_thread
-          else
-            worker = @busy.shift
-          end
-        else
-          worker = @idle.pop
-        end
-
-        @busy.push(worker)
-        worker.signal(*args, &block)
-
-        prune_stale_workers
-        true
-      end
-    end
-
-    def running?
-      return @state == :running
-    end
-
-    def wait_for_termination(timeout = nil)
-      return @terminator.wait(timeout)
-    end
-
-    def shutdown
-      @mutex.synchronize do
-        break unless @state == :running
-        if @idle.empty? && @busy.empty?
-          @state = :shutdown
-          @terminator.set
-        else
-          @state = :shuttingdown
-          @idle.each{|worker| worker.stop }
-          @busy.each{|worker| worker.stop }
-        end
-      end
-    end
-
-    def kill
-      @mutex.synchronize do
-        break if @state == :shutdown
-        @state = :shutdown
-          @idle.each{|worker| worker.kill }
-          @busy.each{|worker| worker.kill }
-        @terminator.set
-      end
-    end
-
-    def length
-      @mutex.synchronize do
-        @state == :running ? @busy.length + @idle.length : 0
-      end
-    end
-
-    def on_worker_exit(worker)
-      @mutex.synchronize do
-        @idle.delete(worker)
-        @busy.delete(worker)
-        if @idle.empty? && @busy.empty? && @state != :running
-          @state = :shutdown
-          @terminator.set
-        end
-      end
-    end
-
-    def on_end_task(worker)
-      @mutex.synchronize do
-        break unless @state == :running
-        @busy.delete(worker)
-        @idle.push(worker)
-      end
-    end
-
-    protected
-
-    def create_worker_thread
-      wrkr = Worker.new(self)
-      Thread.new(wrkr, self) do |worker, parent|
-        Thread.current.abort_on_exception = false
-        worker.run
-        parent.on_worker_exit(worker)
-      end
-      return wrkr
-    end
-
-    def prune_stale_workers
-      @idle.reject! do |worker|
-        if worker.idletime > @idletime
-          worker.stop
-          true
-        else
-          worker.dead?
-        end
-      end
+  if RUBY_PLATFORM == 'java'
+    require 'concurrent/java_cached_thread_pool'
+    # @!macro [attach] cached_thread_pool
+    #   A thread pool that dynamically grows and shrinks to fit the current workload.
+    #   New threads are created as needed, existing threads are reused, and threads
+    #   that remain idle for too long are killed and removed from the pool. These
+    #   pools are particularly suited to applications that perform a high volume of
+    #   short-lived tasks.
+    #
+    #   On creation a +CachedThreadPool+ has zero running threads. New threads are
+    #   created on the pool as new operations are +#post+. The size of the pool
+    #   will grow until +#max_length+ threads are in the pool or until the number
+    #   of threads exceeds the number of running and pending operations. When a new
+    #   operation is post to the pool the first available idle thread will be tasked
+    #   with the new operation.
+    #
+    #   Should a thread crash for any reason the thread will immediately be removed
+    #   from the pool. Similarly, threads which remain idle for an extended period
+    #   of time will be killed and reclaimed. Thus these thread pools are very
+    #   efficient at reclaiming unused resources.
+    #
+    #   The API and behavior of this class are based on Java's +CachedThreadPool+
+    #
+    #   @note When running on the JVM (JRuby) this class will inherit from +JavaCachedThreadPool+.
+    #     On all other platforms it will inherit from +RubyCachedThreadPool+.
+    #
+    #   @see Concurrent::RubyCachedThreadPool
+    #   @see Concurrent::JavaCachedThreadPool
+    #
+    #   @see http://docs.oracle.com/javase/tutorial/essential/concurrency/pools.html
+    #   @see http://docs.oracle.com/javase/7/docs/api/java/util/concurrent/Executors.html
+    #   @see http://docs.oracle.com/javase/8/docs/api/java/util/concurrent/ExecutorService.html
+    #   @see http://stackoverflow.com/questions/17957382/fixedthreadpool-vs-cachedthreadpool-the-lesser-of-two-evils
+    class CachedThreadPool < JavaCachedThreadPool
+    end
+  else
+    # @!macro cached_thread_pool
+    class CachedThreadPool < RubyCachedThreadPool
     end
   end
 end