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

data/lib/concurrent/atomic_reference/numeric_cas_wrapper.rb

@@ -1,24 +1,25 @@
 module Concurrent
 
+  # Special "compare and set" handling of numeric values.
   module AtomicNumericCompareAndSetWrapper
-    #alias _compare_and_set compare_and_set
 
-    def compare_and_set(expected, new)
-      if expected.kind_of? Numeric
+    # @!macro atomic_reference_method_compare_and_set
+    def compare_and_set(old_value, new_value)
+      if old_value.kind_of? Numeric
         while true
           old = get
 
           return false unless old.kind_of? Numeric
 
-          return false unless old == expected
+          return false unless old == old_value
 
-          result = _compare_and_set(old, new)
+          result = _compare_and_set(old, new_value)
           return result if result
         end
       else
-        _compare_and_set(expected, new)
+        _compare_and_set(old_value, new_value)
       end
     end
-    alias compare_and_swap compare_and_set
+    alias_method :compare_and_swap, :compare_and_set
   end
 end

data/lib/concurrent/atomic_reference/rbx.rb

@@ -3,14 +3,17 @@ require 'concurrent/atomic_reference/numeric_cas_wrapper'
 
 module Concurrent
 
-  # extend Rubinius's version adding aliases and numeric logic
+  # @!macro atomic_reference
+  #
+  # @note Extends `Rubinius::AtomicReference` version adding aliases
+  #   and numeric logic.
   class RbxAtomic < Rubinius::AtomicReference
     alias _compare_and_set compare_and_set
     include Concurrent::AtomicDirectUpdate
     include Concurrent::AtomicNumericCompareAndSetWrapper
 
-    alias value get
-    alias value= set
-    alias swap get_and_set
+    alias_method :value, :get
+    alias_method :value=, :set
+    alias_method :swap, :get_and_set
   end
 end

data/lib/concurrent/atomic_reference/ruby.rb

@@ -9,6 +9,8 @@ require 'concurrent/atomic_reference/direct_update'
 require 'concurrent/atomic_reference/numeric_cas_wrapper'
 
 module Concurrent
+
+  # @!macro atomic_reference
   class CAtomic
     include Concurrent::AtomicDirectUpdate
     include Concurrent::AtomicNumericCompareAndSetWrapper

data/lib/concurrent/executor/executor.rb

@@ -5,25 +5,76 @@ require 'concurrent/atomic/event'
 module Concurrent
 
   module Executor
+    
+    # @!macro [attach] executor_module_method_can_overflow_question
+    #
+    #   Does the task queue have a maximum size?
+    #
+    #   @return [Boolean] True if the task queue has a maximum size else false.
+    #
+    # @note Always returns `false`
     def can_overflow?
       false
     end
+
+    # @!macro [attach] executor_module_method_serialized_question
+    #
+    #   Does this executor guarantee serialization of its operations?
+    #
+    #   @return [Boolean] True if the executor guarantees that all operations
+    #     will be post in the order they are received and no two operations may
+    #     occur simultaneously. Else false.
+    #
+    # @note Always returns `false`
+    def serialized?
+      false
+    end
+  end
+
+  # Indicates that the including `Executor` or `ExecutorService` guarantees
+  # that all operations will occur in the order they are post and that no
+  # two operations may occur simultaneously. This module provides no
+  # functionality and provides no guarantees. That is the responsibility
+  # of the including class. This module exists solely to allow the including
+  # object to be interrogated for its serialization status.
+  #
+  # @example
+  #   class Foo
+  #     include Concurrent::SerialExecutor
+  #   end
+  #
+  #   foo = Foo.new
+  #
+  #   foo.is_a? Concurrent::Executor       #=> true
+  #   foo.is_a? Concurrent::SerialExecutor #=> true
+  #   foo.serialized?                      #=> true
+  module SerialExecutor
+    include Executor
+
+    # @!macro executor_module_method_serialized_question
+    #
+    # @note Always returns `true`
+    def serialized?
+      true
+    end
   end
 
   module RubyExecutor
     include Executor
     include Logging
 
-    # Submit a task to the executor for asynchronous processing.
+    # @!macro [attach] executor_method_post
+    #
+    #   Submit a task to the executor for asynchronous processing.
     #
-    # @param [Array] args zero or more arguments to be passed to the task
+    #   @param [Array] args zero or more arguments to be passed to the task
     #
-    # @yield the asynchronous task to perform
+    #   @yield the asynchronous task to perform
     #
-    # @return [Boolean] `true` if the task is queued, `false` if the executor
-    #   is not running
+    #   @return [Boolean] `true` if the task is queued, `false` if the executor
+    #     is not running
     #
-    # @raise [ArgumentError] if no task is given
+    #   @raise [ArgumentError] if no task is given
     def post(*args, &task)
       raise ArgumentError.new('no block given') unless block_given?
       mutex.synchronize do
