concurrent-ruby 1.0.5 → 1.1.10

data/lib/{concurrent → concurrent-ruby/concurrent}/agent.rb

@@ -129,7 +129,7 @@ module Concurrent
   # end
   # ```
   #
-  # @!macro [new] agent_await_warning
+  # @!macro agent_await_warning
   #
   #   **NOTE** Never, *under any circumstances*, call any of the "await" methods
   #   ({#await}, {#await_for}, {#await_for!}, and {#wait}) from within an action
@@ -147,7 +147,7 @@ module Concurrent
     ERROR_MODES = [:continue, :fail].freeze
     private_constant :ERROR_MODES
 
-    AWAIT_FLAG = Object.new
+    AWAIT_FLAG = ::Object.new
     private_constant :AWAIT_FLAG
 
     AWAIT_ACTION = ->(value, latch) { latch.count_down; AWAIT_FLAG }
@@ -242,7 +242,7 @@ module Concurrent
 
     alias_method :reason, :error
 
-    # @!macro [attach] agent_send
+    # @!macro agent_send
     #
     #   Dispatches an action to the Agent and returns immediately. Subsequently,
     #   in a thread from a thread pool, the {#value} will be set to the return
@@ -271,7 +271,7 @@ module Concurrent
     #     action
     #   @yieldreturn [Object] the new value of the Agent
     #
-    # @!macro [attach] send_return
+    # @!macro send_return
     #   @return [Boolean] true if the action is successfully enqueued, false if
     #     the Agent is {#failed?}
     def send(*args, &action)
@@ -280,7 +280,7 @@ module Concurrent
 
     # @!macro agent_send
     #
-    # @!macro [attach] send_bang_return_and_raise
+    # @!macro send_bang_return_and_raise
     #   @return [Boolean] true if the action is successfully enqueued
     #   @raise [Concurrent::Agent::Error] if the Agent is {#failed?}
     def send!(*args, &action)
@@ -326,7 +326,7 @@ module Concurrent
     #
     # @param [Proc] action the action dispatch to be enqueued
     # @return [Concurrent::Agent] self
-    # @see {#send_off}
+    # @see #send_off
     def <<(action)
       send_off(&action)
       self
@@ -397,7 +397,7 @@ module Concurrent
 
     # Is the Agent in a failed state?
     #
-    # @see {#restart}
+    # @see #restart
     def failed?
       !@error.value.nil?
     end

data/lib/concurrent-ruby/concurrent/array.rb

@@ -0,0 +1,66 @@
+require 'concurrent/utility/engine'
+require 'concurrent/thread_safe/util'
+
+module Concurrent
+
+  # @!macro concurrent_array
+  #
+  #   A thread-safe subclass of Array. This version locks against the object
+  #   itself for every method call, ensuring only one thread can be reading
+  #   or writing at a time. This includes iteration methods like `#each`.
+  #
+  #   @note `a += b` is **not** a **thread-safe** operation on
+  #     `Concurrent::Array`. It reads array `a`, then it creates new `Concurrent::Array`
+  #     which is concatenation of `a` and `b`, then it writes the concatenation to `a`.
+  #     The read and write are independent operations they do not form a single atomic
+  #     operation therefore when two `+=` operations are executed concurrently updates
+  #     may be lost. Use `#concat` instead.
+  #
+  #   @see http://ruby-doc.org/core/Array.html Ruby standard library `Array`
+
+  # @!macro internal_implementation_note
+  ArrayImplementation = case
+                        when Concurrent.on_cruby?
+                          # Array is thread-safe in practice because CRuby runs
+                          # threads one at a time and does not do context
+                          # switching during the execution of C functions.
+                          ::Array
+
+                        when Concurrent.on_jruby?
+                          require 'jruby/synchronized'
+
+                          class JRubyArray < ::Array
+                            include JRuby::Synchronized
+                          end
+                          JRubyArray
+
+                        when Concurrent.on_rbx?
+                          require 'monitor'
+                          require 'concurrent/thread_safe/util/data_structures'
+
+                          class RbxArray < ::Array
+                          end
+
+                          ThreadSafe::Util.make_synchronized_on_rbx RbxArray
+                          RbxArray
+
+                        when Concurrent.on_truffleruby?
+                          require 'concurrent/thread_safe/util/data_structures'
+
+                          class TruffleRubyArray < ::Array
+                          end
+
+                          ThreadSafe::Util.make_synchronized_on_truffleruby TruffleRubyArray
+                          TruffleRubyArray
+
+                        else
+                          warn 'Possibly unsupported Ruby implementation'
+                          ::Array
+                        end
+  private_constant :ArrayImplementation
+
+  # @!macro concurrent_array
+  class Array < ArrayImplementation
+  end
+
+end

