concurrent-ruby 1.0.5 → 1.1.0.pre1

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.rb

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

data/lib/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/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/array.rb

@@ -2,38 +2,65 @@ require 'concurrent/utility/engine'
 require 'concurrent/thread_safe/util'
 
 module Concurrent
-  if Concurrent.on_cruby?
-
-    # Because MRI never runs code in parallel, the existing
-    # non-thread-safe structures should usually work fine.
-
-    # @!macro [attach] 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`.
-    #
-    #   @see http://ruby-doc.org/core-2.2.0/Array.html Ruby standard library `Array`
-    class Array < ::Array;
-    end
-
-  elsif Concurrent.on_jruby?
-    require 'jruby/synchronized'
-
-    # @!macro concurrent_array
-    class Array < ::Array
-      include JRuby::Synchronized
-    end
-
-  elsif Concurrent.on_rbx? || Concurrent.on_truffle?
-    require 'monitor'
-    require 'concurrent/thread_safe/util/array_hash_rbx'
-
-    # @!macro concurrent_array
-    class Array < ::Array
-    end
-
-    ThreadSafe::Util.make_synchronized_on_rbx Array
+
+  # @!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?
+                          # Because MRI never runs code in parallel, the existing
+                          # non-thread-safe structures should usually work fine.
+                          ::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