@@ -33,40 +84,50 @@ module Concurrent
       end
     end
 
-    # Submit a task to the executor for asynchronous processing.
+    # @!macro [attach] executor_method_left_shift
     #
-    # @param [Proc] task the asynchronous task to perform
+    #   Submit a task to the executor for asynchronous processing.
     #
-    # @return [self] returns itself
+    #   @param [Proc] task the asynchronous task to perform
+    #
+    #   @return [self] returns itself
     def <<(task)
       post(&task)
       self
     end
 
-    # Is the executor running?
+    # @!macro [attach] executor_method_running_question
+    #
+    #   Is the executor running?
     #
-    # @return [Boolean] `true` when running, `false` when shutting down or shutdown
+    #   @return [Boolean] `true` when running, `false` when shutting down or shutdown
     def running?
       ! stop_event.set?
     end
 
-    # Is the executor shuttingdown?
+    # @!macro [attach] executor_method_shuttingdown_question
+    #
+    #   Is the executor shuttingdown?
     #
-    # @return [Boolean] `true` when not running and not shutdown, else `false`
+    #   @return [Boolean] `true` when not running and not shutdown, else `false`
     def shuttingdown?
       ! (running? || shutdown?)
     end
 
-    # Is the executor shutdown?
+    # @!macro [attach] executor_method_shutdown_question
     #
-    # @return [Boolean] `true` when shutdown, `false` when shutting down or running
+    #   Is the executor shutdown?
+    #
+    #   @return [Boolean] `true` when shutdown, `false` when shutting down or running
     def shutdown?
       stopped_event.set?
     end
 
-    # Begin an orderly shutdown. Tasks already in the queue will be executed,
-    # but no new tasks will be accepted. Has no additional effect if the
-    # thread pool is not running.
+    # @!macro [attach] executor_method_shutdown
+    #
+    #   Begin an orderly shutdown. Tasks already in the queue will be executed,
+    #   but no new tasks will be accepted. Has no additional effect if the
+    #   thread pool is not running.
     def shutdown
       mutex.synchronize do
         break unless running?
@@ -76,10 +137,12 @@ module Concurrent
       true
     end
 
-    # Begin an immediate shutdown. In-progress tasks will be allowed to
-    # complete but enqueued tasks will be dismissed and no new tasks
-    # will be accepted. Has no additional effect if the thread pool is
-    # not running.
+    # @!macro [attach] executor_method_kill
+    #
+    #   Begin an immediate shutdown. In-progress tasks will be allowed to
+    #   complete but enqueued tasks will be dismissed and no new tasks
+    #   will be accepted. Has no additional effect if the thread pool is
+    #   not running.
     def kill
       mutex.synchronize do
         break if shutdown?
@@ -90,15 +153,17 @@ module Concurrent
       true
     end
 
-    # Block until executor shutdown is complete or until `timeout` seconds have
-    # passed.
+    # @!macro [attach] executor_method_wait_for_termination
     #
-    # @note Does not initiate shutdown or termination. Either `shutdown` or `kill`
-    #   must be called before this method (or on another thread).
+    #   Block until executor shutdown is complete or until `timeout` seconds have
+    #   passed.
     #
-    # @param [Integer] timeout the maximum number of seconds to wait for shutdown to complete
+    #   @note Does not initiate shutdown or termination. Either `shutdown` or `kill`
+    #     must be called before this method (or on another thread).
     #
-    # @return [Boolean] `true` if shutdown complete or false on `timeout`
+    #   @param [Integer] timeout the maximum number of seconds to wait for shutdown to complete
+    #
+    #   @return [Boolean] `true` if shutdown complete or false on `timeout`
     def wait_for_termination(timeout = nil)
       stopped_event.wait(timeout)
     end
@@ -107,20 +172,33 @@ module Concurrent
 
     attr_reader :mutex, :stop_event, :stopped_event
 
+    # @!macro [attach] executor_method_init_executor
+    #
+    #   Initialize the executor by creating and initializing all the
+    #   internal synchronization objects.
     def init_executor
       @mutex = Mutex.new
       @stop_event = Event.new
       @stopped_event = Event.new
     end
 
+    # @!macro [attach] executor_method_execute
     def execute(*args, &task)
       raise NotImplementedError
     end
 
+    # @!macro [attach] executor_method_shutdown_execution
+    # 
+    #   Callback method called when an orderly shutdown has completed.
+    #   The default behavior is to signal all waiting threads.
     def shutdown_execution
       stopped_event.set
     end
 
+    # @!macro [attach] executor_method_kill_execution
+    #
+    #   Callback method called when the executor has been killed.
+    #   The default behavior is to do nothing.
     def kill_execution
       # do nothing
     end
@@ -130,49 +208,34 @@ module Concurrent
 
     module JavaExecutor
       include Executor
+      java_import 'java.lang.Runnable'
 
