concurrent-ruby 1.0.5 → 1.1.6

data/ext/concurrent-ruby/com/concurrent_ruby/ext/jsr166y/ThreadLocalRandom.java

@@ -0,0 +1,199 @@
+/*
+ * Written by Doug Lea with assistance from members of JCP JSR-166
+ * Expert Group and released to the public domain, as explained at
+ * http://creativecommons.org/publicdomain/zero/1.0/
+ */
+
+// This is based on 1.16 version
+
+package com.concurrent_ruby.ext.jsr166y;
+
+import java.util.Random;
+
+/**
+ * A random number generator isolated to the current thread.  Like the
+ * global {@link java.util.Random} generator used by the {@link
+ * java.lang.Math} class, a {@code ThreadLocalRandom} is initialized
+ * with an internally generated seed that may not otherwise be
+ * modified. When applicable, use of {@code ThreadLocalRandom} rather
+ * than shared {@code Random} objects in concurrent programs will
+ * typically encounter much less overhead and contention.  Use of
+ * {@code ThreadLocalRandom} is particularly appropriate when multiple
+ * tasks (for example, each a {@link ForkJoinTask}) use random numbers
+ * in parallel in thread pools.
+ *
+ * <p>Usages of this class should typically be of the form:
+ * {@code ThreadLocalRandom.current().nextX(...)} (where
+ * {@code X} is {@code Int}, {@code Long}, etc).
+ * When all usages are of this form, it is never possible to
+ * accidently share a {@code ThreadLocalRandom} across multiple threads.
+ *
+ * <p>This class also provides additional commonly used bounded random
+ * generation methods.
+ *
+ * @since 1.7
+ * @author Doug Lea
+ */
+public class ThreadLocalRandom extends Random {
+    // same constants as Random, but must be redeclared because private
+    private static final long multiplier = 0x5DEECE66DL;
+    private static final long addend = 0xBL;
+    private static final long mask = (1L << 48) - 1;
+
+    /**
+     * The random seed. We can't use super.seed.
+     */
+    private long rnd;
+
+    /**
+     * Initialization flag to permit calls to setSeed to succeed only
+     * while executing the Random constructor.  We can't allow others
+     * since it would cause setting seed in one part of a program to
+     * unintentionally impact other usages by the thread.
+     */
+    boolean initialized;
+
+    // Padding to help avoid memory contention among seed updates in
+    // different TLRs in the common case that they are located near
+    // each other.
+    private long pad0, pad1, pad2, pad3, pad4, pad5, pad6, pad7;
+
+    /**
+     * The actual ThreadLocal
+     */
+    private static final ThreadLocal<ThreadLocalRandom> localRandom =
+        new ThreadLocal<ThreadLocalRandom>() {
+            protected ThreadLocalRandom initialValue() {
+                return new ThreadLocalRandom();
+            }
+    };
+
+
+    /**
+     * Constructor called only by localRandom.initialValue.
+     */
+    ThreadLocalRandom() {
+        super();
+        initialized = true;
+    }
+
+    /**
+     * Returns the current thread's {@code ThreadLocalRandom}.
+     *
+     * @return the current thread's {@code ThreadLocalRandom}
+     */
+    public static ThreadLocalRandom current() {
+        return localRandom.get();
+    }
+
+    /**
+     * Throws {@code UnsupportedOperationException}.  Setting seeds in
+     * this generator is not supported.
+     *
+     * @throws UnsupportedOperationException always
+     */
+    public void setSeed(long seed) {
+        if (initialized)
+            throw new UnsupportedOperationException();
+        rnd = (seed ^ multiplier) & mask;
+    }
+
+    protected int next(int bits) {
+        rnd = (rnd * multiplier + addend) & mask;
+        return (int) (rnd >>> (48-bits));
+    }
+
+    /**
+     * Returns a pseudorandom, uniformly distributed value between the
+     * given least value (inclusive) and bound (exclusive).
+     *
+     * @param least the least value returned
+     * @param bound the upper bound (exclusive)
+     * @throws IllegalArgumentException if least greater than or equal
+     * to bound
+     * @return the next value
+     */
+    public int nextInt(int least, int bound) {
+        if (least >= bound)
+            throw new IllegalArgumentException();
+        return nextInt(bound - least) + least;
+    }
+
+    /**
+     * Returns a pseudorandom, uniformly distributed value
+     * between 0 (inclusive) and the specified value (exclusive).
+     *
+     * @param n the bound on the random number to be returned.  Must be
+     *        positive.
+     * @return the next value
+     * @throws IllegalArgumentException if n is not positive
+     */
+    public long nextLong(long n) {
+        if (n <= 0)
+            throw new IllegalArgumentException("n must be positive");
+        // Divide n by two until small enough for nextInt. On each
+        // iteration (at most 31 of them but usually much less),
+        // randomly choose both whether to include high bit in result
+        // (offset) and whether to continue with the lower vs upper
+        // half (which makes a difference only if odd).
+        long offset = 0;
+        while (n >= Integer.MAX_VALUE) {
+            int bits = next(2);
+            long half = n >>> 1;
+            long nextn = ((bits & 2) == 0) ? half : n - half;
+            if ((bits & 1) == 0)
+                offset += n - nextn;
+            n = nextn;
+        }
+        return offset + nextInt((int) n);
+    }
+
+    /**
+     * Returns a pseudorandom, uniformly distributed value between the
+     * given least value (inclusive) and bound (exclusive).
+     *
+     * @param least the least value returned
+     * @param bound the upper bound (exclusive)
+     * @return the next value
+     * @throws IllegalArgumentException if least greater than or equal
+     * to bound
+     */
+    public long nextLong(long least, long bound) {
+        if (least >= bound)
+            throw new IllegalArgumentException();
+        return nextLong(bound - least) + least;
+    }
+
+    /**
+     * Returns a pseudorandom, uniformly distributed {@code double} value
+     * between 0 (inclusive) and the specified value (exclusive).
+     *
+     * @param n the bound on the random number to be returned.  Must be
+     *        positive.
+     * @return the next value
+     * @throws IllegalArgumentException if n is not positive
+     */
+    public double nextDouble(double n) {
+        if (n <= 0)
+            throw new IllegalArgumentException("n must be positive");
+        return nextDouble() * n;
+    }
+
+    /**
+     * Returns a pseudorandom, uniformly distributed value between the
+     * given least value (inclusive) and bound (exclusive).
+     *
+     * @param least the least value returned
+     * @param bound the upper bound (exclusive)
+     * @return the next value
+     * @throws IllegalArgumentException if least greater than or equal
+     * to bound
+     */
+    public double nextDouble(double least, double bound) {
+        if (least >= bound)
+            throw new IllegalArgumentException();
+        return nextDouble() * (bound - least) + least;
+    }
+
+    private static final long serialVersionUID = -5851777807851030925L;
+}

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