data/lib/{concurrent → concurrent-ruby/concurrent}/async.rb

@@ -58,26 +58,6 @@ module Concurrent
   # end
   # ```
   #
-  # When defining a constructor it is critical that the first line be a call to
-  # `super` with no arguments. The `super` method initializes the background
-  # thread and other asynchronous components.
-  #
-  # ```
-  # class BackgroundLogger
-  #   include Concurrent::Async
-  #
-  #   def initialize(level)
-  #     super()
-  #     @logger = Logger.new(STDOUT)
-  #     @logger.level = level
-  #   end
-  #
-  #   def info(msg)
-  #     @logger.info(msg)
-  #   end
-  # end
-  # ```
-  #
   # Mixing this module into a class provides each object two proxy methods:
   # `async` and `await`. These methods are thread safe with respect to the
   # enclosing object. The former proxy allows methods to be called
@@ -159,7 +139,7 @@ module Concurrent
   #
   # To get the state *at the current* time, irrespective of an enqueued method
   # calls, a reader method must be called directly. This is inherently unsafe
-  # unless the instance variable is itself thread-safe, preferrably using one
+  # unless the instance variable is itself thread-safe, preferably using one
   # of the thread-safe classes within this library. Because the thread-safe
   # classes within this library are internally-locking or non-locking, they can
   # be safely used from within asynchronous methods without causing deadlocks.
@@ -188,7 +168,7 @@ module Concurrent
   #
   # Class variables should be avoided. Class variables represent shared state.
   # Shared state is anathema to concurrency. Should there be a need to share
-  # state using class variables they *must* be thread-safe, preferrably
+  # state using class variables they *must* be thread-safe, preferably
   # using the thread-safe classes within this library. When updating class
   # variables, never assign a new value/object to the variable itself. Assignment
   # is not thread-safe in Ruby. Instead, use the thread-safe update functions
@@ -292,6 +272,7 @@ module Concurrent
         obj.send(:init_synchronization)
         obj
       end
+      ruby2_keywords :new if respond_to?(:ruby2_keywords, true)
     end
     private_constant :ClassMethods
 
@@ -309,6 +290,7 @@ module Concurrent
         @delegate = delegate
         @queue = []
         @executor = Concurrent.global_io_executor
+        @ruby_pid = $$
       end
 
       # Delegates method calls to the wrapped object.
@@ -326,6 +308,7 @@ module Concurrent
 
         ivar = Concurrent::IVar.new
         synchronize do
+          reset_if_forked
           @queue.push [ivar, method, args, block]
           @executor.post { perform } if @queue.length == 1
         end
@@ -333,6 +316,13 @@ module Concurrent
         ivar
       end
 
+      # Check whether the method is responsive
+      #
+      # @param [Symbol] method the method being called
+      def respond_to_missing?(method, include_private = false)
+        @delegate.respond_to?(method) || super
+      end
+
       # Perform all enqueued tasks.
       #
       # This method must be called from within the executor. It must not be
@@ -354,6 +344,13 @@ module Concurrent
           end
         end
       end
+
+      def reset_if_forked
+        if $$ != @ruby_pid
+          @queue.clear
+          @ruby_pid = $$
+        end
+      end
     end
     private_constant :AsyncDelegator
 
@@ -383,6 +380,13 @@ module Concurrent
         ivar.wait
         ivar
       end
+
+      # Check whether the method is responsive
+      #
+      # @param [Symbol] method the method being called
+      def respond_to_missing?(method, include_private = false)
+        @delegate.respond_to?(method) || super
+      end
     end
     private_constant :AwaitDelegator
 