-      # Submit a task to the executor for asynchronous processing.
-      #
-      # @param [Array] args zero or more arguments to be passed to the task
-      #
-      # @yield the asynchronous task to perform
-      #
-      # @return [Boolean] `true` if the task is queued, `false` if the executor
-      #   is not running
-      #
-      # @raise [ArgumentError] if no task is given
+      # @!macro executor_method_post
       def post(*args)
         raise ArgumentError.new('no block given') unless block_given?
         if running?
-          @executor.submit{ yield(*args) }
+          executor_submit = @executor.java_method(:submit, [Runnable.java_class])
+          executor_submit.call { yield(*args) }
           true
         else
           false
         end
-      rescue Java::JavaUtilConcurrent::RejectedExecutionException => ex
+      rescue Java::JavaUtilConcurrent::RejectedExecutionException
         raise RejectedExecutionError
       end
 
-      # Submit a task to the executor for asynchronous processing.
-      #
-      # @param [Proc] task the asynchronous task to perform
-      #
-      # @return [self] returns itself
+      # @!macro executor_method_left_shift
       def <<(task)
         post(&task)
         self
       end
 
-      # Is the executor running?
-      #
-      # @return [Boolean] `true` when running, `false` when shutting down or shutdown
+      # @!macro executor_method_running_question
       def running?
         ! (shuttingdown? || shutdown?)
       end
 
-      # Is the executor shuttingdown?
-      #
-      # @return [Boolean] `true` when not running and not shutdown, else `false`
+      # @!macro executor_method_shuttingdown_question
       def shuttingdown?
         if @executor.respond_to? :isTerminating
           @executor.isTerminating
@@ -181,38 +244,23 @@ module Concurrent
         end
       end
 
-      # Is the executor shutdown?
-      #
-      # @return [Boolean] `true` when shutdown, `false` when shutting down or running
+      # @!macro executor_method_shutdown_question
       def shutdown?
         @executor.isShutdown || @executor.isTerminated
       end
 
-      # Block until executor shutdown is complete or until `timeout` seconds have
-      # passed.
-      #
-      # @note Does not initiate shutdown or termination. Either `shutdown` or `kill`
-      #   must be called before this method (or on another thread).
-      #
-      # @param [Integer] timeout the maximum number of seconds to wait for shutdown to complete
-      #
-      # @return [Boolean] `true` if shutdown complete or false on `timeout`
+      # @!macro executor_method_wait_for_termination
       def wait_for_termination(timeout)
         @executor.awaitTermination(1000 * timeout, java.util.concurrent.TimeUnit::MILLISECONDS)
       end
 
-      # Begin an orderly shutdown. Tasks already in the queue will be executed,
-      # but no new tasks will be accepted. Has no additional effect if the
-      # executor is not running.
+      # @!macro executor_method_shutdown
       def shutdown
         @executor.shutdown
         nil
       end
 
-      # Begin an immediate shutdown. In-progress tasks will be allowed to
-      # complete but enqueued tasks will be dismissed and no new tasks
-      # will be accepted. Has no additional effect if the executor is
-      # not running.
+      # @!macro executor_method_kill
       def kill
         @executor.shutdownNow
         nil

data/lib/concurrent/executor/immediate_executor.rb

@@ -1,16 +1,65 @@
+require 'concurrent/atomic/event'
+require 'concurrent/executor/executor'
+
 module Concurrent
+
+  # An executor service which runs all operations on the current thread,
+  # blocking as necessary. Operations are performed in the order they are
+  # received and no two operations can be performed simultaneously.
+  #
+  # This executor service exists mainly for testing an debugging. When used
+  # it immediately runs every `#post` operation on the current thread, blocking
+  # that thread until the operation is complete. This can be very beneficial
+  # during testing because it makes all operations deterministic.
+  #
+  # @note Intended for use primarily in testing and debugging.
   class ImmediateExecutor
-    include Executor
+    include SerialExecutor
+
+    # Creates a new executor
+    def initialize
+      @stopped = Concurrent::Event.new
+    end
 
+    # @!macro executor_method_post
     def post(*args, &task)
       raise ArgumentError.new('no block given') unless block_given?
+      return false unless running?
       task.call(*args)
       true
     end
 
+    # @!macro executor_method_left_shift
     def <<(task)
       post(&task)
       self
     end
+
+    # @!macro executor_method_running_question
+    def running?
+      ! shutdown?
+    end
+
+    # @!macro executor_method_shuttingdown_question
+    def shuttingdown?
+      false
+    end
+
+    # @!macro executor_method_shutdown_question
+    def shutdown?
+      @stopped.set?
+    end
+
+    # @!macro executor_method_shutdown
+    def shutdown
+      @stopped.set
+      true
+    end
+    alias_method :kill, :shutdown
+
+    # @!macro executor_method_wait_for_termination
+    def wait_for_termination(timeout = nil)
+      @stopped.wait(timeout)
+    end
   end
 end