@@ -0,0 +1 @@
+require_relative "./concurrent"

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

@@ -7,11 +7,13 @@ require 'concurrent/atomics'
 require 'concurrent/executors'
 require 'concurrent/synchronization'
 
+require 'concurrent/atomic/atomic_markable_reference'
 require 'concurrent/atomic/atomic_reference'
 require 'concurrent/agent'
 require 'concurrent/atom'
 require 'concurrent/array'
 require 'concurrent/hash'
+require 'concurrent/set'
 require 'concurrent/map'
 require 'concurrent/tuple'
 require 'concurrent/async'
@@ -29,20 +31,21 @@ require 'concurrent/scheduled_task'
 require 'concurrent/settable_struct'
 require 'concurrent/timer_task'
 require 'concurrent/tvar'
+require 'concurrent/promises'
 
 require 'concurrent/thread_safe/synchronized_delegator'
 require 'concurrent/thread_safe/util'
 
 require 'concurrent/options'
 
-# @!macro [new] internal_implementation_note
+# @!macro internal_implementation_note
 #
 #   @note **Private Implementation:** This abstraction is a private, internal
 #     implementation detail. It should never be used directly.
 
-# @!macro [new] monotonic_clock_warning
+# @!macro monotonic_clock_warning
 #
-#   @note Time calculations one all platforms and languages are sensitive to
+#   @note Time calculations on all platforms and languages are sensitive to
 #     changes to the system clock. To alleviate the potential problems
 #     associated with changing the system clock while an application is running,
 #     most modern operating systems provide a monotonic clock that operates
@@ -58,7 +61,7 @@ require 'concurrent/options'
 #
 #   @see http://linux.die.net/man/3/clock_gettime Linux clock_gettime(3)
 
-# @!macro [new] copy_options
+# @!macro copy_options
 #
 #   ## Copy Options
 #
@@ -94,7 +97,7 @@ require 'concurrent/options'
 #   as close to the behavior of a "pure" functional language (like Erlang, Clojure,
 #   or Haskell) as we are likely to get in Ruby.
 
-# @!macro [attach] deref_options
+# @!macro deref_options
 #
 #   @option opts [Boolean] :dup_on_deref (false) Call `#dup` before
 #     returning the data from {#value}
@@ -104,27 +107,28 @@ require 'concurrent/options'
 #     method, call the given proc passing the internal value as the sole
 #     argument then return the new value returned from the proc.
 
-# @!macro [attach] executor_and_deref_options
+# @!macro executor_and_deref_options
 #
 #   @param [Hash] opts the options used to define the behavior at update and deref
 #     and to specify the executor on which to perform actions
 #   @option opts [Executor] :executor when set use the given `Executor` instance.
-#     Three special values are also supported: `:task` returns the global task pool,
-#     `:operation` returns the global operation pool, and `:immediate` returns a new
-#     `ImmediateExecutor` object.
+#     Three special values are also supported: `:io` returns the global pool for
+#     long, blocking (IO) tasks, `:fast` returns the global pool for short, fast
+#     operations, and `:immediate` returns the global `ImmediateExecutor` object.
 #   @!macro deref_options
 
-# Modern concurrency tools for Ruby. Inspired by Erlang, Clojure, Scala, Haskell,
-# F#, C#, Java, and classic concurrency patterns.
+# @!macro warn.edge
+#   @api Edge
+#   @note **Edge Features** are under active development and may change frequently.
 #
-# The design goals of this gem are:
-#
-# * Stay true to the spirit of the languages providing inspiration
-# * But implement in a way that makes sense for Ruby
-# * Keep the semantics as idiomatic Ruby as possible
-# * Support features that make sense in Ruby
-# * Exclude features that don't make sense in Ruby
-# * Be small, lean, and loosely coupled
-module Concurrent
+#     -   Deprecations are not added before incompatible changes.
+#     -   Edge version: _major_ is always 0, _minor_ bump means incompatible change,
+#         _patch_ bump means compatible change.
+#     -   Edge features may also lack tests and documentation.
+#     -   Features developed in `concurrent-ruby-edge` are expected to move
+#         to `concurrent-ruby` when finalised.
 
+
+# {include:file:README.md}
+module Concurrent
 end

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-2.2.0/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

@@ -159,7 +159,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 +188,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
@@ -333,6 +333,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
@@ -383,6 +390,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 +406,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 +449,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__)