1 /*
   2  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   3  *
   4  * This code is free software; you can redistribute it and/or modify it
   5  * under the terms of the GNU General Public License version 2 only, as
   6  * published by the Free Software Foundation.  Oracle designates this
   7  * particular file as subject to the "Classpath" exception as provided
   8  * by Oracle in the LICENSE file that accompanied this code.
   9  *
  10  * This code is distributed in the hope that it will be useful, but WITHOUT
  11  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  12  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  13  * version 2 for more details (a copy is included in the LICENSE file that
  14  * accompanied this code).
  15  *
  16  * You should have received a copy of the GNU General Public License version
  17  * 2 along with this work; if not, write to the Free Software Foundation,
  18  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  19  *
  20  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  21  * or visit www.oracle.com if you need additional information or have any
  22  * questions.
  23  */
  24 
  25 /*
  26  * This file is available under and governed by the GNU General Public
  27  * License version 2 only, as published by the Free Software Foundation.
  28  * However, the following notice accompanied the original version of this
  29  * file:
  30  *
  31  * Written by Doug Lea with assistance from members of JCP JSR-166
  32  * Expert Group and released to the public domain, as explained at
  33  * http://creativecommons.org/publicdomain/zero/1.0/
  34  */
  35 
  36 package java.util.concurrent;
  37 
  38 import java.io.ObjectStreamField;
  39 import java.util.Random;
  40 import java.util.Spliterator;
  41 import java.util.concurrent.atomic.AtomicInteger;
  42 import java.util.concurrent.atomic.AtomicLong;
  43 import java.util.function.DoubleConsumer;
  44 import java.util.function.IntConsumer;
  45 import java.util.function.LongConsumer;
  46 import java.util.stream.DoubleStream;
  47 import java.util.stream.IntStream;
  48 import java.util.stream.LongStream;
  49 import java.util.stream.StreamSupport;
  50 
  51 /**
  52  * A random number generator isolated to the current thread.  Like the
  53  * global {@link java.util.Random} generator used by the {@link
  54  * java.lang.Math} class, a {@code ThreadLocalRandom} is initialized
  55  * with an internally generated seed that may not otherwise be
  56  * modified. When applicable, use of {@code ThreadLocalRandom} rather
  57  * than shared {@code Random} objects in concurrent programs will
  58  * typically encounter much less overhead and contention.  Use of
  59  * {@code ThreadLocalRandom} is particularly appropriate when multiple
  60  * tasks (for example, each a {@link ForkJoinTask}) use random numbers
  61  * in parallel in thread pools.
  62  *
  63  * <p>Usages of this class should typically be of the form:
  64  * {@code ThreadLocalRandom.current().nextX(...)} (where
  65  * {@code X} is {@code Int}, {@code Long}, etc).
  66  * When all usages are of this form, it is never possible to
  67  * accidently share a {@code ThreadLocalRandom} across multiple threads.
  68  *
  69  * <p>This class also provides additional commonly used bounded random
  70  * generation methods.
  71  *
  72  * <p>Instances of {@code ThreadLocalRandom} are not cryptographically
  73  * secure.  Consider instead using {@link java.security.SecureRandom}
  74  * in security-sensitive applications. Additionally,
  75  * default-constructed instances do not use a cryptographically random
  76  * seed unless the {@linkplain System#getProperty system property}
  77  * {@code java.util.secureRandomSeed} is set to {@code true}.
  78  *
  79  * @since 1.7
  80  * @author Doug Lea
  81  */
  82 public class ThreadLocalRandom extends Random {
  83     /*
  84      * This class implements the java.util.Random API (and subclasses
  85      * Random) using a single static instance that accesses random
  86      * number state held in class Thread (primarily, field
  87      * threadLocalRandomSeed). In doing so, it also provides a home
  88      * for managing package-private utilities that rely on exactly the
  89      * same state as needed to maintain the ThreadLocalRandom
  90      * instances. We leverage the need for an initialization flag
  91      * field to also use it as a "probe" -- a self-adjusting thread
  92      * hash used for contention avoidance, as well as a secondary
  93      * simpler (xorShift) random seed that is conservatively used to
  94      * avoid otherwise surprising users by hijacking the
  95      * ThreadLocalRandom sequence.  The dual use is a marriage of
  96      * convenience, but is a simple and efficient way of reducing
  97      * application-level overhead and footprint of most concurrent
  98      * programs.
  99      *
 100      * Even though this class subclasses java.util.Random, it uses the
 101      * same basic algorithm as java.util.SplittableRandom.  (See its
 102      * internal documentation for explanations, which are not repeated
 103      * here.)  Because ThreadLocalRandoms are not splittable
 104      * though, we use only a single 64bit gamma.
 105      *
 106      * Because this class is in a different package than class Thread,
 107      * field access methods use Unsafe to bypass access control rules.
 108      * To conform to the requirements of the Random superclass
 109      * constructor, the common static ThreadLocalRandom maintains an
 110      * "initialized" field for the sake of rejecting user calls to
 111      * setSeed while still allowing a call from constructor.  Note
 112      * that serialization is completely unnecessary because there is
 113      * only a static singleton.  But we generate a serial form
 114      * containing "rnd" and "initialized" fields to ensure
 115      * compatibility across versions.
 116      *
 117      * Implementations of non-core methods are mostly the same as in
 118      * SplittableRandom, that were in part derived from a previous
 119      * version of this class.
 120      *
 121      * The nextLocalGaussian ThreadLocal supports the very rarely used
 122      * nextGaussian method by providing a holder for the second of a
 123      * pair of them. As is true for the base class version of this
 124      * method, this time/space tradeoff is probably never worthwhile,
 125      * but we provide identical statistical properties.
 126      */
 127 
 128     /** Generates per-thread initialization/probe field */
 129     private static final AtomicInteger probeGenerator = new AtomicInteger();
 130 
 131     /**
 132      * The next seed for default constructors.
 133      */
 134     private static final AtomicLong seeder = new AtomicLong(initialSeed());
 135 
 136     private static long initialSeed() {
 137         String pp = java.security.AccessController.doPrivileged(
 138                 new sun.security.action.GetPropertyAction(
 139                         "java.util.secureRandomSeed"));
 140         if (pp != null && pp.equalsIgnoreCase("true")) {
 141             byte[] seedBytes = java.security.SecureRandom.getSeed(8);
 142             long s = (long)(seedBytes[0]) & 0xffL;
 143             for (int i = 1; i < 8; ++i)
 144                 s = (s << 8) | ((long)(seedBytes[i]) & 0xffL);
 145             return s;
 146         }
 147         return (mix64(System.currentTimeMillis()) ^
 148                 mix64(System.nanoTime()));
 149     }
 150 
 151     /**
 152      * The seed increment.
 153      */
 154     private static final long GAMMA = 0x9e3779b97f4a7c15L;
 155 
 156     /**
 157      * The increment for generating probe values.
 158      */
 159     private static final int PROBE_INCREMENT = 0x9e3779b9;
 160 
 161     /**
 162      * The increment of seeder per new instance.
 163      */
 164     private static final long SEEDER_INCREMENT = 0xbb67ae8584caa73bL;
 165 
 166     // Constants from SplittableRandom
 167     private static final double DOUBLE_UNIT = 0x1.0p-53;  // 1.0  / (1L << 53)
 168     private static final float  FLOAT_UNIT  = 0x1.0p-24f; // 1.0f / (1 << 24)
 169 
 170     /** Rarely-used holder for the second of a pair of Gaussians */
 171     private static final ThreadLocal<Double> nextLocalGaussian =
 172         new ThreadLocal<>();
 173 
 174     private static long mix64(long z) {
 175         z = (z ^ (z >>> 33)) * 0xff51afd7ed558ccdL;
 176         z = (z ^ (z >>> 33)) * 0xc4ceb9fe1a85ec53L;
 177         return z ^ (z >>> 33);
 178     }
 179 
 180     private static int mix32(long z) {
 181         z = (z ^ (z >>> 33)) * 0xff51afd7ed558ccdL;
 182         return (int)(((z ^ (z >>> 33)) * 0xc4ceb9fe1a85ec53L) >>> 32);
 183     }
 184 
 185     /**
 186      * Field used only during singleton initialization.
 187      * True when constructor completes.
 188      */
 189     boolean initialized;
 190 
 191     /** Constructor used only for static singleton */
 192     private ThreadLocalRandom() {
 193         initialized = true; // false during super() call
 194     }
 195 
 196     /** The common ThreadLocalRandom */
 197     static final ThreadLocalRandom instance = new ThreadLocalRandom();
 198 
 199     /**
 200      * Initialize Thread fields for the current thread.  Called only
 201      * when Thread.threadLocalRandomProbe is zero, indicating that a
 202      * thread local seed value needs to be generated. Note that even
 203      * though the initialization is purely thread-local, we need to
 204      * rely on (static) atomic generators to initialize the values.
 205      */
 206     static final void localInit() {
 207         int p = probeGenerator.addAndGet(PROBE_INCREMENT);
 208         int probe = (p == 0) ? 1 : p; // skip 0
 209         long seed = mix64(seeder.getAndAdd(SEEDER_INCREMENT));
 210         Thread t = Thread.currentThread();
 211         U.putLong(t, SEED, seed);
 212         U.putInt(t, PROBE, probe);
 213     }
 214 
 215     /**
 216      * Returns the current thread's {@code ThreadLocalRandom}.
 217      *
 218      * @return the current thread's {@code ThreadLocalRandom}
 219      */
 220     public static ThreadLocalRandom current() {
 221         if (U.getInt(Thread.currentThread(), PROBE) == 0)
 222             localInit();
 223         return instance;
 224     }
 225 
 226     /**
 227      * Throws {@code UnsupportedOperationException}.  Setting seeds in
 228      * this generator is not supported.
 229      *
 230      * @throws UnsupportedOperationException always
 231      */
 232     public void setSeed(long seed) {
 233         // only allow call from super() constructor
 234         if (initialized)
 235             throw new UnsupportedOperationException();
 236     }
 237 
 238     final long nextSeed() {
 239         Thread t; long r; // read and update per-thread seed
 240         U.putLong(t = Thread.currentThread(), SEED,
 241                   r = U.getLong(t, SEED) + GAMMA);
 242         return r;
 243     }
 244 
 245     // We must define this, but never use it.
 246     protected int next(int bits) {
 247         return (int)(mix64(nextSeed()) >>> (64 - bits));
 248     }
 249 
 250     // IllegalArgumentException messages
 251     static final String BAD_BOUND = "bound must be positive";
 252     static final String BAD_RANGE = "bound must be greater than origin";
 253     static final String BAD_SIZE  = "size must be non-negative";
 254 
 255     /**
 256      * The form of nextLong used by LongStream Spliterators.  If
 257      * origin is greater than bound, acts as unbounded form of
 258      * nextLong, else as bounded form.
 259      *
 260      * @param origin the least value, unless greater than bound
 261      * @param bound the upper bound (exclusive), must not equal origin
 262      * @return a pseudorandom value
 263      */
 264     final long internalNextLong(long origin, long bound) {
 265         long r = mix64(nextSeed());
 266         if (origin < bound) {
 267             long n = bound - origin, m = n - 1;
 268             if ((n & m) == 0L)  // power of two
 269                 r = (r & m) + origin;
 270             else if (n > 0L) {  // reject over-represented candidates
 271                 for (long u = r >>> 1;            // ensure nonnegative
 272                      u + m - (r = u % n) < 0L;    // rejection check
 273                      u = mix64(nextSeed()) >>> 1) // retry
 274                     ;
 275                 r += origin;
 276             }
 277             else {              // range not representable as long
 278                 while (r < origin || r >= bound)
 279                     r = mix64(nextSeed());
 280             }
 281         }
 282         return r;
 283     }
 284 
 285     /**
 286      * The form of nextInt used by IntStream Spliterators.
 287      * Exactly the same as long version, except for types.
 288      *
 289      * @param origin the least value, unless greater than bound
 290      * @param bound the upper bound (exclusive), must not equal origin
 291      * @return a pseudorandom value
 292      */
 293     final int internalNextInt(int origin, int bound) {
 294         int r = mix32(nextSeed());
 295         if (origin < bound) {
 296             int n = bound - origin, m = n - 1;
 297             if ((n & m) == 0)
 298                 r = (r & m) + origin;
 299             else if (n > 0) {
 300                 for (int u = r >>> 1;
 301                      u + m - (r = u % n) < 0;
 302                      u = mix32(nextSeed()) >>> 1)
 303                     ;
 304                 r += origin;
 305             }
 306             else {
 307                 while (r < origin || r >= bound)
 308                     r = mix32(nextSeed());
 309             }
 310         }
 311         return r;
 312     }
 313 
 314     /**
 315      * The form of nextDouble used by DoubleStream Spliterators.
 316      *
 317      * @param origin the least value, unless greater than bound
 318      * @param bound the upper bound (exclusive), must not equal origin
 319      * @return a pseudorandom value
 320      */
 321     final double internalNextDouble(double origin, double bound) {
 322         double r = (nextLong() >>> 11) * DOUBLE_UNIT;
 323         if (origin < bound) {
 324             r = r * (bound - origin) + origin;
 325             if (r >= bound) // correct for rounding
 326                 r = Double.longBitsToDouble(Double.doubleToLongBits(bound) - 1);
 327         }
 328         return r;
 329     }
 330 
 331     /**
 332      * Returns a pseudorandom {@code int} value.
 333      *
 334      * @return a pseudorandom {@code int} value
 335      */
 336     public int nextInt() {
 337         return mix32(nextSeed());
 338     }
 339 
 340     /**
 341      * Returns a pseudorandom {@code int} value between zero (inclusive)
 342      * and the specified bound (exclusive).
 343      *
 344      * @param bound the upper bound (exclusive).  Must be positive.
 345      * @return a pseudorandom {@code int} value between zero
 346      *         (inclusive) and the bound (exclusive)
 347      * @throws IllegalArgumentException if {@code bound} is not positive
 348      */
 349     public int nextInt(int bound) {
 350         if (bound <= 0)
 351             throw new IllegalArgumentException(BAD_BOUND);
 352         int r = mix32(nextSeed());
 353         int m = bound - 1;
 354         if ((bound & m) == 0) // power of two
 355             r &= m;
 356         else { // reject over-represented candidates
 357             for (int u = r >>> 1;
 358                  u + m - (r = u % bound) < 0;
 359                  u = mix32(nextSeed()) >>> 1)
 360                 ;
 361         }
 362         return r;
 363     }
 364 
 365     /**
 366      * Returns a pseudorandom {@code int} value between the specified
 367      * origin (inclusive) and the specified bound (exclusive).
 368      *
 369      * @param origin the least value returned
 370      * @param bound the upper bound (exclusive)
 371      * @return a pseudorandom {@code int} value between the origin
 372      *         (inclusive) and the bound (exclusive)
 373      * @throws IllegalArgumentException if {@code origin} is greater than
 374      *         or equal to {@code bound}
 375      */
 376     public int nextInt(int origin, int bound) {
 377         if (origin >= bound)
 378             throw new IllegalArgumentException(BAD_RANGE);
 379         return internalNextInt(origin, bound);
 380     }
 381 
 382     /**
 383      * Returns a pseudorandom {@code long} value.
 384      *
 385      * @return a pseudorandom {@code long} value
 386      */
 387     public long nextLong() {
 388         return mix64(nextSeed());
 389     }
 390 
 391     /**
 392      * Returns a pseudorandom {@code long} value between zero (inclusive)
 393      * and the specified bound (exclusive).
 394      *
 395      * @param bound the upper bound (exclusive).  Must be positive.
 396      * @return a pseudorandom {@code long} value between zero
 397      *         (inclusive) and the bound (exclusive)
 398      * @throws IllegalArgumentException if {@code bound} is not positive
 399      */
 400     public long nextLong(long bound) {
 401         if (bound <= 0)
 402             throw new IllegalArgumentException(BAD_BOUND);
 403         long r = mix64(nextSeed());
 404         long m = bound - 1;
 405         if ((bound & m) == 0L) // power of two
 406             r &= m;
 407         else { // reject over-represented candidates
 408             for (long u = r >>> 1;
 409                  u + m - (r = u % bound) < 0L;
 410                  u = mix64(nextSeed()) >>> 1)
 411                 ;
 412         }
 413         return r;
 414     }
 415 
 416     /**
 417      * Returns a pseudorandom {@code long} value between the specified
 418      * origin (inclusive) and the specified bound (exclusive).
 419      *
 420      * @param origin the least value returned
 421      * @param bound the upper bound (exclusive)
 422      * @return a pseudorandom {@code long} value between the origin
 423      *         (inclusive) and the bound (exclusive)
 424      * @throws IllegalArgumentException if {@code origin} is greater than
 425      *         or equal to {@code bound}
 426      */
 427     public long nextLong(long origin, long bound) {
 428         if (origin >= bound)
 429             throw new IllegalArgumentException(BAD_RANGE);
 430         return internalNextLong(origin, bound);
 431     }
 432 
 433     /**
 434      * Returns a pseudorandom {@code double} value between zero
 435      * (inclusive) and one (exclusive).
 436      *
 437      * @return a pseudorandom {@code double} value between zero
 438      *         (inclusive) and one (exclusive)
 439      */
 440     public double nextDouble() {
 441         return (mix64(nextSeed()) >>> 11) * DOUBLE_UNIT;
 442     }
 443 
 444     /**
 445      * Returns a pseudorandom {@code double} value between 0.0
 446      * (inclusive) and the specified bound (exclusive).
 447      *
 448      * @param bound the upper bound (exclusive).  Must be positive.
 449      * @return a pseudorandom {@code double} value between zero
 450      *         (inclusive) and the bound (exclusive)
 451      * @throws IllegalArgumentException if {@code bound} is not positive
 452      */
 453     public double nextDouble(double bound) {
 454         if (!(bound > 0.0))
 455             throw new IllegalArgumentException(BAD_BOUND);
 456         double result = (mix64(nextSeed()) >>> 11) * DOUBLE_UNIT * bound;
 457         return (result < bound) ? result : // correct for rounding
 458             Double.longBitsToDouble(Double.doubleToLongBits(bound) - 1);
 459     }
 460 
 461     /**
 462      * Returns a pseudorandom {@code double} value between the specified
 463      * origin (inclusive) and bound (exclusive).
 464      *
 465      * @param origin the least value returned
 466      * @param bound the upper bound (exclusive)
 467      * @return a pseudorandom {@code double} value between the origin
 468      *         (inclusive) and the bound (exclusive)
 469      * @throws IllegalArgumentException if {@code origin} is greater than
 470      *         or equal to {@code bound}
 471      */
 472     public double nextDouble(double origin, double bound) {
 473         if (!(origin < bound))
 474             throw new IllegalArgumentException(BAD_RANGE);
 475         return internalNextDouble(origin, bound);
 476     }
 477 
 478     /**
 479      * Returns a pseudorandom {@code boolean} value.
 480      *
 481      * @return a pseudorandom {@code boolean} value
 482      */
 483     public boolean nextBoolean() {
 484         return mix32(nextSeed()) < 0;
 485     }
 486 
 487     /**
 488      * Returns a pseudorandom {@code float} value between zero
 489      * (inclusive) and one (exclusive).
 490      *
 491      * @return a pseudorandom {@code float} value between zero
 492      *         (inclusive) and one (exclusive)
 493      */
 494     public float nextFloat() {
 495         return (mix32(nextSeed()) >>> 8) * FLOAT_UNIT;
 496     }
 497 
 498     public double nextGaussian() {
 499         // Use nextLocalGaussian instead of nextGaussian field
 500         Double d = nextLocalGaussian.get();
 501         if (d != null) {
 502             nextLocalGaussian.set(null);
 503             return d.doubleValue();
 504         }
 505         double v1, v2, s;
 506         do {
 507             v1 = 2 * nextDouble() - 1; // between -1 and 1
 508             v2 = 2 * nextDouble() - 1; // between -1 and 1
 509             s = v1 * v1 + v2 * v2;
 510         } while (s >= 1 || s == 0);
 511         double multiplier = StrictMath.sqrt(-2 * StrictMath.log(s)/s);
 512         nextLocalGaussian.set(new Double(v2 * multiplier));
 513         return v1 * multiplier;
 514     }
 515 
 516     // stream methods, coded in a way intended to better isolate for
 517     // maintenance purposes the small differences across forms.
 518 
 519     /**
 520      * Returns a stream producing the given {@code streamSize} number of
 521      * pseudorandom {@code int} values.
 522      *
 523      * @param streamSize the number of values to generate
 524      * @return a stream of pseudorandom {@code int} values
 525      * @throws IllegalArgumentException if {@code streamSize} is
 526      *         less than zero
 527      * @since 1.8
 528      */
 529     public IntStream ints(long streamSize) {
 530         if (streamSize < 0L)
 531             throw new IllegalArgumentException(BAD_SIZE);
 532         return StreamSupport.intStream
 533             (new RandomIntsSpliterator
 534              (0L, streamSize, Integer.MAX_VALUE, 0),
 535              false);
 536     }
 537 
 538     /**
 539      * Returns an effectively unlimited stream of pseudorandom {@code int}
 540      * values.
 541      *
 542      * @implNote This method is implemented to be equivalent to {@code
 543      * ints(Long.MAX_VALUE)}.
 544      *
 545      * @return a stream of pseudorandom {@code int} values
 546      * @since 1.8
 547      */
 548     public IntStream ints() {
 549         return StreamSupport.intStream
 550             (new RandomIntsSpliterator
 551              (0L, Long.MAX_VALUE, Integer.MAX_VALUE, 0),
 552              false);
 553     }
 554 
 555     /**
 556      * Returns a stream producing the given {@code streamSize} number
 557      * of pseudorandom {@code int} values, each conforming to the given
 558      * origin (inclusive) and bound (exclusive).
 559      *
 560      * @param streamSize the number of values to generate
 561      * @param randomNumberOrigin the origin (inclusive) of each random value
 562      * @param randomNumberBound the bound (exclusive) of each random value
 563      * @return a stream of pseudorandom {@code int} values,
 564      *         each with the given origin (inclusive) and bound (exclusive)
 565      * @throws IllegalArgumentException if {@code streamSize} is
 566      *         less than zero, or {@code randomNumberOrigin}
 567      *         is greater than or equal to {@code randomNumberBound}
 568      * @since 1.8
 569      */
 570     public IntStream ints(long streamSize, int randomNumberOrigin,
 571                           int randomNumberBound) {
 572         if (streamSize < 0L)
 573             throw new IllegalArgumentException(BAD_SIZE);
 574         if (randomNumberOrigin >= randomNumberBound)
 575             throw new IllegalArgumentException(BAD_RANGE);
 576         return StreamSupport.intStream
 577             (new RandomIntsSpliterator
 578              (0L, streamSize, randomNumberOrigin, randomNumberBound),
 579              false);
 580     }
 581 
 582     /**
 583      * Returns an effectively unlimited stream of pseudorandom {@code
 584      * int} values, each conforming to the given origin (inclusive) and bound
 585      * (exclusive).
 586      *
 587      * @implNote This method is implemented to be equivalent to {@code
 588      * ints(Long.MAX_VALUE, randomNumberOrigin, randomNumberBound)}.
 589      *
 590      * @param randomNumberOrigin the origin (inclusive) of each random value
 591      * @param randomNumberBound the bound (exclusive) of each random value
 592      * @return a stream of pseudorandom {@code int} values,
 593      *         each with the given origin (inclusive) and bound (exclusive)
 594      * @throws IllegalArgumentException if {@code randomNumberOrigin}
 595      *         is greater than or equal to {@code randomNumberBound}
 596      * @since 1.8
 597      */
 598     public IntStream ints(int randomNumberOrigin, int randomNumberBound) {
 599         if (randomNumberOrigin >= randomNumberBound)
 600             throw new IllegalArgumentException(BAD_RANGE);
 601         return StreamSupport.intStream
 602             (new RandomIntsSpliterator
 603              (0L, Long.MAX_VALUE, randomNumberOrigin, randomNumberBound),
 604              false);
 605     }
 606 
 607     /**
 608      * Returns a stream producing the given {@code streamSize} number of
 609      * pseudorandom {@code long} values.
 610      *
 611      * @param streamSize the number of values to generate
 612      * @return a stream of pseudorandom {@code long} values
 613      * @throws IllegalArgumentException if {@code streamSize} is
 614      *         less than zero
 615      * @since 1.8
 616      */
 617     public LongStream longs(long streamSize) {
 618         if (streamSize < 0L)
 619             throw new IllegalArgumentException(BAD_SIZE);
 620         return StreamSupport.longStream
 621             (new RandomLongsSpliterator
 622              (0L, streamSize, Long.MAX_VALUE, 0L),
 623              false);
 624     }
 625 
 626     /**
 627      * Returns an effectively unlimited stream of pseudorandom {@code long}
 628      * values.
 629      *
 630      * @implNote This method is implemented to be equivalent to {@code
 631      * longs(Long.MAX_VALUE)}.
 632      *
 633      * @return a stream of pseudorandom {@code long} values
 634      * @since 1.8
 635      */
 636     public LongStream longs() {
 637         return StreamSupport.longStream
 638             (new RandomLongsSpliterator
 639              (0L, Long.MAX_VALUE, Long.MAX_VALUE, 0L),
 640              false);
 641     }
 642 
 643     /**
 644      * Returns a stream producing the given {@code streamSize} number of
 645      * pseudorandom {@code long}, each conforming to the given origin
 646      * (inclusive) and bound (exclusive).
 647      *
 648      * @param streamSize the number of values to generate
 649      * @param randomNumberOrigin the origin (inclusive) of each random value
 650      * @param randomNumberBound the bound (exclusive) of each random value
 651      * @return a stream of pseudorandom {@code long} values,
 652      *         each with the given origin (inclusive) and bound (exclusive)
 653      * @throws IllegalArgumentException if {@code streamSize} is
 654      *         less than zero, or {@code randomNumberOrigin}
 655      *         is greater than or equal to {@code randomNumberBound}
 656      * @since 1.8
 657      */
 658     public LongStream longs(long streamSize, long randomNumberOrigin,
 659                             long randomNumberBound) {
 660         if (streamSize < 0L)
 661             throw new IllegalArgumentException(BAD_SIZE);
 662         if (randomNumberOrigin >= randomNumberBound)
 663             throw new IllegalArgumentException(BAD_RANGE);
 664         return StreamSupport.longStream
 665             (new RandomLongsSpliterator
 666              (0L, streamSize, randomNumberOrigin, randomNumberBound),
 667              false);
 668     }
 669 
 670     /**
 671      * Returns an effectively unlimited stream of pseudorandom {@code
 672      * long} values, each conforming to the given origin (inclusive) and bound
 673      * (exclusive).
 674      *
 675      * @implNote This method is implemented to be equivalent to {@code
 676      * longs(Long.MAX_VALUE, randomNumberOrigin, randomNumberBound)}.
 677      *
 678      * @param randomNumberOrigin the origin (inclusive) of each random value
 679      * @param randomNumberBound the bound (exclusive) of each random value
 680      * @return a stream of pseudorandom {@code long} values,
 681      *         each with the given origin (inclusive) and bound (exclusive)
 682      * @throws IllegalArgumentException if {@code randomNumberOrigin}
 683      *         is greater than or equal to {@code randomNumberBound}
 684      * @since 1.8
 685      */
 686     public LongStream longs(long randomNumberOrigin, long randomNumberBound) {
 687         if (randomNumberOrigin >= randomNumberBound)
 688             throw new IllegalArgumentException(BAD_RANGE);
 689         return StreamSupport.longStream
 690             (new RandomLongsSpliterator
 691              (0L, Long.MAX_VALUE, randomNumberOrigin, randomNumberBound),
 692              false);
 693     }
 694 
 695     /**
 696      * Returns a stream producing the given {@code streamSize} number of
 697      * pseudorandom {@code double} values, each between zero
 698      * (inclusive) and one (exclusive).
 699      *
 700      * @param streamSize the number of values to generate
 701      * @return a stream of {@code double} values
 702      * @throws IllegalArgumentException if {@code streamSize} is
 703      *         less than zero
 704      * @since 1.8
 705      */
 706     public DoubleStream doubles(long streamSize) {
 707         if (streamSize < 0L)
 708             throw new IllegalArgumentException(BAD_SIZE);
 709         return StreamSupport.doubleStream
 710             (new RandomDoublesSpliterator
 711              (0L, streamSize, Double.MAX_VALUE, 0.0),
 712              false);
 713     }
 714 
 715     /**
 716      * Returns an effectively unlimited stream of pseudorandom {@code
 717      * double} values, each between zero (inclusive) and one
 718      * (exclusive).
 719      *
 720      * @implNote This method is implemented to be equivalent to {@code
 721      * doubles(Long.MAX_VALUE)}.
 722      *
 723      * @return a stream of pseudorandom {@code double} values
 724      * @since 1.8
 725      */
 726     public DoubleStream doubles() {
 727         return StreamSupport.doubleStream
 728             (new RandomDoublesSpliterator
 729              (0L, Long.MAX_VALUE, Double.MAX_VALUE, 0.0),
 730              false);
 731     }
 732 
 733     /**
 734      * Returns a stream producing the given {@code streamSize} number of
 735      * pseudorandom {@code double} values, each conforming to the given origin
 736      * (inclusive) and bound (exclusive).
 737      *
 738      * @param streamSize the number of values to generate
 739      * @param randomNumberOrigin the origin (inclusive) of each random value
 740      * @param randomNumberBound the bound (exclusive) of each random value
 741      * @return a stream of pseudorandom {@code double} values,
 742      *         each with the given origin (inclusive) and bound (exclusive)
 743      * @throws IllegalArgumentException if {@code streamSize} is
 744      *         less than zero
 745      * @throws IllegalArgumentException if {@code randomNumberOrigin}
 746      *         is greater than or equal to {@code randomNumberBound}
 747      * @since 1.8
 748      */
 749     public DoubleStream doubles(long streamSize, double randomNumberOrigin,
 750                                 double randomNumberBound) {
 751         if (streamSize < 0L)
 752             throw new IllegalArgumentException(BAD_SIZE);
 753         if (!(randomNumberOrigin < randomNumberBound))
 754             throw new IllegalArgumentException(BAD_RANGE);
 755         return StreamSupport.doubleStream
 756             (new RandomDoublesSpliterator
 757              (0L, streamSize, randomNumberOrigin, randomNumberBound),
 758              false);
 759     }
 760 
 761     /**
 762      * Returns an effectively unlimited stream of pseudorandom {@code
 763      * double} values, each conforming to the given origin (inclusive) and bound
 764      * (exclusive).
 765      *
 766      * @implNote This method is implemented to be equivalent to {@code
 767      * doubles(Long.MAX_VALUE, randomNumberOrigin, randomNumberBound)}.
 768      *
 769      * @param randomNumberOrigin the origin (inclusive) of each random value
 770      * @param randomNumberBound the bound (exclusive) of each random value
 771      * @return a stream of pseudorandom {@code double} values,
 772      *         each with the given origin (inclusive) and bound (exclusive)
 773      * @throws IllegalArgumentException if {@code randomNumberOrigin}
 774      *         is greater than or equal to {@code randomNumberBound}
 775      * @since 1.8
 776      */
 777     public DoubleStream doubles(double randomNumberOrigin, double randomNumberBound) {
 778         if (!(randomNumberOrigin < randomNumberBound))
 779             throw new IllegalArgumentException(BAD_RANGE);
 780         return StreamSupport.doubleStream
 781             (new RandomDoublesSpliterator
 782              (0L, Long.MAX_VALUE, randomNumberOrigin, randomNumberBound),
 783              false);
 784     }
 785 
 786     /**
 787      * Spliterator for int streams.  We multiplex the four int
 788      * versions into one class by treating a bound less than origin as
 789      * unbounded, and also by treating "infinite" as equivalent to
 790      * Long.MAX_VALUE. For splits, it uses the standard divide-by-two
 791      * approach. The long and double versions of this class are
 792      * identical except for types.
 793      */
 794     private static final class RandomIntsSpliterator
 795             implements Spliterator.OfInt {
 796         long index;
 797         final long fence;
 798         final int origin;
 799         final int bound;
 800         RandomIntsSpliterator(long index, long fence,
 801                               int origin, int bound) {
 802             this.index = index; this.fence = fence;
 803             this.origin = origin; this.bound = bound;
 804         }
 805 
 806         public RandomIntsSpliterator trySplit() {
 807             long i = index, m = (i + fence) >>> 1;
 808             return (m <= i) ? null :
 809                 new RandomIntsSpliterator(i, index = m, origin, bound);
 810         }
 811 
 812         public long estimateSize() {
 813             return fence - index;
 814         }
 815 
 816         public int characteristics() {
 817             return (Spliterator.SIZED | Spliterator.SUBSIZED |
 818                     Spliterator.NONNULL | Spliterator.IMMUTABLE);
 819         }
 820 
 821         public boolean tryAdvance(IntConsumer consumer) {
 822             if (consumer == null) throw new NullPointerException();
 823             long i = index, f = fence;
 824             if (i < f) {
 825                 consumer.accept(ThreadLocalRandom.current().internalNextInt(origin, bound));
 826                 index = i + 1;
 827                 return true;
 828             }
 829             return false;
 830         }
 831 
 832         public void forEachRemaining(IntConsumer consumer) {
 833             if (consumer == null) throw new NullPointerException();
 834             long i = index, f = fence;
 835             if (i < f) {
 836                 index = f;
 837                 int o = origin, b = bound;
 838                 ThreadLocalRandom rng = ThreadLocalRandom.current();
 839                 do {
 840                     consumer.accept(rng.internalNextInt(o, b));
 841                 } while (++i < f);
 842             }
 843         }
 844     }
 845 
 846     /**
 847      * Spliterator for long streams.
 848      */
 849     private static final class RandomLongsSpliterator
 850             implements Spliterator.OfLong {
 851         long index;
 852         final long fence;
 853         final long origin;
 854         final long bound;
 855         RandomLongsSpliterator(long index, long fence,
 856                                long origin, long bound) {
 857             this.index = index; this.fence = fence;
 858             this.origin = origin; this.bound = bound;
 859         }
 860 
 861         public RandomLongsSpliterator trySplit() {
 862             long i = index, m = (i + fence) >>> 1;
 863             return (m <= i) ? null :
 864                 new RandomLongsSpliterator(i, index = m, origin, bound);
 865         }
 866 
 867         public long estimateSize() {
 868             return fence - index;
 869         }
 870 
 871         public int characteristics() {
 872             return (Spliterator.SIZED | Spliterator.SUBSIZED |
 873                     Spliterator.NONNULL | Spliterator.IMMUTABLE);
 874         }
 875 
 876         public boolean tryAdvance(LongConsumer consumer) {
 877             if (consumer == null) throw new NullPointerException();
 878             long i = index, f = fence;
 879             if (i < f) {
 880                 consumer.accept(ThreadLocalRandom.current().internalNextLong(origin, bound));
 881                 index = i + 1;
 882                 return true;
 883             }
 884             return false;
 885         }
 886 
 887         public void forEachRemaining(LongConsumer consumer) {
 888             if (consumer == null) throw new NullPointerException();
 889             long i = index, f = fence;
 890             if (i < f) {
 891                 index = f;
 892                 long o = origin, b = bound;
 893                 ThreadLocalRandom rng = ThreadLocalRandom.current();
 894                 do {
 895                     consumer.accept(rng.internalNextLong(o, b));
 896                 } while (++i < f);
 897             }
 898         }
 899 
 900     }
 901 
 902     /**
 903      * Spliterator for double streams.
 904      */
 905     private static final class RandomDoublesSpliterator
 906             implements Spliterator.OfDouble {
 907         long index;
 908         final long fence;
 909         final double origin;
 910         final double bound;
 911         RandomDoublesSpliterator(long index, long fence,
 912                                  double origin, double bound) {
 913             this.index = index; this.fence = fence;
 914             this.origin = origin; this.bound = bound;
 915         }
 916 
 917         public RandomDoublesSpliterator trySplit() {
 918             long i = index, m = (i + fence) >>> 1;
 919             return (m <= i) ? null :
 920                 new RandomDoublesSpliterator(i, index = m, origin, bound);
 921         }
 922 
 923         public long estimateSize() {
 924             return fence - index;
 925         }
 926 
 927         public int characteristics() {
 928             return (Spliterator.SIZED | Spliterator.SUBSIZED |
 929                     Spliterator.NONNULL | Spliterator.IMMUTABLE);
 930         }
 931 
 932         public boolean tryAdvance(DoubleConsumer consumer) {
 933             if (consumer == null) throw new NullPointerException();
 934             long i = index, f = fence;
 935             if (i < f) {
 936                 consumer.accept(ThreadLocalRandom.current().internalNextDouble(origin, bound));
 937                 index = i + 1;
 938                 return true;
 939             }
 940             return false;
 941         }
 942 
 943         public void forEachRemaining(DoubleConsumer consumer) {
 944             if (consumer == null) throw new NullPointerException();
 945             long i = index, f = fence;
 946             if (i < f) {
 947                 index = f;
 948                 double o = origin, b = bound;
 949                 ThreadLocalRandom rng = ThreadLocalRandom.current();
 950                 do {
 951                     consumer.accept(rng.internalNextDouble(o, b));
 952                 } while (++i < f);
 953             }
 954         }
 955     }
 956 
 957 
 958     // Within-package utilities
 959 
 960     /*
 961      * Descriptions of the usages of the methods below can be found in
 962      * the classes that use them. Briefly, a thread's "probe" value is
 963      * a non-zero hash code that (probably) does not collide with
 964      * other existing threads with respect to any power of two
 965      * collision space. When it does collide, it is pseudo-randomly
 966      * adjusted (using a Marsaglia XorShift). The nextSecondarySeed
 967      * method is used in the same contexts as ThreadLocalRandom, but
 968      * only for transient usages such as random adaptive spin/block
 969      * sequences for which a cheap RNG suffices and for which it could
 970      * in principle disrupt user-visible statistical properties of the
 971      * main ThreadLocalRandom if we were to use it.
 972      *
 973      * Note: Because of package-protection issues, versions of some
 974      * these methods also appear in some subpackage classes.
 975      */
 976 
 977     /**
 978      * Returns the probe value for the current thread without forcing
 979      * initialization. Note that invoking ThreadLocalRandom.current()
 980      * can be used to force initialization on zero return.
 981      */
 982     static final int getProbe() {
 983         return U.getInt(Thread.currentThread(), PROBE);
 984     }
 985 
 986     /**
 987      * Pseudo-randomly advances and records the given probe value for the
 988      * given thread.
 989      */
 990     static final int advanceProbe(int probe) {
 991         probe ^= probe << 13;   // xorshift
 992         probe ^= probe >>> 17;
 993         probe ^= probe << 5;
 994         U.putInt(Thread.currentThread(), PROBE, probe);
 995         return probe;
 996     }
 997 
 998     /**
 999      * Returns the pseudo-randomly initialized or updated secondary seed.
1000      */
1001     static final int nextSecondarySeed() {
1002         int r;
1003         Thread t = Thread.currentThread();
1004         if ((r = U.getInt(t, SECONDARY)) != 0) {
1005             r ^= r << 13;   // xorshift
1006             r ^= r >>> 17;
1007             r ^= r << 5;
1008         }
1009         else if ((r = mix32(seeder.getAndAdd(SEEDER_INCREMENT))) == 0)
1010             r = 1; // avoid zero
1011         U.putInt(t, SECONDARY, r);
1012         return r;
1013     }
1014 
1015     // Serialization support
1016 
1017     private static final long serialVersionUID = -5851777807851030925L;
1018 
1019     /**
1020      * @serialField rnd long
1021      *              seed for random computations
1022      * @serialField initialized boolean
1023      *              always true
1024      */
1025     private static final ObjectStreamField[] serialPersistentFields = {
1026         new ObjectStreamField("rnd", long.class),
1027         new ObjectStreamField("initialized", boolean.class),
1028     };
1029 
1030     /**
1031      * Saves the {@code ThreadLocalRandom} to a stream (that is, serializes it).
1032      * @param s the stream
1033      * @throws java.io.IOException if an I/O error occurs
1034      */
1035     private void writeObject(java.io.ObjectOutputStream s)
1036         throws java.io.IOException {
1037 
1038         java.io.ObjectOutputStream.PutField fields = s.putFields();
1039         fields.put("rnd", U.getLong(Thread.currentThread(), SEED));
1040         fields.put("initialized", true);
1041         s.writeFields();
1042     }
1043 
1044     /**
1045      * Returns the {@link #current() current} thread's {@code ThreadLocalRandom}.
1046      * @return the {@link #current() current} thread's {@code ThreadLocalRandom}
1047      */
1048     private Object readResolve() {
1049         return current();
1050     }
1051 
1052     // Unsafe mechanics
1053     private static final jdk.internal.misc.Unsafe U = jdk.internal.misc.Unsafe.getUnsafe();
1054     private static final long SEED;
1055     private static final long PROBE;
1056     private static final long SECONDARY;
1057     static {
1058         try {
1059             SEED = U.objectFieldOffset
1060                 (Thread.class.getDeclaredField("threadLocalRandomSeed"));
1061             PROBE = U.objectFieldOffset
1062                 (Thread.class.getDeclaredField("threadLocalRandomProbe"));
1063             SECONDARY = U.objectFieldOffset
1064                 (Thread.class.getDeclaredField("threadLocalRandomSecondarySeed"));
1065         } catch (ReflectiveOperationException e) {
1066             throw new Error(e);
1067         }
1068     }
1069 }