@@ -392,7 +396,7 @@ module Concurrent
     # object's thread. The final disposition of the method call can be obtained
     # by inspecting the returned future.
     #
-    # @!macro [attach] async_thread_safety_warning
+    # @!macro 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
@@ -435,7 +439,7 @@ module Concurrent
     #
     # @!visibility private
     def init_synchronization
-      return self if @__async_initialized__
+      return self if defined?(@__async_initialized__) && @__async_initialized__
       @__async_initialized__ = true
       @__async_delegator__ = AsyncDelegator.new(self)
       @__await_delegator__ = AwaitDelegator.new(@__async_delegator__)

data/lib/{concurrent → concurrent-ruby/concurrent}/atom.rb

@@ -3,7 +3,7 @@ require 'concurrent/collection/copy_on_notify_observer_set'
 require 'concurrent/concern/observable'
 require 'concurrent/synchronization'
 
-# @!macro [new] thread_safe_variable_comparison
+# @!macro thread_safe_variable_comparison
 #
 #   ## Thread-safe Variable Classes
 #
@@ -18,7 +18,7 @@ require 'concurrent/synchronization'
 #     uncoordinated, *synchronous* change of individual values. Best used when
 #     the value will undergo frequent reads but only occasional, though complex,
 #     updates. Suitable when the result of an update must be known immediately.
-#   * *{Concurrent::AtomicReference}:* A simple object reference that can be
+#   * *{Concurrent::AtomicReference}:* A simple object reference that can be updated
 #     atomically. Updates are synchronous but fast. Best used when updates a
 #     simple set operations. Not suitable when updates are complex.
 #     {Concurrent::AtomicBoolean} and {Concurrent::AtomicFixnum} are similar
@@ -96,8 +96,15 @@ module Concurrent
     include Concern::Observable
 
     safe_initialization!
-    private(*attr_atomic(:value))
+    attr_atomic(:value)
+    private :value=, :swap_value, :compare_and_set_value, :update_value
     public :value
+    alias_method :deref, :value
+
+    # @!method value
+    #   The current value of the atom.
+    #
+    #   @return [Object] The current value.
 
     # Create a new atom with the given initial value.
     #
@@ -118,13 +125,6 @@ module Concurrent
       self.value     = value
     end
 
-    # @!method value
-    #   The current value of the atom.
-    #
-    #   @return [Object] The current value.
-
-    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

data/lib/{concurrent → concurrent-ruby/concurrent}/atomic/atomic_boolean.rb

@@ -5,19 +5,19 @@ module Concurrent
 
   ###################################################################
 
-  # @!macro [new] atomic_boolean_method_initialize
+  # @!macro atomic_boolean_method_initialize
   #
   #   Creates a new `AtomicBoolean` with the given initial value.
   #
   #   @param [Boolean] initial the initial value
 
-  # @!macro [new] atomic_boolean_method_value_get
+  # @!macro atomic_boolean_method_value_get
   #
   #   Retrieves the current `Boolean` value.
   #
   #   @return [Boolean] the current value
 
-  # @!macro [new] atomic_boolean_method_value_set
+  # @!macro atomic_boolean_method_value_set
   #
   #   Explicitly sets the value.
   #
@@ -25,33 +25,33 @@ module Concurrent
   #
   #   @return [Boolean] the current value
 
-  # @!macro [new] atomic_boolean_method_true_question
+  # @!macro atomic_boolean_method_true_question
   #
   #   Is the current value `true`
   #
   #   @return [Boolean] true if the current value is `true`, else false
 
-  # @!macro [new] atomic_boolean_method_false_question
+  # @!macro atomic_boolean_method_false_question
   #
   #   Is the current value `false`
   #
   #   @return [Boolean] true if the current value is `false`, else false
 
-  # @!macro [new] atomic_boolean_method_make_true
+  # @!macro atomic_boolean_method_make_true
   #
   #   Explicitly sets the value to true.
   #
-  #   @return [Boolean] true is value has changed, otherwise false
+  #   @return [Boolean] true if value has changed, otherwise false
 
-  # @!macro [new] atomic_boolean_method_make_false
+  # @!macro atomic_boolean_method_make_false
   #
   #   Explicitly sets the value to false.
   #
-  #   @return [Boolean] true is value has changed, otherwise false
+  #   @return [Boolean] true if value has changed, otherwise false
 
   ###################################################################
 
-  # @!macro [new] atomic_boolean_public_api
+  # @!macro atomic_boolean_public_api
   #
   #   @!method initialize(initial = false)
   #     @!macro  atomic_boolean_method_initialize
@@ -88,7 +88,7 @@ module Concurrent
                                 end
   private_constant :AtomicBooleanImplementation
 
-  # @!macro [attach] atomic_boolean
+  # @!macro atomic_boolean
   #
   #   A boolean value that can be updated atomically. Reads and writes to an atomic
   #   boolean and thread-safe and guaranteed to succeed. Reads and writes may block
@@ -96,17 +96,21 @@ module Concurrent
   #
   #   @!macro thread_safe_variable_comparison
   #
-  #       Testing with ruby 2.1.2
-  #       Testing with Concurrent::MutexAtomicBoolean...
-  #         2.790000   0.000000   2.790000 (  2.791454)
-  #       Testing with Concurrent::CAtomicBoolean...
-  #         0.740000   0.000000   0.740000 (  0.740206)
+  #   Performance:
+  #
+  #   ```
+  #   Testing with ruby 2.1.2
+  #   Testing with Concurrent::MutexAtomicBoolean...
+  #     2.790000   0.000000   2.790000 (  2.791454)
+  #   Testing with Concurrent::CAtomicBoolean...
+  #     0.740000   0.000000   0.740000 (  0.740206)
   #
-  #       Testing with jruby 1.9.3
-  #       Testing with Concurrent::MutexAtomicBoolean...
-  #         5.240000   2.520000   7.760000 (  3.683000)
-  #       Testing with Concurrent::JavaAtomicBoolean...
-  #         3.340000   0.010000   3.350000 (  0.855000)
+  #   Testing with jruby 1.9.3
+  #   Testing with Concurrent::MutexAtomicBoolean...
+  #     5.240000   2.520000   7.760000 (  3.683000)
+  #   Testing with Concurrent::JavaAtomicBoolean...
+  #     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
   #
@@ -114,7 +118,7 @@ module Concurrent
   class AtomicBoolean < AtomicBooleanImplementation
     # @return [String] Short string representation.
     def to_s
-      format '<#%s:0x%x value:%s>', self.class, object_id << 1, value
+      format '%s value:%s>', super[0..-2], value
     end
 
     alias_method :inspect, :to_s

data/lib/{concurrent → concurrent-ruby/concurrent}/atomic/atomic_fixnum.rb

@@ -5,20 +5,20 @@ module Concurrent
 
   ###################################################################
 
-  # @!macro [new] atomic_fixnum_method_initialize
+  # @!macro atomic_fixnum_method_initialize
   #
   #   Creates a new `AtomicFixnum` with the given initial value.
   #
   #   @param [Fixnum] initial the initial value
   #   @raise [ArgumentError] if the initial value is not a `Fixnum`
 
-  # @!macro [new] atomic_fixnum_method_value_get
+  # @!macro atomic_fixnum_method_value_get
   #
   #   Retrieves the current `Fixnum` value.
   #
   #   @return [Fixnum] the current value
 
-  # @!macro [new] atomic_fixnum_method_value_set
+  # @!macro atomic_fixnum_method_value_set
   #
   #   Explicitly sets the value.
   #
@@ -28,7 +28,7 @@ module Concurrent
   #
   #   @raise [ArgumentError] if the new value is not a `Fixnum`
 
-  # @!macro [new] atomic_fixnum_method_increment
+  # @!macro atomic_fixnum_method_increment
   #
   #   Increases the current value by the given amount (defaults to 1).
   #
@@ -36,7 +36,7 @@ module Concurrent
   #
   #   @return [Fixnum] the current value after incrementation
 
-  # @!macro [new] atomic_fixnum_method_decrement
+  # @!macro atomic_fixnum_method_decrement
   #
   #   Decreases the current value by the given amount (defaults to 1).
   #
@@ -44,7 +44,7 @@ module Concurrent
   #
   #   @return [Fixnum] the current value after decrementation
 
-  # @!macro [new] atomic_fixnum_method_compare_and_set
+  # @!macro atomic_fixnum_method_compare_and_set
   #
   #   Atomically sets the value to the given updated value if the current
   #   value == the expected value.
@@ -52,9 +52,9 @@ module Concurrent
   #   @param [Fixnum] expect the expected value
   #   @param [Fixnum] update the new value
   #
-  #   @return [Fixnum] true if the value was updated else false
+  #   @return [Boolean] true if the value was updated else false
 
-  # @!macro [new] atomic_fixnum_method_update
+  # @!macro atomic_fixnum_method_update
   #
   #   Pass the current value to the given block, replacing it
   #   with the block's result. May retry if the value changes
@@ -68,7 +68,7 @@ module Concurrent
 
   ###################################################################
 
-  # @!macro [new] atomic_fixnum_public_api
+  # @!macro atomic_fixnum_public_api
   #
   #   @!method initialize(initial = 0)
   #     @!macro atomic_fixnum_method_initialize
@@ -79,10 +79,10 @@ module Concurrent
   #   @!method value=(value)
   #     @!macro atomic_fixnum_method_value_set
   #
-  #   @!method increment
+  #   @!method increment(delta = 1)
   #     @!macro atomic_fixnum_method_increment
   #
-  #   @!method decrement
+  #   @!method decrement(delta = 1)
   #     @!macro atomic_fixnum_method_decrement
   #
   #   @!method compare_and_set(expect, update)
@@ -105,7 +105,7 @@ module Concurrent
                                end
   private_constant :AtomicFixnumImplementation
 
-  # @!macro [attach] atomic_fixnum
+  # @!macro atomic_fixnum
   #
   #   A numeric value that can be updated atomically. Reads and writes to an atomic
   #   fixnum and thread-safe and guaranteed to succeed. Reads and writes may block
@@ -113,17 +113,21 @@ module Concurrent
   #
   #   @!macro thread_safe_variable_comparison
   #
-  #       Testing with ruby 2.1.2
-  #       Testing with Concurrent::MutexAtomicFixnum...
-  #         3.130000   0.000000   3.130000 (  3.136505)
-  #       Testing with Concurrent::CAtomicFixnum...
-  #         0.790000   0.000000   0.790000 (  0.785550)
+  #   Performance:
+  #
+  #   ```
+  #   Testing with ruby 2.1.2
+  #   Testing with Concurrent::MutexAtomicFixnum...
+  #     3.130000   0.000000   3.130000 (  3.136505)
+  #   Testing with Concurrent::CAtomicFixnum...
+  #     0.790000   0.000000   0.790000 (  0.785550)
   #
-  #       Testing with jruby 1.9.3
-  #       Testing with Concurrent::MutexAtomicFixnum...
-  #         5.460000   2.460000   7.920000 (  3.715000)
-  #       Testing with Concurrent::JavaAtomicFixnum...
-  #         4.520000   0.030000   4.550000 (  1.187000)
+  #   Testing with jruby 1.9.3
+  #   Testing with Concurrent::MutexAtomicFixnum...
+  #     5.460000   2.460000   7.920000 (  3.715000)
+  #   Testing with Concurrent::JavaAtomicFixnum...
+  #     4.520000   0.030000   4.550000 (  1.187000)
+  #   ```
   #
   #   @see http://docs.oracle.com/javase/7/docs/api/java/util/concurrent/atomic/AtomicLong.html java.util.concurrent.atomic.AtomicLong
   #
@@ -131,7 +135,7 @@ module Concurrent
   class AtomicFixnum < AtomicFixnumImplementation
     # @return [String] Short string representation.
     def to_s
-      format '<#%s:0x%x value:%s>', self.class, object_id << 1, value
+      format '%s value:%s>', super[0..-2], value
     end
 
     alias_method :inspect, :to_s